所有权：SourceMap 里的 String 归谁

构造函数和 getter#

1
impl SourceFile {
2
    fn new(id: SourceId, name: String, text: String) -> Self {
3
        let line_starts = compute_line_starts(&text);
4
        Self {
5
            id,
6
            name,
7
            text,
8
            line_starts,
9
        }
10
    }

注意 new 没有 pub：外面的人不能直接造一个 SourceFile，只有 SourceMap::add 可以（它会负责发 id）。这是 Rust 里表达”只能通过工厂创建”的标准办法，没有 friend 也没有 private 构造函数。

这四行里藏着所有权的第一次实战。compute_line_starts(&text) 里的 &text 是借用：把 text 的一个只读引用交给函数，函数用完还回来，text 仍然属于我们。接下来 Self { id, name, text, line_starts } 把 name、text 和 line_starts 移动进新结构体，之后这三个局部变量不能再用。顺序很重要：如果先移动再借用，就是上面的 E0382。

接着三个 getter：

1
    /// The id handed out by the owning [`SourceMap`].
2
    #[must_use]
3
    pub fn id(&self) -> SourceId {
4
        self.id
5
    }
6

7
    /// A human-readable name, e.g. a path.
8
    #[must_use]
9
    pub fn name(&self) -> &str {
10
        &self.name
11
    }
12

13
    /// The raw source text.
14
    #[must_use]
15
    pub fn text(&self) -> &str {
16
        &self.text
17
    }

id() 返回 SourceId，Copy，直接按值复制一份。name() 返回 &str：把内部 String 借出去。&self.name 的类型是 &String，函数声明要 &str，这里编译器自动做了转换（解引用强制转换，&String 能自动变成 &str，因为 String 实现了”可以当 str 用”，第 5 篇再细讲这个机制；现在记住：需要 &str 的地方放 &String 总是可以的）。

&self 是第 1 篇预告过的东西：方法借用调用者，不拿走。也就是说 file.name() 之后 file 还在。返回的 &str 因此必须不比 file 活得更久。我们当场验证编译器是否强制这一点（ch02_getter.rs：把一个 File 的 name() 存到块外面，然后让 File 先死）：

1
$ cargo build --bin ch02_getter
2
error[E0597]: `file` does not live long enough
3
  --> src/bin/ch02_getter.rs:15:16
4
   |
5
14 |         let file = File { name: String::from("a.pebble") };
6
   |             ---- binding `file` declared here
7
15 |         name = file.name();
8
   |                ^^^^ borrowed value does not live long enough
9
16 |     }
10
   |     - `file` dropped here while still borrowed
11
17 |     println!("{name}");
12
   |                ---- borrow later used here
13
...

编译器从 fn name(&self) -> &str 这个签名读出了：“返回值借自 self”。这叫生命周期省略：规则是”如果有 &self，返回的引用默认借自 self”。ch02_getter_ok.rs 里我把编译器补上的完整写法也放了进去，fn name_explicit<'a>(&'a self) -> &'a str，运行正常，输出 a.pebble a.pebble。那个 'a 是生命周期参数，第 4 篇是整整一篇的主题，现在你只要知道：签名里藏着一条”返回值借自谁”的声明，编译器据此检查调用点。

#[must_use] 你在第 1 篇见过了。

建表：Vec、迭代、as#

new 调用的 compute_line_starts 是一个自由函数，放在 impl 外面（文件里任何位置都行，我放在 Debug 实现的后面，下面一并给出完整位置）：

1
fn compute_line_starts(text: &str) -> Vec<u32> {
2
    let mut starts = Vec::with_capacity(text.len() / 24 + 1);
3
    starts.push(0);
4
    for (index, byte) in text.bytes().enumerate() {
5
        if byte == b'\n' {
6
            starts.push(index as u32 + 1);
7
        }
8
    }
9
    starts
10
}

参数是 &str：只读借用，调用者传 &String 或字符串字面量都行。逐行看：

• Vec::with_capacity(n) 预留 n 个元素的空间，对应 std::vector::reserve。我猜每行平均 24 个字节（拍脑袋的估计），所以预留 len / 24 + 1。Vec<u32> 的元素类型靠后面的 push(0) 和返回类型推断出来。
• let mut starts：push 要修改向量，所以绑定必须是 mut（第 1 篇）。
• text.bytes() 是字节迭代器，.enumerate() 给每个元素配上下标，产出 (下标, 字节) 的元组。for (index, byte) in ... 在循环头里直接把元组拆开，这叫解构模式。迭代器第 3 篇和第 4 篇会详细讲，这里把它当成一个范围 for。
• b'\n' 是字节字面量，类型是 u8，对应 C 的 '\n'（但 Rust 的 '\n' 是 char，是 Unicode 标量值，两者不同：字符和字节在 Rust 里是不同类型）。
• index as u32 + 1：index 是 usize，要存进 Vec<u32>，所以 as u32。as 比 + 优先级高，所以是 (index as u32) + 1。这是第 1 篇预告过的”我断言这个文件小于 4 GiB”。
• 最后一行 starts 没有分号，它是返回值，移动出函数：调用者拿到向量，没有拷贝。

