diff --git a/README.md b/README.md index 45482ff4..25b9919d 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,9 @@ - **规避陷阱和对抗编译器**，只有真的上手写过一长段时间 Rust 项目，才知道该如何规避常见的陷阱以及解决一些难搞的编译器错误，而本书将帮助你大大缩短这个过程，提前规避这些问题 -- **Cook Book**，涵盖多个应用场景的实战代码片段，程序员上网查询文件操作、正则解析、数据库操作是常事，没有人能记住所有代码，而 Cook Book 可解君忧，Ctrl + C/V 走天下 +- **[Cookbook](https://cookbook.rs)**，涵盖多个应用场景的实战代码片段，程序员上网查询文件操作、正则解析、数据库操作是常事，没有人能记住所有代码，而 Cook Book 可解君忧，Ctrl + C/V 走天下 -- **配套练习题**，像学习一门大学课程一样学习 Rust 是一种什么感觉？*Rust语言圣经 + [Rust语言实战](https://github.com/sunface/rust-by-practice)* 双剑合璧，给你最极致的学习体验 +- **[配套练习题](https://github.com/sunface/rust-by-practice)**，像学习一门大学课程一样学习 Rust 是一种什么感觉？*Rust语言圣经 + Rust语言实战* 双剑合璧，给你最极致的学习体验 总之在写作过程中我们始终铭记初心：为中国用户打造一门**全面的、深入的、持续更新的** Rust 教程。 新手用来入门，老手用来提高，高手用来提升生产力。 diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 51a325e9..7358fe75 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -164,35 +164,7 @@ # 应用实战 --- -- [CookBook doing](cookbook/intro.md) - - [实用算法](cookbook/algos/intro.md) - - [生成随机值](cookbook/algos/randomness.md) - - [Vec 排序](cookbook/algos/sorting.md) - - [命令行]() - - [参数解析](cookbook/cmd/parsing.md) - - [终端输出格式化](cookbook/cmd/ansi.md) - - [压缩]() - - [使用.tar包](cookbook/compression/tar.md) - - [并发]() - - [线程](cookbook/cocurrency/threads.md) - - [使用rayon并行处理数据](cookbook/cocurrency/parallel.md) - - [密码学]() - - [哈希](cookbook/cryptography/hashing.md) - - [加密](cookbook/cryptography/encryption.md) - - [数据结构]() - - [位字段](cookbook/datastructures/bitfield.md) - - [数据库]() - - [SQLite](cookbook/database/sqlite.md) - - [Postgres](cookbook/database/postgres.md) - - [日期和时间]() - - [时间计算和转换](cookbook/datetime/duration.md) - - [解析和显示](cookbook/datetime/parsing.md) - - [开发者工具]() - - [日志](cookbook/devtools/log.md) - - [配置日志](cookbook/devtools/config-log.md) - - [版本号](cookbook/devtools/version.md) - - [构建时工具](cookbook/devtools/build-tools.md) - +- [CookBook](cookbook/intro.md) - [Rust 最佳实践](practice/intro.md) - [对抗编译检查](practice/fight-with-compiler/intro.md) diff --git a/src/cookbook/algos/intro.md b/src/cookbook/algos/intro.md deleted file mode 100644 index ace373bf..00000000 --- a/src/cookbook/algos/intro.md +++ /dev/null @@ -1,4 +0,0 @@ -# 实用算法 -本章将收集一些在实战中经常使用的算法 API。 - -> Note: 这里没有具体的算法实现，都是关于如何应用的 \ No newline at end of file diff --git a/src/cookbook/algos/randomness.md b/src/cookbook/algos/randomness.md deleted file mode 100644 index 04241a7e..00000000 --- a/src/cookbook/algos/randomness.md +++ /dev/null @@ -1,155 +0,0 @@ -# 生成随机值 - -### 生成随机数 - -使用 [rand::thread_rng](https://docs.rs/rand/*/rand/fn.thread_rng.html) 可以获取一个随机数生成器 [rand::Rng](https://docs.rs/rand/0.8.5/rand/trait.Rng.html) ，该生成器需要在每个线程都初始化一个。 - -整数的随机分布范围等于类型的取值范围，但是浮点数只分布在 `[0, 1)` 区间内。 - -```rust,editable -use rand::Rng; - -fn main() { - let mut rng = rand::thread_rng(); - - let n1: u8 = rng.gen(); - let n2: u16 = rng.gen(); - println!("Random u8: {}", n1); - println!("Random u16: {}", n2); - println!("Random u32: {}", rng.gen::()); - println!("Random i32: {}", rng.gen::()); - println!("Random float: {}", rng.gen::()); -} -``` - -### 指定范围生成随机数 - -使用 [Rng::gen_range](https://rust-lang-nursery.github.io/rust-cookbook/algorithms/randomness.html) 生成 [0, 10) 区间内的随机数( 右开区间，不包括 `10` )。 -```rust,editable -use rand::Rng; - -fn main() { - let mut rng = rand::thread_rng(); - println!("Integer: {}", rng.gen_range(0..10)); - println!("Float: {}", rng.gen_range(0.0..10.0)); -} -``` - -[Uniform](https://docs.rs/rand/*/rand/distributions/uniform/struct.Uniform.html) 可以用于生成均匀分布uniform distribution的随机数。当需要在同一个范围内重复生成随机数时，该方法虽然和之前的方法效果一样，但会更快一些。 - -```rust,editable -use rand::distributions::{Distribution, Uniform}; - -fn main() { - let mut rng = rand::thread_rng(); - let die = Uniform::from(1..7); - - loop { - let throw = die.sample(&mut rng); - println!("Roll the die: {}", throw); - if throw == 6 { - break; - } - } -} -``` - -### 使用指定分布来生成随机数 - -默认情况下，`rand` 包使用均匀分布来生成随机数，而 [rand_distr](https://docs.rs/rand_distr/*/rand_distr/index.html) 包提供了其它类型的分布方式。 - -首先，你需要获取想要使用的分布的实例，然后在 [rand::Rng](https://docs.rs/rand/*/rand/trait.Rng.html) 的帮助下使用 [Distribution::sample](https://docs.rs/rand/*/rand/distributions/trait.Distribution.html#tymethod.sample) 对该实例进行取样。 - -如果想要查询可用的分布列表，可以访问[这里](https://docs.rs/rand_distr/*/rand_distr/index.html)，下面的示例中我们将使用 [Normal](https://docs.rs/rand_distr/0.4.3/rand_distr/struct.Normal.html) 分布: -```rust,editable -use rand_distr::{Distribution, Normal, NormalError}; -use rand::thread_rng; - -fn main() -> Result<(), NormalError> { - let mut rng = thread_rng(); - let normal = Normal::new(2.0, 3.0)?; - let v = normal.sample(&mut rng); - println!("{} is from a N(2, 9) distribution", v); - Ok(()) -} -``` - -### 在自定义类型中生成随机值 - - -使用 [Distribution](https://docs.rs/rand/*/rand/distributions/trait.Distribution.html) 特征包裹我们的自定义类型，并为 [Standard](https://docs.rs/rand/*/rand/distributions/struct.Standard.html) 实现该特征，可以为自定义类型的指定字段生成随机数。 - - -```rust,editable -use rand::Rng; -use rand::distributions::{Distribution, Standard}; - -#[derive(Debug)] -struct Point { - x: i32, - y: i32, -} - -impl Distribution for Standard { - fn sample(&self, rng: &mut R) -> Point { - let (rand_x, rand_y) = rng.gen(); - Point { - x: rand_x, - y: rand_y, - } - } -} - -fn main() { - let mut rng = rand::thread_rng(); - - // 生成一个随机的 Point - let rand_point: Point = rng.gen(); - println!("Random Point: {:?}", rand_point); - - // 通过类型暗示( hint )生成一个随机的元组 - let rand_tuple = rng.gen::<(i32, bool, f64)>(); - println!("Random tuple: {:?}", rand_tuple); -} -``` - -### 生成随机的字符串(A-Z, a-z, 0-9) -通过 [Alphanumeric](https://docs.rs/rand/0.8.5/rand/distributions/struct.Alphanumeric.html) 采样来生成随机的 ASCII 字符串，包含从 `A-Z, a-z, 0-9` 的字符。 - -```rust,editble -use rand::{thread_rng, Rng}; -use rand::distributions::Alphanumeric; - -fn main() { - let rand_string: String = thread_rng() - .sample_iter(&Alphanumeric) - .take(30) - .map(char::from) - .collect(); - - println!("{}", rand_string); -} -``` - -### 生成随机的字符串( 用户指定 ASCII 字符 ) -通过 [gen_string](https://docs.rs/rand/0.8.5/rand/trait.Rng.html#method.gen_range) 生成随机的 ASCII 字符串，包含用户指定的字符。 - -```rust,editable -fn main() { - use rand::Rng; - const CHARSET: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ\ - abcdefghijklmnopqrstuvwxyz\ - 0123456789)(*&^%$#@!~"; - const PASSWORD_LEN: usize = 30; - let mut rng = rand::thread_rng(); - - let password: String = (0..PASSWORD_LEN) - .map(|_| { - let idx = rng.gen_range(0..CHARSET.len()); - CHARSET[idx] as char - }) - .collect(); - - println!("{:?}", password); -} -``` diff --git a/src/cookbook/algos/sorting.md b/src/cookbook/algos/sorting.md deleted file mode 100644 index 76e44e8c..00000000 --- a/src/cookbook/algos/sorting.md +++ /dev/null @@ -1,84 +0,0 @@ -## Vector 排序 - - -### 对整数 Vector 排序 - -以下示例使用 [Vec::sort](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort) 来排序，如果大家希望获得更高的性能，可以使用 [Vec::sort_unstable](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort_unstable)，但是该方法无法保留相等元素的顺序。 - -```rust,editable -fn main() { - let mut vec = vec![1, 5, 10, 2, 15]; - - vec.sort(); - - assert_eq!(vec, vec![1, 2, 5, 10, 15]); -} -``` - -### 对浮点数 Vector 排序 - -浮点数数组可以使用 [Vec::sort_by](https://doc.rust-lang.org/std/primitive.slice.html#method.sort_by) 和 [PartialOrd::partial_cmp](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#tymethod.partial_cmp) 进行排序。 - -```rust,editable -fn main() { - let mut vec = vec![1.1, 1.15, 5.5, 1.123, 2.0]; - - vec.sort_by(|a, b| a.partial_cmp(b).unwrap()); - - assert_eq!(vec, vec![1.1, 1.123, 1.15, 2.0, 5.5]); -} -``` - -### 对结构体 Vector 排序 - -以下示例中的结构体 `Person` 将实现基于字段 `name` 和 `age` 的自然排序。为了让 `Person` 变为可排序的，我们需要为其派生 `Eq、PartialEq、Ord、PartialOrd` 特征，关于这几个特征的详情，请见[这里](https://course.rs/advance/confonding/eq.html)。 - -当然，还可以使用 [vec:sort_by](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.sort_by) 方法配合一个自定义比较函数，只按照 `age` 的维度对 `Person` 数组排序。 - -```rust,editable -#[derive(Debug, Eq, Ord, PartialEq, PartialOrd)] -struct Person { - name: String, - age: u32 -} - -impl Person { - pub fn new(name: String, age: u32) -> Self { - Person { - name, - age - } - } -} - -fn main() { - let mut people = vec![ - Person::new("Zoe".to_string(), 25), - Person::new("Al".to_string(), 60), - Person::new("John".to_string(), 1), - ]; - - // 通过派生后的自然顺序(Name and age)排序 - people.sort(); - - assert_eq!( - people, - vec![ - Person::new("Al".to_string(), 60), - Person::new("John".to_string(), 1), - Person::new("Zoe".to_string(), 25), - ]); - - // 只通过 age 排序 - people.sort_by(|a, b| b.age.cmp(&a.age)); - - assert_eq!( - people, - vec![ - Person::new("Al".to_string(), 60), - Person::new("Zoe".to_string(), 25), - Person::new("John".to_string(), 1), - ]); - -} -``` \ No newline at end of file diff --git a/src/cookbook/cmd/ansi.md b/src/cookbook/cmd/ansi.md deleted file mode 100644 index 87c18682..00000000 --- a/src/cookbook/cmd/ansi.md +++ /dev/null @@ -1,50 +0,0 @@ -# ANSI 终端 - -[ansi_term](https://crates.io/crates/ansi_term) 包可以帮我们控制终端上的输出样式，例如使用颜色文字、控制输出格式等，当然，前提是在 ANSI 终端上。 - -`ansi_term` 中有两个主要数据结构：[ANSIString](https://docs.rs/ansi_term/0.12.1/ansi_term/type.ANSIString.html) 和 [Style](https://docs.rs/ansi_term/0.12.1/ansi_term/struct.Style.html)。 - -`Style` 用于控制样式：颜色、加粗、闪烁等，而前者是一个带有样式的字符串。 - -## 颜色字体 - -```rust,editable -use ansi_term::Colour; - -fn main() { - println!("This is {} in color, {} in color and {} in color", - Colour::Red.paint("red"), - Colour::Blue.paint("blue"), - Colour::Green.paint("green")); -} -``` - -## 加粗字体 - -比颜色复杂的样式构建需要使用 `Style` 结构体: -```rust,editable -use ansi_term::Style; - -fn main() { - println!("{} and this is not", - Style::new().bold().paint("This is Bold")); -} -``` - -## 加粗和颜色 - -`Colour` 实现了很多跟 `Style` 类似的函数，因此可以实现链式调用。 - -```rust,editable -use ansi_term::Colour; -use ansi_term::Style; - -fn main(){ - println!("{}, {} and {}", - Colour::Yellow.paint("This is colored"), - Style::new().bold().paint("this is bold"), - // Colour 也可以使用 bold 方法进行加粗 - Colour::Yellow.bold().paint("this is bold and colored")); -} -``` - diff --git a/src/cookbook/cmd/parsing.md b/src/cookbook/cmd/parsing.md deleted file mode 100644 index b0356aef..00000000 --- a/src/cookbook/cmd/parsing.md +++ /dev/null @@ -1,70 +0,0 @@ -# 参数解析 - -## Clap -下面的程序给出了使用 `clap` 来解析命令行参数的样式结构，如果大家想了解更多，在 `clap` [文档](https://docs.rs/clap/)中还给出了另外两种初始化一个应用的方式。 - -在下面的构建中，`value_of` 将获取通过 `with_name` 解析出的值。`short` 和 `long` 用于设置用户输入的长短命令格式，例如短命令 `-f` 和长命令 `--file`。 - -```rust,editable -use clap::{Arg, App}; - -fn main() { - let matches = App::new("My Test Program") - .version("0.1.0") - .author("Hackerman Jones ") - .about("Teaches argument parsing") - .arg(Arg::with_name("file") - .short("f") - .long("file") - .takes_value(true) - .help("A cool file")) - .arg(Arg::with_name("num") - .short("n") - .long("number") - .takes_value(true) - .help("Five less than your favorite number")) - .get_matches(); - - let myfile = matches.value_of("file").unwrap_or("input.txt"); - println!("The file passed is: {}", myfile); - - let num_str = matches.value_of("num"); - match num_str { - None => println!("No idea what your favorite number is."), - Some(s) => { - match s.parse::() { - Ok(n) => println!("Your favorite number must be {}.", n + 5), - Err(_) => println!("That's not a number! {}", s), - } - } - } -} -``` - -`clap` 针对上面提供的构建样式，会自动帮我们生成相应的使用方式说明。例如，上面代码生成的使用说明如下： -```shell -My Test Program 0.1.0 -Hackerman Jones -Teaches argument parsing - -USAGE: - testing [OPTIONS] - -FLAGS: - -h, --help Prints help information - -V, --version Prints version information - -OPTIONS: - -f, --file A cool file - -n, --number Five less than your favorite number -``` - -最后，再使用一些参数来运行下我们的代码: -```shell -$ cargo run -- -f myfile.txt -n 251 -The file passed is: myfile.txt -Your favorite number must be 256. -``` - -## Structopt -@todo \ No newline at end of file diff --git a/src/cookbook/cocurrency/parallel.md b/src/cookbook/cocurrency/parallel.md deleted file mode 100644 index d1d5c521..00000000 --- a/src/cookbook/cocurrency/parallel.md +++ /dev/null @@ -1,201 +0,0 @@ -# 任务并行处理 - -### 并行修改数组中的元素 - -[rayon](https://docs.rs/rayon/1.5.1/rayon/index.html) 提供了一个 [par_iter_mut](https://docs.rs/rayon/*/rayon/iter/trait.IntoParallelRefMutIterator.html#tymethod.par_iter_mut) 方法用于并行化迭代一个数据集合。 - -```rust,editable -use rayon::prelude::*; - -fn main() { - let mut arr = [0, 7, 9, 11]; - arr.par_iter_mut().for_each(|p| *p -= 1); - println!("{:?}", arr); -} -``` - -### 并行测试集合中的元素是否满足给定的条件 - -[rayon::any](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.any) 和 [rayon::all](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.all) 类似于 [std::any](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.any) / [std::all](https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.all) ，但是是并行版本的。 - -- `rayon::any` 并行检查迭代器中是否有任何元素满足给定的条件，一旦发现符合条件的元素，就立即返回 -- `rayon::all` 并行检查迭代器中的所有元素是否满足给定的条件，一旦发现不满足条件的元素，就立即返回 - -```rust,editable -use rayon::prelude::*; - -fn main() { - let mut vec = vec![2, 4, 6, 8]; - - assert!(!vec.par_iter().any(|n| (*n % 2) != 0)); - assert!(vec.par_iter().all(|n| (*n % 2) == 0)); - assert!(!vec.par_iter().any(|n| *n > 8 )); - assert!(vec.par_iter().all(|n| *n <= 8 )); - - vec.push(9); - - assert!(vec.par_iter().any(|n| (*n % 2) != 0)); - assert!(!vec.par_iter().all(|n| (*n % 2) == 0)); - assert!(vec.par_iter().any(|n| *n > 8 )); - assert!(!vec.par_iter().all(|n| *n <= 8 )); -} -``` - -### 使用给定条件并行搜索 -下面例子使用 [par_iter](https://docs.rs/rayon/*/rayon/iter/trait.IntoParallelRefIterator.html#tymethod.par_iter) 和 [rayon::find_any](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.find_any) 来并行搜索一个数组，直到找到任意一个满足条件的元素。 - -如果有多个元素满足条件，`rayon` 会返回第一个找到的元素，注意：第一个找到的元素未必是数组中的顺序最靠前的那个。 - -```rust,editable -use rayon::prelude::*; - -fn main() { - let v = vec![6, 2, 1, 9, 3, 8, 11]; - - // 这里使用了 `&&x` 的形式，大家可以在以下链接阅读更多 https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find - let f1 = v.par_iter().find_any(|&&x| x == 9); - let f2 = v.par_iter().find_any(|&&x| x % 2 == 0 && x > 6); - let f3 = v.par_iter().find_any(|&&x| x > 8); - - assert_eq!(f1, Some(&9)); - assert_eq!(f2, Some(&8)); - assert!(f3 > Some(&8)); -} -``` - -### 对数组进行并行排序 -下面的例子将对字符串数组进行并行排序。 - -[par_sort_unstable](https://docs.rs/rayon/*/rayon/slice/trait.ParallelSliceMut.html#method.par_sort_unstable) 方法的排序性能往往要比[稳定的排序算法](https://docs.rs/rayon/1.5.1/rayon/slice/trait.ParallelSliceMut.html#method.par_sort)更高。 - - -```rust,editable -use rand::{Rng, thread_rng}; -use rand::distributions::Alphanumeric; -use rayon::prelude::*; - -fn main() { - let mut vec = vec![String::new(); 100_000]; - // 并行生成数组中的字符串 - vec.par_iter_mut().for_each(|p| { - let mut rng = thread_rng(); - *p = (0..5).map(|_| rng.sample(&Alphanumeric)).collect() - }); - - // - vec.par_sort_unstable(); -} -``` - -### 并行化 Map-Reuduce - -下面例子使用 [rayon::filter](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.filter), [rayon::map](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.map), 和 [rayon::reduce](https://docs.rs/rayon/*/rayon/iter/trait.ParallelIterator.html#method.reduce) 来超过 30 岁的 `Person` 的平均年龄。 - -- `rayon::filter` 返回集合中所有满足给定条件的元素 -- `rayon::map` 对集合中的每一个元素执行一个操作，创建并返回新的迭代器，类似于[迭代器适配器](https://course.rs/advance/functional-programing/iterator.html#迭代器适配器) -- `rayon::reduce` 则迭代器的元素进行不停的聚合运算，直到获取一个最终结果，这个结果跟例子中 `rayon::sum` 获取的结果是相同的 - -```rust,editable -use rayon::prelude::*; - -struct Person { - age: u32, -} - -fn main() { - let v: Vec = vec![ - Person { age: 23 }, - Person { age: 19 }, - Person { age: 42 }, - Person { age: 17 }, - Person { age: 17 }, - Person { age: 31 }, - Person { age: 30 }, - ]; - - let num_over_30 = v.par_iter().filter(|&x| x.age > 30).count() as f32; - let sum_over_30 = v.par_iter() - .map(|x| x.age) - .filter(|&x| x > 30) - .reduce(|| 0, |x, y| x + y); - - let alt_sum_30: u32 = v.par_iter() - .map(|x| x.age) - .filter(|&x| x > 30) - .sum(); - - let avg_over_30 = sum_over_30 as f32 / num_over_30; - let alt_avg_over_30 = alt_sum_30 as f32/ num_over_30; - - assert!((avg_over_30 - alt_avg_over_30).abs() < std::f32::EPSILON); - println!("The average age of people older than 30 is {}", avg_over_30); -} -``` - -### 并行生成缩略图 -下面例子将为目录中的所有图片并行生成缩略图，然后将结果存到新的目录 `thumbnails` 中。 - -[glob::glob_with](https://docs.rs/glob/*/glob/fn.glob_with.html) 可以找出当前目录下的所有 `.jpg` 文件，`rayon` 通过 [DynamicImage::resize](https://docs.rs/image/*/image/enum.DynamicImage.html#method.resize) 来并行调整图片的大小。 - -```rust,editable -# use error_chain::error_chain; - -use std::path::Path; -use std::fs::create_dir_all; - -# use error_chain::ChainedError; -use glob::{glob_with, MatchOptions}; -use image::{FilterType, ImageError}; -use rayon::prelude::*; - -# error_chain! { -# foreign_links { -# Image(ImageError); -# Io(std::io::Error); -# Glob(glob::PatternError); -# } -#} - -fn main() -> Result<()> { - let options: MatchOptions = Default::default(); - // 找到当前目录中的所有 `jpg` 文件 - let files: Vec<_> = glob_with("*.jpg", options)? - .filter_map(|x| x.ok()) - .collect(); - - if files.len() == 0 { - error_chain::bail!("No .jpg files found in current directory"); - } - - let thumb_dir = "thumbnails"; - create_dir_all(thumb_dir)?; - - println!("Saving {} thumbnails into '{}'...", files.len(), thumb_dir); - - let image_failures: Vec<_> = files - .par_iter() - .map(|path| { - make_thumbnail(path, thumb_dir, 300) - .map_err(|e| e.chain_err(|| path.display().to_string())) - }) - .filter_map(|x| x.err()) - .collect(); - - image_failures.iter().for_each(|x| println!("{}", x.display_chain())); - - println!("{} thumbnails saved successfully", files.len() - image_failures.len()); - Ok(()) -} - -fn make_thumbnail(original: PA, thumb_dir: PB, longest_edge: u32) -> Result<()> -where - PA: AsRef, - PB: AsRef, -{ - let img = image::open(original.as_ref())?; - let file_path = thumb_dir.as_ref().join(original); - - Ok(img.resize(longest_edge, longest_edge, FilterType::Nearest) - .save(file_path)?) -} -``` \ No newline at end of file diff --git a/src/cookbook/cocurrency/threads.md b/src/cookbook/cocurrency/threads.md deleted file mode 100644 index b980f9ca..00000000 --- a/src/cookbook/cocurrency/threads.md +++ /dev/null @@ -1,336 +0,0 @@ -# 线程 - -### 生成一个临时性的线程 - -下面例子用到了 [crossbeam](cookbook/cocurrency/intro.md) 包，它提供了非常实用的、用于并发和并行编程的数据结构和函数。 - -[Scope::spawn](https://docs.rs/crossbeam/*/crossbeam/thread/struct.Scope.html#method.spawn) 会生成一个被限定了作用域的线程，该线程最大的特点就是：它会在传给 [crossbeam::scope](https://docs.rs/crossbeam/0.8.1/crossbeam/fn.scope.html) 的闭包函数返回前先行结束。得益于这个特点，子线程的创建使用就像是本地闭包函数调用，因此生成的线程内部可以使用外部环境中的变量！ - - -```rust,editable -fn main() { - let arr = &[1, 25, -4, 10]; - let max = find_max(arr); - assert_eq!(max, Some(25)); -} - -// 将数组分成两个部分，并使用新的线程对它们进行处理 -fn find_max(arr: &[i32]) -> Option { - const THRESHOLD: usize = 2; - - if arr.len() <= THRESHOLD { - return arr.iter().cloned().max(); - } - - let mid = arr.len() / 2; - let (left, right) = arr.split_at(mid); - - crossbeam::scope(|s| { - let thread_l = s.spawn(|_| find_max(left)); - let thread_r = s.spawn(|_| find_max(right)); - - let max_l = thread_l.join().unwrap()?; - let max_r = thread_r.join().unwrap()?; - - Some(max_l.max(max_r)) - }).unwrap() -} -``` - -### 创建并行流水线 -下面我们使用 [crossbeam](https://docs.rs/crossbeam/latest/crossbeam/) 和 [crossbeam-channel](https://docs.rs/crossbeam-channel/*/crossbeam_channel/index.html) 来创建一个并行流水线：流水线的两端分别是数据源和数据下沉( sink )，在流水线中间，有两个工作线程会从源头接收数据，对数据进行并行处理，最后将数据下沉。 - -- 消息通道( channel )是 [crossbeam_channel::bounded](https://docs.rs/crossbeam-channel/0.5.4/crossbeam_channel/fn.bounded.html)，它只能缓存一条消息。当缓存满后，发送者继续调用 [crossbeam_channel::Sender::send] 发送消息时会阻塞，直到一个工作线程( 消费者 ) 拿走这条消息 -- 消费者获取消息时先到先得的策略，因此两个工作线程只有一个能取到消息，保证消息不会被重复消费、处理 -- 通过迭代器 [crossbeam_channel::Receiver::iter](https://docs.rs/crossbeam-channel/*/crossbeam_channel/struct.Receiver.html#method.iter) 读取消息会阻塞当前线程，直到新消息的到来或 channel 关闭 -- channel 只有在所有的发送者或消费者关闭后，才能被关闭。而其中一个消费者 `rcv2` 处于阻塞读取状态，无比被关闭，因此我们必须要关闭所有发送者: `drop(snd1);` `drop(snd2)` ，这样 channel 关闭后，主线程的 `rcv2` 才能从阻塞状态退出，最后整个程序结束。大家还是迷惑的话，可以看看这篇[文章](https://course.rs/practice/pitfalls/main-with-channel-blocked.html)。 - -```rust,editable -extern crate crossbeam; -extern crate crossbeam_channel; - -use std::thread; -use std::time::Duration; -use crossbeam_channel::bounded; - -fn main() { - let (snd1, rcv1) = bounded(1); - let (snd2, rcv2) = bounded(1); - let n_msgs = 4; - let n_workers = 2; - - crossbeam::scope(|s| { - // 生产者线程 - s.spawn(|_| { - for i in 0..n_msgs { - snd1.send(i).unwrap(); - println!("Source sent {}", i); - } - - // 关闭其中一个发送者 snd1 - // 该关闭操作对于结束最后的循环是必须的 - drop(snd1); - }); - - // 通过两个线程并行处理 - for _ in 0..n_workers { - // 从数据源接收数据，然后发送到下沉端 - let (sendr, recvr) = (snd2.clone(), rcv1.clone()); - // 生成单独的工作线程 - s.spawn(move |_| { - thread::sleep(Duration::from_millis(500)); - // 等待通道的关闭 - for msg in recvr.iter() { - println!("Worker {:?} received {}.", - thread::current().id(), msg); - sendr.send(msg * 2).unwrap(); - } - }); - } - // 关闭通道，如果不关闭，下沉端将永远无法结束循环 - drop(snd2); - - // 下沉端 - for msg in rcv2.iter() { - println!("Sink received {}", msg); - } - }).unwrap(); -} -``` - - -### 线程间传递数据 - -下面我们来看看 [crossbeam-channel](https://docs.rs/crossbeam-channel/*/crossbeam_channel/index.html) 的单生产者单消费者( SPSC ) 使用场景。 - -```rust,editable -use std::{thread, time}; -use crossbeam_channel::unbounded; - -fn main() { - // unbounded 意味着 channel 可以存储任意多的消息 - let (snd, rcv) = unbounded(); - let n_msgs = 5; - crossbeam::scope(|s| { - s.spawn(|_| { - for i in 0..n_msgs { - snd.send(i).unwrap(); - thread::sleep(time::Duration::from_millis(100)); - } - }); - }).unwrap(); - for _ in 0..n_msgs { - let msg = rcv.recv().unwrap(); - println!("Received {}", msg); - } -} -``` - -### 维护全局可变的状态 - -[lazy_static]() 会创建一个全局的静态引用( static ref )，该引用使用了 `Mutex` 以支持可变性，因此我们可以在代码中对其进行修改。`Mutex` 能保证该全局状态同时只能被一个线程所访问。 - -```rust,editable -use error_chain::error_chain; -use lazy_static::lazy_static; -use std::sync::Mutex; - -error_chain!{ } - -lazy_static! { - static ref FRUIT: Mutex> = Mutex::new(Vec::new()); -} - -fn insert(fruit: &str) -> Result<()> { - let mut db = FRUIT.lock().map_err(|_| "Failed to acquire MutexGuard")?; - db.push(fruit.to_string()); - Ok(()) -} - -fn main() -> Result<()> { - insert("apple")?; - insert("orange")?; - insert("peach")?; - { - let db = FRUIT.lock().map_err(|_| "Failed to acquire MutexGuard")?; - - db.iter().enumerate().for_each(|(i, item)| println!("{}: {}", i, item)); - } - insert("grape")?; - Ok(()) -} -``` - -### 并行计算 iso 文件的 SHA256 - -下面的示例将为当前目录中的每一个 .iso 文件都计算一个 SHA256 sum。其中线程池中会初始化和 CPU 核心数一致的线程数，其中核心数是通过 [num_cpus::get](https://docs.rs/num_cpus/*/num_cpus/fn.get.html) 函数获取。 - -`Walkdir::new` 可以遍历当前的目录，然后调用 `execute` 来执行读操作和 SHA256 哈希计算。 - -```rust,editable - -use walkdir::WalkDir; -use std::fs::File; -use std::io::{BufReader, Read, Error}; -use std::path::Path; -use threadpool::ThreadPool; -use std::sync::mpsc::channel; -use ring::digest::{Context, Digest, SHA256}; - -// Verify the iso extension -fn is_iso(entry: &Path) -> bool { - match entry.extension() { - Some(e) if e.to_string_lossy().to_lowercase() == "iso" => true, - _ => false, - } -} - -fn compute_digest>(filepath: P) -> Result<(Digest, P), Error> { - let mut buf_reader = BufReader::new(File::open(&filepath)?); - let mut context = Context::new(&SHA256); - let mut buffer = [0; 1024]; - - loop { - let count = buf_reader.read(&mut buffer)?; - if count == 0 { - break; - } - context.update(&buffer[..count]); - } - - Ok((context.finish(), filepath)) -} - -fn main() -> Result<(), Error> { - let pool = ThreadPool::new(num_cpus::get()); - - let (tx, rx) = channel(); - - for entry in WalkDir::new("/home/user/Downloads") - .follow_links(true) - .into_iter() - .filter_map(|e| e.ok()) - .filter(|e| !e.path().is_dir() && is_iso(e.path())) { - let path = entry.path().to_owned(); - let tx = tx.clone(); - pool.execute(move || { - let digest = compute_digest(path); - tx.send(digest).expect("Could not send data!"); - }); - } - - drop(tx); - for t in rx.iter() { - let (sha, path) = t?; - println!("{:?} {:?}", sha, path); - } - Ok(()) -} -``` - - -### 使用线程池来绘制分形 - -下面例子中将基于 [Julia Set]() 来绘制一个分形图片，其中使用到了线程池来做分布式计算。 - - - -```rust,edtiable -# use error_chain::error_chain; -use std::sync::mpsc::{channel, RecvError}; -use threadpool::ThreadPool; -use num::complex::Complex; -use image::{ImageBuffer, Pixel, Rgb}; - -# -# error_chain! { -# foreign_links { -# MpscRecv(RecvError); -# Io(std::io::Error); -# } -# } -# -# // Function converting intensity values to RGB -# // Based on http://www.efg2.com/Lab/ScienceAndEngineering/Spectra.htm -# fn wavelength_to_rgb(wavelength: u32) -> Rgb { -# let wave = wavelength as f32; -# -# let (r, g, b) = match wavelength { -# 380..=439 => ((440. - wave) / (440. - 380.), 0.0, 1.0), -# 440..=489 => (0.0, (wave - 440.) / (490. - 440.), 1.0), -# 490..=509 => (0.0, 1.0, (510. - wave) / (510. - 490.)), -# 510..=579 => ((wave - 510.) / (580. - 510.), 1.0, 0.0), -# 580..=644 => (1.0, (645. - wave) / (645. - 580.), 0.0), -# 645..=780 => (1.0, 0.0, 0.0), -# _ => (0.0, 0.0, 0.0), -# }; -# -# let factor = match wavelength { -# 380..=419 => 0.3 + 0.7 * (wave - 380.) / (420. - 380.), -# 701..=780 => 0.3 + 0.7 * (780. - wave) / (780. - 700.), -# _ => 1.0, -# }; -# -# let (r, g, b) = (normalize(r, factor), normalize(g, factor), normalize(b, factor)); -# Rgb::from_channels(r, g, b, 0) -# } -# -# // Maps Julia set distance estimation to intensity values -# fn julia(c: Complex, x: u32, y: u32, width: u32, height: u32, max_iter: u32) -> u32 { -# let width = width as f32; -# let height = height as f32; -# -# let mut z = Complex { -# // scale and translate the point to image coordinates -# re: 3.0 * (x as f32 - 0.5 * width) / width, -# im: 2.0 * (y as f32 - 0.5 * height) / height, -# }; -# -# let mut i = 0; -# for t in 0..max_iter { -# if z.norm() >= 2.0 { -# break; -# } -# z = z * z + c; -# i = t; -# } -# i -# } -# -# // Normalizes color intensity values within RGB range -# fn normalize(color: f32, factor: f32) -> u8 { -# ((color * factor).powf(0.8) * 255.) as u8 -# } - -fn main() -> Result<()> { - let (width, height) = (1920, 1080); - // 为指定宽高的输出图片分配内存 - let mut img = ImageBuffer::new(width, height); - let iterations = 300; - - let c = Complex::new(-0.8, 0.156); - - let pool = ThreadPool::new(num_cpus::get()); - let (tx, rx) = channel(); - - for y in 0..height { - let tx = tx.clone(); - // execute 将每个像素作为单独的作业接收 - pool.execute(move || for x in 0..width { - let i = julia(c, x, y, width, height, iterations); - let pixel = wavelength_to_rgb(380 + i * 400 / iterations); - tx.send((x, y, pixel)).expect("Could not send data!"); - }); - } - - for _ in 0..(width * height) { - let (x, y, pixel) = rx.recv()?; - // 使用数据来设置像素的颜色 - img.put_pixel(x, y, pixel); - } - - // 输出图片内容到指定文件中 - let _ = img.save("output.png")?; - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/compression/tar.md b/src/cookbook/compression/tar.md deleted file mode 100644 index 992d8ddc..00000000 --- a/src/cookbook/compression/tar.md +++ /dev/null @@ -1,77 +0,0 @@ -# 使用tar包 - -## 解压 tar 包 -以下代码将解压缩( [GzDecoder](https://docs.rs/flate2/*/flate2/read/struct.GzDecoder.html) )当前目录中的 `archive.tar.gz` ，并将所有文件抽取出( [Archive::unpack](https://docs.rs/tar/*/tar/struct.Archive.html#method.unpack) )来后当入到当前目录中。 - -```rust,editable -use std::fs::File; -use flate2::read::GzDecoder; -use tar::Archive; - -fn main() -> Result<(), std::io::Error> { - let path = "archive.tar.gz"; - - let tar_gz = File::open(path)?; - let tar = GzDecoder::new(tar_gz); - let mut archive = Archive::new(tar); - archive.unpack(".")?; - - Ok(()) -} -``` - -## 将目录压缩成 tar 包 -以下代码将 `/var/log` 目录压缩成 `archive.tar.gz`: - -- 创建一个 [File](https://doc.rust-lang.org/std/fs/struct.File.html) 文件，并使用 [GzEncoder](https://docs.rs/flate2/*/flate2/write/struct.GzEncoder.html) 和 [tar::Builder](https://docs.rs/tar/*/tar/struct.Builder.html) 对其进行包裹 -- 通过 [Builder::append_dir_all](https://docs.rs/tar/*/tar/struct.Builder.html#method.append_dir_all) 将 `/var/log` 目录下的所有内容添加到压缩文件中，该文件在 `backup/logs` 目录下。 -- [GzEncoder](https://docs.rs/flate2/*/flate2/write/struct.GzEncoder.html) 负责在写入压缩文件 `archive.tar.gz` 之前对数据进行压缩。 - -```rust,editable -use std::fs::File; -use flate2::Compression; -use flate2::write::GzEncoder; - -fn main() -> Result<(), std::io::Error> { - let tar_gz = File::create("archive.tar.gz")?; - let enc = GzEncoder::new(tar_gz, Compression::default()); - let mut tar = tar::Builder::new(enc); - tar.append_dir_all("backup/logs", "/var/log")?; - Ok(()) -} -``` - -## 解压的同时删除指定的文件前缀 -遍历目录中的文件 [Archive::entries](https://docs.rs/tar/*/tar/struct.Archive.html#method.entries)，若解压前的文件名包含 `bundle/logs` 前缀，需要将前缀从文件名移除( [Path::strip_prefix](https://doc.rust-lang.org/std/path/struct.Path.html#method.strip_prefix) )后，再解压。 - - - -```rust,editable -use std::fs::File; -use std::path::PathBuf; -use flate2::read::GzDecoder; -use tar::Archive; - -fn main() -> Result<()> { - let file = File::open("archive.tar.gz")?; - let mut archive = Archive::new(GzDecoder::new(file)); - let prefix = "bundle/logs"; - - println!("Extracted the following files:"); - archive - .entries()? // 获取压缩档案中的文件条目列表 - .filter_map(|e| e.ok()) - // 对每个文件条目进行 map 处理 - .map(|mut entry| -> Result { - // 将文件路径名中的前缀移除，获取一个新的路径名 - let path = entry.path()?.strip_prefix(prefix)?.to_owned(); - // 将内容解压到新的路径名中 - entry.unpack(&path)?; - Ok(path) - }) - .filter_map(|e| e.ok()) - .for_each(|x| println!("> {}", x.display())); - - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/config.md b/src/cookbook/config.md deleted file mode 100644 index 33eb3d73..00000000 --- a/src/cookbook/config.md +++ /dev/null @@ -1 +0,0 @@ -# 配置文件 todo diff --git a/src/cookbook/crypto.md b/src/cookbook/crypto.md deleted file mode 100644 index f9455099..00000000 --- a/src/cookbook/crypto.md +++ /dev/null @@ -1 +0,0 @@ -# 加密解密 todo diff --git a/src/cookbook/cryptography/encryption.md b/src/cookbook/cryptography/encryption.md deleted file mode 100644 index becab266..00000000 --- a/src/cookbook/cryptography/encryption.md +++ /dev/null @@ -1,57 +0,0 @@ -# 加密 - -### 使用 PBKDF2 对密码进行哈希和加盐( salt ) -[ring::pbkdf2](https://briansmith.org/rustdoc/ring/pbkdf2/index.html) 可以对一个加盐密码进行哈希。 - -```rust,editable - -use data_encoding::HEXUPPER; -use ring::error::Unspecified; -use ring::rand::SecureRandom; -use ring::{digest, pbkdf2, rand}; -use std::num::NonZeroU32; - -fn main() -> Result<(), Unspecified> { - const CREDENTIAL_LEN: usize = digest::SHA512_OUTPUT_LEN; - let n_iter = NonZeroU32::new(100_000).unwrap(); - let rng = rand::SystemRandom::new(); - - let mut salt = [0u8; CREDENTIAL_LEN]; - // 生成 salt: 将安全生成的随机数填入到字节数组中 - rng.fill(&mut salt)?; - - let password = "Guess Me If You Can!"; - let mut pbkdf2_hash = [0u8; CREDENTIAL_LEN]; - pbkdf2::derive( - pbkdf2::PBKDF2_HMAC_SHA512, - n_iter, - &salt, - password.as_bytes(), - &mut pbkdf2_hash, - ); - println!("Salt: {}", HEXUPPER.encode(&salt)); - println!("PBKDF2 hash: {}", HEXUPPER.encode(&pbkdf2_hash)); - - // `verify` 检查哈希是否正确 - let should_`succeed = pbkdf2::verify( - pbkdf2::PBKDF2_HMAC_SHA512, - n_iter, - &salt, - password.as_bytes(), - &pbkdf2_hash, - ); - let wrong_password = "Definitely not the correct password"; - let should_fail = pbkdf2::verify( - pbkdf2::PBKDF2_HMAC_SHA512, - n_iter, - &salt, - wrong_password.as_bytes(), - &pbkdf2_hash, - ); - - assert!(should_succeed.is_ok()); - assert!(!should_fail.is_ok()); - - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/cryptography/hashing.md b/src/cookbook/cryptography/hashing.md deleted file mode 100644 index 60a697c0..00000000 --- a/src/cookbook/cryptography/hashing.md +++ /dev/null @@ -1,71 +0,0 @@ -# 哈希 - -### 计算文件的 SHA-256 摘要 -写入一些数据到文件中，然后使用 [digest::Context](https://briansmith.org/rustdoc/ring/digest/struct.Context.html) 来计算文件内容的 SHA-256 摘要 [digest::Digest](https://briansmith.org/rustdoc/ring/digest/struct.Digest.html)。 - -```rust,editable -# use error_chain::error_chain; -use data_encoding::HEXUPPER; -use ring::digest::{Context, Digest, SHA256}; -use std::fs::File; -use std::io::{BufReader, Read, Write}; - -# error_chain! { -# foreign_links { -# Io(std::io::Error); -# Decode(data_encoding::DecodeError); -# } -# } - -fn sha256_digest(mut reader: R) -> Result { - let mut context = Context::new(&SHA256); - let mut buffer = [0; 1024]; - - loop { - let count = reader.read(&mut buffer)?; - if count == 0 { - break; - } - context.update(&buffer[..count]); - } - - Ok(context.finish()) -} - -fn main() -> Result<()> { - let path = "file.txt"; - - let mut output = File::create(path)?; - write!(output, "We will generate a digest of this text")?; - - let input = File::open(path)?; - let reader = BufReader::new(input); - let digest = sha256_digest(reader)?; - - println!("SHA-256 digest is {}", HEXUPPER.encode(digest.as_ref())); - - Ok(()) -} -``` - -### 使用 HMAC 摘要来签名和验证消息 -使用 [ring::hmac](https://briansmith.org/rustdoc/ring/hmac/) 创建一个字符串签名并检查该签名的正确性。 - -```rust,editable -use ring::{hmac, rand}; -use ring::rand::SecureRandom; -use ring::error::Unspecified; - -fn main() -> Result<(), Unspecified> { - let mut key_value = [0u8; 48]; - let rng = rand::SystemRandom::new(); - rng.fill(&mut key_value)?; - let key = hmac::Key::new(hmac::HMAC_SHA256, &key_value); - - let message = "Legitimate and important message."; - let signature = hmac::sign(&key, message.as_bytes()); - hmac::verify(&key, message.as_bytes(), signature.as_ref())?; - - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/database.md b/src/cookbook/database.md deleted file mode 100644 index de785679..00000000 --- a/src/cookbook/database.md +++ /dev/null @@ -1 +0,0 @@ -# 数据库访问 todo diff --git a/src/cookbook/database/postgres.md b/src/cookbook/database/postgres.md deleted file mode 100644 index 13bd37dd..00000000 --- a/src/cookbook/database/postgres.md +++ /dev/null @@ -1,123 +0,0 @@ -# Postgres - -### 在数据库中创建表格 -我们通过 [postgres](https://docs.rs/postgres/0.17.2/postgres/) 来操作数据库。下面的例子有一个前提：数据库 `library` 已经存在，其中用户名和密码都是 `postgres`。 - -```rust,editable -use postgres::{Client, NoTls, Error}; - -fn main() -> Result<(), Error> { - // 连接到数据库 library - let mut client = Client::connect("postgresql://postgres:postgres@localhost/library", NoTls)?; - - client.batch_execute(" - CREATE TABLE IF NOT EXISTS author ( - id SERIAL PRIMARY KEY, - name VARCHAR NOT NULL, - country VARCHAR NOT NULL - ) - ")?; - - client.batch_execute(" - CREATE TABLE IF NOT EXISTS book ( - id SERIAL PRIMARY KEY, - title VARCHAR NOT NULL, - author_id INTEGER NOT NULL REFERENCES author - ) - ")?; - - Ok(()) - -} -``` - -### 插入和查询 - -```rust,editable -use postgres::{Client, NoTls, Error}; -use std::collections::HashMap; - -struct Author { - _id: i32, - name: String, - country: String -} - -fn main() -> Result<(), Error> { - let mut client = Client::connect("postgresql://postgres:postgres@localhost/library", - NoTls)?; - - let mut authors = HashMap::new(); - authors.insert(String::from("Chinua Achebe"), "Nigeria"); - authors.insert(String::from("Rabindranath Tagore"), "India"); - authors.insert(String::from("Anita Nair"), "India"); - - for (key, value) in &authors { - let author = Author { - _id: 0, - name: key.to_string(), - country: value.to_string() - }; - - // 插入数据 - client.execute( - "INSERT INTO author (name, country) VALUES ($1, $2)", - &[&author.name, &author.country], - )?; - } - - // 查询数据 - for row in client.query("SELECT id, name, country FROM author", &[])? { - let author = Author { - _id: row.get(0), - name: row.get(1), - country: row.get(2), - }; - println!("Author {} is from {}", author.name, author.country); - } - - Ok(()) - -} -``` - -### 聚合数据 - -下面代码将使用降序的方式列出 [Museum of Modern Art]() 数据库中的前 7999 名艺术家的国籍分布. - -```rust,editable -use postgres::{Client, Error, NoTls}; - -struct Nation { - nationality: String, - count: i64, -} - -fn main() -> Result<(), Error> { - let mut client = Client::connect( - "postgresql://postgres:postgres@127.0.0.1/moma", - NoTls, - )?; - - for row in client.query - ("SELECT nationality, COUNT(nationality) AS count - FROM artists GROUP BY nationality ORDER BY count DESC", &[])? { - - let (nationality, count) : (Option, Option) - = (row.get (0), row.get (1)); - - if nationality.is_some () && count.is_some () { - - let nation = Nation{ - nationality: nationality.unwrap(), - count: count.unwrap(), - }; - println!("{} {}", nation.nationality, nation.count); - - } - } - - Ok(()) -} -``` - diff --git a/src/cookbook/database/sqlite.md b/src/cookbook/database/sqlite.md deleted file mode 100644 index 0872fbf2..00000000 --- a/src/cookbook/database/sqlite.md +++ /dev/null @@ -1,136 +0,0 @@ -# SQLite - -### 创建 SQLite 数据库 - -使用 `rusqlite` 可以创建 SQLite 数据库，[Connection::open](https://docs.rs/rusqlite/*/rusqlite/struct.Connection.html#method.open) 会尝试打开一个数据库，若不存在，则创建新的数据库。 - -> 这里创建的 `cats.db` 数据库将被后面的例子所使用 - - -```rust,editable -use rusqlite::{Connection, Result}; -use rusqlite::NO_PARAMS; - -fn main() -> Result<()> { - let conn = Connection::open("cats.db")?; - - conn.execute( - "create table if not exists cat_colors ( - id integer primary key, - name text not null unique - )", - NO_PARAMS, - )?; - conn.execute( - "create table if not exists cats ( - id integer primary key, - name text not null, - color_id integer not null references cat_colors(id) - )", - NO_PARAMS, - )?; - - Ok(()) -} -``` - -### 插入和查询 - -```rust,editable - -use rusqlite::NO_PARAMS; -use rusqlite::{Connection, Result}; -use std::collections::HashMap; - -#[derive(Debug)] -struct Cat { - name: String, - color: String, -} - -fn main() -> Result<()> { - // 打开第一个例子所创建的数据库 - let conn = Connection::open("cats.db")?; - - let mut cat_colors = HashMap::new(); - cat_colors.insert(String::from("Blue"), vec!["Tigger", "Sammy"]); - cat_colors.insert(String::from("Black"), vec!["Oreo", "Biscuit"]); - - for (color, catnames) in &cat_colors { - // 插入一条数据行 - conn.execute( - "INSERT INTO cat_colors (name) values (?1)", - &[&color.to_string()], - )?; - // 获取最近插入数据行的 id - let last_id: String = conn.last_insert_rowid().to_string(); - - for cat in catnames { - conn.execute( - "INSERT INTO cats (name, color_id) values (?1, ?2)", - &[&cat.to_string(), &last_id], - )?; - } - } - let mut stmt = conn.prepare( - "SELECT c.name, cc.name from cats c - INNER JOIN cat_colors cc - ON cc.id = c.color_id;", - )?; - - let cats = stmt.query_map(NO_PARAMS, |row| { - Ok(Cat { - name: row.get(0)?, - color: row.get(1)?, - }) - })?; - - for cat in cats { - println!("Found cat {:?}", cat); - } - - Ok(()) -} -``` - -### 使用事务 -使用 [Connection::transaction](https://docs.rs/rusqlite/*/rusqlite/struct.Connection.html#method.transaction) 可以开始新的事务，若没有对事务进行显式地提交 [Transaction::commit](https://docs.rs/rusqlite/0.27.0/rusqlite/struct.Transaction.html#method.commit)，则会进行回滚。 - -下面的例子中，`rolled_back_tx` 插入了重复的颜色名称，会发生回滚。 - -```rust,editable -use rusqlite::{Connection, Result, NO_PARAMS}; - -fn main() -> Result<()> { - // 打开第一个例子所创建的数据库 - let mut conn = Connection::open("cats.db")?; - - successful_tx(&mut conn)?; - - let res = rolled_back_tx(&mut conn); - assert!(res.is_err()); - - Ok(()) -} - -fn successful_tx(conn: &mut Connection) -> Result<()> { - let tx = conn.transaction()?; - - tx.execute("delete from cat_colors", NO_PARAMS)?; - tx.execute("insert into cat_colors (name) values (?1)", &[&"lavender"])?; - tx.execute("insert into cat_colors (name) values (?1)", &[&"blue"])?; - - tx.commit() -} - -fn rolled_back_tx(conn: &mut Connection) -> Result<()> { - let tx = conn.transaction()?; - - tx.execute("delete from cat_colors", NO_PARAMS)?; - tx.execute("insert into cat_colors (name) values (?1)", &[&"lavender"])?; - tx.execute("insert into cat_colors (name) values (?1)", &[&"blue"])?; - tx.execute("insert into cat_colors (name) values (?1)", &[&"lavender"])?; - - tx.commit() -} -``` \ No newline at end of file diff --git a/src/cookbook/datastructures/bitfield.md b/src/cookbook/datastructures/bitfield.md deleted file mode 100644 index 4c9c29e0..00000000 --- a/src/cookbook/datastructures/bitfield.md +++ /dev/null @@ -1,47 +0,0 @@ -# 位字段 - -### 定义和操作位字段 -使用 [`bitflags!`](https://docs.rs/bitflags/1.3.2/bitflags/macro.bitflags.html) 宏可以帮助我们创建安全的位字段类型 `MyFlags`，然后为其实现基本的 `clear` 操作。以下代码展示了基本的位操作和格式化: -```rust,editable -use bitflags::bitflags; -use std::fmt; - -bitflags! { - struct MyFlags: u32 { - const FLAG_A = 0b00000001; - const FLAG_B = 0b00000010; - const FLAG_C = 0b00000100; - const FLAG_ABC = Self::FLAG_A.bits - | Self::FLAG_B.bits - | Self::FLAG_C.bits; - } -} - -impl MyFlags { - pub fn clear(&mut self) -> &mut MyFlags { - self.bits = 0; - self - } -} - -impl fmt::Display for MyFlags { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - write!(f, "{:032b}", self.bits) - } -} - -fn main() { - let e1 = MyFlags::FLAG_A | MyFlags::FLAG_C; - let e2 = MyFlags::FLAG_B | MyFlags::FLAG_C; - assert_eq!((e1 | e2), MyFlags::FLAG_ABC); - assert_eq!((e1 & e2), MyFlags::FLAG_C); - assert_eq!((e1 - e2), MyFlags::FLAG_A); - assert_eq!(!e2, MyFlags::FLAG_A); - - let mut flags = MyFlags::FLAG_ABC; - assert_eq!(format!("{}", flags), "00000000000000000000000000000111"); - assert_eq!(format!("{}", flags.clear()), "00000000000000000000000000000000"); - assert_eq!(format!("{:?}", MyFlags::FLAG_B), "FLAG_B"); - assert_eq!(format!("{:?}", MyFlags::FLAG_A | MyFlags::FLAG_B), "FLAG_A | FLAG_B"); -} -``` \ No newline at end of file diff --git a/src/cookbook/date.md b/src/cookbook/date.md deleted file mode 100644 index a434528a..00000000 --- a/src/cookbook/date.md +++ /dev/null @@ -1 +0,0 @@ -# 时间日期 diff --git a/src/cookbook/datetime/duration.md b/src/cookbook/datetime/duration.md deleted file mode 100644 index 4f14bff9..00000000 --- a/src/cookbook/datetime/duration.md +++ /dev/null @@ -1,69 +0,0 @@ -# 时间计算和转换 - -### 测量某段代码的耗时 -测量从 [time::Instant::now](https://doc.rust-lang.org/std/time/struct.Instant.html#method.now) 开始所经过的时间 [time::Instant::elapsed](https://doc.rust-lang.org/std/time/struct.Instant.html#method.elapsed). - -```rust,editable -use std::time::{Duration, Instant}; - -fn main() { - let start = Instant::now(); - expensive_function(); - let duration = start.elapsed(); - - println!("Time elapsed in expensive_function() is: {:?}", duration); -} -``` - -### 对日期和时间进行计算 -使用 [DateTime::checked_add_signed](https://docs.rs/chrono/*/chrono/struct.Date.html#method.checked_add_signed) 计算和显示从现在开始两周后的日期和时间，然后再计算一天前的日期 [DateTime::checked_sub_signed](https://docs.rs/chrono/*/chrono/struct.Date.html#method.checked_sub_signed)。 - -[DateTime::format](https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.format) 所支持的转义序列可以在 [chrono::format::strftime](https://docs.rs/chrono/*/chrono/format/strftime/index.html) 找到. - -```rust,editable -use chrono::{DateTime, Duration, Utc}; - -fn day_earlier(date_time: DateTime) -> Option> { - date_time.checked_sub_signed(Duration::days(1)) -} - -fn main() { - let now = Utc::now(); - println!("{}", now); - - let almost_three_weeks_from_now = now.checked_add_signed(Duration::weeks(2)) - .and_then(|in_2weeks| in_2weeks.checked_add_signed(Duration::weeks(1))) - .and_then(day_earlier); - - match almost_three_weeks_from_now { - Some(x) => println!("{}", x), - None => eprintln!("Almost three weeks from now overflows!"), - } - - match now.checked_add_signed(Duration::max_value()) { - Some(x) => println!("{}", x), - None => eprintln!("We can't use chrono to tell the time for the Solar System to complete more than one full orbit around the galactic center."), - } -} -``` - -### 将本地时间转换成其它时区 -使用 [offset::Local::now](https://docs.rs/chrono/*/chrono/offset/struct.Local.html#method.now) 获取本地时间并进行显示，接着，使用 [DateTime::from_utc](https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.from_utc) 将它转换成 UTC 标准时间。最后，再使用 [offset::FixedOffset](https://docs.rs/chrono/*/chrono/offset/struct.FixedOffset.html) 将 UTC 时间转换成 UTC+8 和 UTC-2 的时间。 - -```rust,editable -use chrono::{DateTime, FixedOffset, Local, Utc}; - -fn main() { - let local_time = Local::now(); - let utc_time = DateTime::::from_utc(local_time.naive_utc(), Utc); - let china_timezone = FixedOffset::east(8 * 3600); - let rio_timezone = FixedOffset::west(2 * 3600); - println!("Local time now is {}", local_time); - println!("UTC time now is {}", utc_time); - println!( - "Time in Hong Kong now is {}", - utc_time.with_timezone(&china_timezone) - ); - println!("Time in Rio de Janeiro now is {}", utc_time.with_timezone(&rio_timezone)); -} -``` \ No newline at end of file diff --git a/src/cookbook/datetime/parsing.md b/src/cookbook/datetime/parsing.md deleted file mode 100644 index aee55576..00000000 --- a/src/cookbook/datetime/parsing.md +++ /dev/null @@ -1,114 +0,0 @@ -# 解析和显示 - -### 检查日期和时间 -通过 [DateTime](https://docs.rs/chrono/*/chrono/struct.DateTime.html) 获取当前的 UTC 时间: -- [Timelike](https://docs.rs/chrono/*/chrono/trait.Timelike.html), 时/分/秒 -- [Datelike](https://docs.rs/chrono/*/chrono/trait.Datelike.html), 年/月/日 - -```rust,editable -use chrono::{Datelike, Timelike, Utc}; - -fn main() { - let now = Utc::now(); - - let (is_pm, hour) = now.hour12(); - println!( - "The current UTC time is {:02}:{:02}:{:02} {}", - hour, - now.minute(), - now.second(), - if is_pm { "PM" } else { "AM" } - ); - println!( - "And there have been {} seconds since midnight", - now.num_seconds_from_midnight() - ); - - let (is_common_era, year) = now.year_ce(); - println!( - "The current UTC date is {}-{:02}-{:02} {:?} ({})", - year, - now.month(), - now.day(), - now.weekday(), - if is_common_era { "CE" } else { "BCE" } - ); - println!( - "And the Common Era began {} days ago", - now.num_days_from_ce() - ); -} -``` - -### 日期和时间戳的相互转换 - -```rust,editable -use chrono::{NaiveDate, NaiveDateTime}; - -fn main() { - // 生成一个具体的日期时间 - let date_time: NaiveDateTime = NaiveDate::from_ymd(2017, 11, 12).and_hms(17, 33, 44); - println!( - "Number of seconds between 1970-01-01 00:00:00 and {} is {}.", - // 打印日期和日期对应的时间戳 - date_time, date_time.timestamp()); - - // 计算从 1970 1月1日 0:00:00 UTC 开始，10亿秒后是什么日期时间 - let date_time_after_a_billion_seconds = NaiveDateTime::from_timestamp(1_000_000_000, 0); - println!( - "Date after a billion seconds since 1970-01-01 00:00:00 was {}.", - date_time_after_a_billion_seconds); -} -``` - -### 显示格式化的日期和时间 -通过 [Utc::now](https://docs.rs/chrono/*/chrono/offset/struct.Utc.html#method.now) 可以获取当前的 UTC 时间。 - -```rust,editable -use chrono::{DateTime, Utc}; - -fn main() { - let now: DateTime = Utc::now(); - - println!("UTC now is: {}", now); - // 使用 RFC 2822 格式显示当前时间 - println!("UTC now in RFC 2822 is: {}", now.to_rfc2822()); - // 使用 RFC 3339 格式显示当前时间 - println!("UTC now in RFC 3339 is: {}", now.to_rfc3339()); - // 使用自定义格式显示当前时间 - println!("UTC now in a custom format is: {}", now.format("%a %b %e %T %Y")); -} -``` - -### 将字符串解析为 DateTime 结构体 -我们可以将多种格式的日期时间字符串转换成 [DateTime](https://docs.rs/chrono/*/chrono/struct.DateTime.html) 结构体。[DateTime::parse_from_str](https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_str) 使用的转义序列可以在 [chrono::format::strftime](https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html) 找到. - -只有当能唯一的标识出日期和时间时，才能创建 `DateTime`。如果要在没有时区的情况下解析日期或时间，你需要使用 [`NativeDate`](https://docs.rs/chrono/*/chrono/naive/struct.NaiveDate.html) 等函数。 - -```rust,editable -use chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime}; -use chrono::format::ParseError; - - -fn main() -> Result<(), ParseError> { - let rfc2822 = DateTime::parse_from_rfc2822("Tue, 1 Jul 2003 10:52:37 +0200")?; - println!("{}", rfc2822); - - let rfc3339 = DateTime::parse_from_rfc3339("1996-12-19T16:39:57-08:00")?; - println!("{}", rfc3339); - - let custom = DateTime::parse_from_str("5.8.1994 8:00 am +0000", "%d.%m.%Y %H:%M %P %z")?; - println!("{}", custom); - - let time_only = NaiveTime::parse_from_str("23:56:04", "%H:%M:%S")?; - println!("{}", time_only); - - let date_only = NaiveDate::parse_from_str("2015-09-05", "%Y-%m-%d")?; - println!("{}", date_only); - - let no_timezone = NaiveDateTime::parse_from_str("2015-09-05 23:56:04", "%Y-%m-%d %H:%M:%S")?; - println!("{}", no_timezone); - - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/dev/intro.md b/src/cookbook/dev/intro.md deleted file mode 100644 index f0cc50f0..00000000 --- a/src/cookbook/dev/intro.md +++ /dev/null @@ -1 +0,0 @@ -# 开发调试 diff --git a/src/cookbook/dev/logs.md b/src/cookbook/dev/logs.md deleted file mode 100644 index 65c2dbdd..00000000 --- a/src/cookbook/dev/logs.md +++ /dev/null @@ -1 +0,0 @@ -# 日志 diff --git a/src/cookbook/dev/profile.md b/src/cookbook/dev/profile.md deleted file mode 100644 index 124678e8..00000000 --- a/src/cookbook/dev/profile.md +++ /dev/null @@ -1 +0,0 @@ -# 性能分析 diff --git a/src/cookbook/devtools/build-tools.md b/src/cookbook/devtools/build-tools.md deleted file mode 100644 index b3bdc6ad..00000000 --- a/src/cookbook/devtools/build-tools.md +++ /dev/null @@ -1,192 +0,0 @@ -# 构建时工具 -本章节的内容是关于构建工具的，如果大家没有听说过 `build.rs` 文件，强烈建议先看看[这里](https://course.rs/cargo/reference/build-script/intro.html)了解下何为构建工具。 - -### 编译并静态链接一个 C 库 - -[cc](https://docs.rs/cc/latest/cc/) 包能帮助我们更好地跟 C/C++/汇编进行交互：它提供了简单的 API 可以将外部的库编译成静态库( .a )，然后通过 `rustc` 进行静态链接。 - -下面的例子中，我们将在 Rust 代码中使用 C 的代码: *src/hello.c*。在开始编译 Rust 的项目代码前，`build.rs` 构建脚本将先被执行。通过 cc 包，一个静态的库可以被生成( *libhello.a* ),然后该库将被 Rust的代码所使用：通过 `extern` 声明外部函数签名的方式来使用。 - -由于例子中的 C 代码很简单，因此只需要将一个文件传递给 [cc::Build](https://docs.rs/cc/*/cc/struct.Build.html)。如果大家需要更复杂的构建，`cc::Build` 还提供了通过 [include](https://docs.rs/cc/*/cc/struct.Build.html#method.include) 来包含路径的方式，以及额外的编译标志( [flags](https://docs.rs/cc/1.0.73/cc/struct.Build.html#method.flag) )。 - -*Cargo.toml* - -```toml -[package] -... -build = "build.rs" - -[build-dependencies] -cc = "1" - -[dependencies] -error-chain = "0.11" -``` - -*build.rs* - -```rust -fn main() { - cc::Build::new() - .file("src/hello.c") - .compile("hello"); // outputs `libhello.a` -} -``` - -*src/hello.c* - -```C -#include - - -void hello() { - printf("Hello from C!\n"); -} - -void greet(const char* name) { - printf("Hello, %s!\n", name); -} -``` - -*src/main.rs* - -```rust -use error_chain::error_chain; -use std::ffi::CString; -use std::os::raw::c_char; - -error_chain! { - foreign_links { - NulError(::std::ffi::NulError); - Io(::std::io::Error); - } -} -fn prompt(s: &str) -> Result { - use std::io::Write; - print!("{}", s); - std::io::stdout().flush()?; - let mut input = String::new(); - std::io::stdin().read_line(&mut input)?; - Ok(input.trim().to_string()) -} - -extern { - fn hello(); - fn greet(name: *const c_char); -} - -fn main() -> Result<()> { - unsafe { hello() } - let name = prompt("What's your name? ")?; - let c_name = CString::new(name)?; - unsafe { greet(c_name.as_ptr()) } - Ok(()) -} -``` - -### 编译并静态链接一个 C++ 库 -链接到 C++ 库跟之前的方式非常相似。主要的区别在于链接到 C++ 库时，你需要通过构建方法 [cpp(true)](https://docs.rs/cc/*/cc/struct.Build.html#method.cpp) 来指定一个 C++ 编译器，然后在 C++ 的代码顶部添加 `extern "C"` 来阻止 C++ 编译器对库名进行名称重整( name mangling )。 - -*Cargo.toml* - -```toml -[package] -... -build = "build.rs" - -[build-dependencies] -cc = "1" -``` - -*build.rs* - -```rust -fn main() { - cc::Build::new() - .cpp(true) - .file("src/foo.cpp") - .compile("foo"); -} -``` - -*src/foo.cpp* - -```c++ -extern "C" { - int multiply(int x, int y); -} - -int multiply(int x, int y) { - return x*y; -} -``` - -*src/main.rs* - -```rust -extern { - fn multiply(x : i32, y : i32) -> i32; -} - -fn main(){ - unsafe { - println!("{}", multiply(5,7)); - } -} -``` - -### 为 C 库创建自定义的 define - -[cc::Build::define](https://docs.rs/cc/*/cc/struct.Build.html#method.define) 可以让我们使用自定义的 define 来构建 C 库。 - -以下示例在构建脚本 `build.rs` 中动态定义了一个 define，然后在运行时打印出 **Welcome to foo - version 1.0.2**。Cargo 会设置一些[环境变量](https://doc.rust-lang.org/cargo/reference/environment-variables.html)，它们对于自定义的 define 会有所帮助。 - -*Cargo.toml* - -```toml -[package] -... -version = "1.0.2" -build = "build.rs" - -[build-dependencies] -cc = "1" -``` - -*build.rs* -```rust -fn main() { - cc::Build::new() - .define("APP_NAME", "\"foo\"") - .define("VERSION", format!("\"{}\"", env!("CARGO_PKG_VERSION")).as_str()) - .define("WELCOME", None) - .file("src/foo.c") - .compile("foo"); -} -``` - -*src/foo.c* -```C -#include - -void print_app_info() { -#ifdef WELCOME - printf("Welcome to "); -#endif - printf("%s - version %s\n", APP_NAME, VERSION); -} -``` - -*src/main.rs* -```rust -extern { - fn print_app_info(); -} - -fn main(){ - unsafe { - print_app_info(); - } -} -``` - diff --git a/src/cookbook/devtools/config-log.md b/src/cookbook/devtools/config-log.md deleted file mode 100644 index 1121571f..00000000 --- a/src/cookbook/devtools/config-log.md +++ /dev/null @@ -1,140 +0,0 @@ -# 配置日志 - -### 为每个模块开启独立的日志级别 -下面代码创建了模块 `foo` 和嵌套模块 `foo::bar`，并通过 [RUST_LOG](https://docs.rs/env_logger/*/env_logger/#enabling-logging) 环境变量对各自的日志级别进行了控制。 - -```rust,editable -mod foo { - mod bar { - pub fn run() { - log::warn!("[bar] warn"); - log::info!("[bar] info"); - log::debug!("[bar] debug"); - } - } - - pub fn run() { - log::warn!("[foo] warn"); - log::info!("[foo] info"); - log::debug!("[foo] debug"); - bar::run(); - } -} - -fn main() { - env_logger::init(); - log::warn!("[root] warn"); - log::info!("[root] info"); - log::debug!("[root] debug"); - foo::run(); -} -``` - -要让环境变量生效，首先需要通过 `env_logger::init()` 开启相关的支持。然后通过以下命令来运行程序: -```shell -RUST_LOG="warn,test::foo=info,test::foo::bar=debug" ./test -``` - -此时的默认日志级别被设置为 `warn`，但我们还将 `foo` 模块级别设置为 `info`, `foo::bar` 模块日志级别设置为 `debug`。 - -```bash -WARN:test: [root] warn -WARN:test::foo: [foo] warn -INFO:test::foo: [foo] info -WARN:test::foo::bar: [bar] warn -INFO:test::foo::bar: [bar] info -DEBUG:test::foo::bar: [bar] debug -``` - -### 使用自定义环境变量来设置日志 - -[Builder](https://docs.rs/env_logger/*/env_logger/struct.Builder.html) 将对日志进行配置，以下代码使用 `MY_APP_LOG` 来替代 `RUST_LOG` 环境变量: - -```rust,editable -use std::env; -use env_logger::Builder; - -fn main() { - Builder::new() - .parse(&env::var("MY_APP_LOG").unwrap_or_default()) - .init(); - - log::info!("informational message"); - log::warn!("warning message"); - log::error!("this is an error {}", "message"); -} -``` - -### 在日志中包含时间戳 - -```rust,editable -use std::io::Write; -use chrono::Local; -use env_logger::Builder; -use log::LevelFilter; - -fn main() { - Builder::new() - .format(|buf, record| { - writeln!(buf, - "{} [{}] - {}", - Local::now().format("%Y-%m-%dT%H:%M:%S"), - record.level(), - record.args() - ) - }) - .filter(None, LevelFilter::Info) - .init(); - - log::warn!("warn"); - log::info!("info"); - log::debug!("debug"); -} -``` - -以下是 `stderr` 的输出: -```shell -2022-03-22T21:57:06 [WARN] - warn -2022-03-22T21:57:06 [INFO] - info -``` - -### 将日志输出到指定文件 -[log4rs](https://docs.rs/log4rs/) 可以帮我们将日志输出指定的位置，它可以使用外部 YAML 文件或 `builder` 的方式进行配置。 - -```rust,editable -# use error_chain::error_chain; - -use log::LevelFilter; -use log4rs::append::file::FileAppender; -use log4rs::encode::pattern::PatternEncoder; -use log4rs::config::{Appender, Config, Root}; - -#error_chain! { -# foreign_links { -# Io(std::io::Error); -# LogConfig(log4rs::config::Errors); -# SetLogger(log::SetLoggerError); -# } -#} - -fn main() -> Result<()> { - // 创建日志配置，并指定输出的位置 - let logfile = FileAppender::builder() - // 编码模式的详情参见: https://docs.rs/log4rs/1.0.0/log4rs/encode/pattern/index.html - .encoder(Box::new(PatternEncoder::new("{l} - {m}\n"))) - .build("log/output.log")?; - - let config = Config::builder() - .appender(Appender::builder().build("logfile", Box::new(logfile))) - .build(Root::builder() - .appender("logfile") - .build(LevelFilter::Info))?; - - log4rs::init_config(config)?; - - log::info!("Hello, world!"); - - Ok(()) -} - -``` \ No newline at end of file diff --git a/src/cookbook/devtools/log.md b/src/cookbook/devtools/log.md deleted file mode 100644 index adc6616a..00000000 --- a/src/cookbook/devtools/log.md +++ /dev/null @@ -1,127 +0,0 @@ -# 日志 - -## log 包 -[log](https://docs.rs/crate/log/0.4.16) 提供了日志相关的实用工具。 - -### 在控制台打印 debug 信息 -`env_logger` 通过环境变量来配置日志。[log::debug!](https://docs.rs/log/0.4.16/log/macro.debug.html) 使用起来跟 [std::fmt](https://doc.rust-lang.org/std/fmt/) 中的格式化字符串很像。 - -```rust -fn execute_query(query: &str) { - log::debug!("Executing query: {}", query); -} - -fn main() { - env_logger::init(); - - execute_query("DROP TABLE students"); -} -``` - -如果大家运行代码，会发现没有任何日志输出，原因是默认的日志级别是 `error`，因此我们需要通过 `RUST_LOG` 环境变量来设置下新的日志级别： -```shell -$ RUST_LOG=debug cargo run -``` - -然后你将成功看到以下输出: -```shell -DEBUG:main: Executing query: DROP TABLE students -``` - -### 将错误日志输出到控制台 -下面我们通过 [log::error!](https://docs.rs/log/0.4.16/log/macro.error.html) 将错误日志输出到标准错误 `stderr`。 - -```rust -fn execute_query(_query: &str) -> Result<(), &'static str> { - Err("I'm afraid I can't do that") -} - -fn main() { - env_logger::init(); - - let response = execute_query("DROP TABLE students"); - if let Err(err) = response { - log::error!("Failed to execute query: {}", err); - } -} -``` - -### 将错误输出到标准输出 stdout -默认的错误会输出到标准错误输出 `stderr`，下面我们通过自定的配置来让错误输出到标准输出 `stdout`。 - -```rust,editable -use env_logger::{Builder, Target}; - -fn main() { - Builder::new() - .target(Target::Stdout) - .init(); - - log::error!("This error has been printed to Stdout"); -} -``` - -### 使用自定义 logger -下面的代码将实现一个自定义 logger `ConsoleLogger`，输出到标准输出 `stdout`。为了使用日志宏，`ConsoleLogger` 需要实现 [log::Log](https://docs.rs/log/*/log/trait.Log.html) 特征，然后使用 [log::set_logger](https://docs.rs/log/*/log/fn.set_logger.html) 来安装使用。 - -```rust,editable -use log::{Record, Level, Metadata, LevelFilter, SetLoggerError}; - -static CONSOLE_LOGGER: ConsoleLogger = ConsoleLogger; - -struct ConsoleLogger; - -impl log::Log for ConsoleLogger { - fn enabled(&self, metadata: &Metadata) -> bool { - metadata.level() <= Level::Info - } - - fn log(&self, record: &Record) { - if self.enabled(record.metadata()) { - println!("Rust says: {} - {}", record.level(), record.args()); - } - } - - fn flush(&self) {} -} - -fn main() -> Result<(), SetLoggerError> { - log::set_logger(&CONSOLE_LOGGER)?; - log::set_max_level(LevelFilter::Info); - - log::info!("hello log"); - log::warn!("warning"); - log::error!("oops"); - Ok(()) -} -``` - -### 输出到 Unix syslog -下面的代码将使用 [syslog](https://docs.rs/crate/syslog/6.0.1) 包将日志输出到 [Unix Syslog](https://www.gnu.org/software/libc/manual/html_node/Overview-of-Syslog.html). - -```rust,editable -#[cfg(target_os = "linux")] -#[cfg(target_os = "linux")] -use syslog::{Facility, Error}; - -#[cfg(target_os = "linux")] -fn main() -> Result<(), Error> { - // 初始化 logger - syslog::init(Facility::LOG_USER, - log::LevelFilter::Debug, - // 可选的应用名称 - Some("My app name"))?; - log::debug!("this is a debug {}", "message"); - log::error!("this is an error!"); - Ok(()) -} - -#[cfg(not(target_os = "linux"))] -fn main() { - println!("So far, only Linux systems are supported."); -} -``` - - -## tracing -@todo \ No newline at end of file diff --git a/src/cookbook/devtools/version.md b/src/cookbook/devtools/version.md deleted file mode 100644 index 2d9ff997..00000000 --- a/src/cookbook/devtools/version.md +++ /dev/null @@ -1,186 +0,0 @@ -# 版本号 - -### 解析并增加版本号 -下面例子使用 [Version::parse](https://docs.rs/semver/*/semver/struct.Version.html#method.parse) 将一个字符串转换成 [semver::Version](https://docs.rs/semver/*/semver/struct.Version.html) 版本号，然后将它的 patch, minor, major 版本号都增加 1。 - -注意，为了符合[语义化版本的说明](http://semver.org)，增加 `minor` 版本时，`patch` 版本会被重设为 `0`，当增加 `major` 版本时，`minor` 和 `patch` 都将被重设为 `0`。 - -```rust,editable -use semver::{Version, SemVerError}; - -fn main() -> Result<(), SemVerError> { - let mut parsed_version = Version::parse("0.2.6")?; - - assert_eq!( - parsed_version, - Version { - major: 0, - minor: 2, - patch: 6, - pre: vec![], - build: vec![], - } - ); - - parsed_version.increment_patch(); - assert_eq!(parsed_version.to_string(), "0.2.7"); - println!("New patch release: v{}", parsed_version); - - parsed_version.increment_minor(); - assert_eq!(parsed_version.to_string(), "0.3.0"); - println!("New minor release: v{}", parsed_version); - - parsed_version.increment_major(); - assert_eq!(parsed_version.to_string(), "1.0.0"); - println!("New major release: v{}", parsed_version); - - Ok(()) -} -``` - -### 解析一个复杂的版本号字符串 -这里的版本号字符串还将包含 `SemVer` 中定义的预发布和构建元信息。 - -值得注意的是，为了符合 `SemVer` 的规则，构建元信息虽然会被解析，但是在做版本号比较时，该信息会被忽略。换而言之，即使两个版本号的构建字符串不同，它们的版本号依然可能相同。 - -```rust,editable -use semver::{Identifier, Version, SemVerError}; - -fn main() -> Result<(), SemVerError> { - let version_str = "1.0.49-125+g72ee7853"; - let parsed_version = Version::parse(version_str)?; - - assert_eq!( - parsed_version, - Version { - major: 1, - minor: 0, - patch: 49, - pre: vec![Identifier::Numeric(125)], - build: vec![], - } - ); - assert_eq!( - parsed_version.build, - vec![Identifier::AlphaNumeric(String::from("g72ee7853"))] - ); - - let serialized_version = parsed_version.to_string(); - assert_eq!(&serialized_version, version_str); - - Ok(()) -} -``` - -### 检查给定的版本号是否是预发布 -下面例子给出两个版本号，然后通过 [is_prerelease](https://docs.rs/semver/1.0.7/semver/struct.Version.html#method.is_prerelease) 判断哪个是预发布的版本号。 - -```rust,editable -use semver::{Version, SemVerError}; - -fn main() -> Result<(), SemVerError> { - let version_1 = Version::parse("1.0.0-alpha")?; - let version_2 = Version::parse("1.0.0")?; - - assert!(version_1.is_prerelease()); - assert!(!version_2.is_prerelease()); - - Ok(()) -} -``` - -### 找出给定范围内的最新版本 -下面例子给出了一个版本号列表，我们需要找到其中最新的版本。 - -```rust,editable -#use error_chain::error_chain; - -use semver::{Version, VersionReq}; - -#error_chain! { -# foreign_links { -# SemVer(semver::SemVerError); -# SemVerReq(semver::ReqParseError); -# } -3} - -fn find_max_matching_version<'a, I>(version_req_str: &str, iterable: I) -> Result> -where - I: IntoIterator, -{ - let vreq = VersionReq::parse(version_req_str)?; - - Ok( - iterable - .into_iter() - .filter_map(|s| Version::parse(s).ok()) - .filter(|s| vreq.matches(s)) - .max(), - ) -} - -fn main() -> Result<()> { - assert_eq!( - find_max_matching_version("<= 1.0.0", vec!["0.9.0", "1.0.0", "1.0.1"])?, - Some(Version::parse("1.0.0")?) - ); - - assert_eq!( - find_max_matching_version( - ">1.2.3-alpha.3", - vec![ - "1.2.3-alpha.3", - "1.2.3-alpha.4", - "1.2.3-alpha.10", - "1.2.3-beta.4", - "3.4.5-alpha.9", - ] - )?, - Some(Version::parse("1.2.3-beta.4")?) - ); - - Ok(()) -} -``` - -### 检查外部命令的版本号兼容性 -下面将通过 [Command](https://doc.rust-lang.org/std/process/struct.Command.html) 来执行系统命令 `git --version`，并对该系统命令返回的 `git` 版本号进行解析。 - -```rust,editable -#use error_chain::error_chain; - -use std::process::Command; -use semver::{Version, VersionReq}; - -#error_chain! { -# foreign_links { -# Io(std::io::Error); -# Utf8(std::string::FromUtf8Error); -# SemVer(semver::SemVerError); -# SemVerReq(semver::ReqParseError); -# } -#} - -fn main() -> Result<()> { - let version_constraint = "> 1.12.0"; - let version_test = VersionReq::parse(version_constraint)?; - let output = Command::new("git").arg("--version").output()?; - - if !output.status.success() { - error_chain::bail!("Command executed with failing error code"); - } - - let stdout = String::from_utf8(output.stdout)?; - let version = stdout.split(" ").last().ok_or_else(|| { - "Invalid command output" - })?; - let parsed_version = Version::parse(version)?; - - if !version_test.matches(&parsed_version) { - error_chain::bail!("Command version lower than minimum supported version (found {}, need {})", - parsed_version, version_constraint); - } - - Ok(()) -} -``` \ No newline at end of file diff --git a/src/cookbook/encoding/csv.md b/src/cookbook/encoding/csv.md deleted file mode 100644 index 19f2031e..00000000 --- a/src/cookbook/encoding/csv.md +++ /dev/null @@ -1 +0,0 @@ -# CSV diff --git a/src/cookbook/encoding/intro.md b/src/cookbook/encoding/intro.md deleted file mode 100644 index 0e61f3d0..00000000 --- a/src/cookbook/encoding/intro.md +++ /dev/null @@ -1 +0,0 @@ -# 编解码 diff --git a/src/cookbook/encoding/json.md b/src/cookbook/encoding/json.md deleted file mode 100644 index 02ed5a24..00000000 --- a/src/cookbook/encoding/json.md +++ /dev/null @@ -1 +0,0 @@ -# JSON diff --git a/src/cookbook/encoding/protobuf.md b/src/cookbook/encoding/protobuf.md deleted file mode 100644 index 4fdb7ce0..00000000 --- a/src/cookbook/encoding/protobuf.md +++ /dev/null @@ -1 +0,0 @@ -# protobuf diff --git a/src/cookbook/file/dir.md b/src/cookbook/file/dir.md deleted file mode 100644 index c996c7a0..00000000 --- a/src/cookbook/file/dir.md +++ /dev/null @@ -1 +0,0 @@ -# 目录操作 diff --git a/src/cookbook/file/file.md b/src/cookbook/file/file.md deleted file mode 100644 index 9286f56a..00000000 --- a/src/cookbook/file/file.md +++ /dev/null @@ -1 +0,0 @@ -# 文件读写 diff --git a/src/cookbook/file/intro.md b/src/cookbook/file/intro.md deleted file mode 100644 index 0f8e6d56..00000000 --- a/src/cookbook/file/intro.md +++ /dev/null @@ -1 +0,0 @@ -# 文件系统 todo diff --git a/src/cookbook/intro.md b/src/cookbook/intro.md index 12f5f0e6..45419e9a 100644 --- a/src/cookbook/intro.md +++ b/src/cookbook/intro.md @@ -2,6 +2,12 @@ 对于开发者而言，CookBook 是非常实用的，几乎每一门编程语言都是如此。原因无他：聪明的开发者大部分时间不是在复制粘贴就是在复制粘贴的路上。而 CookBook 恰恰为各种实用场景提供了可供直接复制粘贴的代码，例如文件操作、随机数生成、命令行解析等等， +由于这本书的章节非常多，为了不影响大家的整体阅读体验，请访问以下地址阅读。 + +- 在线阅读: https://cookbook.rs + +
+ > CookBook 的部分内容翻译自 [Rust CookBook](https://rust-lang-nursery.github.io/rust-cookbook/intro.html)，但是内容并不相同，因为我们对部分内容进行了整合，最重要的是增加了大量实用库和代码片段 diff --git a/src/cookbook/protocol/grpc.md b/src/cookbook/protocol/grpc.md deleted file mode 100644 index 37b724e9..00000000 --- a/src/cookbook/protocol/grpc.md +++ /dev/null @@ -1 +0,0 @@ -# gRPC diff --git a/src/cookbook/protocol/http.md b/src/cookbook/protocol/http.md deleted file mode 100644 index 03fe6a2d..00000000 --- a/src/cookbook/protocol/http.md +++ /dev/null @@ -1 +0,0 @@ -# HTTP diff --git a/src/cookbook/protocol/intro.md b/src/cookbook/protocol/intro.md deleted file mode 100644 index aaab51db..00000000 --- a/src/cookbook/protocol/intro.md +++ /dev/null @@ -1 +0,0 @@ -# 网络通信 todo diff --git a/src/cookbook/protocol/tcp.md b/src/cookbook/protocol/tcp.md deleted file mode 100644 index fd208cbf..00000000 --- a/src/cookbook/protocol/tcp.md +++ /dev/null @@ -1 +0,0 @@ -# TCP diff --git a/src/cookbook/protocol/udp.md b/src/cookbook/protocol/udp.md deleted file mode 100644 index 2827b96c..00000000 --- a/src/cookbook/protocol/udp.md +++ /dev/null @@ -1 +0,0 @@ -# UDP diff --git a/src/cookbook/regexp.md b/src/cookbook/regexp.md deleted file mode 100644 index b79ef0b1..00000000 --- a/src/cookbook/regexp.md +++ /dev/null @@ -1 +0,0 @@ -# 正则表达式 todo