add manifests

src/SUMMARY.md

@@ -5,58 +5,62 @@
 
 ## Getting started
 
-- [牛刀小试](ch01-first_try/getting-started.md)
+- [牛刀小试](first_try/getting-started.md)
-    - [安装Rust环境](ch01-first_try/installation.md)
+    - [安装Rust环境](first_try/installation.md)
-    - [墙推VSCode!](ch01-first_try/editor.md)
+    - [墙推VSCode!](first_try/editor.md)
-    - [认识Cargo](ch01-first_try/cargo.md)
+    - [认识Cargo](first_try/cargo.md)
-    - [你好，世界!](ch01-first_try/hello-world.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)
 
-- [面向对象]
+- [宏编程](macro/intro.md)
+    - [过程宏](macro/procedure-macro.md)
 
-- [并发编程]
-
-- [Cargo详解]
-
-- [性能调优]
-
-- [Unsafe]
-
-- [宏编程]
     
 ## 场景模版
 
-- [场景示例]
+- [场景示例](use-case/intro.md)

src/advance_rust/collection.md

@@ -0,0 +1 @@
+# collection.md

src/advance_rust/errors.md

@@ -0,0 +1 @@
+# errors.md

src/advance_rust/functional-programing.md

@@ -0,0 +1 @@
+# functional-programing.md

src/advance_rust/generitic.md

@@ -0,0 +1 @@
+# generitic.md

src/advance_rust/interator.md

@@ -0,0 +1 @@
+# interator.md

src/advance_rust/intro.md

@@ -0,0 +1 @@
+# advance rust

src/advance_rust/macro.md

@@ -0,0 +1 @@
+# macro.md

src/advance_rust/smart-pointer.md

@@ -0,0 +1 @@
+# smart-pointer.md

src/advance_rust/tests.md

@@ -0,0 +1 @@
+# tests.md

src/advance_rust/threads.md

@@ -0,0 +1 @@
+# threads.md

src/advance_rust/trait.md

@@ -0,0 +1 @@
+# trait.md

src/async/concurrency-parallelism.md

@@ -0,0 +1 @@
+# 并发与并行

src/async/intro.md

@@ -0,0 +1 @@
+# concurrency

src/basic_rust/comment.md

@@ -0,0 +1 @@
+# comment.md

src/basic_rust/crate-module.md

@@ -0,0 +1 @@
+# crate-module.md

src/basic_rust/exception-error.md

@@ -0,0 +1 @@
+# exception-error.md

src/basic_rust/flow-control.md

@@ -0,0 +1 @@
+# flow-control.md

src/basic_rust/formatted-output.md

@@ -0,0 +1 @@
+# formatted-output.md

src/basic_rust/function-method.md

@@ -0,0 +1 @@
+# function-method.md

src/basic_rust/intro.md

@@ -0,0 +1 @@
+# basic rust

src/basic_rust/match-pattern.md

@@ -0,0 +1 @@
+# match-pattern.md

src/basic_rust/string-array-slice.md

@@ -0,0 +1 @@
+# string-array-slice.md

src/basic_rust/struct-enum.md

@@ -0,0 +1 @@
+# struct-enum.md

src/basic_rust/vars-types.md

@@ -0,0 +1 @@
+# 变量和类型

src/cargo/intro.md

@@ -0,0 +1 @@
+# cargo

src/cargo/manifest.md

@@ -0,0 +1 @@
+# manifest

src/core_concepts/borrowing.md

@@ -0,0 +1 @@
+# borrowing.md

src/core_concepts/intro.md

@@ -0,0 +1 @@
+# core concepts

src/core_concepts/lifetime.md

@@ -0,0 +1 @@
+# lifetime.md

src/core_concepts/ownership.md

@@ -0,0 +1 @@
+# ownership

src/macro/intro.md

@@ -0,0 +1 @@
+# macro

src/object_oriented/characteristics.md

@@ -0,0 +1 @@
+# Characteristics

src/object_oriented/intro.md

@@ -0,0 +1 @@
+# object oriented

src/performance/benchmark.md

@@ -0,0 +1 @@
+# benchmark

src/performance/intro.md

@@ -0,0 +1 @@
+# performance

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<br>borrowed -\> owned (non-Copy types)<br>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<u8>`数组，转换本身是零消耗的。该方法获取`String`的所有权，然后返回一个新的有独立所有权的`Vec<u8>`
+
+
+[`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<Item = &U>
+fn iter_mut(&mut self) -> IterMut  // IterMut implements Iterator<Item = &mut U>
+fn into_iter(self) -> IntoIter     // IntoIter implements Iterator<Item = U>
+```
+上面的规则适用于同构性的数据集合。与之相反，`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
+
+
+<a id="c-feature"></a>
+## 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`。
+
+词序和个人习惯有很大关系，想要注意的是，你可以选择合适的词序，但是要在包的范畴内保持一致性，就如标准库中的包一样。

src/unsafe/intro.md

@@ -0,0 +1 @@
+# unsafe

src/unsafe/raw-pointer.md

@@ -0,0 +1 @@
+# raw pointer

src/use-case/intro.md

@@ -0,0 +1 @@
+# 场景用例