实验 ch02_vec.rs 看一眼 Vec 和切片：

1
let starts: Vec<u32> = vec![0, 4, 9];
2
let middle: &[u32] = &starts[1..];
3
println!("get(1) = {:?}, get(10) = {:?}", starts.get(1), starts.get(10));
4
let mut grown: Vec<u32> = Vec::with_capacity(8);
5
grown.push(0);
6
grown.push(5);
7
println!("len = {}, capacity = {}", grown.len(), grown.capacity());
8
let index = std::hint::black_box(10);
9
println!("starts[10] = {}", starts[index]);

1
$ cargo run --quiet --bin ch02_vec
2
slice = [4, 9], len = 2
3
get(1) = Some(4), get(10) = None
4
len = 2, capacity = 8
5

6
thread 'main' (79263) panicked at src/bin/ch02_vec.rs:13:39:
7
index out of bounds: the len is 3 but the index is 10
8
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

vec![...] 是宏，创建并初始化向量。&starts[1..] 是切片（&[u32]）：指针加长度，对应 std::span<const uint32_t>，借自 starts。starts[10] 越界会 panic（和 at() 一样，而不是 operator[] 那种未定义行为）；.get(10) 返回 None，让你自己决定怎么办。后面会反复看到这对搭档：“会 panic 的下标”和”返回 Option 的 get”。（black_box 只是不让编译器在编译期看穿 10 越界。）

Option：没有空指针#

1
    /// Number of lines. A file always has at least one (possibly empty) line.
2
    #[must_use]
3
    pub fn line_count(&self) -> u32 {
4
        self.line_starts.len() as u32
5
    }
6

7
    /// Byte offset at which one-based `line` starts.
8
    #[must_use]
9
    pub fn line_start(&self, line: u32) -> Option<u32> {
10
        let index = line.checked_sub(1)? as usize;
11
        self.line_starts.get(index).copied()
12
    }

line_start 的返回类型是 Option<u32>：Option<T> 是一个标准库的枚举，要么是 Some(值)，要么是 None。它解决的问题和 C 里”返回 -1 表示没有”、“返回 NULL 表示没有”一样，区别是类型系统逼你处理 None：你拿不到 u32，只拿到 Option<u32>，除非你拆开它。（枚举本身是第 3 篇的主题，先把 Option 当成”可能为空的值”。）

line_start(0) 应该是 None，因为行号从 1 开始。line.checked_sub(1) 是第 1 篇的 checked_* 家族：0 - 1 溢出，返回 None。后面那个小小的 ? 是本章第一个重要的语法：在返回 Option 的函数里，expr? 的意思是”如果 expr 是 None，立刻让整个函数返回 None；如果是 Some(v)，把 v 取出来继续”。没有 ? 的话，同样的逻辑是一个 match：

1
let index = match line.checked_sub(1) {
2
    Some(v) => v,
3
    None => return None,
4
};

match 对每种情况给一个分支，编译器检查你没有漏掉（第 3 篇会让它报错）。? 就是这个 match 的缩写。

第二行 self.line_starts.get(index) 返回 Option<&u32>：向量里元素的引用，因为 get 不想把元素搬出向量。我们的函数要 Option<u32>，所以需要 .copied()，它把 Option<&u32> 里的引用解开、复制成值（u32 是 Copy，可以复制）。如果忘了，编译器直接告诉你该用什么（实验 ch02_copied.rs）：

1
$ cargo build --bin ch02_copied
2
error[E0308]: mismatched types
3
 --> src/bin/ch02_copied.rs:3:5
4
  |
