diff --git a/book-contents/SUMMARY.md b/book-contents/SUMMARY.md index d48ed68c..94577954 100644 --- a/book-contents/SUMMARY.md +++ b/book-contents/SUMMARY.md @@ -54,19 +54,21 @@ - [生命周期](advance/lifetime/intro.md) - [认识生命周期](advance/lifetime/basic.md) - [深入生命周期](advance/lifetime/advance.md) + - [高阶特征约束(HRTB) todo](advance/hrtb.md) - [函数式编程](advance/functional-programing/intro.md) - [闭包closure](advance/functional-programing/closure.md) - [迭代器iterator](advance/functional-programing/iterator.md) - [包和模块](advance/crate-module/intro.md) - [包crate](advance/crate-module/crate.md) - [模块Module](advance/crate-module/module.md) - - [使用use引入](advance/crate-module/use.md) + - [使用use引入模块及受限可见性](advance/crate-module/use.md) - [工作空间workspace](advance/crate-module/workspace.md) - [深入类型之newtype和Sized](advance/custom-type.md) - [格式化输出](advance/formatted-output.md) - [智能指针 todo](advance/smart-pointer/intro.md) - [Box对象(todo)](advance/smart-pointer/box.md) - [Deref和Drop特征(todo)](advance/smart-pointer/deref-drop.md) + - [Cell todo](advance/smart-pointer/cell.md) - [Rc与RefCell(todo)](advance/smart-pointer/rc-refcell.md) - [自引用与内存泄漏(todo)](advance/smart-pointer/self-referrence.md) - [全局变量 todo](advance/global-variable.md) diff --git a/book-contents/advance/crate-module/use.md b/book-contents/advance/crate-module/use.md index 7e8ef00a..ba1cb3d2 100644 --- a/book-contents/advance/crate-module/use.md +++ b/book-contents/advance/crate-module/use.md @@ -1,7 +1,420 @@ -# 使用use引入 +# 使用use及受限可见性 +如果代码中,通篇都是`crate::front_of_house::hosting::add_to_waitlist`这样的函数调用形式,我不知道有谁会喜欢,也许靠代码行数赚工资的人会很喜欢,反正强迫症肯定受不了,而且悲伤的是程序员大多都有强迫症。。。 +因此我们需要一个办法来简化这种使用方式,在Rust中,可以使用`use`关键字把路径提前引入到当前作用域中,随后的调用就可以省略该路径,极大的简化了代码。 -self 在路径中,有两种意思: +## 基本引入方式 +在Rust中,引入模块中的项有两种方式:[绝对路径和相对路径](./module.md#用路径引用模块),这两者在前面章节都有讲过,就不再赘述,先来看看使用绝对路径的引入方式。 + +#### 绝对路径引入模块 +```rust +mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} + +use crate::front_of_house::hosting; + +pub fn eat_at_restaurant() { + hosting::add_to_waitlist(); + hosting::add_to_waitlist(); + hosting::add_to_waitlist(); +} +``` + +这里,我们使用`use`和绝对路径的方式,将`hosting`模块引入到当前作用域中,然后只需通过`hosting::add_to_waitlist`的方式,即可调用目标模块中的函数,相比`crate::front_of_house::hosting::add_to_waitlist()`的方式要简单的多,那么还能更简单吗? + +#### 相对路径引入模块中的函数 +在下面代码中,我们不仅要使用相对路径进行引入,而且与上面引入`hosting`模块不同,直接引入该模块中的`add_to_waitlist`函数: +```rust +mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} + +use front_of_house::hosting::add_to_waitlist; + +pub fn eat_at_restaurant() { + add_to_waitlist(); + add_to_waitlist(); + add_to_waitlist(); +} +``` + +很明显,三兄弟又变得更短了,不过,怎么觉得这句话怪怪的。。 + +#### 引入模块还是函数 +从使用简洁性来说,引入函数自然是更甚一筹,但是在某些时候,引入模块会更好: + +- 需要引入同一个模块的多个函数 +- 作用域中存在同名函数 + +在以上两种情况中, 使用`use front_of_house::hosting`引入模块要比`use front_of_house::hosting::add_to_waitlist;`引入函数更好。 + +例如,如果想使用`HashMap`,那么直接引入该结构体是比引入模块更好的选择,因为在`collections`模块中,我们只需要使用一个`HashMap`结构体: +```rust +use std::collections::HashMap; + +fn main() { + let mut map = HashMap::new(); + map.insert(1, 2); +} +``` + +其实严格来说,对于引用方式并没有需要遵守的惯例,主要还是取决于你的喜好,不过我们建议:**优先使用最细粒度(引入函数、结构体等)的引用方式,如果引起了某种麻烦(例如前面两种情况),再使用引入模块的方式**。 + +## 避免同名引用 +根据上一章节的内容,我们只要保证同一个模块中不存在同名项就行,模块之间、包之间的同名,谁管的着谁啊,话虽如此,一起看看,如果遇到同名的情况该如何处理. + +#### 使用模块::函数 +```rust +use std::fmt; +use std::io; + +fn function1() -> fmt::Result { + // --snip-- +} + +fn function2() -> io::Result<()> { + // --snip-- +} +``` + +上面的例子给出了很好的解决方案,使用模块引入的方式,具体的`Result`通过`模块::Result`的方式进行调用。 + +可以看出,避免同名冲突的关键,就是使用**父模块的方式来调用**,除此之外,还可以给予引入的项一个新的名称。 + +#### `as`别名引用 +对于同名冲突问题,还可以使用`as`关键字来解决。它可以赋予引入项一个全新的名称: +```rust +use std::fmt::Result; +use std::io::Result as IoResult; + +fn function1() -> Result { + // --snip-- +} + +fn function2() -> IoResult<()> { + // --snip-- +} +``` + +如上所示,首先通过`use std::io::Result`将`Result`引入到作用域,然后使用`as`给予它一个全新的名称`IoResult`,这样就不会再产生冲突: + +- `Result`代表`std::fmt::Result` +- `IoResult`代表`std:io::Result` + +## 引入项再导出 +当外部的模块项`A`被引入到当前模块中时,它的可见性自动被设置为私有的,如果你允许其它外部代码引入我们模块中的`A`,那么可以对它进行再导出: +```rust +mod front_of_house { + pub mod hosting { + pub fn add_to_waitlist() {} + } +} + +pub use crate::front_of_house::hosting; + +pub fn eat_at_restaurant() { + hosting::add_to_waitlist(); + hosting::add_to_waitlist(); + hosting::add_to_waitlist(); +} +``` + +如上,使用`pub use`即可实现。这里`use`代表引入`hosting`模块到当前作用域,`pub`表示将该引入的内容再度设置为可见。 + +当你希望将内部的实现细节隐藏起来或者按照某个目的组织代码时,可以使用`pub use`再导出,例如统一使用一个模块来提供对外的API,那该模块就可以引入其它模块中的API,然后进行再导出,最终对于用户来说,所有的API都是由一个模块统一提供的。 + +## 使用三方包 +之前我们一直在引入标准库模块或者自定义模块,现在来引入下三方包中的模块,关于如何引入外部依赖,我们在[Cargo入门](../../first-try/cargo.md#package配置段落)中就有讲,这里直接给出操作步骤: + +1. 修改Cargo.toml文件,在`[dependencies]`区域添加一行: `rand = "0.8.3"` +2. 此时,如果你用的是`VSCode`和`rust-analyzer`插件,该插件会自动拉取该库,你可能需要等它完成后,再进行下一步(VSCODE左下角有提示) + +好了,此时,`rand`包已经被我们添加到依赖中,下一步就是在代码中使用: +```rust +use rand::Rng; + +fn main() { + let secret_number = rand::thread_rng().gen_range(1..101); +} +``` + +这里使用`use`引入了三方包`rand`中的`Rng`特征,因为我们需要调用的`gen_range`方法定义在该特征中。 + +#### crates.io, lib.rs +Rust社区已经为我们贡献了大量高质量的三方包,你可以在`crates.io`或者`lib.rs`中检索和使用,从目前来说查找包更推荐`lib.rs`,搜索功能更强大,内容展示也更加合理, 但是下载依赖包还是得用`crates.io`。 + +你可以在网站上搜索`rand`包,看看它的文档使用方式是否和我们之前引入方式相一致: 在网上找到想要的包,然后将你想要的包和版本信息写入到`Cargo.toml`中。 + +## 使用{}简化引入方式 +对于以下一行一行的引入方式: +```rust +use std::collections::HashMap; +use std::collections::BTreeMap; +use std::collections::HashSet; + +use std::cmp::Ordering; +use std::io; +``` + +可以使用`{}`来一起引入进来,在大型项目中,使用这种方式来引入,可以减少大量`use`的使用: +```rust +use std::collections::{HashMap,BTreeMap,HashSet}; +use std::{cmp::Ordering, io}; +``` + +对于下面的同时引入模块和模块中的项: +```rust +use std::io; +use std::io::Write; +``` + +可以使用`{}`的方式进行简化: +```rust +use std::io::{self, Write}; +``` + +#### self + +上面使用到了模块章节提到的`self`关键字,用来替代模块自身,结合上一节中的`self`,可以得出它在模块中的两个用途: + +- `use self::xxx`,表示加载当前模块中的`xxx`。此时`self`可省略 +- `use xxx::{self, yyy}`,表示,加载当前路径下模块`xxx`本身,以及模块`xxx`下的`yyy`; + +## 使用*引入模块下的所有项 +对于之前一行一行引入`std::collections`的方式,我们还可以使用 +```rust +use std::collections::*; +``` + +以上这种方式来引入`std::collections`模块下的所有公共项,这些公共项自然包含了`HashMap`,`HashSet`等想手动引入的集合类型。 + +当使用`*`来引入的时候要格外小心,因为你很难知道到底哪些被引入到了当前作用域中,有哪些会和你自己程序中的名称相冲突: +```rust +use std::collections::*; + +struct HashMap; +fn main() { + let mut v = HashMap::new(); + v.insert("a", 1); +} +``` + +以上代码中,`std::collection::HashMap`被`*`引入到当前作用域,但是由于存在另一个同名的结构体,因此`HashMap::new`根本不存在,因为对于编译器来说,本地同名类型的优先级更高。 + +在实际项目中,这种引用方式往往用于快速写测试代码,它可以把所有东西一次性引入到`tests`模块中。 + +## 受限的可见性 +在上一节中,我们学习了[可见性](./module.md#代码可见性)这个概念,这也是模块体系中最为核心的概念,控制了模块中哪些内容可以被外部看见,但是在实际使用时,光被外面看到还不行,我们还想控制哪些人能看,这就是Rust提供的受限可见性。 + +例如,在Rust中,包是一个模块树,我们可以通过`pub(crate) item;`这种方式来实现:`item`虽然是对外可见的,但是只在当前包内可见,外部包无法引用到该`item`。 + +如果我们想要让某一项可以在整个包中都可以被使用,那么有两种办法: + +- 在包根中定义一个非`pub`类型的`X`(父模块的项对子模块都是可见的,因此包根中的项对模块树上的所有模块都可见) +- 在子模块中定义一个`pub`类型的`Y`,同时通过`use`将其引入到包根 + +```rust +mod a { + pub mod b { + pub fn c() { + println!("{:?}",crate::X); + } + + #[derive(Debug)] + pub struct Y; + } +} + +#[derive(Debug)] +struct X; +use a::b::Y; +fn d() { + println!("{:?}",Y); +} +``` + +以上代码充分说明了之前两种办法的使用方式,但是有时我们会遇到这两种方法都不太好用的时候。例如希望对于某些特定的模块可见,但是对于其他模块又不可见: +```rust +// 目标: `a` 导出 `I`, `bar`, and `foo`, 其他的不导出 +pub mod a { + pub const I: i32 = 3; + + fn semisecret(x: i32) -> i32 { use self::b::c::J; x + J } + + pub fn bar(z: i32) -> i32 { semisecret(I) * z } + pub fn foo(y: i32) -> i32 { semisecret(I) + y } + + mod b { + mod c { + const J: i32 = 4; + } + } +} +``` + +这段代码会报错,因为与父模块中的项对子模块可见相反,子模块中的项对父模块是不可见的。这里`a`->`b`->`c`形成了父子模块链,那`c`中的`J`自然对`a`模块不可见。 + +如果使用之前的可见性方式,那么要保持`J`私有,同时让`a`继续使用`semisecret`函数的办法是将该函数移动到`c`模块中,然后用`pub use`进行再导出: +```rust +pub mod a { + pub const I: i32 = 3; + + use self::b::semisecret; + + pub fn bar(z: i32) -> i32 { semisecret(I) * z } + pub fn foo(y: i32) -> i32 { semisecret(I) + y } + + mod b { + pub use self::c::semisecret; + mod c { + const J: i32 = 4; + pub fn semisecret(x: i32) -> i32 { x + J } + } + } +} +``` + +这段代码说实话问题不大,但是有些破坏了我们之前的逻辑,如果想保持代码逻辑,同时又只让`J`在`a`内可见怎么办? + +```rust +pub mod a { + pub const I: i32 = 3; + + fn semisecret(x: i32) -> i32 { use self::b::c::J; x + J } + + pub fn bar(z: i32) -> i32 { semisecret(I) * z } + pub fn foo(y: i32) -> i32 { semisecret(I) + y } + + mod b { + pub(in crate::a) mod c { + pub(in crate::a) const J: i32 = 4; + } + } +} +``` + +通过`pub(in crate::a)`的方式,我们指定了模块`c`和常量`J`的可见范围都是`a`模块中,`a`之外的模块是完全访问不到它们的。 + +#### 限制可见性语法 +`pub(crate)`或`pub(in crate::a)`就是限制可见性语法, 前者是限制在整个包内可见,后者是通过绝对路径,限制在包内的某个模块内可见,总结一下: + +- `pub`意味着可见性无任何限制 +- `pub(crate)`, 表示在当前包可见 +- `pub(self)`, 在当前模块可见 +- `pub(super)`,在父模块可见 +- `pub(in )`, 表示在某个路径代表的模块中可见, `path`必须是父模块或者祖先模块 + + +#### 一个综合例子 +```rust +// 一个名为 `my_mod` 的模块 +mod my_mod { + // 模块中的项默认具有私有的可见性 + fn private_function() { + println!("called `my_mod::private_function()`"); + } + + // 使用 `pub` 修饰语来改变默认可见性。 + pub fn function() { + println!("called `my_mod::function()`"); + } + + // 在同一模块中,项可以访问其它项,即使它是私有的。 + pub fn indirect_access() { + print!("called `my_mod::indirect_access()`, that\n> "); + private_function(); + } + + // 模块也可以嵌套 + pub mod nested { + pub fn function() { + println!("called `my_mod::nested::function()`"); + } + + #[allow(dead_code)] + fn private_function() { + println!("called `my_mod::nested::private_function()`"); + } + + // 使用 `pub(in path)` 语法定义的函数只在给定的路径中可见。 + // `path` 必须是父模块(parent module)或祖先模块(ancestor module) + pub(in crate::my_mod) fn public_function_in_my_mod() { + print!("called `my_mod::nested::public_function_in_my_mod()`, that\n > "); + public_function_in_nested() + } + + // 使用 `pub(self)` 语法定义的函数则只在当前模块中可见。 + pub(self) fn public_function_in_nested() { + println!("called `my_mod::nested::public_function_in_nested"); + } + + // 使用 `pub(super)` 语法定义的函数只在父模块中可见。 + pub(super) fn public_function_in_super_mod() { + println!("called my_mod::nested::public_function_in_super_mod"); + } + } + + pub fn call_public_function_in_my_mod() { + print!("called `my_mod::call_public_funcion_in_my_mod()`, that\n> "); + nested::public_function_in_my_mod(); + print!("> "); + nested::public_function_in_super_mod(); + } + + // `pub(crate)` 使得函数只在当前包中可见 + pub(crate) fn public_function_in_crate() { + println!("called `my_mod::public_function_in_crate()"); + } + + // 嵌套模块的可见性遵循相同的规则 + mod private_nested { + #[allow(dead_code)] + pub fn function() { + println!("called `my_mod::private_nested::function()`"); + } + } +} + +fn function() { + println!("called `function()`"); +} + +fn main() { + // 模块机制消除了相同名字的项之间的歧义。 + function(); + my_mod::function(); + + // 公有项,包括嵌套模块内的,都可以在父模块外部访问。 + my_mod::indirect_access(); + my_mod::nested::function(); + my_mod::call_public_function_in_my_mod(); + + // pub(crate) 项可以在同一个 crate 中的任何地方访问 + my_mod::public_function_in_crate(); + + // pub(in path) 项只能在指定的模块中访问 + // 报错!函数 `public_function_in_my_mod` 是私有的 + //my_mod::nested::public_function_in_my_mod(); + // 试一试 ^ 取消该行的注释 + + // 模块的私有项不能直接访问,即便它是嵌套在公有模块内部的 + + // 报错!`private_function` 是私有的 + //my_mod::private_function(); + // 试一试 ^ 取消此行注释 + + // 报错!`private_function` 是私有的 + //my_mod::nested::private_function(); + // 试一试 ^ 取消此行的注释 + + // Error! `private_nested` is a private module + //my_mod::private_nested::function(); + // 试一试 ^ 取消此行的注释 +} +``` -use self::xxx 表示,加载当前模块中的 xxx。此时 self 可省略; -use xxx::{self, yyy},表示,加载当前路径下模块 xxx 本身,以及模块 xxx 下的 yyy; \ No newline at end of file diff --git a/book-contents/advance/hrtb.md b/book-contents/advance/hrtb.md new file mode 100644 index 00000000..15e0ec05 --- /dev/null +++ b/book-contents/advance/hrtb.md @@ -0,0 +1,8 @@ +# 高阶特征约束(HRTB) todo + + +## for<'a> + +https://www.reddit.com/r/rust/comments/rq43c6/generic_fn_impl_for_iterating_over_mut_items_twice/ + +https://www.reddit.com/r/rust/comments/6uobit/fora_lifetime_syntax/ diff --git a/book-contents/advance/smart-pointer/cell.md b/book-contents/advance/smart-pointer/cell.md new file mode 100644 index 00000000..de1504f0 --- /dev/null +++ b/book-contents/advance/smart-pointer/cell.md @@ -0,0 +1,4 @@ +# Cell todo + + +https://ryhl.io/blog/temporary-shared-mutation/ \ No newline at end of file diff --git a/book-contents/pitfalls/multiple-mutable-references.md b/book-contents/pitfalls/multiple-mutable-references.md index 6cd9c377..283c6c50 100644 --- a/book-contents/pitfalls/multiple-mutable-references.md +++ b/book-contents/pitfalls/multiple-mutable-references.md @@ -144,6 +144,89 @@ fn increase(&mut self) { 在这里,我们不再单独声明变量`b`,而是直接调用`self.b+=1`进行递增,根据借用生命周期[NLL](https://course.rs/advance/lifetime/advance.html#nllnon-lexical-lifetime)的规则,第一个可变借用`self.increase_a()`的生命周期随着方法调用的结束而结束,那么就不会影响`self.b += 1`中的借用。 + +## 闭包中的例子 +再来看一个使用了闭包的例子: +```rust +use tokio::runtime::Runtime; + +struct Server { + number_of_connections : u64 +} + +impl Server { + pub fn new() -> Self { + Server { number_of_connections : 0} + } + + pub fn increase_connections_count(&mut self) { + self.number_of_connections += 1; + } +} + +struct ServerRuntime { + runtime: Runtime, + server: Server +} + +impl ServerRuntime { + pub fn new(runtime: Runtime, server: Server) -> Self { + ServerRuntime { runtime, server } + } + + pub fn increase_connections_count(&mut self) { + self.runtime.block_on(async { + self.server.increase_connections_count() + }) + } +} +``` + +代码中使用了`tokio`,在`increase_connections_count`函数中启动了一个异步任务,并且等待它的完成。这个函数中分别引用了`self`中的不同字段:`runtime`和`server`,但是可能因为闭包的原因,编译器没有像本文最开始的例子中那样聪明,并不能识别这两个引用仅仅引用了同一个结构体的不同部分,因此报错了: +```console +error[E0501]: cannot borrow `self.runtime` as mutable because previous closure requires unique access + --> the_little_things\src\main.rs:28:9 + | +28 | self.runtime.block_on(async { + | __________^____________--------_______- + | | | | + | | _________| first borrow later used by call + | || +29 | || self.server.increase_connections_count() + | || ---- first borrow occurs due to use of `self` in generator +30 | || }) + | ||_________-^ second borrow occurs here + | |__________| + | generator construction occurs here +``` + +#### 解决办法 +解决办法很粗暴,既然编译器不能理解闭包中的引用是不同的,那么我们就主动告诉它: +```rust +pub fn increase_connections_count(&mut self) { + let runtime = &mut self.runtime; + let server = &mut self.server; + runtime.block_on(async { + server.increase_connections_count() + }) +} +``` + +上面通过变量声明的方式,在闭包外声明了两个变量分别引用结构体`self`的不同字段,这样一来,编译器就不会那么笨,编译顺利通过。 + +你也可以这么写: +```rust +pub fn increase_connections_count(&mut self) { + let ServerRuntime { runtime, server } = self; + runtime.block_on(async { + server.increase_connections_count() + }) +} +``` + +当然,如果难以解决,还有一个笨办法,那就是将`server`和`runtime`分离开来,不要放在一个结构体中。 + ## 总结 -心中有剑,手中无剑,是武学至高境界,对于代码而言,亦是如此,当你掌握了内在的原理,就算遇到了未知,也能运用这些原理分析和解决。 +心中有剑,手中无剑,是武学至高境界。 +本文列出的那条编译规则,在未来就将是大家心中的那把剑,当这些心剑招式足够多时,量变产生质变,终将天下无敌。 \ No newline at end of file diff --git a/writing-material/posts/lifetime.md b/writing-material/posts/lifetime.md new file mode 100644 index 00000000..1364b1c8 --- /dev/null +++ b/writing-material/posts/lifetime.md @@ -0,0 +1,5 @@ +## for<'a> + +https://www.reddit.com/r/rust/comments/rq43c6/generic_fn_impl_for_iterating_over_mut_items_twice/ + +https://www.reddit.com/r/rust/comments/6uobit/fora_lifetime_syntax/