diff --git a/README.md b/README.md index bbb9b6db..6c9994ae 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,9 @@ - 在线阅读 - 官方： [https://course.rs](https://course.rs) - 知乎： [支持章节内目录跳转，很好用!](https://www.zhihu.com/column/c_1452781034895446017) - + +- Rust语言社区: QQ群 1009730433 + > 学习 Rust 光看书不够，精心设计的习题和项目实践可以让你事半功倍。[Rust By Practice](https://github.com/sunface/rust-by-practice) 是本书的配套习题和实践，覆盖了 easy to hard 各个难度，满足大家对 Rust 的所有期待。 > > [Rust 语言周刊](https://github.com/sunface/rust-weekly)，每周一发布，精选过去一周的技术文章、业界新闻、开源项目和 Rust 语言动态。 @@ -42,6 +44,7 @@ - [@JesseAtSZ](https://github.com/JesseAtSZ) - [@1132719438](https://github.com/1132719438) - [@Mintnoii](https://github.com/Mintnoii) +- [@Rustln](https://github.com/rustln) 尤其感谢这些主要贡献者，谢谢你们花费大量时间贡献了多处`fix`和高质量的内容优化。非常感动，再次感谢～～ @@ -56,5 +59,5 @@ 因为它们绝大部分是支持 APACHE + MIT 双协议的，因此我们选择了遵循其中的 MIT 协议，并在这里统一对借鉴的书籍进行说明。 -## 一路有你 -欢迎加入QQ交流群 1009730433 进行沟通交流。 +## Rust语言社区 +QQ群 1009730433， 欢迎大家加入，一起 happy，一起进步。 diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 611d70b4..9b54831d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -156,12 +156,14 @@ - [手把手带你实现链表 doing](too-many-lists/intro.md) - [我们到底需不需要链表](too-many-lists/do-we-need-it.md) - [不太优秀的单向链表：栈](too-many-lists/bad-stack/intro.md) - - [数据布局](too-many-lists/bad-stack/layout.md) - - [基本操作](too-many-lists/bad-stack/basic-operations.md) - - [最后实现](too-many-lists/bad-stack/final-code.md) - - - + - [数据布局](too-many-lists/bad-stack/layout.md) + - [基本操作](too-many-lists/bad-stack/basic-operations.md) + - [最后实现](too-many-lists/bad-stack/final-code.md) + - [还可以的单向链表](too-many-lists/ok-stack/intro.md) + - [优化类型定义](too-many-lists/ok-stack/type-optimizing.md) + - [定义 Peek 函数](too-many-lists/ok-stack/peek.md) + - [IntoIter 和 Iter](too-many-lists/ok-stack/iter.md) + - [IterMut以及完整代码](too-many-lists/ok-stack/itermut.md) - [易混淆概念解析](confonding/intro.md) - [切片和切片引用](confonding/slice.md) - [Eq 和 PartialEq](confonding/eq.md) diff --git a/src/basic/ownership/ownership.md b/src/basic/ownership/ownership.md index ef3ef21f..fe1e26fb 100644 --- a/src/basic/ownership/ownership.md +++ b/src/basic/ownership/ownership.md @@ -262,7 +262,7 @@ Rust 有一个叫做 `Copy` 的特征，可以用在类似整型这样在栈中 - 所有浮点数类型，比如 `f64`。 - 字符类型，`char`。 - 元组，当且仅当其包含的类型也都是 `Copy` 的时候。比如，`(i32, i32)` 是 `Copy` 的，但 `(i32, String)` 就不是。 -- 引用类型，例如[转移所有权](#转移所有权)中的最后一个例子 +- 不可变引用 `&T` ，例如[转移所有权](#转移所有权)中的最后一个例子，**但是注意: 可变引用 `&mut T` 是不可以 Copy的** ## 函数传值与返回 diff --git a/src/basic/trait/advance-trait.md b/src/basic/trait/advance-trait.md index 085723f4..a5293933 100644 --- a/src/basic/trait/advance-trait.md +++ b/src/basic/trait/advance-trait.md @@ -20,7 +20,7 @@ pub trait Iterator { 同时，`next` 方法也返回了一个 `Item` 类型，不过使用 `Option` 枚举进行了包裹，假如迭代器中的值是 `i32` 类型，那么调用 `next` 方法就将获取一个 `Option` 的值。 -还记得 `Self` 吧？在之前的章节[提到过](https://course.rs/basic/trait/trait-object#self与self)， `Self` 用来指代当前的特征实例，那么 `Self::Item` 就用来指代特征实例中具体的 `Item` 类型： +还记得 `Self` 吧？在之前的章节[提到过](https://course.rs/basic/trait/trait-object#self-与-self)， **`Self` 用来指代当前调用者的具体类型，那么 `Self::Item` 就用来指代该类型实现中定义的 `Item` 类型**： ```rust impl Iterator for Counter { @@ -30,9 +30,14 @@ impl Iterator for Counter { // --snip-- } } + +fn main() { + let c = Counter{..} + c.next() +} ``` -在上述代码中，我们为 `Counter` 类型实现了 `Iterator` 特征，那么 `Self` 就是当前的 `Iterator` 特征对象， `Item` 就是 `u32` 类型。 +在上述代码中，我们为 `Counter` 类型实现了 `Iterator` 特征，变量 `c` 是特征 `Iterator` 的实例，也是 `next` 方法的调用者。 结合之前的黑体内容可以得出：对于 `next` 方法而言，`Self` 是调用者 `c` 的具体类型： `Counter`，而 `Self::Item` 是 `Counter` 中定义的 `Item` 类型: `u32`。 聪明的读者之所以聪明，是因为你们喜欢联想和举一反三，同时你们也喜欢提问：为何不用泛型，例如如下代码： diff --git a/src/cargo/reference/features/intro.md b/src/cargo/reference/features/intro.md index edf5f609..e91fa58d 100644 --- a/src/cargo/reference/features/intro.md +++ b/src/cargo/reference/features/intro.md @@ -4,7 +4,7 @@ ## [features] -`Featuure` 可以通过 `Cargo.toml` 中的 `[features]` 部分来定义：其中每个 `feature` 通过列表的方式指定了它所能启用的其他 `feature` 或可选依赖。 +`Feature` 可以通过 `Cargo.toml` 中的 `[features]` 部分来定义：其中每个 `feature` 通过列表的方式指定了它所能启用的其他 `feature` 或可选依赖。 假设我们有一个 2D 图像处理库，然后该库所支持的图片格式可以通过以下方式启用： diff --git a/src/index-list.md b/src/index-list.md index e7bed5f0..83ead863 100644 --- a/src/index-list.md +++ b/src/index-list.md @@ -6,5 +6,250 @@ 可能大家会有疑问，不是有站内搜索功能嘛？是的，但是尴尬的是：首先它不支持中文，其次就算支持了中文，也一样不好用，我们需要的是快速精准地找到内容而不是模糊的查询内容。 -## 索引列表 todo +# 索引列表 doing + + +| NN | NN | NN | NN | NN | NN | NN | NN | NN | NN | NN | NN | NN | NN | +| :---------: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | :-----: | +| [Sym](#Sym) | [A](#A) | [B](#B) | [C](#C) | [D](#D) | [E](#E) | [F](#F) | [G](#G) | [H](#H) | [I](#I) | [J](#J) | [K](#K) | [L](#L) | [M](#M) | +| [N](#N) | [O](#O) | [P](#P) | [Q](#Q) | [R](#R) | [S](#S) | [T](#T) | [U](#U) | [V](#V) | [W](#W) | [X](#X) | [Y](#Y) | [Z](#Z) | + +## Sym + +| 名称 | 关键字 | 简介 | +| ----------------------- | ------------ | -------------------------- | +| [?] | 错误传播 | 用于简化错误传播 | +| [()] | 单元类型 | 单元类型，无返回值 | +| `!` : [1] 函数 [2] 类型 | 永不返回 | 永不返回 | +| [@] | 变量绑定 | 为一个字段绑定另外一个变量 | +| ['a: 'b] | 生命周期约束 | | +| A | | AIntroduction | + +[?]: https://course.rs/basic/result-error/result.html#传播界的大明星- +[()]: https://course.rs/basic/base-type/function.html#无返回值 +[1]: https://course.rs/basic/base-type/function.html#永不返回的函数 +[2]: https://course.rs/advance/into-types/custom-type.html#永不返回类型 +[@]: https://course.rs/basic/match-pattern/all-patterns.html#绑定 +['a: 'b]: https://course.rs/advance/lifetime/advance.html#生命周期约束-hrtb + +[back](#head) + +## A + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| A | KWA | AIntroduction | + +[back](#head) + +## B + +| 名称 | 关键字 | 简介 | +| ---------- | --------- | -------------------------------------- | +| [变量遮蔽] | shadowing | 允许声明相同的变量名，后者会遮蔽掉前者 | +| B | KWB | BIntroduction | + +[变量遮蔽]: https://course.rs/basic/variable.html#变量遮蔽shadowing + +[back](#head) + +## C + +| 名称 | 关键字 | 简介 | +| ------ | ------ | -------------------------------- | +| [常量] | const | const MAX_POINTS: u32 = 100_000; | +| C | KWC | CIntroduction | + +[常量]: https://course.rs/basic/variable.html#变量和常量之间的差异 + +[back](#head) + +## D + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| D | KWD | DIntroduction | + +[back](#head) + +## E + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| E | KWE | EIntroduction | + +[back](#head) + +## F + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| F | KWF | FIntroduction | + +[back](#head) + +## G + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| G | KWG | GIntroduction | + +[back](#head) + +## H + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| H | KWH | HIntroduction | + +[back](#head) + +## I + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| I | KWI | IIntroduction | + +[back](#head) + +## J + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| J | KWJ | JIntroduction | + +[back](#head) + +## K + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| K | KWK | KIntroduction | + +[back](#head) + +## L + +| 名称 | 关键字 | 简介 | +| --------- | -------- | --------------------------- | +| [let] | 变量绑定 | let x : u32 = 5; | +| [let mut] | 可变变量 | let mut x : u32 = 5; x = 9; | +| L | KWL | LIntroduction | + +[let]: https://course.rs/basic/variable.html#变量绑定 +[let mut]: https://course.rs/basic/variable.html#变量可变性 + +[back](#head) + +## M + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| M | KWM | MIntroduction | + +[back](#head) + +## N + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| N | KWN | NIntroduction | + +[back](#head) + +## O + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| O | KWO | OIntroduction | + +[back](#head) + +## P + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| P | KWP | PIntroduction | + +[back](#head) + +## Q + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| Q | KWQ | QIntroduction | + +[back](#head) + +## R + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| R | KWR | RIntroduction | + +[back](#head) + +## S + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| S | KWS | SIntroduction | + +[back](#head) + +## T + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| T | KWT | TIntroduction | + +[back](#head) + +## U + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| U | KWU | UIntroduction | + +[back](#head) + +## V + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| V | KWV | VIntroduction | + +[back](#head) + +## W + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| W | KWW | WIntroduction | + +[back](#head) + +## X + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| X | KWX | XIntroduction | + +[back](#head) + +## Y + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| Y | KWY | YIntroduction | + +[back](#head) + +## Z + +| 名称 | 关键字 | 简介 | +| ---- | ------ | ------------- | +| Z | KWZ | ZIntroduction | + +[back](#head) diff --git a/src/too-many-lists/ok-stack/intro.md b/src/too-many-lists/ok-stack/intro.md new file mode 100644 index 00000000..921b08e7 --- /dev/null +++ b/src/too-many-lists/ok-stack/intro.md @@ -0,0 +1,10 @@ +# 还可以的单向链表 +在之前我们写了一个最小可用的单向链表，下面一起来完善下，首先创建一个新的文件 `src/second.rs`，然后在 `lib.rs` 中引入： +```rust +// in lib.rs + +pub mod first; +pub mod second; +``` + +并将 `first.rs` 中的所有内容拷贝到 `second.rs` 中。 \ No newline at end of file diff --git a/src/too-many-lists/ok-stack/iter.md b/src/too-many-lists/ok-stack/iter.md new file mode 100644 index 00000000..d8a8101e --- /dev/null +++ b/src/too-many-lists/ok-stack/iter.md @@ -0,0 +1,443 @@ +## 迭代器 +集合类型可以通过 `Iterator` 特征进行迭代，该特征看起来比 `Drop` 要复杂点： +```rust +pub trait Iterator { + type Item; + fn next(&mut self) -> Option; +} +``` + +这里的 `Item` 是[关联类型](https://course.rs/basic/trait/advance-trait.html#关联类型)，用来指代迭代器中具体的元素类型，`next` 方法返回的也是该类型。 + +其实上面的说法有点不够准确，原因是 `next` 方法返回的是 `Option`，使用 `Option` 枚举的原因是为了方便用户，不然用户需要 `has_next` 和 `get_next` 才能满足使用需求。有值时返回 `Some(T)`，无值时返回 `None`，这种 API 设计工程性更好，也更加安全，完美！ + +有点悲剧的是, Rust 截至目前还没有 `yield` 语句，因此我们需要自己来实现相关的逻辑。还有点需要注意，每个集合类型应该实现 3 种迭代器类型： + +- `IntoIter` - `T` +- `IterMut` - `&mut T` +- `Iter` - `&T` + +也许大家不认识它们，但是其实很好理解，`IntoIter` 类型迭代器的 `next` 方法会拿走被迭代值的所有权，`IterMut` 是可变借用， `Iter` 是不可变借用。事实上，类似的[命名规则](https://course.rs/practice/naming.html#一个集合上的方法如果返回迭代器需遵循命名规则iteriter_mutinto_iter-c-iter)在 Rust 中随处可见，当熟悉后，以后见到类似的命名大家就可以迅速的理解其对值的运用方式。 + +## IntoIter +先来看看 `IntoIter` 该怎么实现: +```rust +pub struct IntoIter(List); + +impl List { + pub fn into_iter(self) -> IntoIter { + IntoIter(self) + } +} + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { + // access fields of a tuple struct numerically + self.0.pop() + } +} +``` + +这里我们通过[元组结构体](https://course.rs/basic/compound-type/struct.html#元组结构体tuple-struct)的方式定义了 `IntoIter`，下面来测试下: +```rust +#[test] +fn into_iter() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.into_iter(); + assert_eq!(iter.next(), Some(3)); + assert_eq!(iter.next(), Some(2)); + assert_eq!(iter.next(), Some(1)); + assert_eq!(iter.next(), None); +} +``` + +```shell +> cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 4 tests +test first::test::basics ... ok +test second::test::basics ... ok +test second::test::into_iter ... ok +test second::test::peek ... ok + +test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured +``` + +## Iter +相对来说，`IntoIter` 是最好实现的，因为它只是简单的拿走值，不涉及到引用，也不涉及到生命周期，而 `Iter` 就有所不同了。 + +这里的基本逻辑是我们持有一个当前节点的指针，当生成一个值后，该指针将指向下一个节点。 + +```rust +pub struct Iter { + next: Option<&Node>, +} + +impl List { + pub fn iter(&self) -> Iter { + Iter { next: self.head.map(|node| &node) } + } +} + +impl Iterator for Iter { + type Item = &T; + + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.map(|node| &node); + &node.elem + }) + } +} +``` + +```shell +> cargo build + +error[E0106]: missing lifetime specifier + --> src/second.rs:72:18 + | +72 | next: Option<&Node>, + | ^ expected lifetime parameter + +error[E0106]: missing lifetime specifier + --> src/second.rs:82:17 + | +82 | type Item = &T; + | ^ expected lifetime parameter +``` + +许久不见的错误又冒了出来，而且这次直指 Rust 中最难的点之一：生命周期。关于生命周期的讲解，这里就不再展开，如果大家还不熟悉，强烈建议看看[此章节](https://course.rs/advance/lifetime/intro.html)，然后再继续。 + +首先，先加一个生命周期试试： +```rust +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} +``` + +```shell +> cargo build + +error[E0106]: missing lifetime specifier + --> src/second.rs:83:22 + | +83 | impl Iterator for Iter { + | ^^^^^^^ expected lifetime parameter + +error[E0106]: missing lifetime specifier + --> src/second.rs:84:17 + | +84 | type Item = &T; + | ^ expected lifetime parameter + +error: aborting due to 2 previous errors +``` + +好的，现在有了更多的提示，来按照提示修改下代码: +```rust +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} + +impl<'a, T> List { + pub fn iter(&'a self) -> Iter<'a, T> { + Iter { next: self.head.map(|node| &'a node) } + } +} + +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + fn next(&'a mut self) -> Option { + self.next.map(|node| { + self.next = node.next.map(|node| &'a node); + &'a node.elem + }) + } +} +``` + +```shell +> cargo build + +error: expected `:`, found `node` + --> src/second.rs:77:47 + | +77 | Iter { next: self.head.map(|node| &'a node) } + | ---- while parsing this struct ^^^^ expected `:` + +error: expected `:`, found `node` + --> src/second.rs:85:50 + | +85 | self.next = node.next.map(|node| &'a node); + | ^^^^ expected `:` + +error[E0063]: missing field `next` in initializer of `second::Iter<'_, _>` + --> src/second.rs:77:9 + | +77 | Iter { next: self.head.map(|node| &'a node) } + | ^^^^ missing `next` +``` + +怎么回事。。感觉错误犹如雨后春笋般冒了出来，Rust 是不是被我们搞坏了 :( + +现在看来，我们的生命周期是用错了，聪明的同学可能已经看出了端倪，那么再修改下试试； +```rust +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} + +// 这里无需生命周期，因为 List 没有使用生命周期的关联项 +impl List { + // 这里我们为 `iter` 生命一个生命周期 'a , 此时 `&self` 需要至少和 `Iter` 活得一样久 + pub fn iter<'a>(&'a self) -> Iter<'a, T> { + Iter { next: self.head.map(|node| &node) } + } +} + +// 这里声明生命周期是因为下面的关联类型 Item 需要 +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + + // 这里无需更改，因为上面已经处理了. + // Self 依然是这么棒 + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.map(|node| &node); + &node.elem + }) + } +} +``` + +现在，我们也许可以自信的编译下试试了： +```shell +cargo build + +error[E0308]: mismatched types + --> src/second.rs:77:22 + | +77 | Iter { next: self.head.map(|node| &node) } + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected struct `second::Node`, found struct `std::boxed::Box` + | + = note: expected type `std::option::Option<&second::Node>` + found type `std::option::Option<&std::boxed::Box>>` + +error[E0308]: mismatched types + --> src/second.rs:85:25 + | +85 | self.next = node.next.map(|node| &node); + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected struct `second::Node`, found struct `std::boxed::Box` + | + = note: expected type `std::option::Option<&'a second::Node>` + found type `std::option::Option<&std::boxed::Box>>` +``` + +(╯°□°)╯︵ ┻━┻ + +这么看，生命周期的问题解决了，但是又引入了新的错误。原因在于，我们希望存储 `&Node` 但是获取的却是 `&Box`。嗯，小问题，解引用搞定： +```rust +impl List { + pub fn iter<'a>(&'a self) -> Iter<'a, T> { + Iter { next: self.head.map(|node| &*node) } + } +} + +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.map(|node| &*node); + &node.elem + }) + } +} +``` + +```shell +cargo build + Compiling lists v0.1.0 (/Users/ABeingessner/dev/temp/lists) +error[E0515]: cannot return reference to local data `*node` + --> src/second.rs:77:43 + | +77 | Iter { next: self.head.map(|node| &*node) } + | ^^^^^^ returns a reference to data owned by the current function + +error[E0507]: cannot move out of borrowed content + --> src/second.rs:77:22 + | +77 | Iter { next: self.head.map(|node| &*node) } + | ^^^^^^^^^ cannot move out of borrowed content + +error[E0515]: cannot return reference to local data `*node` + --> src/second.rs:85:46 + | +85 | self.next = node.next.map(|node| &*node); + | ^^^^^^ returns a reference to data owned by the current function + +error[E0507]: cannot move out of borrowed content + --> src/second.rs:85:25 + | +85 | self.next = node.next.map(|node| &*node); + | ^^^^^^^^^ cannot move out of borrowed content +``` + +又怎么了! (ﾉಥ益ಥ）ﾉ ┻━┻ + +大家还记得之前章节的内容吗？原因是这里我们忘记了 `as_ref` ，然后值的所有权被转移到了 `map` 中，结果我们在内部引用了一个局部值，造成一个垂悬引用： +```rust +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} + +impl List { + pub fn iter<'a>(&'a self) -> Iter<'a, T> { + Iter { next: self.head.as_ref().map(|node| &*node) } + } +} + +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.as_ref().map(|node| &*node); + &node.elem + }) + } +} +``` + +```shell +cargo build + Compiling lists v0.1.0 (/Users/ABeingessner/dev/temp/lists) +error[E0308]: mismatched types + --> src/second.rs:77:22 + | +77 | Iter { next: self.head.as_ref().map(|node| &*node) } + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected struct `second::Node`, found struct `std::boxed::Box` + | + = note: expected type `std::option::Option<&second::Node>` + found type `std::option::Option<&std::boxed::Box>>` + +error[E0308]: mismatched types + --> src/second.rs:85:25 + | +85 | self.next = node.next.as_ref().map(|node| &*node); + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected struct `second::Node`, found struct `std::boxed::Box` + | + = note: expected type `std::option::Option<&'a second::Node>` + found type `std::option::Option<&std::boxed::Box>>` +``` + +😭 + +错误的原因是，`as_ref` 增加了一层间接引用，需要被移除，这里使用另外一种方式来实现: +```rust +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} + +impl List { + pub fn iter<'a>(&'a self) -> Iter<'a, T> { + Iter { next: self.head.as_deref() } + } +} + +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.as_deref(); + &node.elem + }) + } +} +``` + +```shell +cargo build +``` + +🎉 🎉 🎉 + +`as_deref` 和 `as_deref_mut` 函数在 Rust 1.40 版本中正式稳定下来。在那之前，你只能在 `stable` 版本中使用 `map(|node| &**node)` 和 `map(|node| &mut**node)` 的方式来替代。 + +大家可能会觉得 `&**` 的形式看上去有些烂，没错，确实如此。但是就像一瓶好酒一样，Rust 也随着时间的推进变得越来越好，因此现在我们已经无需再这么做了。事实上，Rust 很擅长隐式地做类似的转换，或者可以称之为 [`Deref`](https://course.rs/advance/smart-pointer/deref.html)。 + +但是 `Deref` 在这里并不能很好的完成自己的任务，原因是在闭包中使用 `Option<&T>` 而不是 `&T` 对于它来说有些过于复杂了，因此我们需要显式地去帮助它完成任务。好在根据我的经验来看，这种情况还是相当少见的。 + +事实上，还可以使用另一种方式来实现： +```rust +self.next = node.next.as_ref().map::<&Node, _>(|node| &node); +``` + +这种类型暗示的方式可以使用的原因在于 `map` 是一个泛型函数: +```rust +pub fn map(self, f: F) -> Option +``` + +turbofish 形式的符号 `::<>` 可以告诉编译器我们希望用哪个具体的类型来替代泛型类型，在这种情况里，`::<&Node, _>` 意味着: 它应该返回一个 `&Node`。这种方式可以让编译器知道它需要对 `&node` 应用 `deref`，这样我们就不用手动的添加 `**` 来进行解引用。 + +好了，既然编译通过，那就写个测试来看看运行结果: +```rust +#[test] +fn iter() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.iter(); + assert_eq!(iter.next(), Some(&3)); + assert_eq!(iter.next(), Some(&2)); + assert_eq!(iter.next(), Some(&1)); +} +``` + +```shell +> cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 5 tests +test first::test::basics ... ok +test second::test::basics ... ok +test second::test::into_iter ... ok +test second::test::iter ... ok +test second::test::peek ... ok + +test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured +``` + +最后，还有一点值得注意，之前的代码事实上可以应用[生命周期消除原则](https://course.rs/advance/lifetime/basic.html#生命周期消除): +```rust +impl List { + pub fn iter<'a>(&'a self) -> Iter<'a, T> { + Iter { next: self.head.as_deref() } + } +} +``` + +这段代码跟以下代码是等价的: +```rust +impl List { + pub fn iter(&self) -> Iter { + Iter { next: self.head.as_deref() } + } +} +``` + +当然，如果你就喜欢生命周期那种自由、飘逸的 feeling，还可以使用 Rust 2018 引入的“显式生命周期消除"语法 `'_`： +```rust +impl List { + pub fn iter(&self) -> Iter<'_, T> { + Iter { next: self.head.as_deref() } + } +} +``` + diff --git a/src/too-many-lists/ok-stack/itermut.md b/src/too-many-lists/ok-stack/itermut.md new file mode 100644 index 00000000..b1dc4706 --- /dev/null +++ b/src/too-many-lists/ok-stack/itermut.md @@ -0,0 +1,326 @@ +# IterMut以及完整代码 +上一章节中我们讲到了要为 `List` 实现三种类型的迭代器并实现了其中两种: `IntoIter` 和 `Iter`。下面再来看看最后一种 `IterMut`。 + +再来回顾下 `Iter` 的实现： +```rust +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + + fn next(&mut self) -> Option { /* stuff */ } +} +``` + +这段代码可以进行下脱糖( desugar ): +```rust +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + + fn next<'b>(&'b mut self) -> Option<&'a T> { /* stuff */ } +} +``` + +可以看出 `next` 方法的输入和输出之间的生命周期并没有关联，这样我们就可以无条件的一遍又一遍地调用 `next`: +```rust +let mut list = List::new(); +list.push(1); list.push(2); list.push(3); + +let mut iter = list.iter(); +let x = iter.next().unwrap(); +let y = iter.next().unwrap(); +let z = iter.next().unwrap(); +``` + +对于不可变借用而言，这种方式没有任何问题，因为不可变借用可以同时存在多个，但是如果是可变引用呢？因此，大家可能会以为使用安全代码来写 `IterMut` 是一件相当困难的事。但是令人诧异的是，事实上，我们可以使用安全的代码来为很多数据结构实现 `IterMut`。 + +先将之前的代码修改成可变的： +```rust +pub struct IterMut<'a, T> { + next: Option<&'a mut Node>, +} + +impl List { + pub fn iter_mut(&self) -> IterMut<'_, T> { + IterMut { next: self.head.as_deref_mut() } + } +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.as_deref_mut(); + &mut node.elem + }) + } +} +``` + +```shell +> cargo build +error[E0596]: cannot borrow `self.head` as mutable, as it is behind a `&` reference + --> src/second.rs:95:25 + | +94 | pub fn iter_mut(&self) -> IterMut<'_, T> { + | ----- help: consider changing this to be a mutable reference: `&mut self` +95 | IterMut { next: self.head.as_deref_mut() } + | ^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be borrowed as mutable + +error[E0507]: cannot move out of borrowed content + --> src/second.rs:103:9 + | +103 | self.next.map(|node| { + | ^^^^^^^^^ cannot move out of borrowed content +``` + +果不其然，两个错误发生了。第一错误看上去很清晰，甚至告诉了我们该如何解决: +```rust +pub fn iter_mut(&mut self) -> IterMut<'_, T> { + IterMut { next: self.head.as_deref_mut() } +} +``` + +但是另一个好像就没那么容易了。但是之前的代码就可以工作啊，为何这里就不行了？ + +原因在于有些类型可以 [Copy](https://course.rs/basic/ownership/ownership.html#拷贝浅拷贝)，有些不行。而`Option` 和不可变引用 `&T` 恰恰是可以 Copy 的，但尴尬的是，可变引用 `&mut T` 不可以，因此这里报错了。 + +因此我们需要使用 `take` 方法来处理这种情况： +```rust +fn next(&mut self) -> Option { + self.next.take().map(|node| { + self.next = node.next.as_deref_mut(); + &mut node.elem + }) +} +``` + +```shell +> cargo build +``` + +老规矩，来测试下: +```rust +#[test] +fn iter_mut() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.iter_mut(); + assert_eq!(iter.next(), Some(&mut 3)); + assert_eq!(iter.next(), Some(&mut 2)); + assert_eq!(iter.next(), Some(&mut 1)); +} +``` + +```shell +> cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 6 tests +test first::test::basics ... ok +test second::test::basics ... ok +test second::test::iter_mut ... ok +test second::test::into_iter ... ok +test second::test::iter ... ok +test second::test::peek ... ok + +test result: ok. 7 passed; 0 failed; 0 ignored; 0 measured +``` + +最终，我们完成了迭代器的功能，下面是完整的代码。 + +## 完整代码 + +```rust +pub struct List { + head: Link, +} + +type Link = Option>>; + +struct Node { + elem: T, + next: Link, +} + +impl List { + pub fn new() -> Self { + List { head: None } + } + + pub fn push(&mut self, elem: T) { + let new_node = Box::new(Node { + elem: elem, + next: self.head.take(), + }); + + self.head = Some(new_node); + } + + pub fn pop(&mut self) -> Option { + self.head.take().map(|node| { + self.head = node.next; + node.elem + }) + } + + pub fn peek(&self) -> Option<&T> { + self.head.as_ref().map(|node| { + &node.elem + }) + } + + pub fn peek_mut(&mut self) -> Option<&mut T> { + self.head.as_mut().map(|node| { + &mut node.elem + }) + } + + pub fn into_iter(self) -> IntoIter { + IntoIter(self) + } + + pub fn iter(&self) -> Iter<'_, T> { + Iter { next: self.head.as_deref() } + } + + pub fn iter_mut(&mut self) -> IterMut<'_, T> { + IterMut { next: self.head.as_deref_mut() } + } +} + +impl Drop for List { + fn drop(&mut self) { + let mut cur_link = self.head.take(); + while let Some(mut boxed_node) = cur_link { + cur_link = boxed_node.next.take(); + } + } +} + +pub struct IntoIter(List); + +impl Iterator for IntoIter { + type Item = T; + fn next(&mut self) -> Option { + // access fields of a tuple struct numerically + self.0.pop() + } +} + +pub struct Iter<'a, T> { + next: Option<&'a Node>, +} + +impl<'a, T> Iterator for Iter<'a, T> { + type Item = &'a T; + fn next(&mut self) -> Option { + self.next.map(|node| { + self.next = node.next.as_deref(); + &node.elem + }) + } +} + +pub struct IterMut<'a, T> { + next: Option<&'a mut Node>, +} + +impl<'a, T> Iterator for IterMut<'a, T> { + type Item = &'a mut T; + + fn next(&mut self) -> Option { + self.next.take().map(|node| { + self.next = node.next.as_deref_mut(); + &mut node.elem + }) + } +} + +#[cfg(test)] +mod test { + use super::List; + + #[test] + fn basics() { + let mut list = List::new(); + + // Check empty list behaves right + assert_eq!(list.pop(), None); + + // Populate list + list.push(1); + list.push(2); + list.push(3); + + // Check normal removal + assert_eq!(list.pop(), Some(3)); + assert_eq!(list.pop(), Some(2)); + + // Push some more just to make sure nothing's corrupted + list.push(4); + list.push(5); + + // Check normal removal + assert_eq!(list.pop(), Some(5)); + assert_eq!(list.pop(), Some(4)); + + // Check exhaustion + assert_eq!(list.pop(), Some(1)); + assert_eq!(list.pop(), None); + } + + #[test] + fn peek() { + let mut list = List::new(); + assert_eq!(list.peek(), None); + assert_eq!(list.peek_mut(), None); + list.push(1); list.push(2); list.push(3); + + assert_eq!(list.peek(), Some(&3)); + assert_eq!(list.peek_mut(), Some(&mut 3)); + + list.peek_mut().map(|value| { + *value = 42 + }); + + assert_eq!(list.peek(), Some(&42)); + assert_eq!(list.pop(), Some(42)); + } + + #[test] + fn into_iter() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.into_iter(); + assert_eq!(iter.next(), Some(3)); + assert_eq!(iter.next(), Some(2)); + assert_eq!(iter.next(), Some(1)); + assert_eq!(iter.next(), None); + } + + #[test] + fn iter() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.iter(); + assert_eq!(iter.next(), Some(&3)); + assert_eq!(iter.next(), Some(&2)); + assert_eq!(iter.next(), Some(&1)); + } + + #[test] + fn iter_mut() { + let mut list = List::new(); + list.push(1); list.push(2); list.push(3); + + let mut iter = list.iter_mut(); + assert_eq!(iter.next(), Some(&mut 3)); + assert_eq!(iter.next(), Some(&mut 2)); + assert_eq!(iter.next(), Some(&mut 1)); + } +} +``` \ No newline at end of file diff --git a/src/too-many-lists/ok-stack/peek.md b/src/too-many-lists/ok-stack/peek.md new file mode 100644 index 00000000..a268b40f --- /dev/null +++ b/src/too-many-lists/ok-stack/peek.md @@ -0,0 +1,137 @@ +# Peek 函数 +在之前章节中，我们定义了 `push`、`pop` 等基础操作，下面一起添加几个进阶操作，让我们的链表有用起来。 + + +首先实现的就是 `peek` 函数，它会返回链表的表头元素的引用: +```rust +pub fn peek(&self) -> Option<&T> { + self.head.map(|node| { + &node.elem + }) +} +``` + +```shell +> cargo build + +error[E0515]: cannot return reference to local data `node.elem` + --> src/second.rs:37:13 + | +37 | &node.elem + | ^^^^^^^^^^ returns a reference to data owned by the current function + +error[E0507]: cannot move out of borrowed content + --> src/second.rs:36:9 + | +36 | self.head.map(|node| { + | ^^^^^^^^^ cannot move out of borrowed content +``` + +哎，Rust 大爷，您又哪里不满意了。不过问题倒是也很明显: `map` 方法是通过 `self` 获取的值，我们相当于把内部值的引用返回给函数外面的调用者。 + +一个比较好的解决办法就是让 `map` 作用在引用上，而不是直接作用在 `self.head` 上，为此我们可以使用 `Option` 的 `as_ref` 方法： +```rust +impl Option { + pub fn as_ref(&self) -> Option<&T>; +} +``` + +该方法将一个 `Option` 变成了 `Option<&T>`，然后再调用 `map` 就会对引用进行处理了： +```rust +pub fn peek(&self) -> Option<&T> { + self.head.as_ref().map(|node| { + &node.elem + }) +} +``` + +```shell +cargo build + + Finished dev [unoptimized + debuginfo] target(s) in 0.32s +``` + +当然，我们还可以通过类似的方式获取一个可变引用: +```rust +pub fn peek_mut(&mut self) -> Option<&mut T> { + self.head.as_mut().map(|node| { + &mut node.elem + }) +} +``` + +至此 `peek` 已经完成，为了测试它的功能，我们还需要编写一个测试用例: +```rust +#[test] +fn peek() { + let mut list = List::new(); + assert_eq!(list.peek(), None); + assert_eq!(list.peek_mut(), None); + list.push(1); list.push(2); list.push(3); + + assert_eq!(list.peek(), Some(&3)); + assert_eq!(list.peek_mut(), Some(&mut 3)); + list.peek_mut().map(|&mut value| { + value = 42 + }); + + assert_eq!(list.peek(), Some(&42)); + assert_eq!(list.pop(), Some(42)); +} +``` + +```shell +> cargo test + +error[E0384]: cannot assign twice to immutable variable `value` + --> src/second.rs:100:13 + | +99 | list.peek_mut().map(|&mut value| { + | ----- + | | + | first assignment to `value` + | help: make this binding mutable: `mut value` +100 | value = 42 + | ^^^^^^^^^^ cannot assign twice to immutable variable ^~~~~ +``` + +天呐，错误源源不断，这次编译器抱怨说 `value` 是不可变的，但是我们明明使用 `&mut value`，发生了什么？难道说在闭包中通过这种方式申明的可变性实际上没有效果？ + +实际上 `&mut value` 是一个模式匹配，它用 `&mut value` 模式去匹配一个可变的引用，此时匹配出来的 `value` 显然是一个值，而不是可变引用，因为只有完整的形式才是可变引用！ + +因此我们没必要画蛇添足，这里直接使用 `|value|` 来匹配可变引用即可，那么此时匹配出来的 `value` 就是一个可变引用。 + +```rust +#[test] +fn peek() { + let mut list = List::new(); + assert_eq!(list.peek(), None); + assert_eq!(list.peek_mut(), None); + list.push(1); list.push(2); list.push(3); + + assert_eq!(list.peek(), Some(&3)); + assert_eq!(list.peek_mut(), Some(&mut 3)); + + list.peek_mut().map(|value| { + *value = 42 + }); + + assert_eq!(list.peek(), Some(&42)); + assert_eq!(list.pop(), Some(42)); +} +``` + +这次我们直接匹配出来可变引用 `value`，然后对其修改即可。 + +```shell +cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 3 tests +test first::test::basics ... ok +test second::test::basics ... ok +test second::test::peek ... ok + +test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured +``` \ No newline at end of file diff --git a/src/too-many-lists/ok-stack/type-optimizing.md b/src/too-many-lists/ok-stack/type-optimizing.md new file mode 100644 index 00000000..05667807 --- /dev/null +++ b/src/too-many-lists/ok-stack/type-optimizing.md @@ -0,0 +1,210 @@ +# 优化类型定义 +首先，我们需要优化下类型的定义，可能一部分同学已经觉得之前的类型定义相当不错了，但是如果大家仔细观察下 `Link`: +```rust +enum Link { + Empty, + More(Box), +} +``` + +会发现，它其实跟 `Option>` 非常类似。 + +## Option +但是为了代码可读性，我们不能直接使用这个冗长的类型，否则代码中将充斥着 `Option>` 这种令人难堪的类型，为此可以使用类型别名。首先，将之前的代码使用新的 `Link` 进行修改： +```rust +use std::mem; + +pub struct List { + head: Link, +} + +// 类型别名，type alias +type Link = Option>; + +struct Node { + elem: i32, + next: Link, +} + +impl List { + pub fn new() -> Self { + List { head: None } + } + + pub fn push(&mut self, elem: i32) { + let new_node = Box::new(Node { + elem: elem, + next: mem::replace(&mut self.head, None), + }); + + self.head = Some(new_node); + } + + pub fn pop(&mut self) -> Option { + match mem::replace(&mut self.head, None) { + None => None, + Some(node) => { + self.head = node.next; + Some(node.elem) + } + } + } +} + +impl Drop for List { + fn drop(&mut self) { + let mut cur_link = mem::replace(&mut self.head, None); + while let Some(mut boxed_node) = cur_link { + cur_link = mem::replace(&mut boxed_node.next, None); + } + } +} +``` + +代码看上去稍微好了一些，但是 `Option` 的好处远不止这些。 + +首先，之前咱们用到了 `mem::replace` 这个让人胆战心惊但是又非常有用的函数，而 `Option` 直接提供了一个方法 `take` 用于替代它: +```rust +pub struct List { + head: Link, +} + +type Link = Option>; + +struct Node { + elem: i32, + next: Link, +} + +impl List { + pub fn new() -> Self { + List { head: None } + } + + pub fn push(&mut self, elem: i32) { + let new_node = Box::new(Node { + elem: elem, + next: self.head.take(), + }); + + self.head = Some(new_node); + } + + pub fn pop(&mut self) -> Option { + match self.head.take() { + None => None, + Some(node) => { + self.head = node.next; + Some(node.elem) + } + } + } +} + +impl Drop for List { + fn drop(&mut self) { + let mut cur_link = self.head.take(); + while let Some(mut boxed_node) = cur_link { + cur_link = boxed_node.next.take(); + } + } +} +``` + +其次，`match option { None => None, Some(x) => Some(y) }` 这段代码可以直接使用 `map` 方法代替，`map` 会对 `Some(x)` 中的值进行映射，最终返回一个新的 `Some(y)` 值。 + +> 我们往往将闭包作为参数传递给 map 方法，关于闭包可以参见[此章](https://course.rs/advance/functional-programing/closure.html) + +```rust +pub fn pop(&mut self) -> Option { + self.head.take().map(|node| { + self.head = node.next; + node.elem + }) +} +``` + +不错，看上去简洁了很多，下面运行下测试代码确保链表依然可以正常运行(这就是 TDD 的优点！) : +```shell +> cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 2 tests +test first::test::basics ... ok +test second::test::basics ... ok + +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured +``` + +很棒，接下来让我们来解决目前链表最大的问题：只支持 i32 类型的元素值。 + +## 泛型 +为了让链表支持任何类型的元素，泛型就是绕不过去的坎，首先将所有的类型定义修改为泛型实现： +```rust +pub struct List { + head: Link, +} + +type Link = Option>>; + +struct Node { + elem: T, + next: Link, +} + +impl List { + pub fn new() -> Self { + List { head: None } + } + + pub fn push(&mut self, elem: T) { + let new_node = Box::new(Node { + elem: elem, + next: self.head.take(), + }); + + self.head = Some(new_node); + } + + pub fn pop(&mut self) -> Option { + self.head.take().map(|node| { + self.head = node.next; + node.elem + }) + } +} + +impl Drop for List { + fn drop(&mut self) { + let mut cur_link = self.head.take(); + while let Some(mut boxed_node) = cur_link { + cur_link = boxed_node.next.take(); + } + } +} +``` + +大家在修改了 `List` 的定义后，别忘了将 `impl` 中的 `List` 修改为 `List`，切记**泛型参数也是类型定义的一部分**。 + +```shell +> cargo test + + Running target/debug/lists-5c71138492ad4b4a + +running 2 tests +test first::test::basics ... ok +test second::test::basics ... ok + +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured +``` + +如上所示，截至目前，测试用例依然运行良好，尽管我们把代码修改成了更加复杂的泛型。这里有一个点特别值得注意，我们并没有修改关联函数 `new` ： +```rust +pub fn new() -> Self { + List { head: None } +} +``` + +原因是 `Self` 承载了我们所有的荣耀，`List` 时，`Self` 就代表 `List`，当变成 `List` 时，`Self` 也随之变化，代表 `List`，可以看出使用它可以让未来的代码重构变得更加简单。 + diff --git a/内容变更记录.md b/内容变更记录.md index 46e018c8..25391e17 100644 --- a/内容变更记录.md +++ b/内容变更记录.md @@ -1,9 +1,18 @@ # ChangeLog 记录一些值得注意的变更。 +## 2022-03-13 + +- 新增章节: [还 OK 的单向链表 - IterMut](https://course.rs/too-many-lists/ok-stack/itermut.html) +- 新增章节: [还 OK 的单向链表 - IntoIter 和 Iter](https://course.rs/too-many-lists/iter.html) +- 优化[进一步深入特赠 - 关联类型](https://course.rs/basic/trait/advance-trait.html#关联类型)中的部分内容，感谢 AllenYu0018 的[提示](https://github.com/sunface/rust-course/discussions/392). + ## 2022-03-11 +- 新增章节: [还 OK 的单向链表 - Peek 函数](https://course.rs/too-many-lists/ok-stack/peek.html) +- 在特征对象章节添加图表的[详细解释](https://course.rs/basic/trait/trait-object.html#特征对象的动态分发)，感谢 [@Rustln](https://github.com/Rustln) 的倾情贡献 - 新增章节: [不太优秀的单向链表 - 收尾工作及最终代码](https://course.rs/too-many-lists/bad-stack/final-code.html) +- 新增章节：[还 OK 的单向链表 - 类型优化](https://course.rs/too-many-lists/ok-stack/type-optimizing.html) ## 2022-03-10