5
1 | fn line_start(starts: &[u32], line: u32) -> Option<u32> {
6
  |                                             ----------- expected `Option<u32>` because of return type
7
2 |     let index = line.checked_sub(1)? as usize;
8
3 |     starts.get(index)
9
  |     ^^^^^^^^^^^^^^^^^ expected `Option<u32>`, found `Option<&u32>`
10
  |
11
  = note: expected enum `Option<_>`
12
             found enum `Option<&_>`
13
help: use `Option::copied` to copy the value inside the `Option`
14
  |
15
3 |     starts.get(index).copied()
16
  |                      +++++++++
17
...

整个小函数在 ch02_option.rs 里跑一遍：

1
$ cargo run --quiet --bin ch02_option
2
Some(3)
3
None
4
None
5
line 3 starts at byte 9
6
width = 0

line_start(&starts, 2) 是 Some(3)，行号 0 和 7 都是 None。顺带看到了 match 怎么拆 Option，以及 map_or(默认值, 函数)：None 时给默认值，Some(x) 时对 x 调函数。后面马上会用到。

闭包初见：partition_point#

下一个方法，给一个字节偏移，找出它在第几行：

1
    /// Zero-based index of the line containing `offset`.
2
    #[must_use]
3
    pub fn line_index(&self, offset: u32) -> u32 {
4
        // `line_starts[0] == 0 <= offset` always holds, so the result is >= 1.
5
        let count = self.line_starts.partition_point(|&start| start <= offset);
6
        (count - 1) as u32
7
    }

partition_point 是二分查找：假设切片的前半部分让谓词返回 true、后半部分返回 false，返回第一个 false 的位置。C++ 里有同名的 std::partition_point。line_starts 是升序的，所以 |start| start <= offset 对前一段成立、对后一段不成立，返回值就是”起点不超过 offset 的行数”，减 1 得到下标。

|&start| start <= offset 是一个闭包（匿名函数）：竖线里是参数，后面是函数体。它可以直接使用周围的变量 offset，对应 C++ 的 [&](auto start) { return start <= offset; }。Rust 的闭包怎么捕获变量、什么时候是 Fn/FnMut/FnOnce，第 9 篇讲；今天只要会读。

有趣的是参数那个 &start。partition_point 对切片 [u32] 的每个元素传的是 &u32（引用，不是值），所以参数类型是 &u32。&start 写在参数位置，它是一个模式：意思是”这个参数是一个引用，把它指向的 u32 绑定到名字 start”。如果不这样写（实验 ch02_closure_pattern.rs）：

1
$ cargo build --bin ch02_closure_pattern
2
error[E0308]: mismatched types
3
 --> src/bin/ch02_closure_pattern.rs:8:60
4
  |
5
8 |     let bad = line_starts.partition_point(|start| start <= offset);
6
  |                                                            ^^^^^^ expected `&u32`, found `u32`
7
  |
8
help: consider dereferencing the borrow
9
  |
10
8 |     let bad = line_starts.partition_point(|start| *start <= offset);
11
  |                                                   +
12
...

start 是 &u32，offset 是 u32，不能直接比。两种修法，都在 ch02_closure_ok.rs 里跑过（前两行都输出 3；这个文件的第三行用 |&start| start <= 2，输出 1，说明偏移 2 之前只有 0 一个行首）：|&start| 在参数里解引用，或者 |start| *start <= offset 在函数体里用 * 解引用（和 C 一样，* 是解引用）。我偏爱前者，把”它是个引用”这件事放在签名里。

(count - 1) as u32：count 是 usize（切片下标的类型）。因为 line_starts[0] == 0，对任何 offset 谓词至少对第一个元素成立，count >= 1，所以 count - 1 不会下溢。我把这个推理写在了注释里，这是”为什么这里不用 checked_sub”的理由。

取一行文本：借用的切片#

1
    /// The text of one-based `line`, without its trailing line terminator.
2
    #[must_use]
3
    pub fn line(&self, line: u32) -> Option<&str> {
4
        let index = line.checked_sub(1)? as usize;
5
        let start = *self.line_starts.get(index)? as usize;
6
        let end = self
7
            .line_starts
8
            .get(index + 1)
9
            .map_or(self.text.len(), |&next| next as usize);
10
        let raw = &self.text[start..end];
11
        Some(strip_line_ending(raw))
12
    }

这个函数返回 Option<&str>：一段借自 self.text 的文本，没有复制。*self.line_starts.get(index)? as usize 的读法是：get(index) 得到 Option<&u32>，? 在 None 时提前返回，否则得到 &u32，* 解引用得 u32（运算顺序：? 先，* 再，as 最后）。end 是下一行的行首，如果这是最后一行，没有下一行（get 返回 None），就用 map_or 给默认值 self.text.len()，也就是文件末尾。&self.text[start..end] 是范围下标，在 String 上切出 str，前面加 & 得到 &str。

行首总是紧跟在 \n 后面，所以 start 和 end 永远落在字符边界上，切片不会 panic。（不在字符边界上会怎样，下一节马上看。）

最后一个辅助函数把行尾的 \n 和 \r 去掉，处理 Windows 的 \r\n：

1
fn strip_line_ending(line: &str) -> &str {
2
    let line = line.strip_suffix('\n').unwrap_or(line);
3
    line.strip_suffix('\r').unwrap_or(line)
4
}

strip_suffix 返回 Option<&str>：有这个后缀就是去掉后缀后的 Some，没有就是 None；unwrap_or(default) 在 None 时给默认值。参数 line 被遮蔽了两次（第 1 篇的遮蔽），每次都是更短的 &str。注意返回类型 &str 没有任何生命周期标注，编译器用的是”只有一个引用参数，返回值就借自它”的规则。这就是下一节要认真对待的东西。

Debug：不打印全部文本#

SourceFile 里有整个文件的文本，派生 Debug 会把它全打出来，一个 1000 行的文件会淹没断言失败的输出。所以我手写了一个只打印摘要的：

1
impl fmt::Debug for SourceFile {
2
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3
        f.debug_struct("SourceFile")
4
            .field("id", &self.id)
5
            .field("name", &self.name)
6
            .field("lines", &self.line_count())
7
            .field("bytes", &self.text.len())
8
            .finish()
9
    }
10
}

