fixed some issues (#121)

* V 0.3

* V0.3: modify README

* update Version to 0.3

* add code example for P.SEC.01

* modify P.SEC.01

* 3.30 review

* update

* update to 1.0 beta

* fixed for P.NAM.01

* Improvement desc for P.NAM.05 && P.NAM.07 && P.UNS.MEM.04

* fixed code typo

* update some items and add new items : p.uns.ffi.16-17-18

* fixed typo

* update P.NAM.03 && add new G.TYP.ENM.07

* update G.TYP.ENM.07

* update data-type/vec

* fixed some issues

* update P.STR.04

Author: ZhangHanDong

src/SUMMARY.md

@@ -130,7 +130,7 @@
         - [P.STR.01 处理字符串元素时优先按字节处理而非字符](./safe-guides/coding_practice/strings/P.STR.01.md)
         - [P.STR.02 创建字符串时，宜预先分配大约足够的容量来避免后续操作中产生多次分配](./safe-guides/coding_practice/strings/P.STR.02.md)
         - [P.STR.03 在使用内建字符串处理函数或方法的时候，应注意避免隐藏的嵌套迭代或多次迭代](./safe-guides/coding_practice/strings/P.STR.03.md)
-        - [P.STR.04 只在合适的场景下，使用正则表达式第三方库regex](./safe-guides/coding_practice/strings/P.STR.04.md)
+        - [P.STR.04 在使用 `Cow<'a, B> `时要注意选择合理场景以便最大化地优化性能](./safe-guides/coding_practice/strings/P.STR.04.md)
         - [P.STR.05 在拼接字符串时，优先使用format!](./safe-guides/coding_practice/strings/P.STR.05.md)
         - [G.STR.01 在实现Display特质时不应调用to_string()方法](./safe-guides/coding_practice/strings/G.STR.01.md)
         - [G.STR.02 在追加字符串时使用push_str方法](./safe-guides/coding_practice/strings/G.STR.02.md)
@@ -203,7 +203,7 @@
         - [P.CAR.01 应该尽量把项目划分为合理的 crate 组合](./safe-guides/coding_practice/cargo/P.CAR.01.md)
         - [P.CAR.02 不要滥用 Features](./safe-guides/coding_practice/cargo/P.CAR.02.md)
         - [P.CAR.03 使用 cargo features 来代替 `--cfg` 条件编译参数](./safe-guides/coding_practice/cargo/P.CAR.03.md)
-        - [P.CAR.04 如果可能的话，使用 `cfg!` 来代替 `#[cfg]`](./safe-guides/coding_practice/cargo/P.CAR.04.md)
+        - [P.CAR.04 宜使用 `cfg!` 来代替 `#[cfg]`](./safe-guides/coding_practice/cargo/P.CAR.04.md)
         - [G.CAR.01 当项目是可执行程序而非库时，建议使用 `src/main.rs` 和 `src/lib.rs` 模式](./safe-guides/coding_practice/cargo/G.CAR.01.md)
         - [G.CAR.02 Crate 的 Cargo.toml 中应该包含必要的元信息](./safe-guides/coding_practice/cargo/G.CAR.02.md)
         - [G.CAR.03 Feature 命名应该避免否定式或多余的前后缀](./safe-guides/coding_practice/cargo/G.CAR.03.md)
@@ -227,8 +227,9 @@
             - [P.MAC.PRO.02 实现过程宏时要对关键特性增加测试](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.02.md)
             - [P.MAC.PRO.03 保证过程宏的卫生性](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.03.md)
             - [P.MAC.PRO.04 给出正确的错误位置](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.04.md)
-            - [P.MAC.PRO.05 代码生成要按情况选择使用过程宏还是 `build.rs`](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.05.md)
-            - [P.MAC.PRO.06 `build.rs` 生成的代码要保证没有任何警告](./safe-guides/coding_practice/macros/proc/P.MAC.PRO.06.md)
+    - [代码生成](./safe-guides/coding_practice/code-generation.md)
+        - [P.GEN.01 代码生成要按情况选择使用过程宏还是 `build.rs`](./safe-guides/coding_practice/code-generation/P.GEN.01.md)
+        - [P.GEN.02 `build.rs` 生成的代码要保证没有任何警告](./safe-guides/coding_practice/code-generation/P.GEN.02.md)
     - [多线程](./safe-guides/coding_practice/threads.md)
         - [锁同步](./safe-guides/coding_practice/threads/lock.md)
             - [P.MTH.LCK.01 多线程下要注意识别锁争用的情况，避免死锁](./safe-guides/coding_practice/threads/lock/P.MTH.LCK.01.md)

src/safe-guides/Appendix/templates/rustfmt.toml.md

@@ -6,43 +6,71 @@
 
 很多选项都是默认的，无需配置。以下配置的都不是默认值。
 
+
+**【只包含 Stable 的选项】**
+
+```toml
+# 万一你要使用 rustfmt 2.0 就需要指定这个·
+version = "Two"
+
+# 统一管理宽度设置，但不包含 comment_width
+use_small_heuristics="MAX"
+# 在match分支中，如果包含了块，也需要加逗号以示分隔
+match_block_trailing_comma=true
+# 当使用 extern 指定外部函数时，不需要显式指定 C-ABI ，默认就是 C-ABI
+force_explicit_abi=false 
+# 如果项目只在 Unix 平台下跑，可以设置该项为 Unix，表示换行符只依赖 Unix
+newline_style="Unix" 
+# 不要将多个 Derive 宏合并为同一行
+merge_derives = false
+
+# 指定 fmt 忽略的目录
+ignore = [
+     "src/test",
+     "test",
+     "docs",
+]
+```
+
+**【也包含还未 Stable 的选项】**
+
+未稳定，代表该选项还有一些 issue 没有解决，待解决以后就会稳定。
+
 ```toml
 # 万一你要使用 rustfmt 2.0 就需要指定这个·
 version = "Two"
 
 # 统一管理宽度设置，但不包含 comment_width
 use_small_heuristics="MAX"
 # 使多个标识符定义保持对齐风格，代码看上去可以非常工整
-indent_style="Visual" 
+indent_style="Visual"  # 未稳定
 # 设置让自定义具有判别式的枚举体按等号对齐的宽度
-enum_discrim_align_threshold = 10 
+enum_discrim_align_threshold = 10  # 未稳定
 # 在match分支中，如果包含了块，也需要加逗号以示分隔
 match_block_trailing_comma=true
 # 自动将同一个 crate 的模块导入合并到一起
-imports_granularity="Crate" 
+imports_granularity="Crate"  # 未稳定
 # StdExternalCrate 导入模块分组规则
 # 1. 导入来自 std、core 和 alloc 的模块需要置于前面一组。
 # 2. 导入来自 第三方库的模块 应该置于中间一组。
 # 3. 导入来自本地 self、super和crate前缀的模块，置于后面一组。
-group_imports="StdExternalCrate" 
+group_imports="StdExternalCrate"  # 未稳定
 # format_macro_matchers 规则说明：
 # 声明宏 模式匹配分支（=> 左侧）中要使用紧凑格式
 # 默认声明宏分支代码体（=> 右侧） 使用宽松格式
-format_macro_matchers=true 
+format_macro_matchers=true  # 未稳定
 # 当使用 extern 指定外部函数时，不需要显式指定 C-ABI ，默认就是 C-ABI
 force_explicit_abi=false 
 # 指定一行注释允许的最大宽度
-comment_width=100
+comment_width=100   # 未稳定
 # wrap_comments 配合 comment_width 使用，自动将一行超过宽带限制的注释切分为多行注释
-wrap_comments=true
+wrap_comments=true  # 未稳定
 # 将 /**/ 注释转为 //
-normalize_comments=true
-# 会报告注释中的 FIXIME
-report_fixme="Unnumbered"
+normalize_comments=true # 未稳定
 # 元组模式匹配的时候允许使用 `..` 来匹配剩余元素
-condense_wildcard_suffixes=true
+condense_wildcard_suffixes=true # 未稳定
 # 如果项目只在 Unix 平台下跑，可以设置该项为 Unix，表示换行符只依赖 Unix
-newline_style="Unix"
+newline_style="Unix" 
 # 不要将多个 Derive 宏合并为同一行
 merge_derives = false
 

src/safe-guides/coding_practice/cargo/P.CAR.04.md

@@ -1,5 +1,5 @@
-## P.CAR.04 如果可能的话，使用 `cfg!` 来代替 `#[cfg]`
+## P.CAR.04 宜使用 `cfg!` 来代替 `#[cfg]`
 
 **【描述】**
 
-`cfg!` 就像正常代码一样，会检查全部函数逻辑，而 `#[cfg]` 是条件编译，会跳过一些 Dead Code。
+`cfg!` 和正常代码一样，会检查全部函数逻辑，而 `#[cfg]` 是条件编译，则会跳过一些 Dead Code。

src/safe-guides/coding_practice/code-generation.md

@@ -0,0 +1,6 @@
+# 代码生成
+
+Rust 中代码生成的方式包括宏 与 `build.rs` 两种方式。关于宏，有独立的规范章节，本章节规范内容包括：
+
+- `build.rs` 使用规范
+- 代码生成相关其他规范

src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.05.md renamed to src/safe-guides/coding_practice/code-generation/P.GEN.01.md

@@ -1,4 +1,4 @@
-## P.MAC.PRO.05 代码生成要按情况选择使用过程宏还是 `build.rs`
+# P.GEN.01 代码生成要按情况选择使用过程宏还是 `build.rs`
 
 **【描述】**
 

src/safe-guides/coding_practice/macros/proc/P.MAC.PRO.06.md renamed to src/safe-guides/coding_practice/code-generation/P.GEN.02.md

@@ -1,4 +1,4 @@
-## P.MAC.PRO.06 `build.rs` 生成的代码要保证没有任何警告
+# P.GEN.02 `build.rs` 生成的代码要保证没有任何警告
 
 **【描述】**
 

src/safe-guides/coding_practice/strings/P.STR.04.md

@@ -1,11 +1,64 @@
-## P.STR.04 只在合适的场景下，使用正则表达式第三方库`regex`
+## P.STR.04 在使用 `Cow<'a, B> `时要注意选择合理场景以便最大化地优化性能
 
 **【描述】**
 
-合适的场景包括：
+ `Cow<'a, B>` 可以减少不必要的内存拷贝。Cow 代表 Clone-On-Write，意味着，使用它可以只在必要的时候再进行拷贝。
 
-1. 不在乎编译文件大小。`regex` 正则引擎是第三方库，引入它的时候意味着还会引入其他依赖，对编译文件大小有要求可以考虑，是否使用 `Cow` 和 内建函数方法来替代。
-2. 对字符串查找性能有极致需求。`regex` 的  `find` 实现性能很好，但是 `replace` 替换就不一定了。对于替换需求，在适合 `Cow<str>` 的场景下，使用 `Cow` 和 内建函数方法来替代 regex 可能更好。
+ 但它并不是万能的，只有在需要大量读取数据但仅有少量情况需要修改时，`Cow<'a, B>` 才能真正起到优化性能的作用。
 
+ 如果不在意依赖库过多，编译文件更大，也可以使用第三方库 `regex` 来处理大数据的搜索匹配和替换等需求，性能更佳。
 
 
+**【反例】**
+
+假设场景一：要处理的大文件中，至少一半数据包含转义符号
+
+```rust
+// 不符合：这种情况在输入不包含转义符号的数据时，也需要对所有字符进行匹配处理，性能较低
+pub fn naive(input: &str) -> String {
+    let mut output = String::new();
+    for c in input.chars() {
+        match c {
+            '<' => output.push_str("&lt;"),
+            '>' => output.push_str("&gt;"),
+            '&' => output.push_str("&amp;"),
+            _ => output.push(c)
+        }
+    }
+    output
+}
+```
+
+假设场景二：要处理的大文件中，几乎所有数据都包含转义符号。这种场景下，使用 `Cow<'a, B>` 对性能也无法起到太大的优化作用，此时宜尝试使用 `regex` 之类的高性能第三方库处理。
+
+**【正例】**
+
+假设场景一：要处理的大文件中，至少一半数据包含转义符号。
+
+```rust
+// 对输入的字符串进行转义
+// 符合： 性能提升大概 1 倍
+pub fn naive<'a, S: Into<Cow<'a, str>>>(input: S) -> Cow<'a, str> {
+    let input = input.into();
+    fn is_trouble(c: char) -> bool {
+        c == '<' || c == '>' || c == '&'
+    }
+
+    if input.contains(is_trouble) {
+        let mut output = String::with_capacity(input.len());
+        for c in input.chars() {
+            match c {
+                '<' => output.push_str("&lt;"),
+                '>' => output.push_str("&gt;"),
+                '&' => output.push_str("&amp;"),
+                _ => output.push(c)
+            }
+        }
+        // 只有在字符串修改的时候才使用 String
+        Cow::Owned(output)
+    } else {
+        //其他情况使用 &str
+        input
+    }
+}
+```

src/safe-guides/overview/convention.md

@@ -75,7 +75,7 @@ Number 从`01`开始递增。其中 `Element` 为领域知识中关键元素（
 | BOX | `Box<T>` 类型 | DRP  |  析构函数 (Drop) |  
 | DCL | 声明宏 (Declarative)  | PRO  |  过程宏 (Procedural) |  
 | LCK | 锁同步 (Lock)  | LKF |  无锁 (Lock Free) |  
-|  |  | OTH | 其他 (Ohters) |  
+| CGN | 代码生成（Code Generation）  | OTH | 其他 (Ohters) |  
 
 
 ## 引用代码开源许可证说明