diff --git a/assets/.DS_Store b/assets/.DS_Store index 135bf4b1..94ebaff9 100644 Binary files a/assets/.DS_Store and b/assets/.DS_Store differ diff --git a/src/SUMMARY.md b/src/SUMMARY.md index fa49ba7f..c071790f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -5,58 +5,62 @@ ## Getting started -- [牛刀小试](ch01-first_try/getting-started.md) - - [安装Rust环境](ch01-first_try/installation.md) - - [墙推VSCode!](ch01-first_try/editor.md) - - [认识Cargo](ch01-first_try/cargo.md) - - [你好，世界!](ch01-first_try/hello-world.md) +- [牛刀小试](first_try/getting-started.md) + - [安装Rust环境](first_try/installation.md) + - [墙推VSCode!](first_try/editor.md) + - [认识Cargo](first_try/cargo.md) + - [你好，世界!](first_try/hello-world.md) ## Rust学习三部曲 -- [基本概念] - - [变量与类型] - - [结构体、枚举] - - [函数与方法] - - [格式化输出] - - [字符串、数组与切片] - - [流程控制] - - [返回、异常和错误] - - [模式匹配] - - [文档注释] - - [包和模块] +- [基本概念](basic_rust/intro.md) + - [变量与类型](basic_rust/variable-type.md) + - [结构体、枚举](basic_rust/struct-enum.md) + - [函数与方法](basic_rust/function-method.md) + - [格式化输出](basic_rust/formatted-output.md) + - [字符串、数组与切片](basic_rust/string-array-slice.md) + - [流程控制](basic_rust/flow-control.md) + - [返回、异常和错误](basic_rust/exception-error.md) + - [模式匹配](basic_rust/match-pattern.md) + - [文档注释](basic_rust/comment.md) + - [包和模块](basic_rust/crate-module.md) -- [核心概念] - - [所有权] - - [借用] - - [生命周期] +- [核心概念](core_concepts/intro.md) + - [所有权](core_concepts/ownership.md) + - [借用](core_concepts/borrowing.md) + - [生命周期](core_concepts/lifetime.md) -- [进阶编程] - - [泛型与特征] - - [迭代器] - - [集合类型] - - [函数式编程] - - [智能指针] - - [多线程] - - [测试] - - [错误处理] - - [宏] +- [进阶编程](advance_rust/intro.md) + - [泛型](advance_rust/generitic.md) + - [特征](advance_rust/trait.md) + - [迭代器](advance_rust/interator.md) + - [集合类型](advance_rust/collection.md) + - [函数式编程](advance_rust/functional-programing.md) + - [智能指针](advance_rust/smart-pointer.md) + - [多线程](advance_rust/threads.md) + - [测试](advance_rust/tests.md) + - [错误处理](advance_rust/errors.md) + - [宏](advance_rust/macro.md) ## 专题内容 -- [代码风格] +- [代码风格](style_guide/intro.md) + - [命名规范](style_guide/naming.md) +- [面向对象](object_oriented/intro.md) + - [OO所需的特性](object_oriented/characteristics.md) +- [异步编程](async/intro.md) + - [并发与并行](async/concurrency-parallelism.md) +- [Cargo详解](cargo/intro.md) + - [配置参数](cargo/manifest.md) +- [性能调优](performance/intro.md) + - [Benchmark性能测试](performance/benchmark.md) +- [Unsafe](unsafe/intro.md) + - [原始指针](unsafe/raw-pointer.md) -- [面向对象] - -- [并发编程] - -- [Cargo详解] - -- [性能调优] - -- [Unsafe] - -- [宏编程] +- [宏编程](macro/intro.md) + - [过程宏](macro/procedure-macro.md) + ## 场景模版 -- [场景示例] \ No newline at end of file +- [场景示例](use-case/intro.md) \ No newline at end of file diff --git a/src/advance_rust/collection.md b/src/advance_rust/collection.md new file mode 100644 index 00000000..9ceffe5c --- /dev/null +++ b/src/advance_rust/collection.md @@ -0,0 +1 @@ +# collection.md \ No newline at end of file diff --git a/src/advance_rust/errors.md b/src/advance_rust/errors.md new file mode 100644 index 00000000..36a1c2bc --- /dev/null +++ b/src/advance_rust/errors.md @@ -0,0 +1 @@ +# errors.md \ No newline at end of file diff --git a/src/advance_rust/functional-programing.md b/src/advance_rust/functional-programing.md new file mode 100644 index 00000000..e748b8a4 --- /dev/null +++ b/src/advance_rust/functional-programing.md @@ -0,0 +1 @@ +# functional-programing.md \ No newline at end of file diff --git a/src/advance_rust/generitic.md b/src/advance_rust/generitic.md new file mode 100644 index 00000000..9810a313 --- /dev/null +++ b/src/advance_rust/generitic.md @@ -0,0 +1 @@ +# generitic.md \ No newline at end of file diff --git a/src/advance_rust/interator.md b/src/advance_rust/interator.md new file mode 100644 index 00000000..1141f7b7 --- /dev/null +++ b/src/advance_rust/interator.md @@ -0,0 +1 @@ +# interator.md \ No newline at end of file diff --git a/src/advance_rust/intro.md b/src/advance_rust/intro.md new file mode 100644 index 00000000..d5f6dd59 --- /dev/null +++ b/src/advance_rust/intro.md @@ -0,0 +1 @@ +# advance rust \ No newline at end of file diff --git a/src/advance_rust/macro.md b/src/advance_rust/macro.md new file mode 100644 index 00000000..11b2ee8f --- /dev/null +++ b/src/advance_rust/macro.md @@ -0,0 +1 @@ +# macro.md \ No newline at end of file diff --git a/src/advance_rust/smart-pointer.md b/src/advance_rust/smart-pointer.md new file mode 100644 index 00000000..5950d836 --- /dev/null +++ b/src/advance_rust/smart-pointer.md @@ -0,0 +1 @@ +# smart-pointer.md \ No newline at end of file diff --git a/src/advance_rust/tests.md b/src/advance_rust/tests.md new file mode 100644 index 00000000..de3b8613 --- /dev/null +++ b/src/advance_rust/tests.md @@ -0,0 +1 @@ +# tests.md \ No newline at end of file diff --git a/src/advance_rust/threads.md b/src/advance_rust/threads.md new file mode 100644 index 00000000..b0bb675f --- /dev/null +++ b/src/advance_rust/threads.md @@ -0,0 +1 @@ +# threads.md \ No newline at end of file diff --git a/src/advance_rust/trait.md b/src/advance_rust/trait.md new file mode 100644 index 00000000..0c10990d --- /dev/null +++ b/src/advance_rust/trait.md @@ -0,0 +1 @@ +# trait.md \ No newline at end of file diff --git a/src/async/concurrency-parallelism.md b/src/async/concurrency-parallelism.md new file mode 100644 index 00000000..d0f0f892 --- /dev/null +++ b/src/async/concurrency-parallelism.md @@ -0,0 +1 @@ +# 并发与并行 \ No newline at end of file diff --git a/src/async/intro.md b/src/async/intro.md new file mode 100644 index 00000000..3f25f2e5 --- /dev/null +++ b/src/async/intro.md @@ -0,0 +1 @@ +# concurrency \ No newline at end of file diff --git a/src/basic_rust/comment.md b/src/basic_rust/comment.md new file mode 100644 index 00000000..9d86d9b2 --- /dev/null +++ b/src/basic_rust/comment.md @@ -0,0 +1 @@ +# comment.md \ No newline at end of file diff --git a/src/basic_rust/crate-module.md b/src/basic_rust/crate-module.md new file mode 100644 index 00000000..d8cb5f05 --- /dev/null +++ b/src/basic_rust/crate-module.md @@ -0,0 +1 @@ +# crate-module.md \ No newline at end of file diff --git a/src/basic_rust/exception-error.md b/src/basic_rust/exception-error.md new file mode 100644 index 00000000..6fd776dd --- /dev/null +++ b/src/basic_rust/exception-error.md @@ -0,0 +1 @@ +# exception-error.md \ No newline at end of file diff --git a/src/basic_rust/flow-control.md b/src/basic_rust/flow-control.md new file mode 100644 index 00000000..bc1fb805 --- /dev/null +++ b/src/basic_rust/flow-control.md @@ -0,0 +1 @@ +# flow-control.md \ No newline at end of file diff --git a/src/basic_rust/formatted-output.md b/src/basic_rust/formatted-output.md new file mode 100644 index 00000000..394a91d9 --- /dev/null +++ b/src/basic_rust/formatted-output.md @@ -0,0 +1 @@ +# formatted-output.md \ No newline at end of file diff --git a/src/basic_rust/function-method.md b/src/basic_rust/function-method.md new file mode 100644 index 00000000..c11086c4 --- /dev/null +++ b/src/basic_rust/function-method.md @@ -0,0 +1 @@ +# function-method.md \ No newline at end of file diff --git a/src/basic_rust/intro.md b/src/basic_rust/intro.md new file mode 100644 index 00000000..09d7941d --- /dev/null +++ b/src/basic_rust/intro.md @@ -0,0 +1 @@ +# basic rust \ No newline at end of file diff --git a/src/basic_rust/match-pattern.md b/src/basic_rust/match-pattern.md new file mode 100644 index 00000000..49fa3d12 --- /dev/null +++ b/src/basic_rust/match-pattern.md @@ -0,0 +1 @@ +# match-pattern.md \ No newline at end of file diff --git a/src/basic_rust/string-array-slice.md b/src/basic_rust/string-array-slice.md new file mode 100644 index 00000000..01765843 --- /dev/null +++ b/src/basic_rust/string-array-slice.md @@ -0,0 +1 @@ +# string-array-slice.md \ No newline at end of file diff --git a/src/basic_rust/struct-enum.md b/src/basic_rust/struct-enum.md new file mode 100644 index 00000000..f391c141 --- /dev/null +++ b/src/basic_rust/struct-enum.md @@ -0,0 +1 @@ +# struct-enum.md \ No newline at end of file diff --git a/src/basic_rust/vars-types.md b/src/basic_rust/vars-types.md new file mode 100644 index 00000000..8466509b --- /dev/null +++ b/src/basic_rust/vars-types.md @@ -0,0 +1 @@ +# 变量和类型 \ No newline at end of file diff --git a/src/cargo/intro.md b/src/cargo/intro.md new file mode 100644 index 00000000..987a0d31 --- /dev/null +++ b/src/cargo/intro.md @@ -0,0 +1 @@ +# cargo \ No newline at end of file diff --git a/src/cargo/manifest.md b/src/cargo/manifest.md new file mode 100644 index 00000000..dd3071df --- /dev/null +++ b/src/cargo/manifest.md @@ -0,0 +1 @@ +# manifest \ No newline at end of file diff --git a/src/core_concepts/borrowing.md b/src/core_concepts/borrowing.md new file mode 100644 index 00000000..b514e514 --- /dev/null +++ b/src/core_concepts/borrowing.md @@ -0,0 +1 @@ +# borrowing.md \ No newline at end of file diff --git a/src/core_concepts/intro.md b/src/core_concepts/intro.md new file mode 100644 index 00000000..2497c665 --- /dev/null +++ b/src/core_concepts/intro.md @@ -0,0 +1 @@ +# core concepts \ No newline at end of file diff --git a/src/core_concepts/lifetime.md b/src/core_concepts/lifetime.md new file mode 100644 index 00000000..e8d09e98 --- /dev/null +++ b/src/core_concepts/lifetime.md @@ -0,0 +1 @@ +# lifetime.md \ No newline at end of file diff --git a/src/core_concepts/ownership.md b/src/core_concepts/ownership.md new file mode 100644 index 00000000..aac08a8f --- /dev/null +++ b/src/core_concepts/ownership.md @@ -0,0 +1 @@ +# ownership \ No newline at end of file diff --git a/src/ch01-first_try/cargo.md b/src/first_try/cargo.md similarity index 100% rename from src/ch01-first_try/cargo.md rename to src/first_try/cargo.md diff --git a/src/ch01-first_try/editor.md b/src/first_try/editor.md similarity index 100% rename from src/ch01-first_try/editor.md rename to src/first_try/editor.md diff --git a/src/ch01-first_try/getting-started.md b/src/first_try/getting-started.md similarity index 100% rename from src/ch01-first_try/getting-started.md rename to src/first_try/getting-started.md diff --git a/src/ch01-first_try/hello-world.md b/src/first_try/hello-world.md similarity index 100% rename from src/ch01-first_try/hello-world.md rename to src/first_try/hello-world.md diff --git a/src/ch01-first_try/installation.md b/src/first_try/installation.md similarity index 100% rename from src/ch01-first_try/installation.md rename to src/first_try/installation.md diff --git a/src/macro/intro.md b/src/macro/intro.md new file mode 100644 index 00000000..1818a761 --- /dev/null +++ b/src/macro/intro.md @@ -0,0 +1 @@ +# macro \ No newline at end of file diff --git a/src/macro/procedure-macro.md b/src/macro/procedure-macro.md new file mode 100644 index 00000000..e69de29b diff --git a/src/object_oriented/characteristics.md b/src/object_oriented/characteristics.md new file mode 100644 index 00000000..26bc83a9 --- /dev/null +++ b/src/object_oriented/characteristics.md @@ -0,0 +1 @@ +# Characteristics \ No newline at end of file diff --git a/src/object_oriented/intro.md b/src/object_oriented/intro.md new file mode 100644 index 00000000..a904e438 --- /dev/null +++ b/src/object_oriented/intro.md @@ -0,0 +1 @@ +# object oriented \ No newline at end of file diff --git a/src/performance/benchmark.md b/src/performance/benchmark.md new file mode 100644 index 00000000..0ae35de8 --- /dev/null +++ b/src/performance/benchmark.md @@ -0,0 +1 @@ +# benchmark \ No newline at end of file diff --git a/src/performance/intro.md b/src/performance/intro.md new file mode 100644 index 00000000..5062ad24 --- /dev/null +++ b/src/performance/intro.md @@ -0,0 +1 @@ +# performance \ No newline at end of file diff --git a/src/style_guide/intro.md b/src/style_guide/intro.md new file mode 100644 index 00000000..ff247df6 --- /dev/null +++ b/src/style_guide/intro.md @@ -0,0 +1,230 @@ +# 命名规范 + +基本的Rust命名规范在[RFC 430]中有描述. + +通常，对于"type-level"的构造Rust倾向于使用驼峰命名,而对于'value-level'的构造使用蛇形命名。详情如下: + +| 条目 | 惯例 | +| ---- | ---------- | +| 包Crates | [unclear](https://github.com/rust-lang/api-guidelines/issues/29) | +| 模块Modules | `snake_case` | +| 类型Types | `UpperCamelCase` | +| 特征Traits | `UpperCamelCase` | +| 枚举变量Enum variants | `UpperCamelCase` | +| 函数Functions | `snake_case` | +| 方法Methods | `snake_case` | +| 通用构造器General constructors | `new` or `with_more_details` | +| 转换构造器Conversion constructors | `from_some_other_type` | +| 宏Macros | `snake_case!` | +| 局部变量Local variables | `snake_case` | +| 静态类型Statics | `SCREAMING_SNAKE_CASE` | +| 常量Constants | `SCREAMING_SNAKE_CASE` | +| 类型参数Type parameters | `UpperCamelCase`, 通常使用一个大写字母: `T` | +| 生命周期Lifetimes | 通常使用小写字母: `'a`, `'de`, `'src` | +| Features | [unclear](https://github.com/rust-lang/api-guidelines/issues/101) but see [C-FEATURE] | + +对于驼峰命名法, 复合词的缩略形式我们认为是一个单独的词语，所以只对首字母进行大写: 使用`Uuid`而不是`UUID`, `Usize`而不是`USize`, `Stdin`而不是`StdIn`.对于蛇形命名法，缩略词用全小写: `is_xid_start`. + +对于蛇形命名(包括全大写的`SCREAMING_SNAKE_CASE`), 除了最后一部分，其它部分的词语都不能由单个字母组成： +`btree_map`而不是`b_tree_map`, `PI_2`而不是`PI2`. + +包名不应该使用`-rs`或者`-rust`作为后缀，因为每一个包都是Rust写的，因此这种多余的注释其实没有任何意义。 + +[RFC 430]: https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md +[C-FEATURE]: #c-feature + + +## 类型转换要遵守`as_`, `to_`, `into_`命名惯例(C-CONV) +类型转换应该通过方法调用的方式实现，其中的前缀规则如下： + +| 方法前缀 | 性能开销 | 所有权改变 | +| ------ | ---- | --------- | +| `as_` | Free | borrowed -\> borrowed | +| `to_` | Expensive | borrowed -\> borrowed
borrowed -\> owned (non-Copy types)
owned -\> owned (Copy types) | +| `into_` | Variable | owned -\> owned (non-Copy types) | + +For example: + +- [`str::as_bytes()`] 把`str`变成UTF-8字节数组, 性能开销是0. 其中输入是一个借用的`&str`，输出也是一个借用的`&str`. +- [`Path::to_str`] 会执行一次昂贵的UTF-8字节数组检查，输入和输出都是借用的。对于这种情况，如果把方法命名为`as_str`是不正确的，因为这个方法的开销还挺大. +- [`str::to_lowercase()`]在调用过程中会遍历字符串的字符，且可能会分配新的内存对象.输入是一个借用的`str`，输出是一个有独立所有权的`String` +- [`String::into_bytes()`]返回`String`底层的`Vec`数组，转换本身是零消耗的。该方法获取`String`的所有权，然后返回一个新的有独立所有权的`Vec` + + +[`str::as_bytes()`]: https://doc.rust-lang.org/std/primitive.str.html#method.as_bytes +[`Path::to_str`]: https://doc.rust-lang.org/std/path/struct.Path.html#method.to_str +[`str::to_lowercase()`]: https://doc.rust-lang.org/std/primitive.str.html#method.to_lowercase +[`f64::to_radians()`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_radians +[`String::into_bytes()`]: https://doc.rust-lang.org/std/string/struct.String.html#method.into_bytes +[`BufReader::into_inner()`]: https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner +[`BufWriter::into_inner()`]: https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.into_inner + + +当一个单独的值被某个类型所包装时，访问该类型的内部值应通过`into_inner()`方法来访问。例如将一个缓冲区值包装为[`BufReader`]类型，还有[`GzDecoder`]、[`AtomicBool`]等，都是这种类型。 + + +[`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html#method.into_inner +[`GzDecoder`]: https://docs.rs/flate2/0.2.19/flate2/read/struct.GzDecoder.html#method.into_inner +[`AtomicBool`]: https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html#method.into_inner + +如果`mut`限定符在返回类型中出现，那么在命名上也应该体现出来。例如，[`Vec::as_mut_slice`] 就说明它返回了一个mut切片，在这种情况下`as_mut_slice`比`as_slice_mut`更适合。 + +[`Vec::as_mut_slice`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.as_mut_slice + +```rust +// 返回类型是一个mut切片. +fn as_mut_slice(&mut self) -> &mut [T]; +``` + +##### 标准库中的一些例子 + +- [`Result::as_ref`](https://doc.rust-lang.org/std/result/enum.Result.html#method.as_ref) +- [`RefCell::as_ptr`](https://doc.rust-lang.org/std/cell/struct.RefCell.html#method.as_ptr) +- [`slice::to_vec`](https://doc.rust-lang.org/std/primitive.slice.html#method.to_vec) +- [`Option::into_iter`](https://doc.rust-lang.org/std/option/enum.Option.html#method.into_iter) + + +## 读访问器(Getter)的名称遵循Rust的命名规范(C-GETTER) + +除了少数例外，在Rust代码中`get`前缀不用于getter。 + +```rust +pub struct S { + first: First, + second: Second, +} + +impl S { + // 而不是get_first + pub fn first(&self) -> &First { + &self.first + } + + // 而不是get_first_mut, get_mut_first, or mut_first. + pub fn first_mut(&mut self) -> &mut First { + &mut self.first + } +} +``` +至于上文提到的少数例外，如下：当有且仅有一个值能被getter所获取时，才使用`get`前缀。例如， +[`Cell::get`]能直接访问到`Cell`中的内容。 + +[`Cell::get`]: https://doc.rust-lang.org/std/cell/struct.Cell.html#method.get + +有些getter会在过程中执行运行时检查，那么我们就可以考虑添加`_unchecked`getter函数，这个函数虽然不安全，但是往往具有更高的性能， +典型的例子如下： + +```rust +fn get(&self, index: K) -> Option<&V>; +fn get_mut(&mut self, index: K) -> Option<&mut V>; +unsafe fn get_unchecked(&self, index: K) -> &V; +unsafe fn get_unchecked_mut(&mut self, index: K) -> &mut V; +``` + +[`TempDir::path`]: https://docs.rs/tempdir/0.3.5/tempdir/struct.TempDir.html#method.path +[`TempDir::into_path`]: https://docs.rs/tempdir/0.3.5/tempdir/struct.TempDir.html#method.into_path + +### 标准库示例 + +- [`std::io::Cursor::get_mut`](https://doc.rust-lang.org/std/io/struct.Cursor.html#method.get_mut) +- [`std::ptr::Unique::get_mut`](https://doc.rust-lang.org/std/ptr/struct.Unique.html#method.get_mut) +- [`std::sync::PoisonError::get_mut`](https://doc.rust-lang.org/std/sync/struct.PoisonError.html#method.get_mut) +- [`std::sync::atomic::AtomicBool::get_mut`](https://doc.rust-lang.org/std/sync/atomic/struct.AtomicBool.html#method.get_mut) +- [`std::collections::hash_map::OccupiedEntry::get_mut`](https://doc.rust-lang.org/std/collections/hash_map/struct.OccupiedEntry.html#method.get_mut) +- [`<[T]>::get_unchecked`](https://doc.rust-lang.org/std/primitive.slice.html#method.get_unchecked) + +## 一个集合上的方法，如果返回迭代器，需遵循命名规则：`iter`, `iter_mut`, `into_iter` (C-ITER) + +```rust +fn iter(&self) -> Iter // Iter implements Iterator +fn iter_mut(&mut self) -> IterMut // IterMut implements Iterator +fn into_iter(self) -> IntoIter // IntoIter implements Iterator +``` +上面的规则适用于同构性的数据集合。与之相反，`str`类型是一个utf8字节数组切片，与同构性集合有一点微妙的差别，它可以认为是字节集合，也可以认为是字符集合，因此它提供了[`str::bytes`]去遍历字节，还有[`str::chars`]去遍历字符，而并没有直接定义`iter`等方法。 + +[`str::bytes`]: https://doc.rust-lang.org/std/primitive.str.html#method.bytes +[`str::chars`]: https://doc.rust-lang.org/std/primitive.str.html#method.chars + +上述规则只适用于方法，并不适用于函数。例如`url`包的[`percent_encode`]函数返回一个迭代器用于遍历百分比编码([Percent encoding](https://en.wikipedia.org/wiki/Percent-encoding))的字符串片段. 在这种情况下，使用`iter`/`iter_mut`/`into_iter`诸如此类的函数命名无法表达任何具体的含义。 + +[`percent_encode`]: https://docs.rs/url/1.4.0/url/percent_encoding/fn.percent_encode.html +[RFC 199]: https://github.com/rust-lang/rfcs/blob/master/text/0199-ownership-variants.md + +### 标准库示例 + +- [`Vec::iter`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.iter) +- [`Vec::iter_mut`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.iter_mut) +- [`Vec::into_iter`](https://doc.rust-lang.org/std/vec/struct.Vec.html#method.into_iter) +- [`BTreeMap::iter`](https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.iter) +- [`BTreeMap::iter_mut`](https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.iter_mut) + +## 迭代器的类型应该与产生它的方法名相匹配(C-ITER-TY) +例如形如`into_iter()`的方法应该返回一个`IntoIter`类型，与之相似，其它任何返回迭代器的方法也应该遵循这种命名惯例。 + +上述规则主要应用于方法，但是经常对于函数也适用。例如上文提到的url包中的[`percent_encode`]函数，返回了一个[`PercentEncode`]类型. + +[PercentEncode-type]: https://docs.rs/url/1.4.0/url/percent_encoding/struct.PercentEncode.html + +特别是，当这些类型跟包名前缀一起使用时，将具备非常清晰的含义，例如[`vec::IntoIter`]. + +[`vec::IntoIter`]: https://doc.rust-lang.org/std/vec/struct.IntoIter.html + +### 标准库示例 + +* [`Vec::iter`] returns [`Iter`][slice::Iter] +* [`Vec::iter_mut`] returns [`IterMut`][slice::IterMut] +* [`Vec::into_iter`] returns [`IntoIter`][vec::IntoIter] +* [`BTreeMap::keys`] returns [`Keys`][btree_map::Keys] +* [`BTreeMap::values`] returns [`Values`][btree_map::Values] + +[`Vec::iter`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.iter +[slice::Iter]: https://doc.rust-lang.org/std/slice/struct.Iter.html +[`Vec::iter_mut`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.iter_mut +[slice::IterMut]: https://doc.rust-lang.org/std/slice/struct.IterMut.html +[`Vec::into_iter`]: https://doc.rust-lang.org/std/vec/struct.Vec.html#method.into_iter +[vec::IntoIter]: https://doc.rust-lang.org/std/vec/struct.IntoIter.html +[`BTreeMap::keys`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.keys +[btree_map::Keys]: https://doc.rust-lang.org/std/collections/btree_map/struct.Keys.html +[`BTreeMap::values`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.values +[btree_map::Values]: https://doc.rust-lang.org/std/collections/btree_map/struct.Values.html + + + +## Cargo Feature的名称不应该包含占位词(C-FEATURE) + +不要在[Cargo feature]中包含无法传达任何意义的词，例如`use-abc`或`with-abc`，直接命名为`abc`即可。 + +[Cargo feature]: http://doc.crates.io/manifest.html#the-features-section + +一个典型的例子就是：一个包对标准库有可选性的依赖。标准的写法如下： + +```toml +# 在Cargo.toml中 + +[features] +default = ["std"] +std = [] +``` + +```rust +// 在我们自定义的lib.rs中 + +#![cfg_attr(not(feature = "std"), no_std)] +``` +除了`std`之外，不要使用任何`ust-std`或者`with-std`等自以为很有创造性的名称。 + +## 命名要使用一致性的词序(C-WORD-ORDER) + +这是一些标准库中的错误类型: + +- [`JoinPathsError`](https://doc.rust-lang.org/std/env/struct.JoinPathsError.html) +- [`ParseBoolError`](https://doc.rust-lang.org/std/str/struct.ParseBoolError.html) +- [`ParseCharError`](https://doc.rust-lang.org/std/char/struct.ParseCharError.html) +- [`ParseFloatError`](https://doc.rust-lang.org/std/num/struct.ParseFloatError.html) +- [`ParseIntError`](https://doc.rust-lang.org/std/num/struct.ParseIntError.html) +- [`RecvTimeoutError`](https://doc.rust-lang.org/std/sync/mpsc/enum.RecvTimeoutError.html) +- [`StripPrefixError`](https://doc.rust-lang.org/std/path/struct.StripPrefixError.html) + +它们都使用了`谓语-宾语-错误`的词序，如果我们想要表达一个网络地址无法分析的错误，由于词序一致性的原则，命名应该如下`ParseAddrError`,而不是`AddrParseError`。 + +词序和个人习惯有很大关系，想要注意的是，你可以选择合适的词序，但是要在包的范畴内保持一致性，就如标准库中的包一样。 diff --git a/src/unsafe/intro.md b/src/unsafe/intro.md new file mode 100644 index 00000000..1c58b7c9 --- /dev/null +++ b/src/unsafe/intro.md @@ -0,0 +1 @@ +# unsafe \ No newline at end of file diff --git a/src/unsafe/raw-pointer.md b/src/unsafe/raw-pointer.md new file mode 100644 index 00000000..5f6c0b18 --- /dev/null +++ b/src/unsafe/raw-pointer.md @@ -0,0 +1 @@ +# raw pointer \ No newline at end of file diff --git a/src/use-case/intro.md b/src/use-case/intro.md new file mode 100644 index 00000000..0b03bc6f --- /dev/null +++ b/src/use-case/intro.md @@ -0,0 +1 @@ +# 场景用例 \ No newline at end of file