debug_struct 是标准库提供的”构造器”，一连串方法调用最后以 .finish() 结束（这种写法叫 builder，第 3 篇会自己写一个）。&self.line_count() 借用的是一个临时值，这行结束就释放，没有问题。完整的文件顺序是：impl SourceFile 之后紧跟这个 Debug 实现，然后是 compute_line_starts，然后是 strip_line_ending。

为 SourceFile 写测试#

把下面三个测试加到 mod tests 的最前面，也就是 use super::*; 的下面、merge_covers_both 的上面：

1
    #[test]
2
    fn line_starts_include_a_line_after_a_trailing_newline() {
3
        let map_file = SourceFile::new(SourceId(0), "t".into(), "a\nb\n".into());
4
        assert_eq!(map_file.line_count(), 3);
5
        assert_eq!(map_file.line(1), Some("a"));
6
        assert_eq!(map_file.line(2), Some("b"));
7
        assert_eq!(map_file.line(3), Some(""));
8
    }
9

10
    #[test]
11
    fn handles_crlf() {
12
        let file = SourceFile::new(SourceId(0), "t".into(), "a\r\nb".into());
13
        assert_eq!(file.line(1), Some("a"));
14
        assert_eq!(file.line(2), Some("b"));
15
    }
16

17
    #[test]
18
    fn position_counts_characters_not_bytes() {
19
        // Each CJK character is three bytes; the second line's "c" is the 5th
20
        // column even though it sits at byte offset 8.
21
        let file = SourceFile::new(SourceId(0), "t".into(), "ab\n中c".into());
22
        let offset = file.text().find('c').unwrap() as u32;
23
        let pos = file.position(offset);
24
        assert_eq!(pos.line, 2);
25
        assert_eq!(pos.column, 2);
26
    }

我要诚实地指出：这第三个测试里的注释写得不准（c 实际在字节偏移 6，第 2 列，上面的实验已经证明；注释里的数字是我早期写的，后来改了断言但没改注释）。注释留着是因为这一篇的目标是文件和仓库逐字节一致，不过断言本身是对的，这也是为什么测试比注释可信。

几点：

• SourceFile::new 是私有的，但测试在同一个模块的子模块里，use super::* 把它带进来，所以能调用。这就是”同模块可访问私有”的实际用处，单元测试可以直接测内部函数，不用为了测试而 pub。
• "t".into()：new 要的是 String，字面量是 &str，.into() 做转换，目标类型靠函数签名推断。下面 SourceMap::add 会正式讲 Into。
• assert_eq!(map_file.line(1), Some("a")) 比较的是两个 Option<&str>。Option<T> 在 T 可以比较时自己也可以比较，不需要拆开。
• .find('c') 返回 Option<usize>，.unwrap() 取出里面的值，没有的话 panic。测试里 unwrap 是可以的：这里我们知道有，没有就是测试写错了；在库代码里用 unwrap 要三思，第 7 篇再说。

此时 cargo test -p pebble-span 应该有 5 个测试通过（原来的两个加上这三个）。

add：impl Into<String> 和可变借用#

1
    /// Registers a new file and returns its id.
2
    pub fn add(&mut self, name: impl Into<String>, text: impl Into<String>) -> SourceId {
3
        let id = SourceId(self.files.len() as u32);
4
        self.files
5
            .push(SourceFile::new(id, name.into(), text.into()));
6
        id
7
    }

这里有三件新事。

&mut self：可变借用。add 要往 self.files 里 push，所以必须能修改 self。&self 是只读借用，&mut self 是读写借用，调用者的变量必须是 let mut map。

impl Into<String>：参数类型不是 String，也不是 &str，而是”任何能转换成 String 的类型”。调用者可以传字符串字面量、String、format!(...) 的结果，函数体里统一用 .into() 转成 String。Into 是标准库的 trait，&str 和 String 都实现了到 String 的转换。这样 API 对调用者友好：map.add("a.pebble", "...") 不需要 .to_string()。实验 ch02_into.rs 验证三种调用都能工作（输出 8 9 8）；传一个整数则是：

1
$ cargo build --bin ch02_into_bad
2
error[E0277]: the trait bound `String: From<{integer}>` is not satisfied
3
 --> src/bin/ch02_into_bad.rs:7:29
4
  |
5
7 |     println!("{}", register(42));
6
  |                    -------- ^^ the trait `From<{integer}>` is not implemented for `String`
7
  |                    |
8
  |                    required by a bound introduced by this call
9
  |
10
  = help: the following other types implement trait `From<T>`:
11
            `String` implements `From<&String>`
12
            `String` implements `From<&mut str>`
13
            `String` implements `From<&str>`
14
            `String` implements `From<Box<str>>`
15
            `String` implements `From<Cow<'_, str>>`
16
            `String` implements `From<char>`
17
  = note: required for `{integer}` to implement `Into<String>`
18
...

这是第一次出现”trait bound”：函数对参数类型提出的要求。impl Trait 写在参数位置是”某个实现了该 trait 的类型”的简写，它背后是泛型，第 5 篇完整讲。你现在可以把它读成”接受任何能转成 String 的东西”。（和 C++ 的 template <std::convertible_to<std::string> S> 很像。）

所有权的流转：调用者传进来一个 &str，.into() 把它复制成一个新的 String；如果调用者传进来的本来就是 String，.into() 直接移动，没有复制。无论哪种，SourceMap 里的 SourceFile 拥有自己的文本，调用者的变量（如果有的话）和 SourceMap 之间没有任何关系。这回答了本篇标题的问题：String 归 SourceFile，SourceFile 归 SourceMap。其他所有人（词法分析器、诊断渲染器）只能借用。

两种取文件的方式，以及可变借用的代价#

1
    /// Looks up a file by id, returning `None` for an unknown id.
2
    #[must_use]
3
    pub fn get(&self, id: SourceId) -> Option<&SourceFile> {
4
        self.files.get(id.0 as usize)
5
    }
6

7
    /// Number of registered files.
8
    #[must_use]
9
    pub fn len(&self) -> usize {
10
        self.files.len()
11
    }
12

13
    /// Whether no files have been registered.
14
    #[must_use]
15
    pub fn is_empty(&self) -> bool {
16
        self.files.is_empty()
17
    }
18
}

get 返回 Option<&SourceFile>：借用，可能没有。len 和 is_empty 是一对：我试过只写 len，clippy 直接报错：

1
error: struct `SourceMap` has a public `len` method, but no `is_empty` method
2
   --> crates/pebble-span/src/lib.rs:278:5
3
    |
4
278 |     pub fn len(&self) -> usize {
5
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^
6
    |
7
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#len_without_is_empty
8
    = note: `-D clippy::len-without-is-empty` implied by `-D warnings`
9
...

这是 clippy 的 len_without_is_empty 规则，约定任何有 len 的容器都应该有 is_empty。

现在是这篇文章最重要的一个实验：共享借用和可变借用不能同时存在。ch02_borrow.rs：

1
let mut files = vec![String::from("a.pebble")];
2
let first = &files[0];
3
files.push(String::from("b.pebble"));
4
println!("first = {first}");

1
$ cargo build --bin ch02_borrow
2
error[E0502]: cannot borrow `files` as mutable because it is also borrowed as immutable
3
 --> src/bin/ch02_borrow.rs:4:5
4
  |
5
3 |     let first = &files[0];
6
  |                  ----- immutable borrow occurs here
7
4 |     files.push(String::from("b.pebble"));
8
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ mutable borrow occurs here
9
5 |     println!("first = {first}");
10
  |                        ----- immutable borrow later used here
11
...

这是 C++ 里经典的迭代器失效：拿着 vector 里某个元素的引用，然后 push_back，vector 重新分配了内存，旧引用悬空。C++ 编译这段没问题，运行时是未定义行为，Rust 在编译期拒绝它。规则是：

• 任何时刻，对一个值要么有任意多个共享借用（&T，只读），要么恰好一个可变借用（&mut T，读写），不能两者同时存在。
• 引用不能比它指向的值活得久（上面的悬垂引用）。

这叫”别名与可变性互斥”。很多人觉得它很苛刻；我的体会是，它精确地对应了所有”在遍历时修改容器”一类的 bug，换来的是编译器可以保证没有数据竞争，也不需要 C++ 里那种”小心引用失效”的长期警惕。

注意报错里最后一行：immutable borrow later used here。借用的结束点是最后一次使用，不是作用域结束。这叫 NLL（non-lexical lifetimes）。把 println! 挪到 push 之前，同样的代码就合法了（ch02_nll.rs，输出 first = a.pebble 和 now 2 files）。借用检查器看的是”这个引用之后还会不会被用到”，而不是花括号的位置。

SourceMap::add 是 &mut self，所以一个 &SourceFile（比如 &map[id]）活着的时候不能再 add。这在真实代码里是个切实的约束：编译一个文件的过程中不能顺手注册新文件。我们放到练习里体验它。

从 &mut 里搬出东西：std::mem::take#

既然提到 &mut self，还有一个新手几乎一定会撞上的墙。实验 ch02_take.rs：

1
struct Holder {
2
    name: String,
3
}
4

5
impl Holder {
6
    fn steal(&mut self) -> String {
7
        self.name
8
    }
9
}

1
$ cargo build --bin ch02_take
2
error[E0507]: cannot move out of `self.name` which is behind a mutable reference
3
 --> src/bin/ch02_take.rs:7:9
4
  |
5
7 |         self.name
6
  |         ^^^^^^^^^ move occurs because `self.name` has type `String`, which does not implement the `Copy` trait
7
  |
8
help: consider cloning the value if the performance cost is acceptable
9
  |
10
7 |         self.name.clone()
11
  |                  ++++++++
12
...

我们只借了 self，不拥有它。把 name 搬走会让 self 留下一个”空洞”，这个对象之后还要被其他人使用甚至析构，对空洞做析构就是 double free。C++ 的做法是让你写 std::move(self.name)，把字符串掏空，留下一个有效的空串。Rust 的要求是：搬走的同时，必须放回一个有效的值。标准库给了三个工具（ch02_take_ok.rs）：

1
mem::take(&mut self.name)                          // 取走，留下 String::default()，即空串
2
mem::replace(&mut holder.name, String::from("b.pebble"))  // 取走，换上你指定的值
3
mem::swap(&mut holder.name, &mut other)            // 两个位置互换

1
$ cargo run --quiet --bin ch02_take_ok
2
stolen = "a.pebble"
3
left   = ""
4
old = "", new = "b.pebble"
5
holder = "c.pebble", other = "b.pebble"

take 对应 C++ 的 std::exchange(x, T{})，replace 对应 std::exchange(x, v)，swap 对应 std::swap。老实说，我 grep 过整个 Pebble 仓库，一次也没有用到它们：Pebble 的数据流设计得不需要从借用里掏东西。但你一定会在别人的代码里到处遇到，而 E0507 是新手最常撞的墙之一，所以放在这里。

运算符重载：Index#

SourceMap 里还差一个：map[id] 这种写法。C++ 里你重载 operator[]。Rust 里运算符是 trait：a + b 是 Add::add(a, b) 的语法糖，a[b] 是 Index::index(&a, b) 的语法糖。第 1 篇你已经在 u32 + usize 的报错里看过它们的影子。实验 ch02_ops_missing.rs，没有实现 Add 的 Offset 做加法：

1
$ cargo build --bin ch02_ops_missing
2
error[E0369]: cannot add `Offset` to `Offset`
3
 --> src/bin/ch02_ops_missing.rs:7:24
4
  |
5
7 |     println!("{:?}", a + b);
6
  |                      - ^ - Offset
7
  |                      |
8
  |                      Offset
9
  |
10
note: an implementation of `Add` might be missing for `Offset`
11
 --> src/bin/ch02_ops_missing.rs:2:1
12
  |
13
2 | struct Offset(u32);
14
  | ^^^^^^^^^^^^^ must implement `Add`
15
...

在 ch02_ops.rs 里我给 Offset 实现了 Add、Add<u32>（和不同类型相加）、Sub（返回 u32 而不是 Offset，Output 是关联类型，由你决定）、AddAssign（+=）和 Index：

1
impl Add for Offset {
2
    type Output = Offset;
3
    fn add(self, other: Offset) -> Offset {
4
        Offset(self.0 + other.0)
5
    }
6
}
7

8
impl Index<Offset> for Names {
9
    type Output = String;
10
    fn index(&self, at: Offset) -> &String {
11
        &self.0[at.0 as usize]
12
    }
13
}

1
$ cargo run --quiet --bin ch02_ops
2
Offset(7) Offset(4) 14
3
b.pebble
4
...
5
thread 'main' (78868) panicked at src/bin/ch02_ops.rs:51:25:
6
index out of bounds: the len is 2 but the index is 9

（最后几行是故意越界的 names[Offset(9)]。）一条规则：impl Add for Offset 的意思是 Offset + Offset 可用，Add<u32> 是 Offset + u32，每一种右操作数各自是一个 trait 实例，这比 C++ 里 operator+ 重载解析要明确。type Output 是 trait 里的关联类型：实现者在这里声明”这个运算的结果类型是什么”。

现在为 SourceMap 写 Index<SourceId>。放在 impl SourceMap 的后面：

1
impl core::ops::Index<SourceId> for SourceMap {
2
    type Output = SourceFile;
3

4
    /// Looks up a file by id, panicking on an unknown id.
5
    ///
6
    /// Ids only ever come from this map, so a bad id is a bug in the compiler,
7
    /// not something the user did. Use [`SourceMap::get`] for a fallible lookup.
8
    ///
9
    /// # Panics
10
    ///
11
    /// Panics when `id` did not come from this map.
12
    fn index(&self, id: SourceId) -> &SourceFile {
13
        &self.files[id.0 as usize]
14
    }
15
}

map[id] 现在等价于 *map.index(id)。index 的实现用 self.files[...]，所以越界时 panic。一个 panic 的函数应该在文档里说明，惯例是 # Panics 小节，clippy 会检查它。get 和 [] 同时存在，就像 Vec::get 和 vec[i]：调用者知道 id 一定合法就用 []，不确定就用 get。（C++ 里这对搭档是 operator[]（不检查）和 at()（检查，抛异常）。Rust 的 [] 检查并 panic，不会 UB。）

没写 Index 时，下面这个测试会得到什么（它就是第 6 个测试）？

1
    #[test]
2
    fn source_map_assigns_sequential_ids() {
3
        let mut map = SourceMap::new();
4
        let first = map.add("a.pebble", "");
5
        let second = map.add("b.pebble", "");
6
        assert_eq!(first, SourceId(0));
7
        assert_eq!(second, SourceId(1));
8
        assert_eq!(map[second].name(), "b.pebble");
9
    }

把它加到 mod tests 的末尾（merge_across_files_is_a_bug 的后面），然后在还没写 Index 的时候运行 cargo test：

1
$ cargo test -p pebble-span
2
   Compiling pebble-span v0.1.0 (/tmp/pebble-rebuild-02/crates/pebble-span)
3
error[E0608]: cannot index into a value of type `SourceMap`
4
   --> crates/pebble-span/src/lib.rs:339:23
5
    |
6
339 |         assert_eq!(map[second].name(), "b.pebble");
7
    |                       ^^^^^^^^
8

9
For more information about this error, try `rustc --explain E0608`.
10
error: could not compile `pebble-span` (lib test) due to 1 previous error

写上 Index 的实现，这个错误消失。为了让你看到 [] 越界到底说什么，我用一个临时的小程序对一个只有两个文件的 SourceMap 查 SourceId(9)：map.get(SourceId(9)) 给出 None，而 map[SourceId(9)] 给出：

1
thread 'main' (83327) panicked at crates/pebble-span/examples/ex_index_panic.rs:8:23:
2
index out of bounds: the len is 2 but the index is 9

最后，SourceMap 的 Debug，和 SourceFile 一样，只打印摘要。放在 Index 实现之后：

1
impl fmt::Debug for SourceMap {
2
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
3
        f.debug_struct("SourceMap")
4
            .field("files", &self.files.len())
5
            .finish()
6
    }
7
}

到这里 SourceMap 写完了，上面那个 dead_code 警告也消失了：SourceMap::add 调用了 SourceFile::new。这时的 cargo test -p pebble-span 应该有 6 个测试通过。但我们还差一件事。

core、alloc、std：三层标准库#

no_std 是什么？Rust 的标准库分三层：

std 是你平常用的那个，它把 core 和 alloc 的东西重新导出，所以 std::fmt 和 core::fmt 是同一个东西，这也兑现了第 1 篇的承诺。#![no_std] 的意思是”我只链接 core，不链接 std”。对应 C 里的 freestanding 与 hosted：freestanding 环境（-ffreestanding）没有 malloc，没有 printf，没有文件，只有语言本身；hosted 才有完整的标准库。

我为什么要这样限制一个看起来是普通数据结构的 crate？因为第 13 篇会写一个跑在没有操作系统的环境里的求值器，它要用 Pebble 的词法分析器，而词法分析器依赖 pebble-span。依赖链上的每一个 crate 都得是 no_std，一个 crate 不能比它的依赖更自由。

我们试一试。只加第一行属性（不加 forbid），然后 cargo build -p pebble-span：

1
$ cargo build -p pebble-span
2
   Compiling pebble-span v0.1.0 (/tmp/pebble-rebuild-02/crates/pebble-span)
3
error[E0425]: cannot find type `String` in this scope
4
   --> crates/pebble-span/src/lib.rs:114:11
5
    |
6
114 |     name: String,
7
    |           ^^^^^^ not found in this scope
8

9
error[E0425]: cannot find type `String` in this scope
10
   --> crates/pebble-span/src/lib.rs:115:11
11
    |
12
115 |     text: String,
13
    |           ^^^^^^ not found in this scope
14

15
...
16
Some errors have detailed explanations: E0425, E0433.
17
For more information about this error, try `rustc --explain E0425`.
18
error: could not compile `pebble-span` (lib) due to 10 previous errors

一共 10 条错误，都是同一件事：String 和 Vec 不在了。它们之前在预导入（prelude）里：每个 Rust 文件开头都隐式有 use std::prelude::*，里面有 String、Vec、Option、Some、None、Box 等。no_std 的预导入是 core 的那一份，没有堆类型。

String 和 Vec 属于 alloc 层。要用它们，先把 use alloc::string::String; use alloc::vec::Vec; 写上，试一下（只加 use）：

1
error[E0433]: cannot find module or crate `alloc` in this scope
2
 --> crates/pebble-span/src/lib.rs:8:5
3
  |
4
8 | use alloc::string::String;
5
  |     ^^^^^ use of unresolved module or unlinked crate `alloc`
6
  |
7
  = help: add `extern crate alloc` to use the `alloc` crate
8
...

编译器告诉你要显式链接 alloc：extern crate alloc;（extern crate 是 2015 年时代的写法，现在几乎只用于 alloc 这种”标准库里不在预导入的 crate”）。把文件开头整个换成这样：

1
#![cfg_attr(not(test), no_std)]
2
#![forbid(unsafe_code)]
3
//! Source offsets, spans, and source maps.
4
//!
5
//! Everything in the front end of the compiler talks about positions in terms
6
//! of *byte offsets into a source file*. Those offsets are grouped into
7
//! [`Span`]s, and [`SourceMap`] is the thing that turns an offset back into a
8
//! human position (`file.pebble:12:7`).
9
//!
10
//! The crate is `#![no_std]` on purpose: it only needs `core` and `alloc`, so
11
//! the same code runs on a microcontroller (see `pebble-nostd`). That is also
12
//! why you will see `alloc::string::String` instead of `std::string::String`.
13

14
extern crate alloc;
15

16
use alloc::string::String;
17
use alloc::vec::Vec;
18
use core::fmt;
19

20
/// Identifies one source file inside a [`SourceMap`].
21
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
22
pub struct SourceId(pub u32);

也就是：删掉第 1 篇那段旧的 //! 文档和 use core::fmt;，换成这一段，并把 SourceId 的文档注释改成现在这个（现在 SourceMap 存在，文档链接才有意义；[SourceMap] 是 rustdoc 的文档链接，第 15 篇讲）。其余部分不变。

为什么是 not(test)？Rust 的测试框架依赖 std（线程、println!、panic 捕获），所以 cargo test 时 crate 仍然用 std 编译，只有正常构建才是 no_std。这也意味着：一个 no_std crate 在测试里即使偷用了 std 的东西，cargo test 也会通过，但 cargo build 会失败，所以光看测试通过是不够的，必须同时构建（检查点会跑）。

实验清单#

这一篇的所有实验文件都在仓库的 lab/ 目录里。按第 1 篇克隆的 ~/pebble-tag，它们在 ~/pebble-tag/lab/rust-lab，先 cd ~/pebble-tag/lab/rust-lab（或者把这个目录复制成 ~/rust-lab）再运行下面的命令。结果列是我用 rustc 1.95.0 在调试构建下重新跑出来的。

这里面的大多数（尤其是编译错误的那些）是上文给出的几行代码外加一个 fn main；ch02_ops.rs 是上面三个 impl 加一个 Offset 和一个 Names(Vec<String>) 的完整小程序。动手写一遍比抄快。

仓库里还有 ch02_exercise_borrow.rs 和 ch02_exercise_borrow_ok.rs（用 Vec<String> 做的练习 3 的缩小版，前者 E0502，后者输出 b.pebble），文章正文没有引用它们。