Rust Bootstrap Course for C/C++ Programmers
Rust 面向 C/C++ 程序员入门训练营

Course Overview
课程总览

• Course overview
  课程内容概览
  • The case for Rust (from both C and C++ perspectives)
    为什么要学 Rust，会分别从 C 和 C++ 两个视角展开
  • Local installation
    本地安装与环境准备
  • Types, functions, control flow, pattern matching
    类型、函数、控制流与模式匹配
  • Modules, cargo
    模块系统与 cargo
  • Traits, generics
    Trait 与泛型
  • Collections, error handling
    集合类型与错误处理
  • Closures, memory management, lifetimes, smart pointers
    闭包、内存管理、生命周期与智能指针
  • Concurrency
    并发编程
  • Unsafe Rust, including Foreign Function Interface (FFI)
    Unsafe Rust，包括外部函数接口 FFI
  • no_std and embedded Rust essentials for firmware teams
    面向固件团队的 no_std 与嵌入式 Rust 基础
  • Case studies: real-world C++ to Rust translation patterns
    案例分析：真实世界中的 C++ 到 Rust 迁移模式
• We’ll not cover async Rust in this course — see the companion Async Rust Training for a full treatment of futures, executors, Pin, tokio, and production async patterns
  本课程里不会展开 async Rust；如果要系统学习 futures、执行器、Pin、tokio 和生产环境里的异步模式，请查看配套的 Async Rust Training。

Self-Study Guide
自学指南

This material works both as an instructor-led course and for self-study. If you’re working through it on your own, here’s how to get the most out of it:
这套材料既适合讲师授课，也适合个人自学。若是单独推进，按下面这套方式读，吸收效率会高很多。

Pacing recommendations:
学习节奏建议：

How to use the exercises:
练习怎么做：

• Every chapter has hands-on exercises marked with difficulty: 🟢 Starter, 🟡 Intermediate, 🔴 Challenge
  每章都带有动手练习，并按难度标成：🟢 入门、🟡 进阶、🔴 挑战。
• Always try the exercise before expanding the solution. Struggling with the borrow checker is part of learning — the compiler’s error messages are your teacher
  一定先自己做，再展开答案。 和借用检查器死磕本来就是学习过程，编译器报错就是老师。
• If you’re stuck for more than 15 minutes, expand the solution, study it, then close it and try again from scratch
  如果卡住超过 15 分钟，就先看答案研究思路，再合上答案从头重做一遍。
• The Rust Playground lets you run code without a local install
  Rust Playground 可以在没有本地安装环境时直接运行代码。

When you hit a wall:
如果学到一半撞墙了：

• Read the compiler error message carefully — Rust’s errors are exceptionally helpful
  认真读编译器报错。Rust 的错误信息通常写得非常细，很多时候已经把方向点明了。
• Re-read the relevant section; concepts like ownership (ch7) often click on the second pass
  把对应章节再读一遍；像所有权这种内容，很多人第二遍才真正开窍。
• The Rust standard library docs are excellent — search for any type or method
  Rust 标准库文档 质量很高，类型和方法基本都能直接搜到。
• For async patterns, see the companion Async Rust Training
  如果问题落到 async 模式上，继续看配套的 Async Rust Training。

Table of Contents
目录总览

Part I — Foundations
第一部分：基础知识

1. Introduction and Motivation
1. 引言与动机

• Speaker intro and general approach
  讲者介绍与整体思路
• The case for Rust
  为什么选择 Rust
• How does Rust address these issues?
  Rust 如何解决这些问题
• Other Rust USPs and features
  Rust 其他独特卖点与特性
• Quick Reference: Rust vs C/C++
  速查：Rust 与 C/C++ 对比
• Why C/C++ Developers Need Rust
  为什么 C/C++ 开发者需要 Rust
  • What Rust Eliminates — The Complete List
    Rust 到底消灭了什么：完整清单
  • The Problems Shared by C and C++
    C 和 C++ 共同存在的问题
  • C++ Adds More Problems on Top
    C++ 在此基础上又额外引入的问题
  • How Rust Addresses All of This
    Rust 如何系统性解决这些问题

2. Getting Started
2. 快速开始

• Enough talk already: Show me some code
  少说废话，先上代码
• Rust Local installation
  Rust 本地安装
• Rust packages (crates)
  Rust 包与 crate
• Example: cargo and crates
  示例：cargo 与 crate

3. Basic Types and Variables
3. 基础类型与变量

• Built-in Rust types
  Rust 内建类型
• Rust type specification and assignment
  Rust 类型标注与赋值
• Rust type specification and inference
  Rust 类型标注与类型推断
• Rust variables and mutability
  Rust 变量与可变性

4. Control Flow
4. 控制流

• Rust if keyword
  Rust 中的 if
• Rust loops using while and for
  使用 while 与 for 的循环
• Rust loops using loop
  使用 loop 的循环
• Rust expression blocks
  Rust 表达式代码块

5. Data Structures and Collections
5. 数据结构与集合

• Rust array type
  Rust 数组
• Rust tuples
  Rust 元组
• Rust references
  Rust 引用
• C++ References vs Rust References — Key Differences
  C++ 引用与 Rust 引用的关键区别
• Rust slices
  Rust slice
• Rust constants and statics
  Rust 常量与静态变量
• Rust strings: String vs &str
  Rust 字符串：String 与 &str
• Rust structs
  Rust 结构体
• Rust Vec<T>
  Rust Vec<T>
• Rust HashMap
  Rust HashMap
• Exercise: Vec and HashMap
  练习：Vec 与 HashMap

6. Pattern Matching and Enums
6. 模式匹配与枚举

• Rust enum types
  Rust 枚举类型
• Rust match statement
  Rust match 语句
• Exercise: Implement add and subtract using match and enum
  练习：用 match 与枚举实现加减法

7. Ownership and Memory Management
7. 所有权与内存管理

• Rust memory management
  Rust 内存管理
• Rust ownership, borrowing and lifetimes
  Rust 所有权、借用与生命周期
• Rust move semantics
  Rust 移动语义
• Rust Clone
  Rust Clone
• Rust Copy trait
  Rust Copy trait
• Rust Drop trait
  Rust Drop trait
• Exercise: Move, Copy and Drop
  练习：Move、Copy 与 Drop
• Rust lifetime and borrowing
  Rust 生命周期与借用
• Rust lifetime annotations
  Rust 生命周期标注
• Exercise: Slice storage with lifetimes
  练习：带生命周期的 slice 存储
• Lifetime Elision Rules Deep Dive
  生命周期省略规则深入解析
• Rust Box<T>
  Rust Box<T>
• Interior Mutability: Cell<T> and RefCell<T>
  内部可变性：Cell<T> 与 RefCell<T>
• Shared Ownership: Rc<T>
  共享所有权：Rc<T>
• Exercise: Shared ownership and interior mutability
  练习：共享所有权与内部可变性

8. Modules and Crates
8. 模块与 crate

• Rust crates and modules
  Rust crate 与模块
• Exercise: Modules and functions
  练习：模块与函数
• Workspaces and crates (packages)
  Workspace 与 crate（package）
• Exercise: Using workspaces and package dependencies
  练习：使用 workspace 与包依赖
• Using community crates from crates.io
  使用 crates.io 社区 crate
• Crates dependencies and SemVer
  crate 依赖与语义化版本
• Exercise: Using the rand crate
  练习：使用 rand crate
• Cargo.toml and Cargo.lock
  Cargo.toml 与 Cargo.lock
• Cargo test feature
  cargo test 功能
• Other Cargo features
  其他 Cargo 功能
• Testing Patterns
  测试模式

9. Error Handling
9. 错误处理

• Connecting enums to Option and Result
  把枚举与 Option、Result 联系起来
• Rust Option type
  Rust Option 类型
• Rust Result type
  Rust Result 类型
• Exercise: log() function implementation with Option
  练习：用 Option 实现 log() 函数
• Rust error handling
  Rust 错误处理
• Exercise: error handling
  练习：错误处理
• Error Handling Best Practices
  错误处理最佳实践

10. Traits and Generics
10. Trait 与泛型

• Rust traits
  Rust trait
• C++ Operator Overloading → Rust std::ops Traits
  C++ 运算符重载与 Rust std::ops trait
• Exercise: Logger trait implementation
  练习：实现 Logger trait
• When to use enum vs dyn Trait
  何时使用枚举，何时使用 dyn Trait
• Exercise: Think Before You Translate
  练习：先思考，再翻译设计
• Rust generics
  Rust 泛型
• Exercise: Generics
  练习：泛型
• Combining Rust traits and generics
  组合使用 Rust trait 与泛型
• Rust traits constraints in data types
  数据类型中的 Rust trait 约束
• Exercise: Trait constraints and generics
  练习：trait 约束与泛型
• Rust type state pattern and generics
  Rust 类型状态模式与泛型
• Rust builder pattern
  Rust Builder 模式

11. Type System Advanced Features
11. 类型系统高级特性

• Rust From and Into traits
  Rust From 与 Into trait
• Exercise: From and Into
  练习：From 与 Into
• Rust Default trait
  Rust Default trait
• Other Rust type conversions
  Rust 的其他类型转换方式

12. Functional Programming
12. 函数式编程

• Rust closures
  Rust 闭包
• Exercise: Closures and capturing
  练习：闭包与捕获
• Rust iterators
  Rust 迭代器
• Exercise: Rust iterators
  练习：Rust 迭代器
• Iterator Power Tools Reference
  迭代器高阶工具速查

13. Concurrency
13. 并发

• Rust concurrency
  Rust 并发
• Why Rust prevents data races: Send and Sync
  为什么 Rust 能阻止数据竞争：Send 与 Sync
• Exercise: Multi-threaded word count
  练习：多线程词频统计

14. Unsafe Rust and FFI
14. Unsafe Rust 与 FFI

• Unsafe Rust
  Unsafe Rust
• Simple FFI example
  简单 FFI 示例
• Complex FFI example
  复杂 FFI 示例
• Ensuring correctness of unsafe code
  如何保证 unsafe 代码的正确性
• Exercise: Writing a safe FFI wrapper
  练习：编写安全的 FFI 包装层

Part II — Deep Dives
第二部分：专题深入

15. no_std — Rust for Bare Metal
15. no_std：面向裸机的 Rust

• What is no_std?
  什么是 no_std
• When to use no_std vs std
  什么时候用 no_std，什么时候用 std
• Exercise: no_std ring buffer
  练习：no_std 环形缓冲区
• Embedded Deep Dive
  嵌入式专题深入

16. Case Studies: Real-World C++ to Rust Translation
16. 案例研究：真实世界里的 C++ 到 Rust 迁移

• Case Study 1: Inheritance hierarchy → Enum dispatch
  案例 1：继承层级到枚举分发
• Case Study 2: shared_ptr tree → Arena/index pattern
  案例 2：shared_ptr 树到 arena/index 模式
• Case Study 3: Framework communication → Lifetime borrowing
  案例 3：框架通信到生命周期借用
• Case Study 4: God object → Composable state
  案例 4：上帝对象到可组合状态
• Case Study 5: Trait objects — when they ARE right
  案例 5：什么时候 trait object 反而是正确选择

Part III — Best Practices & Reference
第三部分：最佳实践与参考资料

17. Best Practices
17. 最佳实践

• Rust Best Practices Summary
  Rust 最佳实践总结
• Avoiding excessive clone()
  避免过度使用 clone()
• Avoiding unchecked indexing
  避免未检查的索引访问
• Collapsing assignment pyramids
  压平层层嵌套的赋值金字塔
• Capstone Exercise: Diagnostic Event Pipeline
  综合练习：诊断事件流水线
• Logging and Tracing Ecosystem
  日志与追踪生态

18. C++ → Rust Semantic Deep Dives
18. C++ → Rust 语义深入对照

• Casting, Preprocessor, Modules, volatile, static, constexpr, SFINAE, and more
  类型转换、预处理器、模块、volatile、static、constexpr、SFINAE 等主题

19. Rust Macros
19. Rust 宏

• Declarative macros (macro_rules!)
  声明式宏 macro_rules!
• Common standard library macros
  标准库中的常见宏
• Derive macros
  派生宏
• Attribute macros
  属性宏
• Procedural macros
  过程宏
• When to use what: macros vs functions vs generics
  宏、函数与泛型分别适合什么场景
• Exercises
  练习

Speaker intro and general approach
讲者介绍与课程整体思路

What you’ll learn: Course structure, the interactive format, and how familiar C/C++ concepts map to Rust equivalents. This chapter sets expectations and gives you a roadmap for the rest of the book.
本章将学到什么： 课程结构、互动式学习方式，以及熟悉的 C / C++ 概念如何映射到 Rust。本章先把预期对齐，再给出整本书的路线图。

• Speaker intro
  讲者背景
  • Principal Firmware Architect in Microsoft SCHIE (Silicon and Cloud Hardware Infrastructure Engineering) team
    微软 SCHIE（Silicon and Cloud Hardware Infrastructure Engineering）团队的首席固件架构师。
  • Industry veteran with expertise in security, systems programming, CPU and platform architecture, and C++ systems
    长期深耕安全、系统编程、CPU 与平台架构，以及 C++ 系统开发。
  • Started programming in Rust in 2017 at AWS EC2 and have been deeply invested in the language ever since
    2017 年在 AWS EC2 开始写 Rust，之后就一直深度投入这门语言。
• This course is intended to be as interactive as possible.
  这门课会尽量做成高互动形式。
  • Assumption: You know C, C++, or both
    默认前提：已经熟悉 C、C++，或者两者都熟。
  • Examples deliberately map familiar concepts to Rust equivalents
    示例会故意沿着熟悉概念往 Rust 对应物上带，减少认知跳跃。
  • Please feel free to ask clarifying questions at any point of time
    任何时候都可以插进来问澄清问题。
• Continued engagement with engineering teams is encouraged.
  也希望后续能继续和工程团队深入交流。

The case for Rust
为什么值得认真看 Rust

Want to skip straight to code? Jump to Show me some code
想直接看代码？ 可以跳到 给点代码看看。

Whether the background is C or C++, the core pain points are basically the same: memory-safety bugs that compile cleanly, then crash, corrupt, or leak at runtime.
不管主要背景是 C 还是 C++，最烦人的核心问题其实都差不多：内存安全 bug 编译时屁事没有，运行时却能把程序搞崩、把数据搞坏、把资源搞漏。

• Over 70% of CVEs are caused by memory-safety issues such as buffer overflows, dangling pointers, and use-after-free.
  超过 70% 的 CVE 都和内存安全问题有关，比如缓冲区溢出、悬垂指针、释放后继续使用。
• C++ shared_ptr、unique_ptr、RAII and move semantics are useful steps forward, but they are still bandaids, not cures.
  C++ 的 shared_ptr、unique_ptr、RAII 和移动语义确实进步很大，但本质上还只是 止血贴，不是根治方案。
• Gaps such as use-after-move, reference cycles, iterator invalidation, and exception-safety hazards are still left open.
  像 use-after-move、引用环、迭代器失效、异常安全这些口子，依然都在。
• Rust keeps the performance expectations of C / C++, while adding compile-time guarantees for safety.
  Rust 保住了 C / C++ 这一级别的性能，同时把安全保证提前到 编译期。

📖 Deep dive: See Why C/C++ Developers Need Rust for concrete vulnerability examples, the full list of problems Rust eliminates, and why C++ smart pointers still fall short.
📖 深入阅读： 为什么 C / C++ 开发者需要 Rust 里有更具体的漏洞案例、Rust 能消灭的问题清单，以及为什么 C++ 智能指针依然不够。

How does Rust address these issues?
Rust 是怎么处理这些问题的

Buffer overflows and bounds violations
缓冲区溢出与越界访问

• All Rust arrays, slices, and strings carry explicit bounds information.
  Rust 的数组、切片和字符串都带着明确的边界信息。
• The compiler inserts checks so that a bounds violation becomes a runtime panic, never undefined behavior.
  编译器会插入边界检查，越界访问顶多触发 运行时 panic，不会悄悄掉进未定义行为。

Dangling pointers and references
悬垂指针与悬垂引用

• Rust introduces lifetimes and borrow checking to eliminate dangling references at compile time.
  Rust 通过生命周期和借用检查，在 编译期 直接消灭悬垂引用。
• No dangling pointers and no use-after-free — the compiler simply refuses to accept such code.
  没有悬垂指针，也没有释放后继续使用；这种代码编译器压根就不让过。

Use-after-move
移动后继续使用

• Rust’s ownership system makes moves destructive. Once a value is moved, the original binding is unusable.
  Rust 的所有权系统把 move 设计成 破坏性转移。值一旦被移动，原绑定立刻失效。
• That means no zombie objects and no “valid but unspecified state” nonsense left behind.
  这样就不会留下什么僵尸对象，也不会冒出那种“有效但状态未指定”的烂摊子。

Resource management
资源管理

• Rust’s Drop trait is RAII done properly: resources are released automatically when they go out of scope.
  Rust 的 Drop trait 把 RAII 真正做扎实了：资源一出作用域就自动释放。
• It also blocks use-after-move, which is exactly the hole C++ RAII still cannot seal completely.
  同时它还和所有权系统联动，直接堵上了 C++ RAII 依然兜不住的 use-after-move 问题。
• No Rule of Five ceremony is required.
  也不用再背什么 Rule of Five 套路。

Error handling
错误处理

• Rust has no exceptions. Errors are values, usually represented as Result<T, E>.
  Rust 没有异常系统，错误就是值，最常见的载体就是 Result<T, E>。
• Error paths stay explicit in the type signature instead of藏在控制流后面。
  错误分支会直接写进类型签名里，而不是躲在隐蔽控制流后面。

Iterator invalidation
迭代器失效

• Rust’s borrow checker forbids modifying a collection while iterating over it.
  Rust 的借用检查器会 禁止边遍历边改容器 这种写法。
• A whole class of C++ 老毛病 therefore cannot even be expressed in valid Rust.
  这类在 C++ 代码库里反复出没的老毛病，在 Rust 里连合法代码都写不出来。

#![allow(unused)]
fn main() {
// Rust equivalent of erase-during-iteration: retain()
pending_faults.retain(|f| f.id != fault_to_remove.id);

// Or: collect into a new Vec (functional style)
let remaining: Vec<_> = pending_faults
    .into_iter()
    .filter(|f| f.id != fault_to_remove.id)
    .collect();
}

Data races
数据竞争

• The type system prevents data races at compile time through Send and Sync.
  类型系统通过 Send 和 Sync 在 编译期 阻止数据竞争。

Memory Safety Visualization
内存安全可视化

Rust Ownership — Safe by Design
Rust 所有权：从设计上就偏安全

#![allow(unused)]
fn main() {
fn safe_rust_ownership() {
    // Move is destructive: original is gone
    let data = vec![1, 2, 3];
    let data2 = data;           // Move happens
    // data.len();              // Compile error: value used after move
    
    // Borrowing: safe shared access
    let owned = String::from("Hello, World!");
    let slice: &str = &owned;  // Borrow — no allocation
    println!("{}", slice);     // Always safe
    
    // No dangling references possible
    /*
    let dangling_ref;
    {
        let temp = String::from("temporary");
        dangling_ref = &temp;  // Compile error: temp doesn't live long enough
    }
    */
}
}

graph TD
    A["Rust Ownership Safety<br/>Rust 所有权安全"] --> B["Destructive Moves<br/>破坏性移动"]
    A --> C["Automatic Memory Management<br/>自动内存管理"]
    A --> D["Compile-time Lifetime Checking<br/>编译期生命周期检查"]
    A --> E["No Exceptions - Result Types<br/>没有异常，靠 Result 类型"]
    
    B --> B1["Use-after-move is compile error<br/>移动后使用会直接编译失败"]
    B --> B2["No zombie objects<br/>不会留下僵尸对象"]
    
    C --> C1["Drop trait = RAII done right<br/>Drop trait 让 RAII 真正站住"]
    C --> C2["No Rule of Five needed<br/>不用写 Rule of Five 套路"]
    
    D --> D1["Borrow checker prevents dangling<br/>借用检查器阻止悬垂引用"]
    D --> D2["References always valid<br/>引用始终保持有效"]
    
    E --> E1["Result<T,E> - errors in types<br/>错误直接写进类型"]
    E --> E2["? operator for propagation<br/>用 ? 传播错误"]
    
    style A fill:#51cf66,color:#000
    style B fill:#91e5a3,color:#000
    style C fill:#91e5a3,color:#000
    style D fill:#91e5a3,color:#000
    style E fill:#91e5a3,color:#000

Memory Layout: Rust References
内存布局：Rust 引用

graph TD
    RM1["Stack<br/>栈"] --> RP1["&i32 ref<br/>`&i32` 引用"]
    RM2["Stack/Heap<br/>栈或堆"] --> RV1["i32 value = 42<br/>`i32` 值 = 42"]
    RP1 -.->|"Safe reference - Lifetime checked<br/>安全引用，已做生命周期检查"| RV1
    RM3["Borrow Checker<br/>借用检查器"] --> RC1["Prevents dangling refs at compile time<br/>在编译期阻止悬垂引用"]
    
    style RC1 fill:#51cf66,color:#000
    style RP1 fill:#91e5a3,color:#000

Box<T> Heap Allocation Visualization
Box<T> 堆分配示意

#![allow(unused)]
fn main() {
fn box_allocation_example() {
    // Stack allocation
    let stack_value = 42;
    
    // Heap allocation with Box
    let heap_value = Box::new(42);
    
    // Moving ownership
    let moved_box = heap_value;
    // heap_value is no longer accessible
}
}

graph TD
    subgraph "Stack Frame<br/>栈帧"
        SV["stack_value: 42"]
        BP["heap_value: Box<i32>"]
        BP2["moved_box: Box<i32>"]
    end
    
    subgraph "Heap<br/>堆"
        HV["42"]
    end
    
    BP -->|"Owns<br/>拥有"| HV
    BP -.->|"Move ownership<br/>转移所有权"| BP2
    BP2 -->|"Now owns<br/>现在拥有"| HV
    
    subgraph "After Move<br/>移动之后"
        BP_X["heap_value: MOVED<br/>heap_value：已移动"]
        BP2_A["moved_box: Box<i32>"]
    end
    
    BP2_A -->|"Owns<br/>拥有"| HV
    
    style BP_X fill:#ff6b6b,color:#000
    style HV fill:#91e5a3,color:#000
    style BP2_A fill:#51cf66,color:#000

Slice Operations Visualization
切片操作示意

#![allow(unused)]
fn main() {
fn slice_operations() {
    let data = vec![1, 2, 3, 4, 5, 6, 7, 8];
    
    let full_slice = &data[..];        // [1,2,3,4,5,6,7,8]
    let partial_slice = &data[2..6];   // [3,4,5,6]
    let from_start = &data[..4];       // [1,2,3,4]
    let to_end = &data[3..];           // [4,5,6,7,8]
}
}

graph TD
    V["Vec: [1, 2, 3, 4, 5, 6, 7, 8]"] --> FS["&data[..] -> all elements<br/>所有元素"]
    V --> PS["&data[2..6] -> [3, 4, 5, 6]"]
    V --> SS["&data[..4] -> [1, 2, 3, 4]"]
    V --> ES["&data[3..] -> [4, 5, 6, 7, 8]"]
    
    style V fill:#e3f2fd,color:#000
    style FS fill:#91e5a3,color:#000
    style PS fill:#91e5a3,color:#000
    style SS fill:#91e5a3,color:#000
    style ES fill:#91e5a3,color:#000

Other Rust USPs and features
Rust 其他明显优势

• No data races between threads because Send / Sync are checked at compile time.
  线程之间没有数据竞争，因为 Send / Sync 会在编译期被检查。
• No use-after-move, unlike C++ std::move, which can留下“被搬空但还能碰”的对象。
  没有 use-after-move，这一点和 C++ std::move 形成鲜明对比。
• No uninitialized variables.
  没有未初始化变量。
  • Every variable must be initialized before it is used.
    所有变量都必须先初始化再使用。
• No trivial memory leaks.
  不会出现那种轻轻松松就漏掉的内存泄漏。
  • Drop trait gives proper RAII without Rule of Five ceremony.
    Drop trait 把 RAII 做顺了，不需要 Rule of Five 仪式感写法。
  • The compiler releases memory automatically when values go out of scope.
    值离开作用域时，编译器会自动安排释放。
• No forgotten locks on mutexes.
  不会忘记解互斥锁。
  • Lock guards are the only legal way to access the protected data.
    锁守卫才是访问受保护数据的唯一正规入口。
• No exception-handling maze.
  也没有异常处理迷宫。
  • Errors are values (Result<T, E>) and are propagated with ?.
    错误就是值，通过 Result<T, E> 表达，再用 ? 传播。
• Excellent support for type inference, enums, pattern matching, and zero-cost abstractions.
  类型推断、枚举、模式匹配和零成本抽象都很能打。
• Built-in support for dependency management, building, testing, formatting, and linting.
  依赖管理、构建、测试、格式化、lint 这一整套工具链都是自带的。
  • cargo replaces the usual make / CMake plus extra lint and test glue.
    cargo 基本能替代 make / CMake 再加一堆零碎测试与检查工具。

Quick Reference: Rust vs C/C++
速查表：Rust 与 C / C++ 对照

Why C/C++ Developers Need Rust
为什么 C/C++ 开发者需要 Rust

What you’ll learn:
本章将学到什么：

• The full set of problems Rust removes: memory safety bugs, undefined behavior, data races, and more
  Rust 能从结构上消灭哪些问题：内存安全漏洞、未定义行为、数据竞争等等
• Why shared_ptr、unique_ptr and other C++ mitigations are patches rather than cures
  为什么 shared_ptr、unique_ptr 等 C++ 缓解手段更像补丁，而不是根治方案
• Concrete vulnerability patterns in C and C++ that are structurally impossible in safe Rust
  C 与 C++ 中那些真实存在的漏洞模式，为什么在安全 Rust 里从结构上就写不出来

Want to skip straight to code? Jump to Show me some code
想直接看代码？ 可以跳到 给点代码看看。

What Rust Eliminates — The Complete List
Rust 到底消灭了什么——完整清单

Before looking at examples, here is the executive summary: safe Rust prevents every issue in the list below by construction. These are not “best practices” that depend on discipline or review; they are guarantees enforced by the compiler and type system.
先别急着看例子，先看一句总纲：下面这张表里的每一类问题，安全 Rust 都是从结构上卡死的。这不是“靠自觉遵守规范”，也不是“靠 code review 多盯一眼”，而是编译器和类型系统直接给出的保证。

Bottom line: These are compile-time guarantees, not aspirations. If safe Rust code compiles, these classes of bugs cannot be present.
一句话概括： 这不是靠理想主义喊口号，而是编译期保证。只要安全 Rust 代码能编过，这些类别的 bug 就不存在。

The Problems Shared by C and C++
C 和 C++ 共有的问题

Want to skip the examples? Jump to How Rust Addresses All of This or straight to Show me some code.
如果懒得看这些例子： 可以直接跳到 Rust 是怎么把这些问题都收拾掉的，或者直接去 给点代码看看。

Both languages share a core group of memory-safety problems, and these problems sit behind a huge fraction of real-world CVEs.
这两门语言共享一整套核心内存安全问题，而现实世界里大量 CVE 的根子，基本都能追到这些地方来。

Buffer overflows
缓冲区溢出

C arrays, pointers, and C strings carry no built-in bounds information, so stepping past the end is absurdly easy.
C 的数组、指针和 C 风格字符串本身没有边界信息，所以越界这件事简直轻松得离谱。

#include <stdlib.h>
#include <string.h>

void buffer_dangers() {
    char buffer[10];
    strcpy(buffer, "This string is way too long!");  // Buffer overflow

    int arr[5] = {1, 2, 3, 4, 5};
    int *ptr = arr;           // Loses size information
    ptr[10] = 42;             // No bounds check — undefined behavior
}

在 C++ 里也没有彻底解决这个问题，std::vector::operator[] 一样不做边界检查，真想检查还得主动用 .at()。然后异常谁来接、什么时候接，又是另一坨事。
C++ does not fully solve this either: std::vector::operator[] still skips bounds checking. You only get checking with .at(), and then you are back to asking who catches the exception and where.

Dangling pointers and use-after-free
悬空指针与释放后继续使用

int *bar() {
    int i = 42;
    return &i;    // Returns address of stack variable — dangling!
}

void use_after_free() {
    char *p = (char *)malloc(20);
    free(p);
    *p = '\0';   // Use after free — undefined behavior
}

Uninitialized variables and undefined behavior
未初始化变量与未定义行为

C 和 C++ 都允许未初始化变量存在，读它们的时候会发生什么，全靠运气和编译器心情。
Both C and C++ allow uninitialized variables, and reading them is undefined behavior. What actually happens depends on luck, compiler optimizations, and whatever garbage happened to be in memory.

int x;               // Uninitialized
if (x > 0) { ... }  // UB — x could be anything

Signed integer overflow is also a classic trap. Unsigned overflow in C is defined, but signed overflow in both C and C++ is undefined behavior, and modern compilers absolutely exploit that fact for optimization.
有符号整数溢出也是老坑。C 里无符号溢出有定义，但有符号溢出在 C 和 C++ 里都是 UB。现代编译器是真的会利用这一点做优化，不是在吓唬人。

NULL pointer dereferences
空指针解引用

int *ptr = NULL;
*ptr = 42;           // SEGV — but the compiler won't stop you

在 C++ 里，std::optional<T> 确实能缓和一部分空值问题，但很多人最后还是直接 .value()，然后把风险换成抛异常。
C++ offers std::optional<T>, which helps, but many codebases still end up calling .value() and merely replacing null bugs with hidden exception paths.

The visualization: shared problems
可视化：共有问题

graph TD
    ROOT["C/C++ Memory Safety Issues<br/>C/C++ 内存安全问题"] --> BUF["Buffer Overflows<br/>缓冲区溢出"]
    ROOT --> DANGLE["Dangling Pointers<br/>悬空指针"]
    ROOT --> UAF["Use-After-Free<br/>释放后继续使用"]
    ROOT --> UNINIT["Uninitialized Variables<br/>未初始化变量"]
    ROOT --> NULL["NULL Dereferences<br/>空指针解引用"]
    ROOT --> UB["Undefined Behavior<br/>未定义行为"]
    ROOT --> RACE["Data Races<br/>数据竞争"]

    BUF --> BUF1["No bounds on arrays/pointers<br/>数组和指针没有边界信息"]
    DANGLE --> DANGLE1["Returning stack addresses<br/>返回栈地址"]
    UAF --> UAF1["Reusing freed memory<br/>继续使用已释放内存"]
    UNINIT --> UNINIT1["Indeterminate values<br/>不确定值"]
    NULL --> NULL1["No forced null checks<br/>没有强制空值检查"]
    UB --> UB1["Signed overflow, aliasing<br/>有符号溢出、别名等"]
    RACE --> RACE1["No compile-time safety<br/>没有编译期并发安全保障"]

    style ROOT fill:#ff6b6b,color:#000
    style BUF fill:#ffa07a,color:#000
    style DANGLE fill:#ffa07a,color:#000
    style UAF fill:#ffa07a,color:#000
    style UNINIT fill:#ffa07a,color:#000
    style NULL fill:#ffa07a,color:#000
    style UB fill:#ffa07a,color:#000
    style RACE fill:#ffa07a,color:#000

C++ Adds More Problems on Top
C++ 还额外叠了一层问题

C audience: If C++ is not part of your world, you can skip ahead to How Rust Addresses All of This.
如果主要写 C，不怎么碰 C++： 可以直接跳到 Rust 是怎么把这些问题都收拾掉的。

Want to skip straight to code? Jump to Show me some code.
想直接看代码？ 可以直接跳到 给点代码看看。

C++ introduced smart pointers, RAII, move semantics, templates, and exceptions to improve on C. These are meaningful improvements, but they often change “obvious crash at runtime” into “subtler bug at runtime” rather than eliminating the entire class of failure.
C++ 引入了智能指针、RAII、move 语义、模板、异常，确实比 C 前进了一大步。但很多时候，它做的是把“当场炸掉的 bug”换成“更隐蔽、更难查的 bug”，而不是直接把这类错误从语言层面抹掉。

unique_ptr and shared_ptr — patches, not cures
unique_ptr 和 shared_ptr——补丁，不是根治

// unique_ptr: use-after-move compiles cleanly
std::unique_ptr<int> ptr = std::make_unique<int>(42);
std::unique_ptr<int> ptr2 = std::move(ptr);
std::cout << *ptr;  // Compiles! Undefined behavior at runtime.
                     // In Rust, this is a compile error: "value used after move"

// shared_ptr: reference cycles leak silently
struct Node {
    std::shared_ptr<Node> next;
    std::shared_ptr<Node> parent;  // Cycle! Destructor never called.
};
auto a = std::make_shared<Node>();
auto b = std::make_shared<Node>();
a->next = b;
b->parent = a;  // Memory leak — ref count never reaches 0
                 // In Rust, Rc<T> + Weak<T> makes cycles explicit and breakable

Use-after-move — the quiet killer
move 之后继续使用——安静又致命

C++ 的 std::move 并不是真的“把原变量从语义上抹掉”，它更像一个 cast。原对象还在，只是处于“合法但未指定状态”。而编译器允许继续用它。
C++ std::move is not a destructive move in the Rust sense. It is closer to a cast that enables moving, while leaving the original object in a “valid but unspecified” state. The compiler still lets you touch it.

auto vec = std::make_unique<std::vector<int>>({1, 2, 3});
auto vec2 = std::move(vec);
vec->size();  // Compiles! But dereferencing nullptr — crash at runtime

In Rust, the move is destructive and the old binding is gone.
Rust 则不玩这套暧昧状态，move 完就是没了。

#![allow(unused)]
fn main() {
let vec = vec![1, 2, 3];
let vec2 = vec;           // Move — vec is consumed
// vec.len();             // Compile error: value used after move
}

Iterator invalidation — real production bugs
迭代器失效——线上常见真 bug

These are not toy snippets. They represent real bug patterns that repeatedly appear in large C++ codebases.
下面这些不是教学玩具，而是大体量 C++ 代码库里反复出现的真问题模式。

// BUG 1: erase without reassigning iterator (undefined behavior)
while (it != pending_faults.end()) {
    if (*it != nullptr && (*it)->GetId() == fault->GetId()) {
        pending_faults.erase(it);   // ← iterator invalidated!
        removed_count++;            //   next loop uses dangling iterator
    } else {
        ++it;
    }
}
// Fix: it = pending_faults.erase(it);

// BUG 2: index-based erase skips elements
for (auto i = 0; i < entries.size(); i++) {
    if (config_status == ConfigDisable::Status::Disabled) {
        entries.erase(entries.begin() + i);  // ← shifts elements
    }                                         //   i++ skips the shifted one
}

// BUG 3: one erase path correct, the other isn't
while (it != incomplete_ids.end()) {
    if (current_action == nullptr) {
        incomplete_ids.erase(it);  // ← BUG: iterator not reassigned
        continue;
    }
    it = incomplete_ids.erase(it); // ← Correct path
}

These all compile. Rust simply refuses to let the same “iterate while mutating unsafely” shape exist in safe code.
这些代码全都能编。Rust 的做法更干脆：这种“边迭代边危险修改”的代码形状，在安全代码里根本不给过。

Exception safety and dynamic_cast plus new
异常安全，以及 dynamic_cast 加 new 这一套

// Typical C++ factory pattern — every branch is a potential bug
DriverBase* driver = nullptr;
if (dynamic_cast<ModelA*>(device)) {
    driver = new DriverForModelA(framework);
} else if (dynamic_cast<ModelB*>(device)) {
    driver = new DriverForModelB(framework);
}
// What if driver is still nullptr? What if new throws? Who owns driver?

这种模式的问题不是“写不出来”，而是每一个分支都在偷藏前提：谁负责释放，哪个分支可能抛异常，没匹配到类型时怎么办，半构造状态怎么收尾。
The issue here is not that the code cannot be made to work. The issue is that every branch quietly depends on ownership, construction, and failure assumptions that the compiler does not fully verify.

Dangling references and lambda captures
悬空引用与 lambda 捕获

int& get_reference() {
    int x = 42;
    return x;  // Dangling reference — compiles, UB at runtime
}

auto make_closure() {
    int local = 42;
    return [&local]() { return local; };  // Dangling capture!
}

The visualization: C++ additional problems
可视化：C++ 额外叠加的问题

graph TD
    ROOT["C++ Additional Problems<br/>C++ 额外问题"] --> UAM["Use-After-Move<br/>move 后继续使用"]
    ROOT --> CYCLE["Reference Cycles<br/>循环引用"]
    ROOT --> ITER["Iterator Invalidation<br/>迭代器失效"]
    ROOT --> EXC["Exception Safety<br/>异常安全"]
    ROOT --> TMPL["Template Error Messages<br/>模板报错灾难"]

    UAM --> UAM1["std::move leaves zombie<br/>move 完还留僵尸对象"]
    CYCLE --> CYCLE1["shared_ptr cycles leak<br/>shared_ptr 环状泄漏"]
    ITER --> ITER1["erase() invalidates iterators<br/>erase 让迭代器失效"]
    EXC --> EXC1["Partial construction<br/>半构造状态"]
    TMPL --> TMPL1["30+ lines of nested<br/>几十行模板实例化报错"]

    style ROOT fill:#ff6b6b,color:#000
    style UAM fill:#ffa07a,color:#000
    style CYCLE fill:#ffa07a,color:#000
    style ITER fill:#ffa07a,color:#000
    style EXC fill:#ffa07a,color:#000
    style TMPL fill:#ffa07a,color:#000

How Rust Addresses All of This
Rust 是怎么把这些问题都收拾掉的

Every issue above maps to one or more compile-time guarantees in Rust.
上面那些问题，在 Rust 里基本都能对应到一条或几条编译期保证。

#![allow(unused)]
fn main() {
fn rust_prevents_everything() {
    // ✅ No buffer overflow — bounds checked
    let arr = [1, 2, 3, 4, 5];
    // arr[10];  // panic at runtime, never UB

    // ✅ No use-after-move — compile error
    let data = vec![1, 2, 3];
    let moved = data;
    // data.len();  // error: value used after move

    // ✅ No dangling pointer — lifetime error
    // let r;
    // { let x = 5; r = &x; }  // error: x does not live long enough

    // ✅ No null — Option forces handling
    let maybe: Option<i32> = None;
    // maybe.unwrap();  // panic, but you'd use match or if let instead

    // ✅ No data race — compile error
    // let mut shared = vec![1, 2, 3];
    // std::thread::spawn(|| shared.push(4));  // error: closure may outlive
    // shared.push(5);                         //   borrowed value
}
}

Rust’s safety model — the full picture
Rust 安全模型全景图

graph TD
    RUST["Rust Safety Guarantees<br/>Rust 安全保证"] --> OWN["Ownership System<br/>所有权系统"]
    RUST --> BORROW["Borrow Checker<br/>借用检查器"]
    RUST --> TYPES["Type System<br/>类型系统"]
    RUST --> TRAITS["Send/Sync Traits<br/>并发安全 trait"]

    OWN --> OWN1["No use-after-free<br/>No use-after-move<br/>No double-free"]
    BORROW --> BORROW1["No dangling references<br/>No iterator invalidation<br/>No data races through refs"]
    TYPES --> TYPES1["No NULL (Option&lt;T&gt;)<br/>No exceptions (Result&lt;T,E&gt;)<br/>No uninitialized values"]
    TRAITS --> TRAITS1["No data races<br/>Send = safe to transfer<br/>Sync = safe to share"]

    style RUST fill:#51cf66,color:#000
    style OWN fill:#91e5a3,color:#000
    style BORROW fill:#91e5a3,color:#000
    style TYPES fill:#91e5a3,color:#000
    style TRAITS fill:#91e5a3,color:#000

Quick Reference: C vs C++ vs Rust
速查表：C、C++ 与 Rust 对照

Enough talk already: Show me some code
废话少说，先上代码

What you’ll learn: Your first Rust program — fn main(), println!(), and how Rust macros differ fundamentally from C/C++ preprocessor macros. By the end you’ll be able to write, compile, and run simple Rust programs.
本章将学到什么： 第一个 Rust 程序应该怎么写，fn main() 和 println!() 是什么，以及 Rust 宏和 C/C++ 预处理宏在根子上有什么不同。读完这一章，就能自己写、编译并运行简单的 Rust 程序。

fn main() {
    println!("Hello world from Rust");
}

• The above syntax should be similar to anyone familiar with C-style languages
  上面这段语法，对熟悉 C 风格语言的人来说应该很眼熟。

  • All functions in Rust begin with the fn keyword
    Rust 里的函数统一用 fn 关键字开头。
  • The default entry point for executables is main()
    可执行程序的默认入口函数就是 main()。
  • The println! looks like a function, but is actually a macro. Macros in Rust are very different from C/C++ preprocessor macros — they are hygienic, type-safe, and operate on the syntax tree rather than text substitution
    println! 看着像函数，其实是 宏。Rust 的宏和 C/C++ 的预处理宏差别很大，它们具备卫生性和类型安全，操作对象是语法树，而不是简单的文本替换。

• Two great ways to quickly try out Rust snippets:
  想快速试一小段 Rust 代码，有两个特别方便的办法：

  • Online: Rust Playground — paste code, hit Run, share results. No install needed
    在线方式：Rust Playground。把代码贴进去，点 Run 就能跑，还方便分享结果，连安装都省了。
  • Local REPL: Install evcxr_repl for an interactive Rust REPL (like Python’s REPL, but for Rust):
    本地 REPL：安装 evcxr_repl，就能得到一个交互式 Rust REPL，体验上有点像 Python 的交互解释器。

cargo install --locked evcxr_repl
evcxr   # Start the REPL, type Rust expressions interactively

Rust Local installation
Rust 本地安装

• Rust can be locally installed using the following methods
  Rust 本地安装通常用下面这些方式：

  • Windows: https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe
    Windows 直接运行 rustup-init.exe 安装器即可。
  • Linux / WSL: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    Linux / WSL 一般用官方提供的一条 shell 安装命令。

• The Rust ecosystem is composed of the following components
  Rust 工具链大致由下面几块组成：

  • rustc is the standalone compiler, but it’s seldom used directly
    rustc 是底层编译器，但平时很少直接裸用它。
  • The preferred tool, cargo is the Swiss Army knife and is used for dependency management, building, testing, formatting, linting, etc.
    真正高频使用的是 cargo。这玩意就是 Rust 世界的瑞士军刀，依赖管理、构建、测试、格式化、lint 基本都归它管。
  • The Rust toolchain comes in the stable, beta and nightly (experimental) channels, but we’ll stick with stable. Use the rustup update command to upgrade the stable installation that’s released every six weeks
    Rust 工具链分 stable、beta 和实验性质更强的 nightly。这里默认先用 stable。它大约每六周发一版，更新时跑 rustup update 就行。

• We’ll also install the rust-analyzer plug-in for VSCode
  另外也建议顺手装上 VS Code 的 rust-analyzer 插件，补全、跳转和诊断体验会好很多。

这套安装流程比传统 C/C++ 开发环境省心得多。尤其是刚从“编译器、构建系统、包管理器、IDE 插件全靠自己拼”的世界里过来时，Cargo 和 rustup 的统一体验会显得格外顺。
很多人第一次碰 Rust 就觉得工具链终于像一个整体了，说的就是这个感觉。

Rust packages (crates)
Rust 包，也就是 crate

• Rust binaries are created using packages (hereby called crates)
  Rust 的可执行程序通常由 package 构建出来，这里统一把它们叫 crate。
  • A crate may either be standalone, or may have dependency on other crates. The crates for the dependencies can be local or remote. Third-party crates are typically downloaded from a centralized repository called crates.io.
    crate 可以是独立项目，也可以依赖其他 crate。依赖既可以是本地路径，也可以是远程来源。第三方 crate 通常从集中仓库 crates.io 下载。
  • The cargo tool automatically handles the downloading of crates and their dependencies. This is conceptually equivalent to linking to C-libraries
    cargo 会自动处理 crate 以及其依赖的下载和构建。从概念上说，这有点像 C 里链接外部库，但流程自动化程度高得多。
  • Crate dependencies are expressed in a file called Cargo.toml. It also defines the target type for the crate: standalone executable, static library, dynamic library (uncommon)
    crate 的依赖都写在 Cargo.toml 里。这个文件还会描述目标类型，例如独立可执行程序、静态库、动态库等。
  • Reference: https://doc.rust-lang.org/cargo/reference/cargo-targets.html
    参考文档： https://doc.rust-lang.org/cargo/reference/cargo-targets.html

对 C/C++ 开发者来说，这一节是非常关键的思维切换。Rust 不是“把源码交给编译器，再自己去 Makefile 或 CMake 里补完剩下的一切”；它默认就把项目定义、依赖图和构建流程绑在一起了。
这会让不少老 C++ 工程师一开始觉得有点不习惯，但习惯之后基本回不去手搓依赖那套日子。

Cargo vs Traditional C Build Systems
Cargo 与传统 C 构建系统对比

Dependency Management Comparison
依赖管理对比

graph TD
    subgraph "Traditional C Build Process"
        CC["C Source Files<br/>(.c, .h)"]
        CM["Manual Makefile<br/>or CMake"]
        CL["Linker"]
        CB["Final Binary"]
        
        CC --> CM
        CM --> CL
        CL --> CB
        
        CDep["Manual dependency<br/>management"]
        CLib1["libcurl-dev<br/>(apt install)"]
        CLib2["libjson-dev<br/>(apt install)"]
        CInc["Manual include paths<br/>-I/usr/include/curl"]
        CLink["Manual linking<br/>-lcurl -ljson"]
        
        CDep --> CLib1
        CDep --> CLib2
        CLib1 --> CInc
        CLib2 --> CInc
        CInc --> CM
        CLink --> CL
        
        C_ISSUES["[ERROR] Version conflicts<br/>[ERROR] Platform differences<br/>[ERROR] Missing dependencies<br/>[ERROR] Linking order matters<br/>[ERROR] No automated updates"]
    end
    
    subgraph "Rust Cargo Build Process"
        RS["Rust Source Files<br/>(.rs)"]
        CT["Cargo.toml<br/>[dependencies]<br/>reqwest = '0.11'<br/>serde_json = '1.0'"]
        CRG["Cargo Build System"]
        RB["Final Binary"]
        
        RS --> CRG
        CT --> CRG
        CRG --> RB
        
        CRATES["crates.io<br/>(Package registry)"]
        DEPS["Automatic dependency<br/>resolution"]
        LOCK["Cargo.lock<br/>(Version pinning)"]
        
        CRATES --> DEPS
        DEPS --> CRG
        CRG --> LOCK
        
        R_BENEFITS["[OK] Semantic versioning<br/>[OK] Automatic downloads<br/>[OK] Cross-platform<br/>[OK] Transitive dependencies<br/>[OK] Reproducible builds"]
    end
    
    style C_ISSUES fill:#ff6b6b,color:#000
    style R_BENEFITS fill:#91e5a3,color:#000
    style CM fill:#ffa07a,color:#000
    style CDep fill:#ffa07a,color:#000
    style CT fill:#91e5a3,color:#000
    style CRG fill:#91e5a3,color:#000
    style DEPS fill:#91e5a3,color:#000
    style CRATES fill:#91e5a3,color:#000

这张图的意思很直接。传统 C 构建流程里，依赖安装、头文件路径、链接顺序、平台差异，样样都可能整出幺蛾子。Cargo 则把其中大半脏活统一吃掉了。
当然 Cargo 不是万能药，但它至少把“构建一份正常项目”这件事从手工拼装活，改造成了标准工作流。

Cargo Project Structure
Cargo 项目结构

my_project/
|-- Cargo.toml          # Project configuration (like package.json)
|-- Cargo.lock          # Exact dependency versions (auto-generated)
|-- src/
|   |-- main.rs         # Main entry point for binary
|   |-- lib.rs          # Library root (if creating a library)
|   `-- bin/            # Additional binary targets
|-- tests/              # Integration tests
|-- examples/           # Example code
|-- benches/            # Benchmarks
`-- target/             # Build artifacts (like C's build/ or obj/)
    |-- debug/          # Debug builds (fast compile, slow runtime)
    `-- release/        # Release builds (slow compile, fast runtime)

这个目录结构很值得熟悉，因为后面几乎所有 Rust 项目都会长得差不多。
它最大的好处，就是“哪里放主程序、哪里放库代码、哪里放测试和例子”这类问题不再需要团队每次重新发明一套规矩。

Common Cargo Commands
常用 Cargo 命令

graph LR
    subgraph "Project Lifecycle"
        NEW["cargo new my_project<br/>[FOLDER] Create new project"]
        CHECK["cargo check<br/>[SEARCH] Fast syntax check"]
        BUILD["cargo build<br/>[BUILD] Compile project"]
        RUN["cargo run<br/>[PLAY] Build and execute"]
        TEST["cargo test<br/>[TEST] Run all tests"]
        
        NEW --> CHECK
        CHECK --> BUILD
        BUILD --> RUN
        BUILD --> TEST
    end
    
    subgraph "Advanced Commands"
        UPDATE["cargo update<br/>[CHART] Update dependencies"]
        FORMAT["cargo fmt<br/>[SPARKLES] Format code"]
        LINT["cargo clippy<br/>[WRENCH] Lint and suggestions"]
        DOC["cargo doc<br/>[BOOKS] Generate documentation"]
        PUBLISH["cargo publish<br/>[PACKAGE] Publish to crates.io"]
    end
    
    subgraph "Build Profiles"
        DEBUG["cargo build<br/>(debug profile)<br/>Fast compile<br/>Slow runtime<br/>Debug symbols"]
        RELEASE["cargo build --release<br/>(release profile)<br/>Slow compile<br/>Fast runtime<br/>Optimized"]
    end
    
    style NEW fill:#a3d5ff,color:#000
    style CHECK fill:#91e5a3,color:#000
    style BUILD fill:#ffa07a,color:#000
    style RUN fill:#ffcc5c,color:#000
    style TEST fill:#c084fc,color:#000
    style DEBUG fill:#94a3b8,color:#000
    style RELEASE fill:#ef4444,color:#000

这里最值得尽快养成习惯的命令通常有三个：cargo check、cargo run、cargo test。
cargo check 特别好使，它只做类型检查和分析，不生成最终二进制，速度比完整编译快得多。写代码时高频跑这个，体验会舒服不少。

Example: cargo and crates
示例：Cargo 与 crate 的基本使用

• In this example, we have a standalone executable crate with no other dependencies
  这个例子里先只建一个没有额外依赖的独立可执行 crate。
• Use the following commands to create a new crate called helloworld
  用下面这些命令创建一个叫 helloworld 的 crate：

cargo new helloworld
cd helloworld
cat Cargo.toml

• By default, cargo run will compile and run the debug (unoptimized) version of the crate. To execute the release version, use cargo run --release
  默认情况下，cargo run 会编译并运行 debug 版本，也就是未优化构建。想跑优化版，就用 cargo run --release。
• Note that actual binary file resides under the target folder under the debug or release folder
  真正生成出来的二进制文件，会落在 target/debug/ 或 target/release/ 下面。
• We might have also noticed a file called Cargo.lock in the same folder as the source. It is automatically generated and should not be modified by hand
  同目录里还会看到一个 Cargo.lock 文件，它是自动生成的，别手动瞎改。
  • We will revisit the specific purpose of Cargo.lock later
    后面还会专门回头讲 Cargo.lock 的具体作用。

这一章最重要的，不是记住某个命令，而是接受一个事实：Rust 项目开发默认就是围绕 Cargo 展开的。
只要把这套工作方式吃透，后面学习依赖管理、测试、文档、工作区和发布流程时，很多东西都会顺着接上。

Built-in Rust types
Rust 内建类型

What you’ll learn: Rust’s fundamental types (i32, u64, f64, bool, char), type inference, explicit type annotations, and how they compare to C/C++ primitive types. No implicit conversions — Rust requires explicit casts.
本章将学到什么： Rust 的基础类型，例如 i32、u64、f64、bool、char，以及类型推断、显式类型标注，还有它们和 C/C++ 基本类型的对照关系。Rust 没有隐式类型转换，涉及转换时必须显式 cast。

• Rust has type inference, but also allows explicit specification of the type
  Rust 支持类型推断，同时也允许显式写出类型。

• Rust permits arbitrarily use of _ between numbers for ease of reading
  Rust 允许在数字中任意插入 _ 来增强可读性。

Rust type specification and assignment
Rust 类型标注与赋值

• Rust uses the let keyword to assign values to variables. The type of the variable can be optionally specified after a :
  Rust 使用 let 给变量赋值。变量类型可以省略，也可以在 : 后面显式标出。

fn main() {
    let x : i32 = 42;
    // These two assignments are logically equivalent
    let y : u32 = 42;
    let z = 42u32;
}

• Function parameters and return values (if any) require an explicit type. The following takes an u8 parameter and returns u32
  函数参数和返回值如果存在，都必须显式标注类型。下面这个函数接收一个 u8 参数，并返回 u32。

#![allow(unused)]
fn main() {
fn foo(x : u8) -> u32
{
    return x as u32 * x as u32;
}
}

• Unused variables are prefixed with _ to avoid compiler warnings
  未使用变量通常以前缀 _ 命名，这样可以避免编译器警告。

Rust type specification and inference
Rust 类型标注与类型推断

• Rust can automatically infer the type of the variable based on the context.
  Rust 可以根据上下文自动推断变量类型。
• ▶ Try it in the Rust Playground
  ▶ 在 Rust Playground 里试一试

fn secret_of_life_u32(x : u32) {
    println!("The u32 secret_of_life is {}", x);
}

fn secret_of_life_u8(x : u8) {
    println!("The u8 secret_of_life is {}", x);
}

fn main() {
    let a = 42; // The let keyword assigns a value; type of a is u32
    let b = 42; // The let keyword assigns a value; inferred type of b is u8
    secret_of_life_u32(a);
    secret_of_life_u8(b);
}

Rust variables and mutability
Rust 变量与可变性

• Rust variables are immutable by default unless the mut keyword is used to denote that a variable is mutable. For example, the following code will not compile unless the let a = 42 is changed to let mut a = 42
  Rust 变量默认是 不可变 的，除非显式使用 mut 表示该变量可变。比如下面这段代码，如果不把 let a = 42 改成 let mut a = 42，就无法通过编译。

fn main() {
    let a = 42; // Must be changed to let mut a = 42 to permit the assignment below 
    a = 43;  // Will not compile unless the above is changed
}

• Rust permits the reuse of the variable names (shadowing)
  Rust 允许重复使用变量名，这叫 shadowing。

fn main() {
    let a = 42;
    {
        let a = 43; //OK: Different variable with the same name
    }
    // a = 43; // Not permitted
    let a = 43; // Ok: New variable and assignment
}

Rust if keyword
Rust 的 if 关键字

What you’ll learn: Rust’s control flow constructs — if/else as expressions, loop/while/for, match, and how they differ from C/C++ counterparts. The key insight: most Rust control flow returns values.
将学到什么： Rust 的控制流结构，包括作为表达式的 if/else、loop/while/for、match，以及它们与 C/C++ 对应写法的差异。最重要的一点是：Rust 中的大多数控制流都能返回值。

• In Rust, if is actually an expression, i.e., it can be used to assign values, but it also behaves like a statement. ▶ Try it
  在 Rust 中，if 实际上是表达式，也就是说它可以参与赋值；但与此同时，它也具备语句的行为。▶ 亲自试试

fn main() {
    let x = 42;
    if x < 42 {
        println!("Smaller than the secret of life");
    } else if x == 42 {
        println!("Is equal to the secret of life");
    } else {
        println!("Larger than the secret of life");
    }
    let is_secret_of_life = if x == 42 {true} else {false};
    println!("{}", is_secret_of_life);
}

Rust loops using while and for
使用 while 和 for 的 Rust 循环

• The while keyword can be used to loop while an expression is true
  while 关键字可以在条件表达式为真时持续循环

fn main() {
    let mut x = 40;
    while x != 42 {
        x += 1;
    }
}

• The for keyword can be used to iterate over ranges
  for 关键字可以用于遍历区间

fn main() {
    // Will not print 43; use 40..=43 to include last element
    for x in 40..43 {
        println!("{}", x);
    } 
}

Rust loops using loop
使用 loop 的 Rust 循环

• The loop keyword creates an infinite loop until a break is encountered
  loop 关键字会创建一个无限循环，直到遇到 break 为止

fn main() {
    let mut x = 40;
    // Change the below to 'here: loop to specify optional label for the loop
    loop {
        if x == 42 {
            break; // Use break x; to return the value of x
        }
        x += 1;
    }
}

• The break statement can include an optional expression that can be used to assign the value of a loop expression
  break 语句可以附带一个表达式，用来作为整个 loop 表达式的返回值
• The continue keyword can be used to return to the top of the loop
continue 关键字可以让流程直接回到 loop 的开头
• Loop labels can be used with break or continue and are useful when dealing with nested loops
  循环标签可以和 break 或 continue 一起使用，在处理嵌套循环时尤其有用

Rust expression blocks
Rust 表达式代码块

• Rust expression blocks are simply a sequence of expressions enclosed in {}. The evaluated value is simply the last expression in the block
  Rust 的表达式代码块就是一串被 {} 包裹起来的表达式，其求值结果就是代码块中的最后一个表达式

fn main() {
    let x = {
        let y = 40;
        y + 2 // Note: ; must be omitted
    };
    // Notice the Python style printing
    println!("{x}");
}

• Rust style is to use this to omit the return keyword in functions
  Rust 的惯用写法经常利用这一点，在函数中省略 return 关键字

fn is_secret_of_life(x: u32) -> bool {
    // Same as if x == 42 {true} else {false}
    x == 42 // Note: ; must be omitted 
}
fn main() {
    println!("{}", is_secret_of_life(42));
}

Data Structures §§ZH§§ 数据结构

Rust array type
Rust 的数组类型

What you’ll learn: Rust’s core data structures — arrays, tuples, slices, strings, structs, Vec, and HashMap. This is a dense chapter; focus on understanding String vs &str and how structs work. You’ll revisit references and borrowing in depth in chapter 7.
本章将学到什么： Rust 里最常用的几类核心数据结构：数组、元组、切片、字符串、结构体、Vec 和 HashMap。这一章信息量比较大，先重点盯住 String 和 &str 的区别，以及结构体是怎么工作的。引用和借用会在第 7 章再深入展开。

• Arrays contain a fixed number of elements of the same type.
  数组里装的是固定数量、相同类型的元素。
  • Like all other Rust types, arrays are immutable by default unless mut is used.
    和 Rust 里其他类型一样，数组默认也是不可变的，除非显式写 mut。
  • Arrays are indexed using [] and the access is bounds-checked. Use .len() to get the array length.
    数组用 [] 索引，而且会做边界检查。数组长度可以通过 .len() 取得。

    fn get_index(y : usize) -> usize {
        y+1        
    }
    
    fn main() {
        // Initializes an array of 10 elements and sets all to 42
        let a : [u8; 3] = [42; 3];
        // Alternative syntax
        // let a = [42u8, 42u8, 42u8];
        for x in a {
            println!("{x}");
        }
        let y = get_index(a.len());
        // Commenting out the below will cause a panic
        //println!("{}", a[y]);
    }

Rust array type continued
Rust 数组补充说明

• Arrays can be nested.
  数组还可以继续嵌套数组。
  • Rust has several built-in formatters for printing. In the example below, :? is the debug formatter, and :#? can be used for pretty printing. These formatters can also be customized per type later on.
    Rust 内置了几种常用打印格式。下面例子里的 :? 是调试打印格式，:#? 则是更适合阅读的 pretty print。后面也会看到，这些输出格式还能按类型自定义。

    fn main() {
        let a = [
            [40, 0], // Define a nested array
            [41, 0],
            [42, 1],
        ];
        for x in a {
            println!("{x:?}");
        }
    }

Rust tuples
Rust 的元组

• Tuples have a fixed size and can group arbitrary types into one compound value.
  元组也是固定大小，但它能把不同类型的值组合到一起。
  • Individual elements are accessed by position: .0, .1, .2, and so on. The empty tuple () is called the unit value and is roughly the Rust equivalent of a void return value.
    元组元素按位置访问，也就是 .0、.1、.2 这种写法。空元组 () 叫 unit value，大致可以看成 Rust 里的“空返回值”。
  • Rust also supports tuple destructuring, which makes it easy to bind names to each element.
    Rust 还支持元组解构，能很方便地把各个位置的值分别绑定到变量上。

fn get_tuple() -> (u32, bool) {
    (42, true)        
}

fn main() {
   let t : (u8, bool) = (42, true);
   let u : (u32, bool) = (43, false);
   println!("{}, {}", t.0, t.1);
   println!("{}, {}", u.0, u.1);
   let (num, flag) = get_tuple(); // Tuple destructuring
   println!("{num}, {flag}");
}

Rust references
Rust 的引用

• References in Rust are roughly comparable to pointers in C, but with much stricter rules.
  Rust 的引用和 C 里的指针有点像，但规则严格得多，不是一个量级。
  • Any number of immutable references may coexist at the same time. A reference also cannot outlive the scope of the value it points to. That idea is the basis of lifetimes, which will be discussed in detail later.
    同一时间可以存在任意多个不可变引用，而且引用的存活时间绝对不能超过它指向的值。这背后就是生命周期的核心概念，后面会单独细讲。
  • Only one mutable reference to a mutable value may exist at a time, and it cannot overlap with other references.
    可变引用则更严格：同一时刻只能有一个，而且不能和其他引用重叠。

fn main() {
    let mut a = 42;
    {
        let b = &a;
        let c = b;
        println!("{} {}", *b, *c); // The compiler automatically dereferences *c
        // Illegal because b and still are still in scope
        // let d = &mut a;
    }
    let d = &mut a; // Ok: b and c are not in scope
    *d = 43;
}

Rust slices
Rust 的切片

• References can be used to create views over part of an array.
  引用还能用来从数组里切出一段视图，也就是切片。
  • Arrays have a compile-time fixed length, while slices can describe a range of arbitrary size. Internally, a slice is a fat pointer containing both a start pointer and a length.
    数组长度在编译期就固定了，而切片只是“看向其中一段”的视图，长度可以变化。底层上，切片是一个胖指针，里面既有起始位置，也有长度信息。

fn main() {
    let a = [40, 41, 42, 43];
    let b = &a[1..a.len()]; // A slice starting with the second element in the original
    let c = &a[1..]; // Same as the above
    let d = &a[..]; // Same as &a[0..] or &a[0..a.len()]
    println!("{b:?} {c:?} {d:?}");
}

Rust constants and statics
Rust 的常量与静态变量

• The const keyword defines a constant value. Constant expressions are evaluated at compile time and typically get inlined into the final program.
  const 用来定义常量值。常量会在编译期求值，通常会被直接内联进程序里。
• The static keyword defines a true global variable similar to what C/C++ programs use. A static has a fixed memory address and exists for the entire lifetime of the program.
  static 则更像 C/C++ 里的全局变量：有固定地址，程序整个生命周期里都一直存在。

const SECRET_OF_LIFE: u32 = 42;
static GLOBAL_VARIABLE : u32 = 2;
fn main() {
    println!("The secret of life is {}", SECRET_OF_LIFE);
    println!("Value of global variable is {GLOBAL_VARIABLE}")
}

Rust strings: String vs &str
Rust 字符串：String 和 &str 的区别

• Rust has two string types with different jobs.
  Rust 里有 两种 字符串类型，它们分工完全不同。
  • String is owned, heap-allocated, and growable. You can roughly compare it to a manually managed heap buffer in C or to C++ std::string.
    String 是拥有型、堆分配、可增长的字符串。大致可以类比 C 里自己管理的堆缓冲区，或者 C++ 的 std::string。
  • &str is a borrowed string slice. It is lightweight, read-only, and closer in spirit to const char* plus a length, or to C++ std::string_view, except that Rust actually checks its lifetime so it cannot dangle.
    &str 是借用来的字符串切片，轻量、只读，更接近“带长度的 const char*”或者 C++ 的 std::string_view。区别在于 Rust 真会检查生命周期，所以它不能悬空。
  • Rust strings are not null-terminated. They track length explicitly and are guaranteed to contain valid UTF-8.
    Rust 字符串也不是靠结尾 \0 判断长度的，而是显式记录长度，并且保证内容是合法 UTF-8。

For C++ developers: String ≈ std::string, &str ≈ std::string_view. Unlike std::string_view, a Rust &str is guaranteed valid for its whole lifetime by the borrow checker.
给 C++ 开发者： String 可以近似看成 std::string，&str 可以近似看成 std::string_view。但 &str 比 std::string_view 更硬，因为借用检查器会保证它在整个生命周期里都有效。

String vs &str: owned vs borrowed
String 和 &str：拥有型与借用型

Production patterns: See JSON handling: nlohmann::json → serde for how string handling works with serde in production code.
生产代码里的用法： 可以顺手参考 JSON handling: nlohmann::json → serde，看看真实项目里字符串和 serde 是怎么配合的。

fn main() {
    // &str - string slice (borrowed, immutable, usually a string literal)
    let greeting: &str = "Hello";  // Points to read-only memory

    // String - owned, heap-allocated, growable
    let mut owned = String::from(greeting);  // Copies data to heap
    owned.push_str(", World!");        // Grow the string
    owned.push('!');                   // Append a single character

    // Converting between String and &str
    let slice: &str = &owned;          // String -> &str (free, just a borrow)
    let owned2: String = slice.to_string();  // &str -> String (allocates)
    let owned3: String = String::from(slice); // Same as above

    // String concatenation (note: + consumes the left operand)
    let hello = String::from("Hello");
    let world = String::from(", World!");
    let combined = hello + &world;  // hello is moved (consumed), world is borrowed
    // println!("{hello}");  // Won't compile: hello was moved

    // Use format! to avoid move issues
    let a = String::from("Hello");
    let b = String::from("World");
    let combined = format!("{a}, {b}!");  // Neither a nor b is consumed

    println!("{combined}");
}

Why you cannot index strings with []
为什么字符串不能直接用 [] 索引

fn main() {
    let s = String::from("hello");
    // let c = s[0];  // Won't compile! Rust strings are UTF-8, not byte arrays

    // Safe alternatives:
    let first_char = s.chars().next();           // Option<char>: Some('h')
    let as_bytes = s.as_bytes();                 // &[u8]: raw UTF-8 bytes
    let substring = &s[0..1];                    // &str: "h" (byte range, must be valid UTF-8 boundary)

    println!("First char: {:?}", first_char);
    println!("Bytes: {:?}", &as_bytes[..5]);
}

Rust 不允许像数组那样随手取 s[0]，核心原因是 UTF-8 字符串里“第几个字符”和“第几个字节”根本不是一回事。
这条限制看起来麻烦，其实是在防止把多字节字符切坏。

Exercise: String manipulation
练习：字符串处理

🟢 Starter
🟢 基础练习

• Write a function fn count_words(text: &str) -> usize that counts whitespace-separated words.
  写一个 fn count_words(text: &str) -> usize，统计字符串里按空白字符分隔后的单词数量。
• Write a function fn longest_word(text: &str) -> &str that returns the longest word. Think about why the return type should be &str rather than String.
  再写一个 fn longest_word(text: &str) -> &str，返回最长的单词。顺手想一想：为什么这里返回 &str 更合适，而不是 String。

fn count_words(text: &str) -> usize {
    text.split_whitespace().count()
}

fn longest_word(text: &str) -> &str {
    text.split_whitespace()
        .max_by_key(|word| word.len())
        .unwrap_or("")
}

fn main() {
    let text = "the quick brown fox jumps over the lazy dog";
    println!("Word count: {}", count_words(text));       // 9
    println!("Longest word: {}", longest_word(text));     // "jumps"
}

Rust structs
Rust 的结构体

• The struct keyword declares a user-defined structure type.
  struct 关键字用来声明自定义结构体类型。
  • A struct can have named fields, or it can be a tuple struct with unnamed fields.
    结构体既可以是带字段名的普通结构体，也可以是没有字段名的 tuple struct。
• Unlike C++, Rust has no concept of data inheritance.
  Rust 这里没有 C++ 那种“数据继承”概念，结构体之间不会靠继承来复用字段。

fn main() {
    struct MyStruct {
        num: u32,
        is_secret_of_life: bool,
    }
    let x = MyStruct {
        num: 42,
        is_secret_of_life: true,
    };
    let y = MyStruct {
        num: x.num,
        is_secret_of_life: x.is_secret_of_life,
    };
    let z = MyStruct { num: x.num, ..x }; // The .. means copy remaining
    println!("{} {} {}", x.num, y.is_secret_of_life, z.num);
}

Rust tuple structs
Rust 的元组结构体

• Tuple structs are similar to tuples except they define a distinct type.
  tuple struct 看起来像元组，但它本身会形成一个新的独立类型。
  • Individual fields are still accessed as .0, .1, .2, and so on. A common use is wrapping primitive types to prevent mixing semantically different values that happen to share the same underlying representation.
    字段访问方式还是 .0、.1 这种形式。它最常见的用途之一，就是把同一种原始类型包成不同语义的新类型，防止用错地方。

struct WeightInGrams(u32);
struct WeightInMilligrams(u32);
fn to_weight_in_grams(kilograms: u32) -> WeightInGrams {
    WeightInGrams(kilograms * 1000)
}

fn to_weight_in_milligrams(w : WeightInGrams) -> WeightInMilligrams  {
    WeightInMilligrams(w.0 * 1000)
}

fn main() {
    let x = to_weight_in_grams(42);
    let y = to_weight_in_milligrams(x);
    // let z : WeightInGrams = x;  // Won't compile: x was moved into to_weight_in_milligrams()
    // let a : WeightInGrams = y;   // Won't compile: type mismatch (WeightInMilligrams vs WeightInGrams)
}

Note: The #[derive(...)] attribute automatically generates common trait implementations for structs and enums. You will see this repeatedly throughout the course.
说明： #[derive(...)] 属性可以自动为结构体和枚举生成常见 trait 实现。后面整本书里都会频繁看到它。

#[derive(Debug, Clone, PartialEq)]
struct Point { x: i32, y: i32 }

fn main() {
    let p = Point { x: 1, y: 2 };
    println!("{:?}", p);           // Debug: works because of #[derive(Debug)]
    let p2 = p.clone();           // Clone: works because of #[derive(Clone)]
    assert_eq!(p, p2);            // PartialEq: works because of #[derive(PartialEq)]
}

The trait system will be covered in detail later, but #[derive(Debug)] is useful so often that it is worth adding to almost every struct and enum you create.
trait 系统后面会专门讲，但 #[derive(Debug)] 实在太常用了，基本新建一个结构体或枚举都可以先把它带上。

Rust Vec type
Rust 的 Vec 类型

• Vec<T> is a dynamically sized heap buffer. It is comparable to manually managed malloc / realloc arrays in C or to C++ std::vector.
  Vec<T> 是动态大小的堆缓冲区，大致相当于 C 里自己管扩容的堆数组，或者 C++ 的 std::vector。
  • Unlike fixed-size arrays, Vec can grow and shrink at runtime.
    和固定大小数组不同，Vec 在运行时可以扩容和缩容。
  • Vec owns its contents and automatically manages allocation and deallocation.
    Vec 拥有里面的数据，也会自动处理内存分配和释放。
• Common operations include push()、pop()、insert()、remove()、len() and capacity().
  常见操作有 push()、pop()、insert()、remove()、len() 和 capacity()。

fn main() {
    let mut v = Vec::new();    // Empty vector, type inferred from usage
    v.push(42);                // Add element to end - Vec<i32>
    v.push(43);                
    
    // Safe iteration (preferred)
    for x in &v {              // Borrow elements, don't consume vector
        println!("{x}");
    }
    
    // Initialization shortcuts
    let mut v2 = vec![1, 2, 3, 4, 5];           // Macro for initialization
    let v3 = vec![0; 10];                       // 10 zeros
    
    // Safe access methods (preferred over indexing)
    match v2.get(0) {
        Some(first) => println!("First: {first}"),
        None => println!("Empty vector"),
    }
    
    // Useful methods
    println!("Length: {}, Capacity: {}", v2.len(), v2.capacity());
    if let Some(last) = v2.pop() {             // Remove and return last element
        println!("Popped: {last}");
    }
    
    // Dangerous: direct indexing (can panic!)
    // println!("{}", v2[100]);  // Would panic at runtime
}

Production patterns: See Avoiding unchecked indexing for safe .get() patterns from production Rust code.
生产代码里的安全写法： 可以对照 Avoiding unchecked indexing，那一节专门讲 .get() 这种更稳妥的访问方式。

Rust HashMap type
Rust 的 HashMap 类型

• HashMap implements generic key-value lookups, also known as dictionaries or maps.
  HashMap 用来做通用的键值查找，也就是常说的字典或映射表。

fn main() {
    use std::collections::HashMap;  // Need explicit import, unlike Vec
    let mut map = HashMap::new();       // Allocate an empty HashMap
    map.insert(40, false);  // Type is inferred as int -> bool
    map.insert(41, false);
    map.insert(42, true);
    for (key, value) in map {
        println!("{key} {value}");
    }
    let map = HashMap::from([(40, false), (41, false), (42, true)]);
    if let Some(x) = map.get(&43) {
        println!("43 was mapped to {x:?}");
    } else {
        println!("No mapping was found for 43");
    }
    let x = map.get(&43).or(Some(&false));  // Default value if key isn't found
    println!("{x:?}"); 
}

Exercise: Vec and HashMap
练习：Vec 与 HashMap

🟢 Starter
🟢 基础练习

• Create a HashMap<u32, bool> with several entries, making sure some values are true and others are false. Loop over the hashmap and place the keys into one Vec and the values into another.
  创建一个 HashMap<u32, bool>，里面放几组数据，注意有些值是 true，有些是 false。遍历这个 hashmap，把所有 key 放进一个 Vec，把所有 value 放进另一个 Vec。

use std::collections::HashMap;

fn main() {
    let map = HashMap::from([(1, true), (2, false), (3, true), (4, false)]);
    let mut keys = Vec::new();
    let mut values = Vec::new();
    for (k, v) in &map {
        keys.push(*k);
        values.push(*v);
    }
    println!("Keys:   {keys:?}");
    println!("Values: {values:?}");

    // Alternative: use iterators with unzip()
    let (keys2, values2): (Vec<u32>, Vec<bool>) = map.into_iter().unzip();
    println!("Keys (unzip):   {keys2:?}");
    println!("Values (unzip): {values2:?}");
}

Deep Dive: C++ references vs Rust references
深入对比：C++ 引用与 Rust 引用

For C++ developers: C++ programmers often assume Rust &T behaves like C++ T&. They look similar on the surface, but the semantics are very different. C developers can skip this section because Rust references are covered again in Ownership and Borrowing.
给 C++ 开发者： 很多人第一眼会把 Rust 的 &T 想成 C++ 的 T&。表面上看确实像，但语义差别相当大。纯 C 开发者可以先跳过这里，Rust 引用的核心规则会在 Ownership and Borrowing 再讲一遍。

1. No rvalue references or universal references
1. 没有右值引用，也没有万能引用

In C++, && means different things depending on the context.
在 C++ 里，&& 这玩意儿看上下文能变出不同含义，这事本身就挺折腾人。

// C++: && means different things:
int&& rref = 42;           // Rvalue reference — binds to temporaries
void process(Widget&& w);   // Rvalue reference — caller must std::move

// Universal (forwarding) reference — deduced template context:
template<typename T>
void forward(T&& arg) {     // NOT an rvalue ref! Deduced as T& or T&&
    inner(std::forward<T>(arg));  // Perfect forwarding
}

In Rust, none of this exists. && is simply the logical AND operator.
Rust 里压根没有这套。 && 就只是逻辑与，别脑补更多戏份。

#![allow(unused)]
fn main() {
// Rust: && is just boolean AND
let a = true && false; // false

// Rust has NO rvalue references, no universal references, no perfect forwarding.
// Instead:
//   - Move is the default for non-Copy types (no std::move needed)
//   - Generics + trait bounds replace universal references
//   - No temporary-binding distinction — values are values

fn process(w: Widget) { }      // Takes ownership (like C++ value param + implicit move)
fn process_ref(w: &Widget) { } // Borrows immutably (like C++ const T&)
fn process_mut(w: &mut Widget) { } // Borrows mutably (like C++ T&, but exclusive)
}

2. Moves are bitwise — no move constructors
2. move 是按位移动，不存在 move 构造函数

In C++, moving is user-defined via move constructors and move assignment. In Rust, a move is fundamentally a bitwise copy of the bytes followed by invalidating the source binding.
C++ 的 move 是用户可定义行为；Rust 的 move 则更底层，就是把值的字节搬过去，再把原绑定判定为失效。

#![allow(unused)]
fn main() {
// Rust move = memcpy the bytes, mark source as invalid
let s1 = String::from("hello");
let s2 = s1; // Bytes of s1 are copied to s2's stack slot
              // s1 is now invalid — compiler enforces this
// println!("{s1}"); // ❌ Compile error: value used after move
}

// C++ move = call the move constructor (user-defined!)
std::string s1 = "hello";
std::string s2 = std::move(s1); // Calls string's move ctor
// s1 is now a "valid but unspecified state" zombie
std::cout << s1; // Compiles! Prints... something (empty string, usually)

Consequences:
直接后果：

• Rust has no Rule of Five ceremony.
  Rust 不需要一整套 Rule of Five 样板。
• There is no moved-from zombie state; the compiler just forbids access.
  不存在“被 move 之后还能勉强访问但状态未定义”的僵尸对象。
• Moves do not raise noexcept style questions; bitwise relocation itself does not throw.
  也没有 C++ 里那种 move 到底会不会抛异常的包袱。

3. Auto-deref: the compiler sees through layers of indirection
3. 自动解引用：编译器会顺着一层层包装往里看

Rust can automatically dereference through pointer-like wrappers using the Deref trait. C++ 没有完全同等的语言级体验。
这也是为什么很多嵌套包装类型在 Rust 里看起来没那么吓人。

#![allow(unused)]
fn main() {
use std::sync::{Arc, Mutex};

// Nested wrapping: Arc<Mutex<Vec<String>>>
let data = Arc::new(Mutex::new(vec!["hello".to_string()]));

// In C++, you'd need explicit unlocking and manual dereferencing at each layer.
// In Rust, the compiler auto-derefs through Arc → Mutex → MutexGuard → Vec:
let guard = data.lock().unwrap(); // Arc auto-derefs to Mutex
let first: &str = &guard[0];      // MutexGuard→Vec (Deref), Vec[0] (Index),
                                   // &String→&str (Deref coercion)
println!("First: {first}");

// Method calls also auto-deref:
let boxed_string = Box::new(String::from("hello"));
println!("Length: {}", boxed_string.len());  // Box→String, then String::len()
// No need for (*boxed_string).len() or boxed_string->len()
}

Deref coercion also applies to function arguments.
函数参数匹配时，编译器也会自动做这类解引用转换。

fn greet(name: &str) {
    println!("Hello, {name}");
}

fn main() {
    let owned = String::from("Alice");
    let boxed = Box::new(String::from("Bob"));
    let arced = std::sync::Arc::new(String::from("Carol"));

    greet(&owned);  // &String → &str  (1 deref coercion)
    greet(&boxed);  // &Box<String> → &String → &str  (2 deref coercions)
    greet(&arced);  // &Arc<String> → &String → &str  (2 deref coercions)
    greet("Dave");  // &str already — no coercion needed
}
// In C++ you'd need .c_str() or explicit conversions for each case.

The deref chain: when Rust sees x.method(), it first tries the receiver as-is, then &T and &mut T, and if that still does not fit it follows Deref implementations one layer at a time. Function argument coercion is related, but it is a separate mechanism.
自动解引用链的核心逻辑： 调方法时，编译器会先尝试原类型，再尝试借用形式，实在不行再顺着 Deref 一层层往里找。函数参数的自动转换和它相关，但不是同一个机制。

4. No null references, no implicit optional references
4. 没有空引用，也没有隐式“可空引用”

// C++: references can't be null, but pointers can, and the distinction is blurry
Widget& ref = *ptr;  // If ptr is null → UB
Widget* opt = nullptr;  // "optional" reference via pointer

#![allow(unused)]
fn main() {
// Rust: references are ALWAYS valid — guaranteed by the borrow checker
// No way to create a null or dangling reference in safe code
let r: &i32 = &42; // Always valid

// "Optional reference" is explicit:
let opt: Option<&Widget> = None; // Clear intent, no null pointer
if let Some(w) = opt {
    w.do_something(); // Only reachable when present
}
}

Rust 这里的态度很干脆：引用就是有效的引用。想表达“可能没有”，就老老实实写 Option<&T>。
别搞那种靠约定区分“这是可空指针还是正常对象”的老把戏。

5. References cannot be reseated in C++, but Rust bindings can be rebound
5. C++ 引用不能改绑，而 Rust 变量绑定可以重新绑定

// C++: a reference is an alias — it can't be rebound
int a = 1, b = 2;
int& r = a;
r = b;  // This ASSIGNS b's value to a — it does NOT rebind r!
// a is now 2, r still refers to a

#![allow(unused)]
fn main() {
// Rust: let bindings can shadow, but references follow different rules
let a = 1;
let b = 2;
let r = &a;
// r = &b;   // ❌ Cannot assign to immutable variable
let r = &b;  // ✅ But you can SHADOW r with a new binding
             // The old binding is gone, not reseated

// With mut:
let mut r = &a;
r = &b;      // ✅ r now points to b — this IS rebinding (not assignment through)
}

Mental model: In C++, a reference is a permanent alias for one object. In Rust, a reference is still a normal value governed by binding rules. If the binding is mutable, it can be rebound to refer elsewhere; if the binding is immutable, it cannot.
心智模型： C++ 的引用更像“永久别名”；Rust 的引用则更像“带额外安全保证的普通值”。它遵守变量绑定规则，本身不是那种永远锁死的别名语义。

Rust enum types
Rust 的 enum 类型

What you’ll learn: Rust enums as discriminated unions (tagged unions done right), match for exhaustive pattern matching, and how enums replace C++ class hierarchies and C tagged unions with compiler-enforced safety.
本章将学到什么： Rust enum 如何作为真正靠谱的判别联合使用，match 怎样实现穷尽式模式匹配，以及 enum 如何在编译器保证下替代 C++ 类层级和 C 风格 tagged union。

• Enum types are discriminated unions, i.e., they are a sum type of several possible different types with a tag that identifies the specific variant
  enum 本质上是判别联合，也就是带标签的和类型。它可以表示多种可能形态，并通过标签标识当前到底是哪一种变体。
  • For C developers: enums in Rust can carry data (tagged unions done right — the compiler tracks which variant is active)
    对 C 开发者来说：Rust 的 enum 可以携带数据，这才是“做对了的 tagged union”，因为编译器会跟踪当前激活的是哪个分支。
  • For C++ developers: Rust enums are like std::variant but with exhaustive pattern matching, no std::get exceptions, and no std::visit boilerplate
    对 C++ 开发者来说：Rust enum 有点像 std::variant，但它自带穷尽匹配，没有 std::get 异常，也不需要一堆 std::visit 样板代码。
  • The size of the enum is that of the largest possible type. The individual variants are not related to one another and can have completely different types
    enum 的整体大小由最大变体决定。各个变体之间不需要有继承关系，也可以带完全不同类型的数据。
  • enum types are one of the most powerful features of the language — they replace entire class hierarchies in C++ (more on this in the Case Studies)
    enum 是 Rust 最有力量的特性之一，很多在 C++ 里要靠整棵类层级才能表达的东西，在 Rust 里一个 enum 就能拿下。

fn main() {
    enum Numbers {
        Zero,
        SmallNumber(u8),
        BiggerNumber(u32),
        EvenBiggerNumber(u64),
    }
    let a = Numbers::Zero;
    let b = Numbers::SmallNumber(42);
    let c : Numbers = a; // Ok -- the type of a is Numbers
    let d : Numbers = b; // Ok -- the type of b is Numbers
}

这里最容易让 C/C++ 开发者眼前一亮的一点，就是 enum 的每个变体都能带不同数据，而且类型系统会一路帮忙兜着。
再也不是手工维护一套 tag 字段，再配一个 union，然后祈祷每个分支都别拿错数据了。

Rust match statement
Rust 的 match 语句

• The Rust match is the equivalent of the C “switch” on steroids
  Rust 的 match 可以看作强化到离谱版本的 C switch。
  • match can be used for pattern matching on simple data types, struct, enum
match 不光能匹配简单值，还能匹配 struct、enum 等结构化数据。
  • The match statement must be exhaustive, i.e., they must cover all possible cases for a given type. The _ can be used a wildcard for the “all else” case
    match 必须穷尽所有可能情况。兜底分支通常用 _ 表示“其余所有情况”。
  • match can yield a value, but all arms (=>) must return a value of the same type
    match 本身可以产出值，但每个分支返回的类型必须一致。

fn main() {
    let x = 42;
    // In this case, the _ covers all numbers except the ones explicitly listed
    let is_secret_of_life = match x {
        42 => true, // return type is boolean value
        _ => false, // return type boolean value
        // This won't compile because return type isn't boolean
        // _ => 0  
    };
    println!("{is_secret_of_life}");
}

match 最可贵的地方，不只是语法漂亮，而是它把“有没有漏分支”“分支返回值是否一致”这些本来容易出错的活都交给了编译器。
和 C/C++ 里那种靠 switch 加 default，再小心翼翼提防漏 break 的日子比，体验差得可不是一星半点。

match supports ranges and guards
match 还支持范围和守卫条件

• match supports ranges, boolean filters, and if guard statements
  match 不光能精确匹配，还支持范围匹配、条件守卫和更复杂的模式。

fn main() {
    let x = 42;
    match x {
        // Note that the =41 ensures the inclusive range
        0..=41 => println!("Less than the secret of life"),
        42 => println!("Secret of life"),
        _ => println!("More than the secret of life"),
    }
    let y = 100;
    match y {
        100 if x == 43 => println!("y is 100% not secret of life"),
        100 if x == 42 => println!("y is 100% secret of life"),
        _ => (),    // Do nothing
    }
}

这种范围和 guard 的能力，会让很多原本需要层层 if 嵌套的逻辑一下整洁很多。
尤其在协议解析、状态分发、错误分类这种分支很多的地方，match 的表现通常相当亮眼。

Combining match with enum
把 match 和 enum 组合起来用

• match and enum are often combined together
  match 和 enum 经常是成套出现的。
  • The match statement can “bind” the contained value to a variable. Use _ if the value is a don’t care
    match 可以把变体里带的数据直接绑定到变量上。如果值无所谓，就用 _ 忽略。
  • The matches! macro can be used to match to specific variant
    matches! 宏可以用来快速判断某个值是否匹配指定模式。

fn main() {
    enum Numbers {
        Zero,
        SmallNumber(u8),
        BiggerNumber(u32),
        EvenBiggerNumber(u64),
    }
    let b = Numbers::SmallNumber(42);
    match b {
        Numbers::Zero => println!("Zero"),
        Numbers::SmallNumber(value) => println!("Small number {value}"),
        Numbers::BiggerNumber(_) | Numbers::EvenBiggerNumber(_) => println!("Some BiggerNumber or EvenBiggerNumber"),
    }
    
    // Boolean test for specific variants
    if matches!(b, Numbers::Zero | Numbers::SmallNumber(_)) {
        println!("Matched Zero or small number");
    }
}

这正是 Rust enum 真正发力的地方。不是单独有个“高级枚举”，也不是单独有个“高级 switch”，而是两者组合之后，数据建模和控制流分发直接咬在一起。
很多在 C++ 里需要继承加虚函数加 downcast 才能兜住的结构，在 Rust 里到这一步就已经非常顺了。

Destructuring with match
用 match 做解构匹配

• match can also perform matches using destructuring and slices
  match 还支持对结构体、元组、数组、切片做解构匹配。

fn main() {
    struct Foo {
        x: (u32, bool),
        y: u32
    }
    let f = Foo {x: (42, true), y: 100};
    match f {
        // Capture the value of x into a variable called tuple
        Foo{y: 100, x : tuple} => println!("Matched x: {tuple:?}"),
        _ => ()
    }
    let a = [40, 41, 42];
    match a {
        // Last element of slice must be 42. @ is used to bind the match
        [rest @ .., 42] => println!("{rest:?}"),
        // First element of the slice must be 42. @ is used to bind the match
        [42, rest @ ..] => println!("{rest:?}"),
        _ => (),
    }
}

这类解构能力特别适合写解析器、协议包判断和结构化数据处理。以前在 C/C++ 里要手动拆字段、手动判断条件的东西，在 Rust 里 often 可以直接在模式里说清楚。
代码读起来就像“描述要匹配的数据形状”，不是一堆零散判断拼起来的过程式流水账。

Exercise: Implement add and subtract using match and enum
练习：用 match 和 enum 实现加减法

🟢 Starter
🟢 基础练习

• Write a function that implements arithmetic operations on unsigned 64-bit numbers
  写一个函数，对无符号 64 位整数执行算术操作。
• Step 1: Define an enum for operations:
  步骤 1：先定义操作枚举：

#![allow(unused)]
fn main() {
enum Operation {
    Add(u64, u64),
    Subtract(u64, u64),
}
}

• Step 2: Define a result enum:
  步骤 2：再定义结果枚举：

#![allow(unused)]
fn main() {
enum CalcResult {
    Ok(u64),                    // Successful result
    Invalid(String),            // Error message for invalid operations
}
}

• Step 3: Implement calculate(op: Operation) -> CalcResult
  步骤 3：实现 calculate(op: Operation) -> CalcResult。
  • For Add: return Ok(sum)
    加法返回 Ok(sum)。
  • For Subtract: return Ok(difference) if first >= second, otherwise Invalid(“Underflow”)
    减法在第一个值大于等于第二个值时返回结果，否则返回 Invalid("Underflow")。
• Hint: Use pattern matching in your function:
  提示：在函数里用模式匹配：

#![allow(unused)]
fn main() {
match op {
    Operation::Add(a, b) => { /* your code */ },
    Operation::Subtract(a, b) => { /* your code */ },
}
}

enum Operation {
    Add(u64, u64),
    Subtract(u64, u64),
}

enum CalcResult {
    Ok(u64),
    Invalid(String),
}

fn calculate(op: Operation) -> CalcResult {
    match op {
        Operation::Add(a, b) => CalcResult::Ok(a + b),
        Operation::Subtract(a, b) => {
            if a >= b {
                CalcResult::Ok(a - b)
            } else {
                CalcResult::Invalid("Underflow".to_string())
            }
        }
    }
}

fn main() {
    match calculate(Operation::Add(10, 20)) {
        CalcResult::Ok(result) => println!("10 + 20 = {result}"),
        CalcResult::Invalid(msg) => println!("Error: {msg}"),
    }
    match calculate(Operation::Subtract(5, 10)) {
        CalcResult::Ok(result) => println!("5 - 10 = {result}"),
        CalcResult::Invalid(msg) => println!("Error: {msg}"),
    }
}
// Output:
// 10 + 20 = 30
// Error: Underflow

Rust associated methods
Rust 的关联方法

• impl can define methods associated for types like struct, enum, etc
  impl 可以为 struct、enum 等类型定义关联方法。
  • The methods may optionally take self as a parameter. self is conceptually similar to passing a pointer to the struct as the first parameter in C, or this in C++
    方法可以选择接收 self。从概念上说，它有点像 C 里把结构体指针作为第一个参数传进去，或者像 C++ 里的 this。
  • The reference to self can be immutable (default: &self), mutable (&mut self), or self (transferring ownership)
    self 可以是不可变借用 &self、可变借用 &mut self，也可以直接拿走所有权，也就是 self。
  • The Self keyword can be used a shortcut to imply the type
    Self 关键字可以作为当前类型的简写。

struct Point {x: u32, y: u32}
impl Point {
    fn new(x: u32, y: u32) -> Self {
        Point {x, y}
    }
    fn increment_x(&mut self) {
        self.x += 1;
    }
}
fn main() {
    let mut p = Point::new(10, 20);
    p.increment_x();
}

这部分和前面的 enum 主题放在一起，其实是在提醒一点：Rust 的类型系统不是只给“数据长什么样”建模，也给“这个类型能做什么操作”建模。
impl 让数据和行为自然绑定，但又没有传统面向对象里那种重继承包袱，整体会更轻一些。

Exercise: Point add and transform
练习：Point 的加法与变换

🟡 Intermediate — requires understanding move vs borrow from method signatures
🟡 进阶：需要理解方法签名里的 move 与 borrow 区别。

• Implement the following associated methods for Point
  为 Point 实现下面这些关联方法：
  • add() will take another Point and will increment the x and y values in place (hint: use &mut self)
    add() 接收另一个 Point，并原地累加 x、y 值，提示：用 &mut self。
  • transform() will consume an existing Point (hint: use self) and return a new Point by squaring the x and y
    transform() 会消费当前 Point，返回一个新的 Point，其中 x、y 都变成平方值，提示：用 self。

struct Point { x: u32, y: u32 }

impl Point {
    fn new(x: u32, y: u32) -> Self {
        Point { x, y }
    }
    fn add(&mut self, other: &Point) {
        self.x += other.x;
        self.y += other.y;
    }
    fn transform(self) -> Point {
        Point { x: self.x * self.x, y: self.y * self.y }
    }
}

fn main() {
    let mut p1 = Point::new(2, 3);
    let p2 = Point::new(10, 20);
    p1.add(&p2);
    println!("After add: x={}, y={}", p1.x, p1.y);           // x=12, y=23
    let p3 = p1.transform();
    println!("After transform: x={}, y={}", p3.x, p3.y);     // x=144, y=529
    // p1 is no longer accessible — transform() consumed it
}

Rust memory management
Rust 的内存管理

What you’ll learn: Rust’s ownership system, the single most important concept in the language. This chapter covers move semantics, borrowing rules, Clone、Copy and Drop. For many C/C++ developers, once ownership clicks, the rest of Rust suddenly stops looking mystical.
本章将学到什么： Rust 的所有权系统，也就是整门语言里最核心的概念。本章会讲 move 语义、借用规则、Clone、Copy 和 Drop。对很多 C/C++ 开发者来说，一旦所有权想明白了，Rust 后面的大半内容都会顺眼很多。

• Memory management in C and C++ is a major source of bugs
  C 和 C++ 里的内存管理，本来就是大量 bug 的来源。
  • In C, malloc() and free() offer no built-in protection against dangling pointers, use-after-free, or double-free.
    在 C 里，malloc() 和 free() 本身不会替着防悬空指针、释放后继续使用、重复释放这些事故。
  • In C++, RAII and smart pointers help a lot, but moved-from objects still exist and misuse can slide into undefined behavior.
    在 C++ 里，RAII 和智能指针当然已经好很多了，但 moved-from 对象依然存在，玩脱了照样可能滚进未定义行为。
• Rust turns RAII into something much harder to misuse
  Rust 把 RAII 这套机制做得更难被误用。
  • Moves are destructive: once ownership is moved, the old binding becomes invalid.
    move 是破坏性的：一旦所有权转走，旧变量立刻失效。
  • No Rule of Five ceremony is needed.
    不需要再手动背一套 Rule of Five 样板。
  • Rust still gives low-level control over stack and heap allocation, but safety is enforced at compile time.
    Rust 依然保留了对栈和堆分配的控制力，只不过安全检查被前移到了编译期。
  • Ownership, borrowing, mutability, and lifetimes work together to make this possible.
    它靠的是所有权、借用、可变性和生命周期这几套机制一起配合。

For C++ developers — Smart Pointer Mapping:
给 C++ 开发者的智能指针对照表：

C++	Rust	Safety Improvement
std::unique_ptr<T>	Box<T>	No use-after-move possible
std::shared_ptr<T>	Rc<T> (single-thread)	No reference cycles by default
std::shared_ptr<T> (thread-safe)	Arc<T>	Explicit thread-safety
std::weak_ptr<T>	Weak<T>	Must check validity
Raw pointer	*const T / *mut T	Only in unsafe blocks

对 C 开发者来说，Box<T> 可以看成替代 malloc/free 配对，Rc<T> 可以看成替代手写引用计数，而裸指针虽然还在，但基本被关进了 unsafe 区域。

Rust ownership, borrowing and lifetimes
Rust 的所有权、借用与生命周期

• Rust permits either one mutable reference or many read-only references to the same value
  Rust 允许的模式非常明确：同一时间要么一个可变引用，要么多个只读引用。
  • The original variable owns the value.
    最初声明变量时，它就成了该值的所有者。
  • Later references borrow from that owner.
    后续产生的引用，则是在向这个所有者借用。
  • A borrow can never outlive the owning scope.
    借用的存活时间绝对不能超过拥有者的作用域。

fn main() {
    let a = 42; // Owner
    let b = &a; // First borrow
    {
        let aa = 42;
        let c = &a; // Second borrow; a is still in scope
        // Ok: c goes out of scope here
        // aa goes out of scope here
    }
    // let d = &aa; // Will not compile unless aa is moved to outside scope
    // b implicitly goes out of scope before a
    // a goes out of scope last
}

• Functions can receive values in several ways
  函数接收参数时，也有几种不同方式。
  • By value copy for small Copy types.
    按值复制，常见于实现了 Copy 的小类型。
  • By reference using & or &mut.
    按引用借用，用 & 或 &mut 表示。
  • By move, transferring ownership into the function.
    按 move 转移所有权，把值整个交给函数。

fn foo(x: &u32) {
    println!("{x}");
}
fn bar(x: u32) {
    println!("{x}");
}
fn main() {
    let a = 42;
    foo(&a);    // By reference
    bar(a);     // By value (copy)
}

• Rust forbids returning dangling references
  Rust 明确禁止返回悬空引用。
  • Returned references must still refer to something that is alive when the function ends.
    函数返回的引用，在函数结束之后也必须还能指向活着的数据。
  • When a value leaves scope, Rust automatically drops it.
    值离开作用域时，Rust 会自动执行清理。

fn no_dangling() -> &u32 {
    // lifetime of a begins here
    let a = 42;
    // Won't compile. lifetime of a ends here
    &a
}

fn ok_reference(a: &u32) -> &u32 {
    // Ok because the lifetime of a always exceeds ok_reference()
    a
}
fn main() {
    let a = 42;     // lifetime of a begins here
    let b = ok_reference(&a);
    // lifetime of b ends here
    // lifetime of a ends here
}

Rust move semantics
Rust 的 move 语义

• By default, assignment transfers ownership for non-Copy values
  默认情况下，对非 Copy 类型做赋值时，会转移所有权。

fn main() {
    let s = String::from("Rust");    // Allocate a string from the heap
    let s1 = s; // Transfer ownership to s1. s is invalid at this point
    println!("{s1}");
    // This will not compile
    //println!("{s}");
    // s1 goes out of scope here and the memory is deallocated
    // s goes out of scope here, but nothing happens because it doesn't own anything
}

graph LR
    subgraph "Before: let s1 = s<br/>赋值之前"
        S["s (stack)<br/>ptr"] -->|"owns"| H1["Heap: R u s t"]
    end

    subgraph "After: let s1 = s<br/>赋值之后"
        S_MOVED["s (stack)<br/>⚠️ MOVED"] -.->|"invalid"| H2["Heap: R u s t"]
        S1["s1 (stack)<br/>ptr"] -->|"now owns"| H2
    end

    style S_MOVED fill:#ff6b6b,color:#000,stroke:#333
    style S1 fill:#51cf66,color:#000,stroke:#333
    style H2 fill:#91e5a3,color:#000,stroke:#333

After let s1 = s, ownership transfers to s1. The heap data stays where it is; only the owning pointer moves, and s becomes invalid.
执行 let s1 = s 之后，所有权转移给 s1。堆上的数据并没有搬家，移动的只是拥有它的那根指针，而 s 从此失效。

Rust move semantics and borrowing
move 语义与借用

fn foo(s : String) {
    println!("{s}");
    // The heap memory pointed to by s will be deallocated here
}
fn bar(s : &String) {
    println!("{s}");
    // Nothing happens -- s is borrowed
}
fn main() {
    let s = String::from("Rust string move example");    // Allocate a string from the heap
    foo(s); // Transfers ownership; s is invalid now
    // println!("{s}");  // will not compile
    let t = String::from("Rust string borrow example");
    bar(&t);    // t continues to hold ownership
    println!("{t}"); 
}

Rust move semantics and ownership
move 与所有权转移

• It is perfectly legal to transfer ownership by moving
  通过 move 转移所有权，本身就是 Rust 的正常操作。
  • Any outstanding borrows must be respected; moved values cannot still be used through old bindings.
    但借用规则仍然有效，已经转走的值不能再通过旧变量继续碰。
  • If moving feels too destructive, borrowing is usually the first alternative to consider.
    如果 move 太“狠”，第一反应通常应该是改成借用。

struct Point {
    x: u32,
    y: u32,
}
fn consume_point(p: Point) {
    println!("{} {}", p.x, p.y);
}
fn borrow_point(p: &Point) {
    println!("{} {}", p.x, p.y);
}
fn main() {
    let p = Point {x: 10, y: 20};
    // Try flipping the two lines
    borrow_point(&p);
    consume_point(p);
}

Rust Clone
Rust 的 Clone

• clone() creates a true duplicate of the owned data
  clone() 会把拥有的数据真正复制一份出来。
  • The upside is both values stay valid.
    好处是原值和新值都继续有效。
  • The downside is that extra allocation or copy work may happen.
    代价则是会产生额外分配或复制成本。

fn main() {
    let s = String::from("Rust");    // Allocate a string from the heap
    let s1 = s.clone(); // Copy the string; creates a new allocation on the heap
    println!("{s1}");  
    println!("{s}");
    // s1 goes out of scope here and the memory is deallocated
    // s goes out of scope here, and the memory is deallocated
}

graph LR
    subgraph "After: let s1 = s.clone()<br/>clone 之后"
        S["s (stack)<br/>ptr"] -->|"owns"| H1["Heap: R u s t"]
        S1["s1 (stack)<br/>ptr"] -->|"owns (copy)"| H2["Heap: R u s t"]
    end

    style S fill:#51cf66,color:#000,stroke:#333
    style S1 fill:#51cf66,color:#000,stroke:#333
    style H1 fill:#91e5a3,color:#000,stroke:#333
    style H2 fill:#91e5a3,color:#000,stroke:#333

clone() creates a separate heap allocation. Both values are valid because each owns its own copy.
clone() 会得到一块独立的堆内存。两个变量都合法，因为它们各自拥有自己那份副本。

Rust Copy trait
Rust 的 Copy trait

• Primitive types use copy semantics through the Copy trait
  Rust 里的很多原始类型，都是通过 Copy trait 按值拷贝的。
  • Examples include u8、u32、i32 这些简单值。
    像 u8、u32、i32 这些简单数值类型，基本都属于这一类。
  • User-defined types can opt in with #[derive(Copy, Clone)] if every field is also Copy.
    用户自定义类型如果所有字段都满足条件，也可以通过 #[derive(Copy, Clone)] 主动加入 Copy 语义。

// Try commenting this out to see the change in let p1 = p; belw
#[derive(Copy, Clone, Debug)]   // We'll discuss this more later
struct Point{x: u32, y:u32}
fn main() {
    let p = Point {x: 42, y: 40};
    let p1 = p;     // This will perform a copy now instead of move
    println!("p: {p:?}");
    println!("p1: {p:?}");
    let p2 = p1.clone();    // Semantically the same as copy
}

Rust Drop trait
Rust 的 Drop trait

• Rust automatically calls drop() at the end of scope
  值离开作用域时，Rust 会自动调用对应的 drop() 逻辑。
  • Drop is the trait that defines custom destruction behavior.
    Drop trait 用来定义自定义析构行为。
  • String uses it to release heap memory, and other resource-owning types do similar cleanup.
    比如 String 就靠它释放堆内存，其他资源管理类型也一样会在这里做清理。
  • For C developers, this replaces a lot of manual free() calls with scope-based cleanup.
    对 C 开发者来说，这基本就是把大量手动 free() 换成了作用域结束自动清理。
• Key safety: You cannot call .drop() directly. Instead use drop(obj), which consumes the value and prevents further use.
  关键安全点： 不能直接手调 .drop() 方法。正确方式是 drop(obj)，它会把值吃掉，析构完之后也杜绝再次使用。

For C++ developers: Drop maps very closely to a destructor.
给 C++ 开发者： Drop 基本就对应析构函数。

	C++ destructor	Rust Drop
Syntax	~MyClass() { ... }	impl Drop for MyType { fn drop(&mut self) { ... } }
When called	End of scope	End of scope
Called on move	Moved-from object still exists	Moved-from value is gone
Manual call	Dangerous explicit destructor call	drop(obj) consumes safely
Order	Reverse declaration order	Reverse declaration order
Rule of Five	Must manage special member functions	Only Drop; Clone is opt-in
Virtual dtor needed?	Sometimes yes	No inheritance, no slicing issue

struct Point {x: u32, y:u32}

// Equivalent to: ~Point() { printf("Goodbye point x:%u, y:%u\n", x, y); }
impl Drop for Point {
    fn drop(&mut self) {
        println!("Goodbye point x:{}, y:{}", self.x, self.y);
    }
}
fn main() {
    let p = Point{x: 42, y: 42};
    {
        let p1 = Point{x:43, y: 43};
        println!("Exiting inner block");
        // p1.drop() called here — like C++ end-of-scope destructor
    }
    println!("Exiting main");
    // p.drop() called here
}

Exercise: Move, Copy and Drop
练习：move、copy 与 drop

🟡 Intermediate — experiment freely; the compiler will teach a lot here
🟡 进阶练习：这里很适合自己多试，编译器会把很多关键区别直接指出来。

• Create your own Point experiments with and without Copy in the derive list, and make sure the difference between move and copy is fully clear.
  给 Point 自己做几组实验，分别试试带 Copy 和不带 Copy 的情况，务必把 move 和 copy 的区别看明白。
• Implement a custom Drop for Point that sets x and y to 0 inside drop() just to observe the pattern.
  再给 Point 手写一个 Drop，在 drop() 里把 x 和 y 设成 0，单纯用来感受这类资源释放模式。

struct Point{x: u32, y: u32}
fn main() {
    // Create Point, assign it to a different variable, create a new scope,
    // pass point to a function, etc.
}

#[derive(Debug)]
struct Point { x: u32, y: u32 }

impl Drop for Point {
    fn drop(&mut self) {
        println!("Dropping Point({}, {})", self.x, self.y);
        self.x = 0;
        self.y = 0;
        // Note: setting to 0 in drop demonstrates the pattern,
        // but you can't observe these values after drop completes
    }
}

fn consume(p: Point) {
    println!("Consuming: {:?}", p);
    // p is dropped here
}

fn main() {
    let p1 = Point { x: 10, y: 20 };
    let p2 = p1;  // Move — p1 is no longer valid
    // println!("{:?}", p1);  // Won't compile: p1 was moved

    {
        let p3 = Point { x: 30, y: 40 };
        println!("p3 in inner scope: {:?}", p3);
        // p3 is dropped here (end of scope)
    }

    consume(p2);  // p2 is moved into consume and dropped there
    // println!("{:?}", p2);  // Won't compile: p2 was moved

    // Now try: add #[derive(Copy, Clone)] to Point (and remove the Drop impl)
    // and observe how p1 remains valid after let p2 = p1;
}
// Output:
// p3 in inner scope: Point { x: 30, y: 40 }
// Dropping Point(30, 40)
// Consuming: Point { x: 10, y: 20 }
// Dropping Point(10, 20)

Rust lifetime and borrowing
Rust 的生命周期与借用

What you’ll learn: How Rust’s lifetime system ensures references never dangle, from implicit lifetimes through explicit annotations to the three elision rules that keep most code annotation-free. This chapter is worth understanding before moving on to smart pointers.
本章将学到什么： Rust 的生命周期系统如何确保引用永远不会悬空；从隐式生命周期、显式标注，到让大部分代码都能免标注的三条省略规则。想继续往智能指针那部分走，这一章最好先吃透。

• Rust enforces one mutable reference or many immutable references at a time
  Rust 强制执行一条核心规则：同一时间要么只有一个可变引用，要么可以有多个不可变引用。
  • Every reference must live no longer than the original owner it borrows from. In most cases this lifetime information is inferred automatically by the compiler.
    任何引用的存活时间都不能超过它所借用的原始所有者。大多数情况下，编译器会自动把这些生命周期推导出来。

fn borrow_mut(x: &mut u32) {
    *x = 43;
}
fn main() {
    let mut x = 42;
    let y = &mut x;
    borrow_mut(y);
    let _z = &x; // Permitted because the compiler knows y isn't subsequently used
    //println!("{y}"); // Will not compile if this is uncommented
    borrow_mut(&mut x); // Permitted because _z isn't used 
let z = &x; // Ok -- mutable borrow of x ended after borrow_mut() returned
    println!("{z}");
}

Rust lifetime annotations
Rust 的生命周期标注

• Explicit lifetime annotations become necessary when multiple borrowed values are involved and the compiler cannot infer how returned references relate to the inputs.
  一旦函数同时处理多个借用值，而编译器又看不清返回引用到底和哪个输入相关，就需要显式生命周期标注了。
  • Lifetimes are written with ' and an identifier such as 'a、'b、'static。
    生命周期用前导 ' 加标识符表示，比如 'a、'b、'static。
  • The goal is not “manual memory management” again, but telling the compiler how references are related.
    重点不是重新手工管内存，而是把“这些引用之间是什么关系”讲清楚给编译器听。
• Common scenario: a function returns a reference, but which input reference does it come from?
  最常见的场景： 函数要返回一个引用，可这个引用到底来自哪个输入参数？

#[derive(Debug)]
struct Point {x: u32, y: u32}

// Without lifetime annotation, this won't compile:
// fn left_or_right(pick_left: bool, left: &Point, right: &Point) -> &Point

// With lifetime annotation - all references share the same lifetime 'a
fn left_or_right<'a>(pick_left: bool, left: &'a Point, right: &'a Point) -> &'a Point {
    if pick_left { left } else { right }
}

// More complex: different lifetimes for inputs
fn get_x_coordinate<'a, 'b>(p1: &'a Point, _p2: &'b Point) -> &'a u32 {
    &p1.x  // Return value lifetime tied to p1, not p2
}

fn main() {
    let p1 = Point {x: 20, y: 30};
    let result;
    {
        let p2 = Point {x: 42, y: 50};
        result = left_or_right(true, &p1, &p2);
        // This works because we use result before p2 goes out of scope
        println!("Selected: {result:?}");
    }
    // This would NOT work - result references p2 which is now gone:
    // println!("After scope: {result:?}");
}

Rust lifetime annotations in data structures
数据结构里的生命周期标注

• Lifetime annotations are also needed when a data structure stores references instead of owning its contents.
  如果一个数据结构里保存的是引用，而不是自己拥有数据，那么这个结构体本身也要把生命周期写出来。

use std::collections::HashMap;
#[derive(Debug)]
struct Point {x: u32, y: u32}
struct Lookup<'a> {
    map: HashMap<u32, &'a Point>,
}
fn main() {
    let p = Point{x: 42, y: 42};
    let p1 = Point{x: 50, y: 60};
    let mut m = Lookup {map : HashMap::new()};
    m.map.insert(0, &p);
    m.map.insert(1, &p1);
    {
        let p3 = Point{x: 60, y:70};
        //m.map.insert(3, &p3); // Will not compile
        // p3 is dropped here, but m will outlive
    }
    for (k, v) in m.map {
        println!("{v:?}");
    }
    // m is dropped here
    // p1 and p are dropped here in that order
} 

这正是生命周期最实在的地方。结构体里如果只是借用外部对象，Rust 会逼着把“它能借多久”写清楚，省得把一个马上要消失的地址偷偷塞进去。
This is where lifetimes become especially concrete. If a struct only borrows outside data, Rust requires the borrowing relationship to be spelled out so temporary values cannot be smuggled into long-lived containers.

Exercise: First word with lifetimes
练习：带生命周期的首个单词

🟢 Starter — practice lifetime elision in action
🟢 基础练习：感受生命周期省略规则是怎么在真实代码里生效的。

Write a function fn first_word(s: &str) -> &str that returns the first whitespace-delimited word from a string. Think about why this compiles without explicit lifetime annotations.
写一个函数 fn first_word(s: &str) -> &str，返回字符串里按空白分隔的第一个单词。顺手想想：为什么这个函数明明返回引用，却完全不用显式生命周期标注？

fn first_word(s: &str) -> &str {
    // The compiler applies elision rules:
    // Rule 1: input &str gets lifetime 'a → fn first_word(s: &'a str) -> &str
    // Rule 2: single input lifetime → output gets same → fn first_word(s: &'a str) -> &'a str
    match s.find(' ') {
        Some(pos) => &s[..pos],
        None => s,
    }
}

fn main() {
    let text = "hello world foo";
    let word = first_word(text);
    println!("First word: {word}");  // "hello"
    
    let single = "onlyone";
    println!("First word: {}", first_word(single));  // "onlyone"
}

Exercise: Slice storage with lifetimes
练习：带生命周期的切片存储结构

🟡 Intermediate — your first encounter with explicit lifetime annotations
🟡 进阶练习：第一次正面写显式生命周期标注。

• Create a structure that stores a reference to a &str slice
  创建一个结构体，用来保存某个 &str 切片的引用。
  • Create one long &str and store multiple slices derived from it inside the structure
    先准备一个较长的 &str，再从中切出多个子切片存进结构体。
  • Write a function that accepts the structure and returns the stored slice
    再写一个函数，接收这个结构体并把里面的切片返回出来。

// TODO: Create a structure to store a reference to a slice
struct SliceStore {

}
fn main() {
    let s = "This is long string";
    let s1 = &s[0..];
    let s2 = &s[1..2];
    // let slice = struct SliceStore {...};
    // let slice2 = struct SliceStore {...};
}

struct SliceStore<'a> {
    slice: &'a str,
}

impl<'a> SliceStore<'a> {
    fn new(slice: &'a str) -> Self {
        SliceStore { slice }
    }

    fn get_slice(&self) -> &'a str {
        self.slice
    }
}

fn main() {
    let s = "This is a long string";
    let store1 = SliceStore::new(&s[0..4]);   // "This"
    let store2 = SliceStore::new(&s[5..7]);   // "is"
    println!("store1: {}", store1.get_slice());
    println!("store2: {}", store2.get_slice());
}
// Output:
// store1: This
// store2: is

Lifetime Elision Rules Deep Dive
生命周期省略规则深入讲解

C programmers often ask: “If lifetimes are so important, why don’t most Rust functions have 'a annotations?” The answer is lifetime elision: the compiler applies three deterministic rules to infer lifetimes automatically.
很多 C 程序员第一次看到这里都会问一句：“如果生命周期这么重要，为什么大多数 Rust 函数签名里根本看不到 'a？”答案就是生命周期省略规则。编译器会按三条固定规则自动把很多生命周期推出来。

The Three Elision Rules
三条省略规则

The compiler applies these rules in order. If all output lifetimes become determined after the rules run, no explicit annotation is required.
编译器会按顺序套用这三条规则。只要规则跑完以后，所有输出生命周期都能唯一确定，就不需要手写标注。

flowchart TD
    A["Function signature with references<br/>带引用的函数签名"] --> R1
    R1["Rule 1: Each input reference<br/>gets its own lifetime<br/><br/>fn f(&str, &str)<br/>→ fn f<'a,'b>(&'a str, &'b str)"]
    R1 --> R2
    R2["Rule 2: If exactly ONE input<br/>lifetime, assign it to ALL outputs<br/><br/>fn f(&str) → &str<br/>→ fn f<'a>(&'a str) → &'a str"]
    R2 --> R3
    R3["Rule 3: If one input is &self<br/>or &mut self, assign its lifetime<br/>to ALL outputs<br/><br/>fn f(&self, &str) → &str<br/>→ fn f<'a>(&'a self, &str) → &'a str"]
    R3 --> CHECK{{"All output lifetimes<br/>determined?<br/>输出生命周期都确定了吗？"}}
    CHECK -->|"Yes"| OK["✅ No annotations needed<br/>不需要显式标注"]
    CHECK -->|"No"| ERR["❌ Compile error<br/>必须手动标注"]
    
    style OK fill:#91e5a3,color:#000
    style ERR fill:#ff6b6b,color:#000

Rule-by-Rule Examples
逐条看例子

Rule 1 — each input reference gets its own lifetime parameter
规则 1：每个输入引用都会先拿到自己的生命周期参数。

#![allow(unused)]
fn main() {
// What you write:
fn first_word(s: &str) -> &str { ... }

// What the compiler sees after Rule 1:
fn first_word<'a>(s: &'a str) -> &str { ... }
// Only one input lifetime → Rule 2 applies
}

Rule 2 — a single input lifetime propagates to all outputs
规则 2：如果只有一个输入生命周期，那所有输出都继承它。

#![allow(unused)]
fn main() {
// After Rule 2:
fn first_word<'a>(s: &'a str) -> &'a str { ... }
// ✅ All output lifetimes determined — no annotation needed!
}

Rule 3 — the lifetime of &self propagates to outputs
规则 3：如果参数里有 &self 或 &mut self，输出默认和它绑定。

#![allow(unused)]
fn main() {
// What you write:
impl SliceStore<'_> {
    fn get_slice(&self) -> &str { self.slice }
}

// What the compiler sees after Rules 1 + 3:
impl SliceStore<'_> {
    fn get_slice<'a>(&'a self) -> &'a str { self.slice }
}
// ✅ No annotation needed — &self lifetime used for output
}

When elision fails — manual annotation is required
省略失败时：就得自己手动标注。

#![allow(unused)]
fn main() {
// Two input references, no &self → Rules 2 and 3 don't apply
// fn longest(a: &str, b: &str) -> &str  ← WON'T COMPILE

// Fix: tell the compiler which input the output borrows from
fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() >= b.len() { a } else { b }
}
}

C Programmer Mental Model
给 C 程序员的心智模型

In C, every pointer is independent and the compiler trusts the programmer completely. In Rust, lifetimes make these relationships explicit and compiler-checked.
在 C 里，每个指针基本都是独立的，编译器默认信任程序员自己兜底。Rust 则把这些关系显式写出来，再交给编译器验证。

The 'static Lifetime
'static 生命周期

'static means a reference remains valid for the entire duration of the program. String literals and true global data are the most common examples.
'static 表示这个引用在整个程序运行期间都有效。最典型的例子就是字符串字面量和真正的全局静态数据。

#![allow(unused)]
fn main() {
// String literals are always 'static — they live in the binary's read-only section
let s: &'static str = "hello";  // Same as: static const char* s = "hello"; in C

// Constants are also 'static
static GREETING: &str = "hello";

// Common in trait bounds for thread spawning:
fn spawn<F: FnOnce() + Send + 'static>(f: F) { /* ... */ }
// 'static here means: "the closure must not borrow any local variables"
// (either move them in, or use only 'static data)
}

Exercise: Predict the Elision
练习：猜猜生命周期能不能省略

🟡 Intermediate
🟡 进阶练习

For each function signature below, predict whether the compiler can elide lifetimes. If not, add the necessary annotations.
看下面这些函数签名，先判断编译器能不能自动省略生命周期；如果不能，就把需要的标注补出来。

#![allow(unused)]
fn main() {
// 1. Can the compiler elide?
fn trim_prefix(s: &str) -> &str { &s[1..] }

// 2. Can the compiler elide?
fn pick(flag: bool, a: &str, b: &str) -> &str {
    if flag { a } else { b }
}

// 3. Can the compiler elide?
struct Parser { data: String }
impl Parser {
    fn next_token(&self) -> &str { &self.data[..5] }
}

// 4. Can the compiler elide?
fn split_at(s: &str, pos: usize) -> (&str, &str) {
    (&s[..pos], &s[pos..])
}
}

// 1. YES — Rule 1 gives 'a to s, Rule 2 propagates to output
fn trim_prefix(s: &str) -> &str { &s[1..] }

// 2. NO — Two input references, no &self. Must annotate:
fn pick<'a>(flag: bool, a: &'a str, b: &'a str) -> &'a str {
    if flag { a } else { b }
}

// 3. YES — Rule 1 gives 'a to &self, Rule 3 propagates to output
impl Parser {
    fn next_token(&self) -> &str { &self.data[..5] }
}

// 4. YES — Rule 1 gives 'a to s (only one input reference),
//    Rule 2 propagates to BOTH outputs. Both slices borrow from s.
fn split_at(s: &str, pos: usize) -> (&str, &str) {
    (&s[..pos], &s[pos..])
}

Rust Box<T>
Rust 的 Box<T>

What you’ll learn: Rust’s smart pointer types — Box<T> for heap allocation, Rc<T> for shared ownership, and Cell<T>/RefCell<T> for interior mutability. These build on the ownership and lifetime concepts from the previous sections. You’ll also see a brief introduction to Weak<T> for breaking reference cycles.
本章将学到什么： Rust 里的几种核心智能指针类型：负责堆分配的 Box<T>，负责共享所有权的 Rc<T>，以及负责内部可变性的 Cell<T> 和 RefCell<T>。这些内容都建立在前面讲过的所有权和生命周期之上。本章也会顺手介绍一下 Weak<T>，看看它是怎么打破引用环的。

Why Box<T>? In C, you use malloc/free for heap allocation. In C++, std::unique_ptr<T> wraps new/delete. Rust’s Box<T> is the equivalent — a heap-allocated, single-owner pointer that is automatically freed when it goes out of scope. Unlike malloc, there’s no matching free to forget. Unlike unique_ptr, there’s no use-after-move — the compiler prevents it entirely.
为什么需要 Box<T>？ 在 C 里，堆分配通常靠 malloc/free。在 C++ 里，对应的是把 new/delete 封进 std::unique_ptr<T>。Rust 里的 Box<T> 就是这一类东西：它指向堆上数据，只允许单一所有者，而且一离开作用域就会自动释放。和 malloc 相比，不存在忘记 free 的问题；和 unique_ptr 相比，编译器会把 use-after-move 这类事故直接拦下来。

When to use Box vs stack allocation:
什么时候该用 Box，什么时候继续放在栈上：

• The contained type is large and you don’t want to copy it on the stack
  值本身比较大，放在栈上复制来复制去不划算。

• You need a recursive type, such as a linked-list node that contains itself
  需要定义递归类型，比如链表节点里再套同类节点。

• You need trait objects such as Box<dyn Trait>
  需要 trait object，比如 Box<dyn Trait>。

• Box<T> can be used to create a pointer to a heap-allocated value. The pointer itself is always a fixed size regardless of T.
  Box<T> 用来创建一个指向堆上数据的指针。无论 T 有多大，这个指针本身的大小都是固定的。

fn main() {
    // Creates a pointer to an integer (with value 42) created on the heap
    let f = Box::new(42);
    println!("{} {}", *f, f);
    // Cloning a box creates a new heap allocation
    let mut g = f.clone();
    *g = 43;
    println!("{f} {g}");
    // g and f go out of scope here and are automatically deallocated
}

graph LR
    subgraph "Stack<br/>栈"
        F["f: Box&lt;i32&gt;"]
        G["g: Box&lt;i32&gt;"]
    end

    subgraph "Heap<br/>堆"
        HF["42"]
        HG["43"]
    end

    F -->|"owns<br/>拥有"| HF
    G -->|"owns (cloned)<br/>clone 后拥有"| HG

    style F fill:#51cf66,color:#000,stroke:#333
    style G fill:#51cf66,color:#000,stroke:#333
    style HF fill:#91e5a3,color:#000,stroke:#333
    style HG fill:#91e5a3,color:#000,stroke:#333

Ownership and Borrowing Visualization
所有权与借用的可视化理解

C/C++ vs Rust: Pointer and Ownership Management
C/C++ 与 Rust：指针和所有权管理对比

// C - Manual memory management, potential issues
void c_pointer_problems() {
    int* ptr1 = malloc(sizeof(int));
    *ptr1 = 42;
    
    int* ptr2 = ptr1;  // Both point to same memory
    int* ptr3 = ptr1;  // Three pointers to same memory
    
    free(ptr1);        // Frees the memory
    
    *ptr2 = 43;        // Use after free - undefined behavior!
    *ptr3 = 44;        // Use after free - undefined behavior!
}

For C++ developers: Smart pointers help, but they still do not eliminate every class of mistake.
给 C++ 开发者： 智能指针当然有帮助，但它们还没有强到能把所有错误一把掐死。

// C++ - Smart pointers help, but don't prevent all issues
void cpp_pointer_issues() {
    auto ptr1 = std::make_unique<int>(42);
    
    // auto ptr2 = ptr1;  // Compile error: unique_ptr not copyable
    auto ptr2 = std::move(ptr1);  // OK: ownership transferred
    
    // But C++ still allows use-after-move:
    // std::cout << *ptr1;  // Compiles! But undefined behavior!
    
    // shared_ptr aliasing:
    auto shared1 = std::make_shared<int>(42);
    auto shared2 = shared1;  // Both own the data
    // Who "really" owns it? Neither. Ref count overhead everywhere.
}

#![allow(unused)]
fn main() {
// Rust - Ownership system prevents these issues
fn rust_ownership_safety() {
    let data = Box::new(42);  // data owns the heap allocation
    
    let moved_data = data;    // Ownership transferred to moved_data
    // data is no longer accessible - compile error if used
    
    let borrowed = &moved_data;  // Immutable borrow
    println!("{}", borrowed);    // Safe to use
    
    // moved_data automatically freed when it goes out of scope
}
}

graph TD
    subgraph "C/C++ Memory Management Issues<br/>C/C++ 内存管理问题"
        CP1["int* ptr1"] --> CM["Heap Memory<br/>堆内存<br/>value: 42"]
        CP2["int* ptr2"] --> CM
        CP3["int* ptr3"] --> CM
        CF["free(ptr1)"] --> CM_F["[ERROR] Freed Memory<br/>已释放内存"]
        CP2 -.->|"Use after free<br/>释放后继续使用"| CM_F
        CP3 -.->|"Use after free<br/>释放后继续使用"| CM_F
    end
    
    subgraph "Rust Ownership System<br/>Rust 所有权系统"
        RO1["data: Box&lt;i32&gt;"] --> RM["Heap Memory<br/>堆内存<br/>value: 42"]
        RO1 -.->|"Move ownership<br/>转移所有权"| RO2["moved_data: Box&lt;i32&gt;"]
        RO2 --> RM
        RO1_X["data: [WARNING] MOVED<br/>已 move，无法访问"]
        RB["&moved_data<br/>Immutable borrow<br/>不可变借用"] -.->|"Safe reference<br/>安全引用"| RM
        RD["Drop automatically<br/>离开作用域自动释放"] --> RM
    end
    
    style CM_F fill:#ff6b6b,color:#000
    style CP2 fill:#ff6b6b,color:#000
    style CP3 fill:#ff6b6b,color:#000
    style RO1_X fill:#ffa07a,color:#000
    style RO2 fill:#51cf66,color:#000
    style RB fill:#91e5a3,color:#000
    style RD fill:#91e5a3,color:#000

Borrowing Rules Visualization
借用规则可视化

#![allow(unused)]
fn main() {
fn borrowing_rules_example() {
    let mut data = vec![1, 2, 3, 4, 5];
    
    // Multiple immutable borrows - OK
    let ref1 = &data;
    let ref2 = &data;
    println!("{:?} {:?}", ref1, ref2);  // Both can be used
    
    // Mutable borrow - exclusive access
    let ref_mut = &mut data;
    ref_mut.push(6);
    // ref1 and ref2 can't be used while ref_mut is active
    
    // After ref_mut is done, immutable borrows work again
    let ref3 = &data;
    println!("{:?}", ref3);
}
}

graph TD
    subgraph "Rust Borrowing Rules<br/>Rust 借用规则"
        D["mut data: Vec&lt;i32&gt;"]
        
        subgraph "Phase 1: Multiple Immutable Borrows [OK]<br/>阶段 1：多个不可变借用"
            IR1["&data (ref1)"]
            IR2["&data (ref2)"]
            D --> IR1
            D --> IR2
            IR1 -.->|"Read-only access<br/>只读访问"| MEM1["Memory: [1,2,3,4,5]"]
            IR2 -.->|"Read-only access<br/>只读访问"| MEM1
        end
        
        subgraph "Phase 2: Exclusive Mutable Borrow [OK]<br/>阶段 2：独占可变借用"
            MR["&mut data (ref_mut)"]
            D --> MR
            MR -.->|"Exclusive read/write<br/>独占读写"| MEM2["Memory: [1,2,3,4,5,6]"]
            BLOCK["[ERROR] Other borrows blocked<br/>其余借用被阻塞"]
        end
        
        subgraph "Phase 3: Immutable Borrows Again [OK]<br/>阶段 3：重新回到不可变借用"
            IR3["&data (ref3)"]
            D --> IR3
            IR3 -.->|"Read-only access<br/>只读访问"| MEM3["Memory: [1,2,3,4,5,6]"]
        end
    end
    
    subgraph "What C/C++ Allows (Dangerous)<br/>C/C++ 允许但很危险的情况"
        CP["int* ptr"]
        CP2["int* ptr2"]
        CP3["int* ptr3"]
        CP --> CMEM["Same Memory<br/>同一块内存"]
        CP2 --> CMEM
        CP3 --> CMEM
        RACE["[ERROR] Data races possible<br/>可能出现数据竞争<br/>[ERROR] Use after free possible<br/>可能出现释放后继续使用"]
    end
    
    style MEM1 fill:#91e5a3,color:#000
    style MEM2 fill:#91e5a3,color:#000
    style MEM3 fill:#91e5a3,color:#000
    style BLOCK fill:#ffa07a,color:#000
    style RACE fill:#ff6b6b,color:#000
    style CMEM fill:#ff6b6b,color:#000

Interior Mutability: Cell<T> and RefCell<T>
内部可变性：Cell<T> 与 RefCell<T>

Recall that by default variables are immutable in Rust. Sometimes it is useful to keep most of a type read-only while permitting writes to one specific field.
前面已经看过，Rust 默认让变量保持不可变。有时候会希望一个类型的大部分字段都保持只读，只给某一个字段开个可写口子。

#![allow(unused)]
fn main() {
struct Employee {
    employee_id : u64,   // This must be immutable
    on_vacation: bool,   // What if we wanted to permit write-access to this field, but make employee_id immutable?
}
}

• Rust normally allows one mutable reference or many immutable references, and this is enforced at compile time.
  Rust 平时遵守的规则还是那一套：一个可变引用，或者多个不可变引用，而且由编译器在编译期检查。
• But what if we wanted to pass an immutable slice or vector of employees while still allowing the on_vacation flag to change, and at the same time ensuring that employee_id remains immutable?
  可如果现在想把员工列表作为不可变引用传出去，同时又允许 on_vacation 这个标记更新，而且还得保证 employee_id 完全不许改，那怎么办？

Cell<T> — interior mutability for Copy types
Cell<T>：适用于 Copy 类型的内部可变性

• Cell<T> provides interior mutability, meaning specific fields can be changed even through an otherwise immutable reference.
  Cell<T> 提供的是 内部可变性：即使拿到的是不可变引用，也能改动其中某些字段。
• It works by copying values in and out, so .get() requires T: Copy.
  它的做法是把值拷进来、再拷出去，因此 .get() 这条路要求 T: Copy。

RefCell<T> — interior mutability with runtime borrow checking
RefCell<T>：把借用检查推迟到运行时

• RefCell<T> is the variant that works for borrowed access to non-Copy data.
  RefCell<T> 则适合那些不能简单复制、需要借用访问的类型。
• It enforces borrow rules at runtime instead of compile time.
  它不在编译期检查借用规则，而是在运行时动态检查。
• It allows one mutable borrow, but panics if another borrow is still active.
  它同样只允许一个可变借用；如果还有别的借用活着，再去可变借用就会 panic。
• Use .borrow() for immutable access and .borrow_mut() for mutable access.
  只读访问用 .borrow()，可变访问用 .borrow_mut()。

When to Choose Cell vs RefCell
Cell 和 RefCell 该怎么选

Shared Ownership: Rc<T>
共享所有权：Rc<T>

Rc<T> allows reference-counted shared ownership of immutable data. This is useful when the same value needs to appear in multiple places without being copied.
Rc<T> 允许通过引用计数实现对不可变数据的共享所有权。它适合那种“同一份对象要挂在多个地方，但又不想真的复制几份”的场景。

#[derive(Debug)]
struct Employee {
    employee_id: u64,
}
fn main() {
    let mut us_employees = vec![];
    let mut all_global_employees = Vec::<Employee>::new();
    let employee = Employee { employee_id: 42 };
    us_employees.push(employee);
    // Won't compile — employee was already moved
    //all_global_employees.push(employee);
}

Rc<T> solves the problem by allowing shared immutable access.
Rc<T> 解决这个问题的方式，就是把“多个地方都要拥有它”转成“多个地方一起共享这份不可变数据”。

• The inner type is dereferenced automatically.
  内部值可以自动解引用使用。
• The value is dropped when the strong reference count reaches zero.
  当强引用计数归零时，内部值就会被释放。

use std::rc::Rc;
#[derive(Debug)]
struct Employee {employee_id: u64}
fn main() {
    let mut us_employees = vec![];
    let mut all_global_employees = vec![];
    let employee = Employee { employee_id: 42 };
    let employee_rc = Rc::new(employee);
    us_employees.push(employee_rc.clone());
    all_global_employees.push(employee_rc.clone());
    let employee_one = all_global_employees.get(0); // Shared immutable reference
    for e in us_employees {
        println!("{}", e.employee_id);  // Shared immutable reference
    }
    println!("{employee_one:?}");
}

For C++ developers: Smart Pointer Mapping
给 C++ 开发者的智能指针对照：

C++ Smart Pointer C++ 智能指针	Rust Equivalent Rust 对应物	Key Difference 关键差异
std::unique_ptr<T>	Box<T>	Rust 把 move 做成了语言级默认行为，不是额外自觉选择的约定 Rust 里的 move 是语言层规则，不是“想安全时再套一个指针”
std::shared_ptr<T>	Rc<T> single-thread, Arc<T> multi-thread	Rc 没有原子计数开销；跨线程共享时再上 Arc 单线程先用 Rc，跨线程再换 Arc
std::weak_ptr<T>	Weak<T>	两边的目的都一样：打破引用环 都是用来处理循环引用的

Key distinction: In C++, smart pointers are a deliberate library choice. In Rust, owned values T plus borrowing &T already cover most cases; Box、Rc and Arc are reserved for situations that genuinely need heap allocation or shared ownership.
最重要的区别： 在 C++ 里，智能指针通常是一种“主动选型”；在 Rust 里，普通拥有值 T 加借用 &T 已经覆盖了大多数场景。只有真的需要堆分配或者共享所有权时，才把 Box、Rc、Arc 拿出来。

Breaking Reference Cycles with Weak<T>
用 Weak<T> 打破引用环

Rc<T> uses reference counting. If two Rc values point to each other, neither side can ever reach a strong count of zero, so the memory is leaked. Weak<T> is the escape hatch.
Rc<T> 靠引用计数工作。如果两个 Rc 互相指着对方，双方的强引用计数就永远降不到零，内存也就永远回收不了。Weak<T> 就是专门拿来破这个局的。

use std::rc::{Rc, Weak};

struct Node {
    value: i32,
    parent: Option<Weak<Node>>,  // Weak reference — doesn't prevent drop
}

fn main() {
    let parent = Rc::new(Node { value: 1, parent: None });
    let child = Rc::new(Node {
        value: 2,
        parent: Some(Rc::downgrade(&parent)),  // Weak ref to parent
    });

    // To use a Weak, try to upgrade it — returns Option<Rc<T>>
    if let Some(parent_rc) = child.parent.as_ref().unwrap().upgrade() {
        println!("Parent value: {}", parent_rc.value);
    }
    println!("Parent strong count: {}", Rc::strong_count(&parent)); // 1, not 2
}

Weak<T> is covered in more depth in Avoiding Excessive clone(). For now, the key takeaway is simple: use Weak for back-references in tree or graph structures so those structures can still be freed.
Weak<T> 会在 Avoiding Excessive clone() 里再展开讲。这里先记住一句话：树和图结构里，凡是“回指父节点”这类反向引用，优先考虑 Weak，这样整棵结构在不用时才能正常释放。

Combining Rc with Interior Mutability
把 Rc 和内部可变性组合起来

The real power shows up when Rc<T> is combined with Cell<T> or RefCell<T>. This allows multiple owners to read and also modify shared state.
真正有意思的地方，在于把 Rc<T> 和 Cell<T> 或 RefCell<T> 叠在一起。这样一来，多个所有者不仅能读同一份数据，还能在受控条件下修改它。

Exercise: Shared ownership and interior mutability
练习：共享所有权与内部可变性

🟡 Intermediate
🟡 进阶练习

• Part 1 (Rc): Create an Employee struct with employee_id: u64 and name: String. Place it in an Rc<Employee> and clone it into two separate Vecs, us_employees and global_employees. Print both vectors to show they share the same data.
  第 1 部分（Rc）：定义一个 Employee，包含 employee_id: u64 和 name: String。把它放进 Rc<Employee> 里，然后 clone 到两个不同的 Vec，分别叫 us_employees 和 global_employees。最后分别打印，确认两边看到的是同一份数据。
• Part 2 (Cell): Add an on_vacation: Cell<bool> field. Pass an immutable &Employee into a function and toggle on_vacation inside that function, without making the reference mutable.
  第 2 部分（Cell）：给 Employee 增加 on_vacation: Cell<bool>。把不可变的 &Employee 传给一个函数，在函数内部切换 on_vacation 的值，而且整个过程中都不把引用改成可变。
• Part 3 (RefCell): Replace name: String with name: RefCell<String> and write a function that appends a suffix to the employee name through an immutable &Employee reference.
  第 3 部分（RefCell）：把 name: String 换成 name: RefCell<String>，然后写一个函数，接收不可变的 &Employee，给员工名字追加后缀。

Starter code:
起始代码：

use std::cell::{Cell, RefCell};
use std::rc::Rc;

#[derive(Debug)]
struct Employee {
    employee_id: u64,
    name: RefCell<String>,
    on_vacation: Cell<bool>,
}

fn toggle_vacation(emp: &Employee) {
    // TODO: Flip on_vacation using Cell::set()
}

fn append_title(emp: &Employee, title: &str) {
    // TODO: Borrow name mutably via RefCell and push_str the title
}

fn main() {
    // TODO: Create an employee, wrap in Rc, clone into two Vecs,
    // call toggle_vacation and append_title, print results
}

use std::cell::{Cell, RefCell};
use std::rc::Rc;

#[derive(Debug)]
struct Employee {
    employee_id: u64,
    name: RefCell<String>,
    on_vacation: Cell<bool>,
}

fn toggle_vacation(emp: &Employee) {
    emp.on_vacation.set(!emp.on_vacation.get());
}

fn append_title(emp: &Employee, title: &str) {
    emp.name.borrow_mut().push_str(title);
}

fn main() {
    let emp = Rc::new(Employee {
        employee_id: 42,
        name: RefCell::new("Alice".to_string()),
        on_vacation: Cell::new(false),
    });

    let mut us_employees = vec![];
    let mut global_employees = vec![];
    us_employees.push(Rc::clone(&emp));
    global_employees.push(Rc::clone(&emp));

    // Toggle vacation through an immutable reference
    toggle_vacation(&emp);
    println!("On vacation: {}", emp.on_vacation.get()); // true

    // Append title through an immutable reference
    append_title(&emp, ", Sr. Engineer");
    println!("Name: {}", emp.name.borrow()); // "Alice, Sr. Engineer"

    // Both Vecs see the same data (Rc shares ownership)
    println!("US: {:?}", us_employees[0].name.borrow());
    println!("Global: {:?}", global_employees[0].name.borrow());
    println!("Rc strong count: {}", Rc::strong_count(&emp));
}
// Output:
// On vacation: true
// Name: Alice, Sr. Engineer
// US: "Alice, Sr. Engineer"
// Global: "Alice, Sr. Engineer"
// Rc strong count: 3

Rust crates and modules
Rust 的 crate 与模块

What you’ll learn: How Rust organizes code with modules and crates, why visibility is private by default, how pub works, what workspaces are for, and how the crates.io ecosystem replaces the old C/C++ header plus build-system dependency stack.
本章将学到什么： Rust 是怎样用模块和 crate 组织代码的，为什么可见性默认是私有，pub 到底控制了什么，workspace 有什么用，以及 crates.io 生态如何取代 C/C++ 里那套头文件加构建系统依赖管理的组合拳。

• Modules are the fundamental code organization unit inside a crate.
  模块是 Rust crate 内部最基础的代码组织单位。
  • Each source file .rs is its own module, and nested modules can be introduced with the mod keyword.
    每个 .rs 源文件本身就是一个模块，也可以继续用 mod 定义子模块。
  • Types and functions inside a module are private by default. They are not visible outside that module unless explicitly marked pub. Visibility can be narrowed further with forms such as pub(crate).
    模块里的类型和函数默认都是私有的，不显式写 pub 就出不了这个模块。pub 还可以继续细分成 pub(crate) 这类范围更窄的可见性。
  • Even if an item is public, it still does not become automatically available in another module’s local scope. It usually needs to be brought in with use, and child modules can reach parent items through super::.
    就算某个条目是公开的，也不会自动出现在别的模块局部作用域里。通常还是要配合 use 引进来，子模块访问父模块时则经常会看到 super::。
  • Source files are not automatically part of the crate unless they are explicitly declared from main.rs or lib.rs.
    一个 .rs 文件摆在那里，并不意味着它已经进了 crate。要让它真正参与编译，通常还得在 main.rs 或 lib.rs 里显式声明。

Exercise: Modules and functions
练习：模块与函数

• Let’s modify a simple hello world so it calls a helper function from another module.
  先拿最简单的 hello world 开刀，改成从另一个模块里调用函数。
  • Functions are declared with the fn keyword. The -> arrow declares a return value, and here the return type is u32.
    函数用 fn 关键字定义。-> 后面跟的是返回类型，这里例子里是 u32。
  • Functions are scoped by module. Two modules can each define a function with the same name without conflict.
    函数的名字是带模块作用域的，所以两个不同模块里就算有同名函数，也不会直接打架。
    • The same scoping rule applies to types. For example, struct foo inside mod a and struct foo inside mod b are two distinct types: a::foo and b::foo.
      类型也是一样。mod a { struct Foo; } 和 mod b { struct Foo; } 里的 Foo 在 Rust 看来根本就是两个不同类型。

Starter code — complete the functions:
起始代码：把下面这段补完整。

mod math {
    // TODO: implement pub fn add(a: u32, b: u32) -> u32
}

fn greet(name: &str) -> String {
    // TODO: return "Hello, <name>! The secret number is <math::add(21,21)>"
    todo!()
}

fn main() {
    println!("{}", greet("Rustacean"));
}

mod math {
    pub fn add(a: u32, b: u32) -> u32 {
        a + b
    }
}

fn greet(name: &str) -> String {
    format!("Hello, {}! The secret number is {}", name, math::add(21, 21))
}

fn main() {
    println!("{}", greet("Rustacean"));
}
// Output: Hello, Rustacean! The secret number is 42

Workspaces and crates (packages)
workspace 与 crate（包）

• Any non-trivial Rust project should strongly consider using a workspace to organize related crates.
  只要项目稍微有点规模，基本都应该认真考虑用 workspace 来组织多个 crate。
  • A workspace is simply a collection of local crates that are built together. The root Cargo.toml lists the member packages.
    workspace 本质上就是一组一起构建的本地 crate。根目录下的 Cargo.toml 会把成员包列出来。

[workspace]
resolver = "2"
members = ["package1", "package2"]

workspace_root/
|-- Cargo.toml      # Workspace configuration
|-- package1/
|   |-- Cargo.toml  # Package 1 configuration
|   `-- src/
|       `-- lib.rs  # Package 1 source code
|-- package2/
|   |-- Cargo.toml  # Package 2 configuration
|   `-- src/
|       `-- main.rs # Package 2 source code

Exercise: Using workspaces and package dependencies
练习：使用 workspace 和包依赖

• We will create a simple workspace and make one package depend on another.
  下面动手建一个最小 workspace，再让其中一个包依赖另一个包。
• Create the workspace directory.
  先创建 workspace 目录。

mkdir workspace
cd workspace

• Create Cargo.toml at the root and initialize an empty workspace.
  然后在根目录创建 Cargo.toml，先把空 workspace 搭起来。

[workspace]
resolver = "2"
members = []

• Add the packages. The --lib flag creates a library crate instead of a binary crate.
  再加两个包。--lib 的意思是建一个库 crate，而不是可执行程序 crate。

cargo new hello
cargo new --lib hellolib

Exercise: Using workspaces and package dependencies
练习继续：把包连起来

• Inspect the generated Cargo.toml files in hello and hellolib. Notice that both of them now participate in the upper-level workspace.
  看看 hello 和 hellolib 里生成出来的 Cargo.toml，会发现它们已经被纳入上层 workspace 了。
• The presence of lib.rs in hellolib indicates a library package. See the Cargo targets reference if customization is needed later.
  hellolib 里有 lib.rs，这就意味着它是个库包。以后如果要玩更复杂的目标配置，可以再去查 Cargo targets 文档。
• Add a dependency on hellolib in hello/Cargo.toml.
  接着在 hello 的 Cargo.toml 里把 hellolib 作为本地依赖加进去。

[dependencies]
hellolib = {path = "../hellolib"}

• Use add() from hellolib.
  然后在 hello 里调用 hellolib::add()。

fn main() {
    println!("Hello, world! {}", hellolib::add(21, 21));
}

# Terminal commands
mkdir workspace && cd workspace

# Create workspace Cargo.toml
cat > Cargo.toml << 'EOF'
[workspace]
resolver = "2"
members = ["hello", "hellolib"]
EOF

cargo new hello
cargo new --lib hellolib

# hello/Cargo.toml — add dependency
[dependencies]
hellolib = {path = "../hellolib"}

#![allow(unused)]
fn main() {
// hellolib/src/lib.rs — already has add() from cargo new --lib
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}
}

// hello/src/main.rs
fn main() {
    println!("Hello, world! {}", hellolib::add(21, 21));
}
// Output: Hello, world! 42

Using community crates from crates.io
使用 crates.io 上的社区 crate

• Rust has a very active ecosystem of community crates. See https://crates.io/.
  Rust 的社区 crate 生态非常活跃，核心入口就是 https://crates.io/。
  • A common Rust philosophy is to keep the standard library relatively compact and move lots of functionality into external crates.
    Rust 的一条重要思路就是：标准库保持相对紧凑，更多功能交给社区 crate 去扩展。
  • There is no absolute rule for whether a community crate should be used, but the usual checks are maturity, version history, and whether maintenance still looks active.
    要不要引入某个社区 crate，没有死规矩。通常先看成熟度、版本演进和维护活跃度，拿不准时再去问项目里更熟这块的人。
• Every crate on crates.io carries semantic version information.
  每个 crate 都会带语义化版本信息。
  • Crates are expected to follow Cargo’s SemVer guidelines: https://doc.rust-lang.org/cargo/reference/semver.html
    Cargo 对 SemVer 的约定可以看官方文档。
  • The simple summary is that within a compatible version range, breaking changes should not suddenly出现。
    简单说，同一兼容区间里不应该突然塞进破坏性改动。

Crate dependencies and SemVer
crate 依赖与语义化版本

• Dependencies can be pinned tightly, loosened to a version range, or left very open. The following Cargo.toml snippets demonstrate several ways to depend on the rand crate.
  依赖版本既可以卡得很死，也可以只约束一个兼容区间，还可以几乎不管。下面用 rand 举几个例子。

• At least 0.10.0, but anything < 0.11.0 is acceptable.
  至少是 0.10.0，但小于 0.11.0 的兼容版本都可以。

[dependencies]
rand = { version = "0.10.0"}

• Exactly 0.10.0, and nothing else.
  只接受 0.10.0，一丁点都不放宽。

[dependencies]
rand = { version = "=0.10.0"}

• “I don’t care, pick the newest one.”
  “无所谓，给我挑最新的。”

[dependencies]
rand = { version = "*"}

• Reference: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
  更完整的依赖写法可以看官方文档。

Exercise: Using the rand crate
练习：使用 rand crate

• Modify the hello world example so it prints random values.
  把 hello world 例子改成打印随机值。
• Use cargo add rand to add the dependency.
  先用 cargo add rand 加依赖。
• Use https://docs.rs/rand/latest/rand/ as the API reference.
  API 文档参考 https://docs.rs/rand/latest/rand/。

Starter code — add this to main.rs after running cargo add rand:
起始代码：执行完 cargo add rand 之后，把下面内容放进 main.rs。

use rand::RngExt;

fn main() {
    let mut rng = rand::rng();
    // TODO: Generate and print a random u32 in 1..=100
    // TODO: Generate and print a random bool
    // TODO: Generate and print a random f64
}

use rand::RngExt;

fn main() {
    let mut rng = rand::rng();
    let n: u32 = rng.random_range(1..=100);
    println!("Random number (1-100): {n}");

    // Generate a random boolean
    let b: bool = rng.random();
    println!("Random bool: {b}");

    // Generate a random float between 0.0 and 1.0
    let f: f64 = rng.random();
    println!("Random float: {f:.4}");
}

Cargo.toml and Cargo.lock
Cargo.toml 与 Cargo.lock

• As mentioned earlier, Cargo.lock is generated automatically based on Cargo.toml.
  前面提过，Cargo.lock 是根据 Cargo.toml 自动生成出来的。
  • Its main purpose is reproducible builds. For example, if Cargo.toml only says 0.10.0, Cargo is allowed to pick any compatible version below 0.11.0.
    它的核心价值是保证构建可复现。比如 Cargo.toml 只写了 0.10.0，那 Cargo 实际可以在兼容区间里选具体版本。
  • Cargo.lock records the exact version that was selected during the build.
    Cargo.lock 会把最终选中的精确版本记下来。
  • The usual recommendation is to commit Cargo.lock into the repository so everyone builds against the same dependency graph.
    通常建议把 Cargo.lock 一起提交进仓库，这样大家拉下来之后用的是同一套依赖图。

cargo test feature
cargo test 与测试模块

• Rust unit tests usually live in the same source file as the code, grouped by convention inside a test-only module.
  Rust 单元测试通常就写在源文件里，按约定放进一个只在测试时启用的模块里。
  • Test code is not included in the production binary. This is powered by the cfg feature, which is also used for platform-specific code such as Linux vs Windows differences.
    测试代码不会混进正式二进制里，这靠的就是 cfg 条件编译机制。平台差异代码，比如 Linux 和 Windows 分支，也经常用它处理。
  • Tests can be run with cargo test.
    执行测试就直接用 cargo test。

#![allow(unused)]
fn main() {
pub fn add(left: u64, right: u64) -> u64 {
    left + right
}
// Will be included only during testing
#[cfg(test)]
mod tests {
    use super::*; // This makes all types in the parent scope visible
    #[test]
    fn it_works() {
        let result = add(2, 2); // Alternatively, super::add(2, 2);
        assert_eq!(result, 4);
    }
}
}

Other Cargo features
Cargo 的其他常用能力

• Cargo also has several other very useful tools built in or tightly integrated.
  Cargo 不只是管编译和依赖，它还把一堆日常工具都串起来了。
  • cargo clippy is Rust’s linting workhorse. Warnings should usually be fixed rather than ignored.
    cargo clippy 是最常用的 Rust lint 工具。大多数警告都应该处理掉，而不是假装没看见。
  • cargo format runs rustfmt and standardizes formatting.
    cargo format 会调用 rustfmt，统一代码格式，省掉样式争论。
  • cargo doc generates documentation from /// comments, and that is how docs for crates.io packages are commonly built.
    cargo doc 可以根据 /// 文档注释生成文档，crates.io 上大部分 crate 的文档就是这么来的。

Build Profiles: Controlling Optimization
构建 profile：控制优化方式

In C, people pass flags like -O0、-O2、-Os、-flto to gcc or clang. In Rust, the equivalent knobs live under build profiles in Cargo.toml.
C 里习惯在命令行里堆 -O0、-O2、-Os、-flto 这些选项；Rust 则把这类配置主要放在 Cargo.toml 的 profile 里。

# Cargo.toml — build profile configuration

[profile.dev]
opt-level = 0          # No optimization (fast compile, like -O0)
debug = true           # Full debug symbols (like -g)

[profile.release]
opt-level = 3          # Maximum optimization (like -O3)
lto = "fat"            # Link-Time Optimization (like -flto)
strip = true           # Strip symbols (like the strip command)
codegen-units = 1      # Single codegen unit — slower compile, better optimization
panic = "abort"        # No unwind tables (smaller binary)

cargo build              # Uses [profile.dev]
cargo build --release    # Uses [profile.release]

Build Scripts (build.rs): Linking C Libraries
构建脚本 build.rs：链接 C 库

In C projects, Makefiles or CMake are usually responsible for linking libraries and running code generation. Rust crates can embed that setup in a build.rs script.
C 项目里，这类事情一般交给 Makefile 或 CMake。Rust 则允许在 crate 根目录放一个 build.rs，把这部分逻辑收进来。

// build.rs — runs before compiling the crate

fn main() {
    // Link a system C library (like -lbmc_ipmi in gcc)
    println!("cargo::rustc-link-lib=bmc_ipmi");

    // Where to find the library (like -L/usr/lib/bmc)
    println!("cargo::rustc-link-search=/usr/lib/bmc");

    // Re-run if the C header changes
    println!("cargo::rerun-if-changed=wrapper.h");
}

You can even compile C source files directly from the Rust crate by using the cc build dependency.
如果需要，Rust crate 还能直接在构建阶段把 C 源文件一起编进去。

# Cargo.toml
[build-dependencies]
cc = "1"  # C compiler integration

// build.rs
fn main() {
    cc::Build::new()
        .file("src/c_helpers/ipmi_raw.c")
        .include("/usr/include/bmc")
        .compile("ipmi_raw");   // Produces libipmi_raw.a, linked automatically
    println!("cargo::rerun-if-changed=src/c_helpers/ipmi_raw.c");
}

Cross-compilation
交叉编译

In C, cross-compilation usually means installing a separate compiler toolchain and then wiring it into Make or CMake. In Rust, the target and the linker are configured a bit differently.
C 里交叉编译通常得另装一套编译器，再去改 Makefile 或 CMake。Rust 的方式会统一一些，但思路仍然差不多：目标三元组加外部 linker。

# Install a cross-compilation target
rustup target add aarch64-unknown-linux-gnu

# Cross-compile
cargo build --target aarch64-unknown-linux-gnu --release

Specify the linker in .cargo/config.toml:
linker 则放在 .cargo/config.toml 里配置。

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

Feature Flags: Conditional Compilation
feature flag：条件编译

C code often relies on #ifdef and -DFOO. Rust expresses the same class of conditional compilation with feature flags declared in Cargo.toml.
C 里常用 #ifdef 和 -DDEBUG 这类写法做条件编译；Rust 则用 Cargo.toml 里的 feature flag 来表达同样思路。

# Cargo.toml
[features]
default = ["json"]         # Enabled by default
json = ["dep:serde_json"]  # Optional dependency
verbose = []               # Flag with no dependency
gpu = ["dep:cuda-sys"]     # Optional GPU support

#![allow(unused)]
fn main() {
// Code gated on features:
#[cfg(feature = "json")]
pub fn parse_config(data: &str) -> Result<Config, Error> {
    serde_json::from_str(data).map_err(Error::from)
}

#[cfg(feature = "verbose")]
macro_rules! verbose {
    ($($arg:tt)*) => { eprintln!("[VERBOSE] {}", format!($($arg)*)); }
}
#[cfg(not(feature = "verbose"))]
macro_rules! verbose {
    ($($arg:tt)*) => {}; // Compiles to nothing
}
}

Integration tests vs unit tests
集成测试与单元测试

Unit tests live next to the implementation, but integration tests live under tests/ and can only see the crate’s public API.
单元测试通常和实现写在一起；集成测试则放在 tests/ 目录下，而且只能通过 crate 的公开 API 来测试。

#![allow(unused)]
fn main() {
// tests/smoke_test.rs — no #[cfg(test)] needed
use my_crate::parse_config;

#[test]
fn parse_valid_config() {
    let config = parse_config("test_data/valid.json").unwrap();
    assert_eq!(config.max_retries, 5);
}
}

Testing patterns and strategies
测试模式与策略

C firmware teams often rely on CUnit, CMocka, or a pile of custom boilerplate. Rust’s built-in test harness is more capable out of the box, and traits make mocking much cleaner.
很多 C 固件团队会用 CUnit、CMocka，或者自己堆一套测试样板。Rust 自带的测试框架已经很够用，再加上 trait 的帮助，mock 也会自然很多。

#[should_panic] — testing expected failures
#[should_panic]：测试“预期会炸”的情况

#![allow(unused)]
fn main() {
// Test that certain conditions cause panics (like C's assert failures)
#[test]
#[should_panic(expected = "index out of bounds")]
fn test_bounds_check() {
    let v = vec![1, 2, 3];
    let _ = v[10];  // Should panic
}

#[test]
#[should_panic(expected = "temperature exceeds safe limit")]
fn test_thermal_shutdown() {
    fn check_temperature(celsius: f64) {
        if celsius > 105.0 {
            panic!("temperature exceeds safe limit: {celsius}°C");
        }
    }
    check_temperature(110.0);
}
}

#[ignore] — slow or hardware-dependent tests
#[ignore]：慢测试或依赖特定硬件的测试

#![allow(unused)]
fn main() {
// Mark tests that require special conditions (like C's #ifdef HARDWARE_TEST)
#[test]
#[ignore = "requires GPU hardware"]
fn test_gpu_ecc_scrub() {
    // This test only runs on machines with GPUs
    // Run with: cargo test -- --ignored
    // Run with: cargo test -- --include-ignored  (runs ALL tests)
}
}

Result-returning tests
返回 Result 的测试函数

#![allow(unused)]
fn main() {
// Instead of many unwrap() calls that hide the actual failure:
#[test]
fn test_config_parsing() -> Result<(), Box<dyn std::error::Error>> {
    let json = r#"{"hostname": "node-01", "port": 8080}"#;
    let config: ServerConfig = serde_json::from_str(json)?;  // ? instead of unwrap()
    assert_eq!(config.hostname, "node-01");
    assert_eq!(config.port, 8080);
    Ok(())  // Test passes if we reach here without error
}
}

This style often produces clearer failure information than stacking unwrap() everywhere.
这种写法通常比一连串 unwrap() 更清楚，失败时也更容易看出究竟是哪一步出问题。

Test fixtures with builder functions
用辅助构造函数做测试夹具

#![allow(unused)]
fn main() {
struct TestFixture {
    temp_dir: std::path::PathBuf,
    config: Config,
}

impl TestFixture {
    fn new() -> Self {
        let temp_dir = std::env::temp_dir().join(format!("test_{}", std::process::id()));
        std::fs::create_dir_all(&temp_dir).unwrap();
        let config = Config {
            log_dir: temp_dir.clone(),
            max_retries: 3,
            ..Default::default()
        };
        Self { temp_dir, config }
    }
}

impl Drop for TestFixture {
    fn drop(&mut self) {
        // Automatic cleanup — like C's tearDown() but can't be forgotten
        let _ = std::fs::remove_dir_all(&self.temp_dir);
    }
}

#[test]
fn test_with_fixture() {
    let fixture = TestFixture::new();
    // Use fixture.config, fixture.temp_dir...
    assert!(fixture.temp_dir.exists());
    // fixture is automatically dropped here → cleanup runs
}
}

This pattern replaces the old setUp() / tearDown() style with regular Rust values plus Drop cleanup.
这种方式本质上就是把 C 世界那种 setUp() / tearDown() 流程，换成了“构造一个值，结束时自动清理”的 Rust 风格。

Mocking traits for hardware interfaces
为硬件接口做 trait mock

In C, mocking hardware often means function-pointer swapping or preprocessor tricks. In Rust, traits make dependency injection much more natural.
C 里做硬件 mock 往往要靠函数指针替换或者预处理器戏法，Rust 则直接用 trait 做依赖注入，结构干净得多。

#![allow(unused)]
fn main() {
// Production trait for IPMI communication
trait IpmiTransport {
    fn send_command(&self, cmd: u8, data: &[u8]) -> Result<Vec<u8>, String>;
}

// Real implementation (used in production)
struct RealIpmi { /* BMC connection details */ }
impl IpmiTransport for RealIpmi {
    fn send_command(&self, cmd: u8, data: &[u8]) -> Result<Vec<u8>, String> {
        // Actually talks to BMC hardware
        todo!("Real IPMI call")
    }
}

// Mock implementation (used in tests)
struct MockIpmi {
    responses: std::collections::HashMap<u8, Vec<u8>>,
}
impl IpmiTransport for MockIpmi {
    fn send_command(&self, cmd: u8, _data: &[u8]) -> Result<Vec<u8>, String> {
        self.responses.get(&cmd)
            .cloned()
            .ok_or_else(|| format!("No mock response for cmd 0x{cmd:02x}"))
    }
}

// Generic function that works with both real and mock
fn read_sensor_temperature(transport: &dyn IpmiTransport) -> Result<f64, String> {
    let response = transport.send_command(0x2D, &[])?;
    if response.len() < 2 {
        return Err("Response too short".into());
    }
    Ok(response[0] as f64 + (response[1] as f64 / 256.0))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_temperature_reading() {
        let mut mock = MockIpmi { responses: std::collections::HashMap::new() };
        mock.responses.insert(0x2D, vec![72, 128]); // 72.5°C

        let temp = read_sensor_temperature(&mock).unwrap();
        assert!((temp - 72.5).abs() < 0.01);
    }

    #[test]
    fn test_short_response() {
        let mock = MockIpmi { responses: std::collections::HashMap::new() };
        // No response configured → error
        assert!(read_sensor_temperature(&mock).is_err());
    }
}
}

Property-based testing with proptest
用 proptest 做性质测试

Instead of only testing a handful of fixed values, property-based testing checks invariants across many generated inputs.
性质测试的思路不是只测几个固定样本，而是定义“某个性质应该永远成立”，再让工具自动生成大量输入去冲它。

#![allow(unused)]
fn main() {
// Cargo.toml: [dev-dependencies] proptest = "1"
use proptest::prelude::*;

fn parse_sensor_id(s: &str) -> Option<u32> {
    s.strip_prefix("sensor_")?.parse().ok()
}

fn format_sensor_id(id: u32) -> String {
    format!("sensor_{id}")
}

proptest! {
    #[test]
    fn roundtrip_sensor_id(id in 0u32..10000) {
        // Property: format then parse should give back the original
        let formatted = format_sensor_id(id);
        let parsed = parse_sensor_id(&formatted);
        prop_assert_eq!(parsed, Some(id));
    }

    #[test]
    fn parse_rejects_garbage(s in "[^s].*") {
        // Property: strings not starting with 's' should never parse
        let result = parse_sensor_id(&s);
        prop_assert!(result.is_none());
    }
}
}

C vs Rust testing comparison
C 测试方式与 Rust 测试方式对照

Testing Patterns §§ZH§§ 测试模式

Testing Patterns for C++ Programmers
面向 C++ 程序员的测试模式

What you’ll learn: Rust’s built-in test framework, including #[test], #[should_panic], Result-returning tests, builder patterns for test data, trait-based mocking, property testing with proptest, snapshot testing with insta, and integration test organization. This is the zero-config testing experience that replaces Google Test plus CMake glue.
本章将学到什么： Rust 内建测试框架的核心用法，包括 #[test]、#[should_panic]、返回 Result 的测试、测试数据的 builder 模式、基于 trait 的 mock、proptest 属性测试、insta 快照测试，以及集成测试的目录组织方式。整体体验就是把 Google Test 加一堆 CMake 胶水活，换成零配置起步。

C++ testing usually relies on external frameworks such as Google Test, Catch2, or Boost.Test, plus a pile of build-system integration. Rust takes a much simpler route: the test framework is built into the language and toolchain itself.
C++ 测试通常离不开外部框架，比如 Google Test、Catch2、Boost.Test，再配上一坨构建系统接线。Rust 走的是另一条路：测试框架直接内建在语言和工具链里。

Test attributes beyond #[test]
除了 #[test] 之外的常用测试属性

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn basic_pass() {
        assert_eq!(2 + 2, 4);
    }

    // Expect a panic — equivalent to GTest's EXPECT_DEATH
    #[test]
    #[should_panic]
    fn out_of_bounds_panics() {
        let v = vec![1, 2, 3];
        let _ = v[10]; // Panics — test passes
    }

    // Expect a panic with a specific message substring
    #[test]
    #[should_panic(expected = "index out of bounds")]
    fn specific_panic_message() {
        let v = vec![1, 2, 3];
        let _ = v[10];
    }

    // Tests that return Result<(), E> — use ? instead of unwrap()
    #[test]
    fn test_with_result() -> Result<(), String> {
        let value: u32 = "42".parse().map_err(|e| format!("{e}"))?;
        assert_eq!(value, 42);
        Ok(())
    }

    // Ignore slow tests by default — run with `cargo test -- --ignored`
    #[test]
    #[ignore]
    fn slow_integration_test() {
        std::thread::sleep(std::time::Duration::from_secs(10));
    }
}
}

cargo test                          # Run all non-ignored tests
cargo test -- --ignored             # Run only ignored tests
cargo test -- --include-ignored     # Run ALL tests including ignored
cargo test test_name                # Run tests matching a name pattern
cargo test -- --nocapture           # Show println! output during tests
cargo test -- --test-threads=1      # Run tests serially (for shared state)

这套属性系统的好处在于，测试行为直接写在函数定义旁边，读代码时一眼就能看到预期。C++ 里那种测试框架宏、运行器参数、构建脚本三头分裂的局面，在 Rust 这里会轻很多。
The biggest advantage of these attributes is that test behavior lives right beside the test function itself. Instead of spreading intent across framework macros, runner flags, and build scripts, Rust keeps it close to the code.

Test helpers: builder pattern for test data
测试辅助：用 builder 模式构造测试数据

In C++ you’d often reach for Google Test fixtures such as class MyTest : public ::testing::Test. In Rust, builder functions and Default usually cover the same use case with less ceremony.
在 C++ 里，这类场景通常会写成 Google Test fixture，比如 class MyTest : public ::testing::Test。在 Rust 里，builder 函数和 Default 往往就够用了，样板更少。

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    // Builder function — creates test data with sensible defaults
    fn make_gpu_event(severity: Severity, fault_code: u32) -> DiagEvent {
        DiagEvent {
            source: "accel_diag".to_string(),
            severity,
            message: format!("Test event FC:{fault_code}"),
            fault_code,
        }
    }

    // Reusable test fixture — a set of pre-built events
    fn sample_events() -> Vec<DiagEvent> {
        vec![
            make_gpu_event(Severity::Critical, 67956),
            make_gpu_event(Severity::Warning, 32709),
            make_gpu_event(Severity::Info, 10001),
        ]
    }

    #[test]
    fn filter_critical_events() {
        let events = sample_events();
        let critical: Vec<_> = events.iter()
            .filter(|e| e.severity == Severity::Critical)
            .collect();
        assert_eq!(critical.len(), 1);
        assert_eq!(critical[0].fault_code, 67956);
    }
}
}

Mocking with traits
用 trait 做 mock

In C++, mocking often means Google Mock, inheritance tricks, or hand-written virtual overrides. In Rust, the common pattern is simpler: abstract the dependency behind a trait, then swap in a test implementation.
在 C++ 里，mock 往往意味着 Google Mock、继承技巧，或者手写虚函数覆盖。Rust 更常见的写法反而更直白：先把依赖抽象成 trait，再在测试里换成一个测试实现。

#![allow(unused)]
fn main() {
// Production trait
trait SensorReader {
    fn read_temperature(&self, sensor_id: u32) -> Result<f64, String>;
}

// Production implementation
struct HwSensorReader;
impl SensorReader for HwSensorReader {
    fn read_temperature(&self, sensor_id: u32) -> Result<f64, String> {
        // Real hardware call...
        Ok(72.5)
    }
}

// Test mock — returns predictable values
#[cfg(test)]
struct MockSensorReader {
    temperatures: std::collections::HashMap<u32, f64>,
}

#[cfg(test)]
impl SensorReader for MockSensorReader {
    fn read_temperature(&self, sensor_id: u32) -> Result<f64, String> {
        self.temperatures.get(&sensor_id)
            .copied()
            .ok_or_else(|| format!("Unknown sensor {sensor_id}"))
    }
}

// Function under test — generic over the reader
fn check_overtemp(reader: &impl SensorReader, ids: &[u32], threshold: f64) -> Vec<u32> {
    ids.iter()
        .filter(|&&id| reader.read_temperature(id).unwrap_or(0.0) > threshold)
        .copied()
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn detect_overtemp_sensors() {
        let mut mock = MockSensorReader { temperatures: Default::default() };
        mock.temperatures.insert(0, 72.5);
        mock.temperatures.insert(1, 91.0);  // Over threshold
        mock.temperatures.insert(2, 65.0);

        let hot = check_overtemp(&mock, &[0, 1, 2], 80.0);
        assert_eq!(hot, vec![1]);
    }
}
}

这就是 Rust 在测试里很典型的一种风格：不靠“神奇 mock 框架”到处 patch，而是让抽象边界本身更清楚。这样测试舒服，生产代码结构也顺手更健康。
This is a very Rust-flavored testing style: instead of relying on magical patching frameworks, the code makes dependency boundaries explicit. That tends to improve both testability and overall design at the same time.

Temporary files and directories in tests
测试中的临时文件与目录

C++ tests often end up with platform-specific temp-directory hacks. Rust has the tempfile crate, which makes this boring in a good way.
C++ 测试里一涉及临时目录，经常就开始平台分支乱飞。Rust 这边有 tempfile crate，基本能把这件事处理得非常省心。

#![allow(unused)]
fn main() {
// Cargo.toml: [dev-dependencies]
// tempfile = "3"

#[cfg(test)]
mod tests {
    use super::*;
    use tempfile::NamedTempFile;
    use std::io::Write;

    #[test]
    fn parse_config_from_file() -> Result<(), Box<dyn std::error::Error>> {
        // Create a temp file that's auto-deleted when dropped
        let mut file = NamedTempFile::new()?;
        writeln!(file, r#"{{"sku": "ServerNode", "level": "Quick"}}"#)?;

        let config = load_config(file.path().to_str().unwrap())?;
        assert_eq!(config.sku, "ServerNode");
        Ok(())
        // file is deleted here — no cleanup code needed
    }
}
}

Property-based testing with proptest
用 proptest 做属性测试

Instead of writing a few hand-picked cases, property testing describes rules that should hold for a wide range of inputs. The framework then generates inputs automatically and shrinks failures to minimal repro cases.
属性测试的思路不是手写几个样例，而是先描述“什么性质必须始终成立”，然后让框架自动生成大量输入，并在失败时尽量收缩到最小复现用例。

#![allow(unused)]
fn main() {
// Cargo.toml: [dev-dependencies]
// proptest = "1"

#[cfg(test)]
mod tests {
    use proptest::prelude::*;

    fn parse_and_format(n: u32) -> String {
        format!("{n}")
    }

    proptest! {
        #[test]
        fn roundtrip_u32(n: u32) {
            let formatted = parse_and_format(n);
            let parsed: u32 = formatted.parse().unwrap();
            prop_assert_eq!(n, parsed);
        }

        #[test]
        fn string_contains_no_null(s in "[a-zA-Z0-9 ]{0,100}") {
            prop_assert!(!s.contains('\0'));
        }
    }
}
}

Snapshot testing with insta
用 insta 做快照测试

For complex JSON, formatted text, or structured output, snapshot testing can save a lot of repetitive assertion code. insta manages the baseline files and helps review changes.
如果测试产物是复杂 JSON、格式化文本或者层次很多的结构化输出，快照测试能省掉一大堆重复断言。insta 会替着管理基线文件，并协助审阅变更。

#![allow(unused)]
fn main() {
// Cargo.toml: [dev-dependencies]
// insta = { version = "1", features = ["json"] }

#[cfg(test)]
mod tests {
    use insta::assert_json_snapshot;

    #[test]
    fn der_entry_format() {
        let entry = DerEntry {
            fault_code: 67956,
            component: "GPU".to_string(),
            message: "ECC error detected".to_string(),
        };
        // First run: creates a snapshot file in tests/snapshots/
        // Subsequent runs: compares against the saved snapshot
        assert_json_snapshot!(entry);
    }
}
}

cargo insta test              # Run tests and review new/changed snapshots
cargo insta review            # Interactive review of snapshot changes

C++ vs Rust testing comparison
C++ 与 Rust 测试对照

Integration tests: the tests/ directory
集成测试：tests/ 目录

Unit tests live inside #[cfg(test)] modules next to the code they exercise. Integration tests live under a top-level tests/ directory and interact only with the crate’s public API, just like an external consumer would.
单元测试一般直接写在被测代码旁边的 #[cfg(test)] 模块里。集成测试则放在 crate 根目录下的 tests/ 目录中，只能通过公开 API 来访问代码，就像真正的外部使用者一样。

my_crate/
├── src/
│   └── lib.rs          # Your library code
├── tests/
│   ├── smoke.rs        # Each .rs file is a separate test binary
│   ├── regression.rs
│   └── common/
│       └── mod.rs      # Shared test helpers (NOT a test itself)
└── Cargo.toml

#![allow(unused)]
fn main() {
// tests/smoke.rs — tests your crate as an external user would
use my_crate::DiagEngine;  // Only public API is accessible

#[test]
fn engine_starts_successfully() {
    let engine = DiagEngine::new("test_config.json");
    assert!(engine.is_ok());
}

#[test]
fn engine_rejects_invalid_config() {
    let engine = DiagEngine::new("nonexistent.json");
    assert!(engine.is_err());
}
}

#![allow(unused)]
fn main() {
// tests/common/mod.rs — shared helpers, NOT compiled as a test binary
pub fn setup_test_environment() -> tempfile::TempDir {
    let dir = tempfile::tempdir().unwrap();
    std::fs::write(dir.path().join("config.json"), r#"{"log_level": "debug"}"#).unwrap();
    dir
}
}

#![allow(unused)]
fn main() {
// tests/regression.rs — can use shared helpers
mod common;

#[test]
fn regression_issue_42() {
    let env = common::setup_test_environment();
    let engine = my_crate::DiagEngine::new(
        env.path().join("config.json").to_str().unwrap()
    );
    assert!(engine.is_ok());
}
}

Running integration tests:
运行集成测试：

cargo test                          # Runs unit AND integration tests
cargo test --test smoke             # Run only tests/smoke.rs
cargo test --test regression        # Run only tests/regression.rs
cargo test --lib                    # Run ONLY unit tests (skip integration)

Key difference from unit tests: Integration tests cannot touch private functions or pub(crate) items. That restriction is useful, because it forces the public API to prove that it is actually testable and complete.
和单元测试最大的区别： 集成测试碰不到私有函数，也碰不到 pub(crate) 项。这种限制其实很有价值，因为它会逼着公共 API 自己站得住，测试用例也更接近真实使用方式。

Error Handling §§ZH§§ 错误处理

Connecting enums to Option and Result
把枚举和 Option、Result 串起来

What you’ll learn: How Rust replaces null pointers with Option<T> and exceptions with Result<T, E>, and how the ? operator makes error propagation concise. This is one of Rust’s most distinctive ideas: errors are values, not hidden control flow.
本章将学到什么： Rust 是怎样用 Option<T> 取代空指针、用 Result<T, E> 取代异常，以及 ? 运算符怎样把错误传播写得简洁明白。这是 Rust 最有代表性的设计之一：错误就是值，而不是藏在控制流背后的机关。

• Remember the enum type from earlier chapters? Option and Result are simply enums from the standard library.
  前面已经学过 enum。Option 和 Result 本质上就是标准库里定义好的两个枚举。

#![allow(unused)]
fn main() {
// This is literally how Option is defined in std:
enum Option<T> {
    Some(T),  // Contains a value
    None,     // No value
}

// And Result:
enum Result<T, E> {
    Ok(T),    // Success with value
    Err(E),   // Error with details
}
}

• That means everything learned earlier about match and pattern matching applies directly to Option and Result.
  这就意味着，前面关于 match 和模式匹配学过的那一整套，可以原封不动地套到 Option 和 Result 上。
• There is no null pointer in Rust. Option<T> is the replacement, and the compiler forces the None case to be handled.
  Rust 里 没有空指针 这回事。对应概念就是 Option<T>，而且编译器会强制把 None 分支处理掉。

C++ Comparison: Exceptions vs Result
C++ 对照：异常机制与 Result

Rust Option type
Rust 的 Option 类型

• Rust 的 Option 是一个只有两个变体的 enum：Some<T> 和 None。
  它的结构很朴素，就两个分支：要么有值，要么没值。
• 它表达的是“这个位置可能为空”的语义。要么里面装着一个有效值 Some<T>，要么就是没有值的 None。
  和 C/C++ 那种靠约定判断空值的写法比起来，这种表达方式更直接，也更难误用。
• Option 常用于“操作可能成功拿到值，也可能失败，但失败原因本身没必要额外说明”的场景。比如在字符串里查找子串位置。
  这类情况里，调用方关心的是“有没有”，而不是“为什么没有”。

fn main() {
    // Returns Option<usize>
    let a = "1234".find("1");
    match a {
        Some(a) => println!("Found 1 at index {a}"),
        None => println!("Couldn't find 1")
    }
}

Working with Option
处理 Option 的常见方式

• Rust 的 Option 有很多处理方式。
  重点是别一上来就手痒去写 unwrap()。
• unwrap() 会在 Option<T> 是 None 时 panic，在有值时返回内部的 T；这是最不推荐的基础写法。
  除非已经百分百确认值一定存在，否则这玩意儿属于把雷埋给未来的自己。
• or() 可以在当前值为空时提供一个替代值。
  适合准备一个后备选项。
• if let 可以快速只处理 Some<T> 的情况。
  不想完整展开 match 时，这个写法更轻快。

Production patterns: See Safe value extraction with unwrap_or and Functional transforms: map, map_err, find_map for real-world examples from production Rust code.
生产代码里的惯用法： 可以继续看 Safe value extraction with unwrap_or 和 Functional transforms: map, map_err, find_map，那里面是更贴近真实项目的写法。

fn main() {
  // This return an Option<usize>
  let a = "1234".find("1");
  println!("{a:?} {}", a.unwrap());
  let a = "1234".find("5").or(Some(42));
  println!("{a:?}");
  if let Some(a) = "1234".find("1") {
      println!("{a}");
  } else {
    println!("Not found in string");
  }
  // This will panic
  // "1234".find("5").unwrap();
}

Rust Result type
Rust 的 Result 类型

• Result 是一个和 Option 很像的 enum，有两个变体：Ok<T> 和 Err<E>。
  区别在于，Err<E> 里可以把错误细节一起带出去。
• Result 大量出现在可能失败的 Rust API 里。成功时返回 Ok<T>，失败时返回明确的错误值 Err<E>。
  这比“返回一个特殊值代表失败”或者“突然抛异常”都更直白。

use std::num::ParseIntError;

fn main() {
    let a: Result<i32, ParseIntError> = "1234z".parse();
    match a {
        Ok(n) => println!("Parsed {n}"),
        Err(e) => println!("Parsing failed {e:?}"),
    }
    let a: Result<i32, ParseIntError> = "1234z".parse().or(Ok(-1));
    println!("{a:?}");
    if let Ok(a) = "1234".parse::<i32>() {
        println!("Let OK {a}");
    }
    // This will panic
    // "1234z".parse().unwrap();
}

Option and Result: Two Sides of the Same Coin
Option 和 Result：一枚硬币的两面

Option 和 Result 之间关系非常近。可以把 Option<T> 看成一种“错误信息为空”的 Result。
也就是说，两者表达的都是“操作可能成功，也可能失败”，只是失败时带的信息量不同。

Converting between them:
两者之间也能互相转换：

fn main() {
    let opt: Option<i32> = Some(42);
    let res: Result<i32, &str> = opt.ok_or("value was None");  // Option → Result
    
    let res: Result<i32, &str> = Ok(42);
    let opt: Option<i32> = res.ok();  // Result → Option (discards error)
    
    // They share many of the same methods:
    // .map(), .and_then(), .unwrap_or(), .unwrap_or_else(), .is_some()/is_ok()
}

Rule of thumb: Use Option when absence is normal, such as a map lookup. Use Result when failure needs explanation, such as file I/O or parsing.
经验判断： “没有值”本来就是正常情况时，用 Option；失败需要解释清楚时，用 Result。例如查字典可以用 Option，文件读取和解析则更适合 Result。

Exercise: log() function implementation with Option
练习：用 Option 实现 log()

🟢 Starter
🟢 基础练习

• Implement a log() function that accepts Option<&str>. If the argument is None, print a default string.
  实现一个 log() 函数，参数类型是 Option<&str>。如果传入的是 None，就打印一条默认字符串。
• The function should return Result<(), ()>. In this example the error branch is never used, but keeping the type makes the exercise align with the chapter theme.
  返回类型写成 Result<(), ()>。虽然这个练习里暂时用不到错误分支，但这样能顺手把本章的思路串起来。

fn log(message: Option<&str>) -> Result<(), ()> {
    match message {
        Some(msg) => println!("LOG: {msg}"),
        None => println!("LOG: (no message provided)"),
    }
    Ok(())
}

fn main() {
    let _ = log(Some("System initialized"));
    let _ = log(None);
    
    // Alternative using unwrap_or:
    let msg: Option<&str> = None;
    println!("LOG: {}", msg.unwrap_or("(default message)"));
}
// Output:
// LOG: System initialized
// LOG: (no message provided)
// LOG: (default message)

Rust error handling
Rust 的错误处理

• Rust 里的错误大体分成两类：不可恢复的致命错误，以及可恢复错误。致命错误通常表现为 panic。
  前者属于程序已经跑歪了，后者才是业务逻辑里应该正常传递和处理的那部分。
• 一般来说，应该尽量减少 panic。大多数 panic 都意味着程序存在 bug，比如数组越界、对 Option::None 调用 unwrap() 等。
  这种错误如果出现在生产代码里，通常不是“用户用错了”，而是代码本身写得有毛病。
• 对那些“理论上绝对不该发生”的情况，显式 panic! 或 assert! 仍然是合理的。
  拿它们做健全性检查没问题，但别把正常错误处理偷懒写成 panic。

fn main() {
   let x : Option<u32> = None;
   // println!("{x}", x.unwrap()); // Will panic
   println!("{}", x.unwrap_or(0));  // OK -- prints 0
   let x = 41;
   //assert!(x == 42); // Will panic
   //panic!("Something went wrong"); // Unconditional panic
   let _a = vec![0, 1];
   // println!("{}", a[2]); // Out of bounds panic; use a.get(2) which will return Option<T>
}

Error Handling: C++ vs Rust
错误处理：C++ 与 Rust 对比

Problems with C++ exception-based handling
C++ 异常式错误处理的麻烦

// C++ error handling - exceptions create hidden control flow
#include <fstream>
#include <stdexcept>

std::string read_config(const std::string& path) {
    std::ifstream file(path);
    if (!file.is_open()) {
        throw std::runtime_error("Cannot open: " + path);
    }
    std::string content;
    // What if getline throws? Is file properly closed?
    // With RAII yes, but what about other resources?
    std::getline(file, content);
    return content;  // What if caller doesn't try/catch?
}

int main() {
    // ERROR: Forgot to wrap in try/catch!
    auto config = read_config("nonexistent.txt");
    // Exception propagates silently, program crashes
    // Nothing in the function signature warned us
    return 0;
}

graph TD
    subgraph "C++ Error Handling Issues<br/>C++ 错误处理问题"
        CF["Function Call<br/>函数调用"]
        CR["throw exception<br/>or return code<br/>抛异常或返回错误码"]
        CIGNORE["[ERROR] Exception not caught<br/>or return code ignored<br/>异常没人接或错误码被忽略"]
        CCHECK["try/catch or check<br/>手动 try/catch 或手动检查"]
        CERROR["Hidden control flow<br/>throws not in signature<br/>控制流隐藏，签名里看不出来"]
        CERRNO["No compile-time<br/>enforcement<br/>编译器不强制"]
        
        CF --> CR
        CR --> CIGNORE
        CR --> CCHECK
        CCHECK --> CERROR
        CERROR --> CERRNO
        
        CPROBLEMS["[ERROR] Exceptions invisible in types<br/>异常不写进类型<br/>[ERROR] Hidden control flow<br/>控制流不直观<br/>[ERROR] Easy to forget try/catch<br/>容易漏掉 try/catch<br/>[ERROR] Exception safety is hard<br/>异常安全本身就难<br/>[ERROR] noexcept is opt-in<br/>`noexcept` 还得手动标"]
    end
    
    subgraph "Rust Result<T, E> System<br/>Rust 的 Result<T, E> 体系"
        RF["Function Call<br/>函数调用"]
        RR["Result&lt;T, E&gt;<br/>Ok(value) | Err(error)"]
        RMUST["[OK] Must handle<br/>必须处理"]
        RMATCH["Pattern matching<br/>match, if let, ?"]
        RDETAIL["Detailed error info<br/>错误信息明确"]
        RSAFE["Type-safe<br/>类型安全<br/>No global state<br/>没有全局副作用"]
        
        RF --> RR
        RR --> RMUST
        RMUST --> RMATCH
        RMATCH --> RDETAIL
        RDETAIL --> RSAFE
        
        RBENEFITS["[OK] Forced error handling<br/>编译器强制处理<br/>[OK] Type-safe errors<br/>错误有类型<br/>[OK] Detailed error info<br/>细节能传上来<br/>[OK] Composable with ?<br/>能和 `?` 配合<br/>[OK] Zero runtime cost<br/>没有异常机制那类额外运行时开销"]
    end
    
    style CPROBLEMS fill:#ff6b6b,color:#000
    style RBENEFITS fill:#91e5a3,color:#000
    style CIGNORE fill:#ff6b6b,color:#000
    style RMUST fill:#91e5a3,color:#000

Result<T, E> Visualization
Result<T, E> 的流程图理解

// Rust error handling - comprehensive and forced
use std::fs::File;
use std::io::Read;

fn read_file_content(filename: &str) -> Result<String, std::io::Error> {
    let mut file = File::open(filename)?;  // ? automatically propagates errors
    let mut contents = String::new();
    file.read_to_string(&mut contents)?;
    Ok(contents)  // Success case
}

fn main() {
    match read_file_content("example.txt") {
        Ok(content) => println!("File content: {}", content),
        Err(error) => println!("Failed to read file: {}", error),
        // Compiler forces us to handle both cases!
    }
}

graph TD
    subgraph "Result<T, E> Flow<br/>`Result<T, E>` 执行流程"
        START["Function starts<br/>函数开始"]
        OP1["File::open()"]
        CHECK1{{"Result check<br/>检查 Result"}}
        OP2["file.read_to_string()"]
        CHECK2{{"Result check<br/>检查 Result"}}
        SUCCESS["Ok(contents)"]
        ERROR1["Err(io::Error)"]
        ERROR2["Err(io::Error)"]
        
        START --> OP1
        OP1 --> CHECK1
        CHECK1 -->|"Ok(file)"| OP2
        CHECK1 -->|"Err(e)"| ERROR1
        OP2 --> CHECK2
        CHECK2 -->|"Ok(())"| SUCCESS
        CHECK2 -->|"Err(e)"| ERROR2
        
        ERROR1 --> PROPAGATE["? operator<br/>传播错误"]
        ERROR2 --> PROPAGATE
        PROPAGATE --> CALLER["Caller must handle error<br/>调用方继续处理"]
    end
    
    subgraph "Pattern Matching Options<br/>几种处理写法"
        MATCH["match result"]
        IFLET["if let Ok(val) = result"]
        UNWRAP["result.unwrap()<br/>[WARNING] Panics on error"]
        EXPECT["result.expect(msg)<br/>[WARNING] Panics with message"]
        UNWRAP_OR["result.unwrap_or(default)<br/>[OK] Safe fallback"]
        QUESTION["result?<br/>[OK] Early return"]
        
        MATCH --> SAFE1["[OK] Handles both cases<br/>把两边都处理掉"]
        IFLET --> SAFE2["[OK] Handy for the success path<br/>成功路径写起来更短"]
        UNWRAP_OR --> SAFE3["[OK] Always returns a value<br/>总能拿到一个值"]
        QUESTION --> SAFE4["[OK] Propagates to caller<br/>把错误继续往上交"]
        UNWRAP --> UNSAFE1["[ERROR] Can panic<br/>可能 panic"]
        EXPECT --> UNSAFE2["[ERROR] Can panic<br/>可能 panic"]
    end
    
    style SUCCESS fill:#91e5a3,color:#000
    style ERROR1 fill:#ffa07a,color:#000
    style ERROR2 fill:#ffa07a,color:#000
    style SAFE1 fill:#91e5a3,color:#000
    style SAFE2 fill:#91e5a3,color:#000
    style SAFE3 fill:#91e5a3,color:#000
    style SAFE4 fill:#91e5a3,color:#000
    style UNSAFE1 fill:#ff6b6b,color:#000
    style UNSAFE2 fill:#ff6b6b,color:#000

Recoverable errors with Result<T, E>
用 Result<T, E> 处理可恢复错误

• Rust 用 Result<T, E> 表达可恢复错误。
  成功时是 Ok<T>，失败时是 Err<E>，没有第三种神秘通道。
• Ok<T> 里装成功结果，Err<E> 里装错误。
  调用方看到返回类型时，就已经知道这一步可能失败。

fn main() {
    let x = "1234x".parse::<u32>();
    match x {
        Ok(x) => println!("Parsed number {x}"),
        Err(e) => println!("Parsing error {e:?}"),
    }
    let x  = "1234".parse::<u32>();
    // Same as above, but with valid number
    if let Ok(x) = &x {
        println!("Parsed number {x}")
    } else if let Err(e) = &x {
        println!("Error: {e:?}");
    }
}

The ? operator
? 运算符

• ? 是 match Ok / Err 模式的一种简写。
  它做的事情很单纯：成功就把内部值拿出来，失败就立刻返回。
• 要使用 ?，当前函数本身也得返回 Result<T, E> 或兼容的类型。
  否则错误没地方往外传，编译器也就不会放行。
• Result<T, E> 里的错误类型是可以转换的。下面这个例子里，函数直接沿用 str::parse() 的错误类型 std::num::ParseIntError。
  这也是 Rust 错误处理能层层组合起来的关键原因。

fn double_string_number(s : &str) -> Result<u32, std::num::ParseIntError> {
   let x = s.parse::<u32>()?; // Returns immediately in case of an error
   Ok(x*2)
}
fn main() {
    let result = double_string_number("1234");
    println!("{result:?}");
    let result = double_string_number("1234x");
    println!("{result:?}");
}

Mapping errors and defaults
错误映射与默认值处理

• Errors can be mapped into different types, or turned into default values when that is the right business decision.
  错误既可以转换成别的类型，也可以在合适的时候退化成默认值，这取决于业务语义，而不是语法限制。
• map_err() is useful when the outer API wants a different error type.
  如果外层接口想统一错误类型，map_err() 就很好使。
• unwrap_or_default() is useful when the type has a sensible default and swallowing the error is acceptable.
  如果类型本身有合理默认值，而且吞掉错误在语义上说得过去，可以考虑 unwrap_or_default()。

#![allow(unused)]
fn main() {
// Changes the error type to () in case of error
fn double_string_number(s : &str) -> Result<u32, ()> {
   let x = s.parse::<u32>().map_err(|_|())?; // Returns immediately in case of an error
   Ok(x*2)
}
}

#![allow(unused)]
fn main() {
fn double_string_number(s : &str) -> Result<u32, ()> {
   let x = s.parse::<u32>().unwrap_or_default(); // Defaults to 0 in case of parse error
   Ok(x*2)
}
}

#![allow(unused)]
fn main() {
fn double_optional_number(x : Option<u32>) -> Result<u32, ()> {
    // ok_or converts Option<None> to Result<u32, ()> in the below
    x.ok_or(()).map(|x|x*2) // .map() is applied only on Ok(u32)
}
}

Exercise: error handling
练习：错误处理

🟡 Intermediate
🟡 进阶练习

• Implement a log() function with a single u32 parameter. If the parameter is not 42, return an error. The success and error types should both be ().
  实现一个 log() 函数，参数只有一个 u32。如果这个参数不是 42，就返回错误。成功和错误类型都写成 ()。
• Write a call_log() function that calls log() and exits early with the same Result type if log() returns an error. Otherwise print a success message.
  再写一个 call_log()，调用 log()。如果 log() 返回错误，就用同样的 Result 提前退出；如果成功，再打印一条说明信息。

fn log(x: u32) -> ?? {

}

fn call_log(x: u32) -> ?? {
    // Call log(x), then exit immediately if it return an error
    println!("log was successfully called");
}

fn main() {
    call_log(42);
    call_log(43);
}

fn log(x: u32) -> Result<(), ()> {
    if x == 42 {
        Ok(())
    } else {
        Err(())
    }
}

fn call_log(x: u32) -> Result<(), ()> {
    log(x)?;  // Exit immediately if log() returns an error
    println!("log was successfully called with {x}");
    Ok(())
}

fn main() {
    let _ = call_log(42);  // Prints: log was successfully called with 42
    let _ = call_log(43);  // Returns Err(()), nothing printed
}
// Output:
// log was successfully called with 42

Rust Option and Result key takeaways
Rust 里 Option 与 Result 的关键结论

What you’ll learn: Idiomatic error handling patterns — safe alternatives to unwrap(), the ? operator for propagation, custom error types, and when to use anyhow vs thiserror in production code.
本章将学到什么： 惯用的错误处理模式，unwrap() 的安全替代方案，? 的错误传播方式，自定义错误类型的设计，以及生产代码里什么时候该用 anyhow、什么时候该用 thiserror。

• Option and Result are an integral part of idiomatic Rust.
  Option 和 Result 是 Rust 惯用写法的核心组成部分。
• Safe alternatives to unwrap():
  unwrap() 的安全替代方案：

#![allow(unused)]
fn main() {
// Option<T> safe alternatives
// Option<T> 的安全替代写法
let value = opt.unwrap_or(default);               // Provide fallback value
let value = opt.unwrap_or_else(|| compute());     // Lazy computation for fallback
let value = opt.unwrap_or_default();              // Use Default trait implementation
let value = opt.expect("descriptive message");    // Only when panic is acceptable

// Result<T, E> safe alternatives
// Result<T, E> 的安全替代写法
let value = result.unwrap_or(fallback);           // Ignore error, use fallback
let value = result.unwrap_or_else(|e| handle(e)); // Handle error, return fallback
let value = result.unwrap_or_default();           // Use Default trait
}

• Pattern matching for explicit control:
  需要显式控制时，用模式匹配：

#![allow(unused)]
fn main() {
match some_option {
    Some(value) => println!("Got: {}", value),
    None => println!("No value found"),
}

match some_result {
    Ok(value) => process(value),
    Err(error) => log_error(error),
}
}

• Use ? operator for error propagation: Short-circuit and bubble up errors.
  用 ? 传播错误：遇到错误立刻短路，并把错误往上返回。

#![allow(unused)]
fn main() {
fn process_file(path: &str) -> Result<String, std::io::Error> {
    let content = std::fs::read_to_string(path)?; // Automatically returns error
    Ok(content.to_uppercase())
}
}

• Transformation methods:
  常见变换方法：
  • map(): Transform the success value Ok(T) -> Ok(U) or Some(T) -> Some(U)
map()：变换成功值，把 Ok(T) 变成 Ok(U)，或者把 Some(T) 变成 Some(U)。
  • map_err(): Transform the error type Err(E) -> Err(F)
map_err()：变换错误类型，把 Err(E) 变成 Err(F)。
  • and_then(): Chain operations that can fail
    and_then()：把一串可能失败的操作接起来。
• Use in your own APIs: Prefer Result<T, E> over exceptions or error codes.
  写自己的 API 时，优先返回 Result<T, E>，别把异常和错误码那套老习惯又拖回来。
• References: Option docs | Result docs
  参考资料： Option 文档 | Result 文档

Rust Common Pitfalls and Debugging Tips
Rust 常见误区与排查提示

• Borrowing issues: Most common beginner mistake.
  借用问题：这是新手最常踩的一类错误。
  • "cannot borrow as mutable" -> Only one mutable reference allowed at a time
    "cannot borrow as mutable"：同一时间只允许存在一个可变引用。
  • "borrowed value does not live long enough" -> Reference outlives the data it points to
    "borrowed value does not live long enough"：引用活得比它指向的数据还久。
  • Fix: Use scopes {} to limit reference lifetimes, or clone data when needed.
    处理方式： 用 {} 缩短引用作用域，或者在确实有必要时复制数据。
• Missing trait implementations: "method not found" errors.
  缺少 trait 实现：经常会炸出 "method not found" 这种报错。
  • Fix: Add #[derive(Debug, Clone, PartialEq)] for common traits.
    处理方式： 常用 trait 可以先补上 #[derive(Debug, Clone, PartialEq)]。
  • Use cargo check to get better error messages than cargo run.
    cargo check 给出的错误通常比 cargo run 更聚焦。
• Integer overflow in debug mode: Rust panics on overflow.
  调试模式下整数溢出：Rust 遇到溢出会直接 panic。
  • Fix: Use wrapping_add(), saturating_add(), or checked_add() for explicit behavior.
    处理方式： 用 wrapping_add()、saturating_add() 或 checked_add() 明确指定溢出语义。
• String vs &str confusion: Different types for different use cases.
  String 和 &str 容易搞混：两者本来就是给不同场景准备的。
  • Use &str for string slices (borrowed), String for owned strings.
    &str 适合借用的字符串切片，String 适合拥有所有权的字符串。
  • Fix: Use .to_string() or String::from() to convert &str to String.
    处理方式： 用 .to_string() 或 String::from() 把 &str 转成 String。
• Fighting the borrow checker: Stop trying to outsmart it.
  跟借用检查器对着干：这事十有八九干不过，别硬拧。
  • Fix: Restructure code to work with ownership rules rather than against them.
    处理方式： 调整代码结构，让它顺着所有权规则走。
  • Consider using Rc<RefCell<T>> for complex sharing scenarios, but use it sparingly.
    特别复杂的共享场景可以考虑 Rc<RefCell<T>>，但用多了代码就容易发黏。

Error Handling Examples: Good vs Bad
错误处理示例：好写法与坏写法

#![allow(unused)]
fn main() {
// [ERROR] BAD: Can panic unexpectedly
// [ERROR] 坏写法：随时可能猝不及防地 panic
fn bad_config_reader() -> String {
    let config = std::env::var("CONFIG_FILE").unwrap(); // Panic if not set!
    std::fs::read_to_string(config).unwrap()           // Panic if file missing!
}

// [OK] GOOD: Handles errors gracefully
// [OK] 好写法：对错误做了正常处理
fn good_config_reader() -> Result<String, ConfigError> {
    let config_path = std::env::var("CONFIG_FILE")
        .unwrap_or_else(|_| "default.conf".to_string()); // Fallback to default
    
    let content = std::fs::read_to_string(config_path)
        .map_err(ConfigError::FileRead)?;                // Convert and propagate error
    
    Ok(content)
}

// [OK] EVEN BETTER: With proper error types
// [OK] 更进一步：定义清楚的错误类型
use thiserror::Error;

#[derive(Error, Debug)]
enum ConfigError {
    #[error("Failed to read config file: {0}")]
    FileRead(#[from] std::io::Error),
    
    #[error("Invalid configuration: {message}")]
    Invalid { message: String },
}
}

Let’s break down what’s happening here. ConfigError has just two variants — one for I/O errors and one for validation errors. This is the right starting point for most modules:
拆开看一下这里的意思。ConfigError 只有 两个变体，一个表示 I/O 错误，一个表示校验错误。对大多数模块来说，这样的起步规模就够用了。

Now you can write functions that return Result<T, ConfigError>:
这样后面的函数就可以统一返回 Result<T, ConfigError>：

#![allow(unused)]
fn main() {
fn read_config(path: &str) -> Result<String, ConfigError> {
    let content = std::fs::read_to_string(path)?;  // io::Error → ConfigError::FileRead
    if content.is_empty() {
        return Err(ConfigError::Invalid {
            message: "config file is empty".to_string(),
        });
    }
    Ok(content)
}
}

🟢 Self-study checkpoint: Before continuing, make sure you can answer:
🟢 自测检查点： 继续往下之前，先确认下面两个问题能答上来：

1. Why does ? on the read_to_string call work? (Because #[from] generates impl From<io::Error> for ConfigError.)
   1. 为什么 read_to_string 后面的 ? 能直接工作？因为 #[from] 会生成 impl From<io::Error> for ConfigError。
2. What happens if you add a third variant MissingKey(String) — what code changes? (Usually just add the variant; existing code still compiles.)
   2. 如果再加一个 MissingKey(String) 变体，需要改什么？通常只要把变体加上，已有代码还是能继续编译。

Crate-Level Error Types and Result Aliases
crate 级错误类型与 Result 别名

As the project grows beyond a single file, multiple module-level errors usually need to be merged into a crate-level error type. This is the standard production pattern in Rust.
项目一旦超过单文件玩具规模，就会出现多个模块各自报错的情况。这时通常要把它们并进一个 crate 级错误类型 里，这就是生产代码里最常见的写法。

In real-world Rust projects, every crate or major module often defines its own Error enum and a Result type alias. This is idiomatic Rust, and in spirit it resembles defining a per-library exception hierarchy plus using Result = std::expected<T, Error> in modern C++.
现实里的 Rust 项目通常会给每个 crate，或者至少每个重要模块，定义自己的 Error 枚举，再顺手配一个 Result 类型别名。这就是惯用法。类比到现代 C++，差不多就是给每个库准备一套异常层级，再写一个 using Result = std::expected<T, Error>。

The pattern
基本模式

#![allow(unused)]
fn main() {
// src/error.rs  (or at the top of lib.rs)
use thiserror::Error;

/// Every error this crate can produce.
#[derive(Error, Debug)]
pub enum Error {
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),          // auto-converts via From

    #[error("JSON parse error: {0}")]
    Json(#[from] serde_json::Error),     // auto-converts via From

    #[error("Invalid sensor id: {0}")]
    InvalidSensor(u32),                  // domain-specific variant

    #[error("Timeout after {ms} ms")]
    Timeout { ms: u64 },
}

/// Crate-wide Result alias — saves typing throughout the crate.
pub type Result<T> = core::result::Result<T, Error>;
}

How it simplifies every function
它如何让每个函数都清爽很多

Without the alias, every signature needs to repeat the full error type:
没有别名时，每个函数签名都得重复一遍完整错误类型：

#![allow(unused)]
fn main() {
// Verbose — error type repeated everywhere
fn read_sensor(id: u32) -> Result<f64, crate::Error> { ... }
fn parse_config(path: &str) -> Result<Config, crate::Error> { ... }
}

With the alias, the signatures become much cleaner:
有了别名以后，签名立刻干净一大截：

#![allow(unused)]
fn main() {
// Clean — just `Result<T>`
use crate::{Error, Result};

fn read_sensor(id: u32) -> Result<f64> {
    if id > 128 {
        return Err(Error::InvalidSensor(id));
    }
    let raw = std::fs::read_to_string(format!("/dev/sensor/{id}"))?; // io::Error → Error::Io
    let value: f64 = raw.trim().parse()
        .map_err(|_| Error::InvalidSensor(id))?;
    Ok(value)
}
}

The #[from] attribute on Io generates the following impl automatically:
Io 变体上的 #[from] 会自动生成下面这样的 impl：

#![allow(unused)]
fn main() {
// Auto-generated by thiserror's #[from]
impl From<std::io::Error> for Error {
    fn from(source: std::io::Error) -> Self {
        Error::Io(source)
    }
}
}

That is why ? works. When the inner call returns std::io::Error but the outer function returns Result<T> using the alias, the compiler inserts From::from() and converts the error automatically.
这就是 ? 能工作的根本原因。内层返回 std::io::Error，外层函数返回的是别名 Result<T>，编译器会在中间自动插入 From::from() 完成转换。

Composing module-level errors
把模块级错误拼成 crate 级错误

Larger crates often define errors per module and compose them at the crate root:
规模再大一点的 crate，通常会让每个模块先定义自己的错误，然后在 crate 根部统一汇总：

#![allow(unused)]
fn main() {
// src/config/error.rs
#[derive(thiserror::Error, Debug)]
pub enum ConfigError {
    #[error("Missing key: {0}")]
    MissingKey(String),
    #[error("Invalid value for '{key}': {reason}")]
    InvalidValue { key: String, reason: String },
}

// src/error.rs  (crate-level)
#[derive(thiserror::Error, Debug)]
pub enum Error {
    #[error(transparent)]               // delegates Display to inner error
    Config(#[from] crate::config::ConfigError),

    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),
}
pub type Result<T> = core::result::Result<T, Error>;
}

Callers can still match on specific configuration errors:
即便统一到了 crate 级错误，调用者依然可以继续匹配具体的配置错误：

#![allow(unused)]
fn main() {
match result {
    Err(Error::Config(ConfigError::MissingKey(k))) => eprintln!("Add '{k}' to config"),
    Err(e) => eprintln!("Other error: {e}"),
    Ok(v) => use_value(v),
}
}

C++ comparison
和 C++ 的对照

Rust traits
Rust 的 trait

What you’ll learn: Traits are Rust’s answer to interfaces, abstract base classes, and operator overloading. This chapter covers how to define traits, implement them for concrete types, and choose between static dispatch and dynamic dispatch. For C++ developers, traits overlap with virtual functions, CRTP, and concepts. For C developers, traits are Rust’s structured form of polymorphism.
本章将学到什么： trait 是 Rust 用来表达接口、抽象行为和运算符重载的核心机制。本章会讲 trait 怎么定义、怎么给类型实现，以及静态分发和动态分发该怎么选。对 C++ 开发者来说，它和虚函数、CRTP、concepts 都有交集；对 C 开发者来说，它就是 Rust 组织多态能力的正规方式。

• Rust traits are conceptually similar to interfaces in other languages.
  trait 的核心作用，就是先把“某种能力长什么样”定义出来。
  • A trait declares methods that implementing types must provide.
    实现这个 trait 的类型，就得把这些方法补上。

fn main() {
    trait Pet {
        fn speak(&self);
    }
    struct Cat;
    struct Dog;
    impl Pet for Cat {
        fn speak(&self) {
            println!("Meow");
        }
    }
    impl Pet for Dog {
        fn speak(&self) {
            println!("Woof!")
        }
    }
    let c = Cat{};
    let d = Dog{};
    c.speak();  // There is no "is a" relationship between Cat and Dog
    d.speak(); // There is no "is a" relationship between Cat and Dog
}

Traits vs C++ Concepts and Interfaces
trait、C++ concepts 和接口的关系

Traditional C++ Inheritance vs Rust Traits
传统 C++ 继承与 Rust trait 的对比

// C++ - Inheritance-based polymorphism
class Animal {
public:
    virtual void speak() = 0;  // Pure virtual function
    virtual ~Animal() = default;
};

class Cat : public Animal {  // "Cat IS-A Animal"
public:
    void speak() override {
        std::cout << "Meow" << std::endl;
    }
};

void make_sound(Animal* animal) {  // Runtime polymorphism
    animal->speak();  // Virtual function call
}

#![allow(unused)]
fn main() {
// Rust - Composition over inheritance with traits
trait Animal {
    fn speak(&self);
}

struct Cat;  // Cat is NOT an Animal, but IMPLEMENTS Animal behavior

impl Animal for Cat {  // "Cat CAN-DO Animal behavior"
    fn speak(&self) {
        println!("Meow");
    }
}

fn make_sound<T: Animal>(animal: &T) {  // Static polymorphism
    animal.speak();  // Direct function call (zero cost)
}
}

graph TD
    subgraph "C++ Object-Oriented Hierarchy<br/>C++ 面向对象继承层次"
        CPP_ANIMAL["Animal<br/>(Abstract base class)<br/>抽象基类"]
        CPP_CAT["Cat : public Animal<br/>(IS-A relationship)<br/>继承关系"]
        CPP_DOG["Dog : public Animal<br/>(IS-A relationship)<br/>继承关系"]
        
        CPP_ANIMAL --> CPP_CAT
        CPP_ANIMAL --> CPP_DOG
        
        CPP_VTABLE["Virtual function table<br/>运行时分发"]
        CPP_HEAP["Often requires<br/>heap allocation<br/>经常伴随堆分配"]
        CPP_ISSUES["[ERROR] Deep inheritance trees<br/>继承树容易越长越深<br/>[ERROR] Diamond problem<br/>菱形继承麻烦<br/>[ERROR] Runtime overhead<br/>运行时开销<br/>[ERROR] Tight coupling<br/>耦合偏重"]
    end
    
    subgraph "Rust Trait-Based Composition<br/>Rust 基于 trait 的组合"
        RUST_TRAIT["trait Animal<br/>(Behavior definition)<br/>行为定义"]
        RUST_CAT["struct Cat<br/>(Data only)<br/>数据类型"]
        RUST_DOG["struct Dog<br/>(Data only)<br/>数据类型"]
        
        RUST_CAT -.->|"impl Animal for Cat<br/>(CAN-DO behavior)<br/>实现某种能力"| RUST_TRAIT
        RUST_DOG -.->|"impl Animal for Dog<br/>(CAN-DO behavior)<br/>实现某种能力"| RUST_TRAIT
        
        RUST_STATIC["Static dispatch<br/>编译期分发"]
        RUST_STACK["Stack allocation<br/>possible<br/>通常可以栈分配"]
        RUST_BENEFITS["[OK] No inheritance hierarchy<br/>没有继承树负担<br/>[OK] Multiple trait impls<br/>一个类型可实现多个 trait<br/>[OK] Zero runtime cost<br/>静态分发零额外成本<br/>[OK] Loose coupling<br/>耦合更松"]
    end
    
    style CPP_ISSUES fill:#ff6b6b,color:#000
    style RUST_BENEFITS fill:#91e5a3,color:#000
    style CPP_VTABLE fill:#ffa07a,color:#000
    style RUST_STATIC fill:#91e5a3,color:#000

Rust 没有“类型必须继承自某个基类”这套默认思路。类型本身只关心数据和结构，行为能力再通过 trait 附着上去。
这也是为什么 Rust 更像“组合能力”，而不是“塞进继承树”。

Trait bounds and generic constraints
trait bound 与泛型约束

#![allow(unused)]
fn main() {
use std::fmt::Display;
use std::ops::Add;

// C++ template equivalent (less constrained)
// template<typename T>
// T add_and_print(T a, T b) {
//     // No guarantee T supports + or printing
//     return a + b;  // Might fail at compile time
// }

// Rust - explicit trait bounds
fn add_and_print<T>(a: T, b: T) -> T 
where 
    T: Display + Add<Output = T> + Copy,
{
    println!("Adding {} + {}", a, b);  // Display trait
    a + b  // Add trait
}
}

graph TD
    subgraph "Generic Constraints Evolution<br/>泛型约束逐步收紧"
        UNCONSTRAINED["fn process&lt;T&gt;(data: T)<br/>[ERROR] T can be anything<br/>类型完全不受约束"]
        SINGLE_BOUND["fn process&lt;T: Display&gt;(data: T)<br/>[OK] T must implement Display<br/>至少要求能打印"]
        MULTI_BOUND["fn process&lt;T&gt;(data: T)<br/>where T: Display + Clone + Debug<br/>[OK] Multiple requirements<br/>多个能力一起约束"]
        
        UNCONSTRAINED --> SINGLE_BOUND
        SINGLE_BOUND --> MULTI_BOUND
    end
    
    subgraph "Trait Bound Syntax<br/>约束写法"
        INLINE["fn func&lt;T: Trait&gt;(param: T)"]
        WHERE_CLAUSE["fn func&lt;T&gt;(param: T)<br/>where T: Trait"]
        IMPL_PARAM["fn func(param: impl Trait)"]
        
        COMPARISON["Inline: simple cases<br/>Where: complex bounds<br/>impl: concise syntax<br/>各有适用场景"]
    end
    
    subgraph "Compile-time Magic<br/>编译期发生的事"
        GENERIC_FUNC["Generic function<br/>generic + bounds"]
        TYPE_CHECK["Compiler verifies<br/>trait implementations<br/>检查能力是否满足"]
        MONOMORPH["Monomorphization<br/>单态化生成专用版本"]
        OPTIMIZED["Fully optimized<br/>machine code<br/>最后还是具体机器码"]
        
        GENERIC_FUNC --> TYPE_CHECK
        TYPE_CHECK --> MONOMORPH
        MONOMORPH --> OPTIMIZED
        
        EXAMPLE["add_and_print::<i32><br/>add_and_print::<f64><br/>不同类型各自生成版本"]
        MONOMORPH --> EXAMPLE
    end
    
    style UNCONSTRAINED fill:#ff6b6b,color:#000
    style SINGLE_BOUND fill:#ffa07a,color:#000
    style MULTI_BOUND fill:#91e5a3,color:#000
    style OPTIMIZED fill:#91e5a3,color:#000

这里最关键的一点是：Rust 不喜欢“先假设你什么都能做，等编译炸了再说”。trait bound 把能力要求写进签名里，函数能接什么类型一眼就看出来。
对大型代码库来说，这种显式约束会省掉很多猜谜时间。

C++ operator overloading → Rust std::ops traits
C++ 运算符重载在 Rust 里的对应物

在 C++ 里，运算符重载是通过带特殊名字的成员函数或自由函数完成的。Rust 则把每个运算符都映射成了一个 trait。
不是写 operator+ 这种魔法名字，而是实现某个标准 trait。

Side-by-side: + operator
并排看 + 运算符

// C++: operator overloading as a member or free function
struct Vec2 {
    double x, y;
    Vec2 operator+(const Vec2& rhs) const {
        return {x + rhs.x, y + rhs.y};
    }
};

Vec2 a{1.0, 2.0}, b{3.0, 4.0};
Vec2 c = a + b;  // calls a.operator+(b)

#![allow(unused)]
fn main() {
use std::ops::Add;

#[derive(Debug, Clone, Copy)]
struct Vec2 { x: f64, y: f64 }

impl Add for Vec2 {
    type Output = Vec2;                     // Associated type — the result of +
    fn add(self, rhs: Vec2) -> Vec2 {
        Vec2 { x: self.x + rhs.x, y: self.y + rhs.y }
    }
}

let a = Vec2 { x: 1.0, y: 2.0 };
let b = Vec2 { x: 3.0, y: 4.0 };
let c = a + b;  // calls <Vec2 as Add>::add(a, b)
println!("{c:?}"); // Vec2 { x: 4.0, y: 6.0 }
}

Key differences from C++
和 C++ 相比的关键差异

The self by-value gotcha
self 按值接收这个坑点

Rust 的 Add::add(self, rhs) 默认会按值拿走 self。对 Copy 类型来说无所谓，因为编译器会自动复制。但对非 Copy 类型，这就意味着 + 可能把左操作数消耗掉。
这一点和 C++ 里“加法通常返回新对象，原对象还在”很不一样。

#![allow(unused)]
fn main() {
let s1 = String::from("hello ");
let s2 = String::from("world");
let s3 = s1 + &s2;  // s1 is MOVED into s3!
// println!("{s1}");  // ❌ Compile error: value used after move
println!("{s2}");     // ✅ s2 was only borrowed (&s2)
}

这就是为什么 String + &str 可行，而 &str + &str 不行。String 这边的实现会消费左值，重用它已有的缓冲区。
这和 C++ std::string::operator+ 的直觉差别挺大，第一次见容易发懵。

Full mapping: C++ operators → Rust traits
C++ 运算符与 Rust trait 的完整对照

Guardrails: what Rust refuses to let you overload
Rust 故意不让重载的那些危险东西

1. No implicit conversions.
   没有隐式类型转换运算符。想转就显式 .into() 或调用 From。
2. No overloading && and ||.
   短路逻辑运算符不给碰，省得把控制流语义玩坏。
3. No overloading assignment itself.
   赋值永远是 move 或 copy，不允许自定义一套怪逻辑。
4. No overloading comma.
   C++ 这个老坑，Rust 干脆整个封死。
5. No overloading address-of.
   & 永远就是借用，不会突然搞出别的花活。
6. Coherence rules limit who can implement what.
   trait 和类型的组合实现受一致性规则约束，避免不同 crate 相互打架。

Bottom line: C++ 的运算符重载很强，但自由度大到容易闹幺蛾子。Rust 保留了足够的表达力，却把历史上最危险的那一批重载口子堵上了。
这样一来，算术和比较照样能写得优雅，语言本身却没那么容易被玩成谜语。

Implementing your own traits on types
给类型实现自定义 trait

• Rust allows implementing a user-defined trait even for built-in types like u32, as long as either the trait or the type belongs to the current crate.
  这就是所谓的孤儿规则边界：trait 和类型至少得有一个是自家的。

trait IsSecret {
  fn is_secret(&self);
}
// The IsSecret trait belongs to the crate, so we are OK
impl IsSecret for u32 {
  fn is_secret(&self) {
      if *self == 42 {
          println!("Is secret of life");
      }
  }
}

fn main() {
  42u32.is_secret();
  43u32.is_secret();
}

这个规则的目的很简单：防止两个外部 crate 同时给“外部 trait + 外部类型”写实现，然后把整个生态搅成一锅粥。
限制虽硬，但换来的是全局一致性。

Supertraits and default implementations
supertrait 与默认实现

• Traits can inherit requirements from other traits and can also provide default method implementations.
  也就是说，trait 不仅能要求“先满足某种能力”，还可以自带一部分通用实现。

trait Animal {
  // Default implementation
  fn is_mammal(&self) -> bool {
    true
  }
}
trait Feline : Animal {
  // Default implementation
  fn is_feline(&self) -> bool {
    true
  }
}

struct Cat;
// Use default implementations. Note that all traits for the supertrait must be individually implemented
impl Feline for Cat {}
impl Animal for Cat {}
fn main() {
  let c = Cat{};
  println!("{} {}", c.is_mammal(), c.is_feline());
}

这里 Feline: Animal 的意思是：想实现 Feline，先得满足 Animal。默认实现则适合写那些“大多数类型都一样”的基础行为。
需要特化时，再由具体类型覆写即可。

Exercise: Logger trait implementation
练习：实现一个 Logger trait

🟡 Intermediate
🟡 进阶练习

• Implement a Log trait with one method log() that accepts a u64.
  实现一个 Log trait，里面只有一个方法 log()，参数是 u64。
• Create two loggers, SimpleLogger and ComplexLogger，都实现这个 trait。前者打印 "Simple logger" 和数值，后者打印 "Complex logger" 以及更详细的格式化信息。
  这道题的重点不是输出花样，而是体会“同一接口，不同实现”的结构。

trait Log {
    fn log(&self, value: u64);
}

struct SimpleLogger;
struct ComplexLogger;

impl Log for SimpleLogger {
    fn log(&self, value: u64) {
        println!("Simple logger: {value}");
    }
}

impl Log for ComplexLogger {
    fn log(&self, value: u64) {
        println!("Complex logger: {value} (hex: 0x{value:x}, binary: {value:b})");
    }
}

fn main() {
    let simple = SimpleLogger;
    let complex = ComplexLogger;
    simple.log(42);
    complex.log(42);
}
// Output:
// Simple logger: 42
// Complex logger: 42 (hex: 0x2a, binary: 101010)

Trait associated types
trait 的关联类型

#[derive(Debug)]
struct Small(u32);
#[derive(Debug)]
struct Big(u32);
trait Double {
    type T;
    fn double(&self) -> Self::T;
}

impl Double for Small {
    type T = Big;
    fn double(&self) -> Self::T {
        Big(self.0 * 2)
    }
}
fn main() {
    let a = Small(42);
    println!("{:?}", a.double());
}

关联类型的作用，是把“这个 trait 的某个相关类型由实现者决定”这件事写进接口本身。
和泛型参数相比，它更适合表达“同一实现里固定绑定的一种返回类型或辅助类型”。

impl Trait in parameters
参数位置里的 impl Trait

• impl can be used with trait bounds to accept any type implementing a trait, while keeping the signature concise.
  语义上它还是泛型，只是写法更顺手。

trait Pet {
    fn speak(&self);
}
struct Dog {}
struct Cat {}
impl Pet for Dog {
    fn speak(&self) {println!("Woof!")}
}
impl Pet for Cat {
    fn speak(&self) {println!("Meow")}
}
fn pet_speak(p: &impl Pet) {
    p.speak();
}
fn main() {
    let c = Cat {};
    let d = Dog {};
    pet_speak(&c);
    pet_speak(&d);
}

impl Trait in return position
返回值位置里的 impl Trait

• impl Trait can also be used for return values, hiding the concrete type from the caller while still using static dispatch.
  调用方知道“返回的是某种实现了这个 trait 的类型”，但不需要知道它到底叫啥。

trait Pet {}
struct Dog;
struct Cat;
impl Pet for Cat {}
impl Pet for Dog {}
fn cat_as_pet() -> impl Pet {
    let c = Cat {};
    c
}
fn dog_as_pet() -> impl Pet {
    let d = Dog {};
    d
}
fn main() {
    let p = cat_as_pet();
    let d = dog_as_pet();
}

这里要注意一点：同一个返回位置的 impl Trait 仍然只能对应一个具体类型，不能今天返回 Cat、明天返回 Dog。
真想在同一个函数里返回多种具体类型，就得考虑 dyn Trait 或 enum。

Dynamic traits
动态 trait 对象

• Dynamic dispatch allows code to call trait methods without knowing the concrete underlying type at compile time. This is the familiar “type erasure” pattern.
  说白了，就是把具体类型藏在一个 trait 对象后面，运行时再通过 vtable 找到对应实现。

trait Pet {
    fn speak(&self);
}
struct Dog {}
struct Cat {x: u32}
impl Pet for Dog {
    fn speak(&self) {println!("Woof!")}
}
impl Pet for Cat {
    fn speak(&self) {println!("Meow")}
}
fn pet_speak(p: &dyn Pet) {
    p.speak();
}
fn main() {
    let c = Cat {x: 42};
    let d = Dog {};
    pet_speak(&c);
    pet_speak(&d);
}

和泛型不同，这里不会为每个具体类型单独生成一份代码。代价是每次调用多一层动态分发。
多数情况下开销很小，但如果在极高频热点路径里，还是值得心里有数。

Choosing between impl Trait, dyn Trait, and enums
impl Trait、dyn Trait 和 enum 到底怎么选

这三种写法都能表达“多态”，但适用场景并不一样。
选错了也不至于立刻出事故，但代码会别扭，性能和可维护性也会跟着受影响。

#![allow(unused)]
fn main() {
trait Shape {
    fn area(&self) -> f64;
}
struct Circle { radius: f64 }
struct Rect { w: f64, h: f64 }
impl Shape for Circle { fn area(&self) -> f64 { std::f64::consts::PI * self.radius * self.radius } }
impl Shape for Rect   { fn area(&self) -> f64 { self.w * self.h } }

// Static dispatch — compiler generates separate code for each type
fn print_area(s: &impl Shape) { println!("{}", s.area()); }

// Dynamic dispatch — one function, works with any Shape behind a pointer
fn print_area_dyn(s: &dyn Shape) { println!("{}", s.area()); }

// Enum — closed set, no trait needed
enum ShapeEnum { Circle(f64), Rect(f64, f64) }
impl ShapeEnum {
    fn area(&self) -> f64 {
        match self {
            ShapeEnum::Circle(r) => std::f64::consts::PI * r * r,
            ShapeEnum::Rect(w, h) => w * h,
        }
    }
}
}

For C++ developers: impl Trait is closest to templates, dyn Trait is closest to virtual dispatch, and enum + match is the Rust-flavored counterpart to std::variant + std::visit。
给 C++ 开发者的速记： impl Trait 像模板，dyn Trait 像虚函数表，enum + match 则像更受编译器强约束的 variant 方案。

Rule of thumb: Start with impl Trait. Reach for dyn Trait when the concrete type truly cannot be known ahead of time or when mixed collections are required. Use enum when the full set of variants is closed and controlled by the current crate.
经验法则： 默认先从 impl Trait 开始。确实要做运行时多态、或者集合里要混装多种实现时，再考虑 dyn Trait。如果所有变体都掌握在当前 crate 手里，那 enum 往往更直接。

Rust generics
Rust 泛型

What you’ll learn: Generic type parameters, monomorphization (zero-cost generics), trait bounds, and how Rust generics compare to C++ templates — with better error messages and no SFINAE.
本章将学到什么： 泛型类型参数是什么，单态化也就是零成本泛型怎么工作，trait bound 如何约束泛型，以及 Rust 泛型和 C++ 模板相比到底强在哪，尤其是错误信息和可读性这一块。

• Generics allow the same algorithm or data structure to be reused across data types
  泛型允许同一套算法或数据结构在不同数据类型上复用。
  • The generic parameter appears as an identifier within <>, e.g.: <T>. The parameter can have any legal identifier name, but is typically kept short for brevity
    泛型参数会写在 <> 里，例如 <T>。理论上名字可以随便起，只要是合法标识符；不过惯例上会保持简短。
  • The compiler performs monomorphization at compile time, i.e., it generates a new type for every variation of T that is encountered
    编译器会在编译期做单态化，也就是针对每一种实际出现的 T 都生成对应版本的实现。

// Returns a tuple of type <T> composed of left and right of type <T>
fn pick<T>(x: u32, left: T, right: T) -> (T, T) {
   if x == 42 {
    (left, right) 
   } else {
    (right, left)
   }
}
fn main() {
    let a = pick(42, true, false);
    let b = pick(42, "hello", "world");
    println!("{a:?}, {b:?}");
}

对 C++ 开发者来说，这里最容易类比的是模板。但 Rust 泛型和模板虽然神似，脾气可差不少。Rust 会更明确地告诉“这里需要什么能力”，也更少出现那种模板炸开之后报错像天书的场面。
单态化带来的结果则类似：最终生成的代码是具体类型版本，不是运行时再绕一层动态分发，所以依然能保持零成本抽象。

Generics on data types and methods
把泛型用在数据类型和方法上

• Generics can also be applied to data types and associated methods. It is possible to specialize the implementation for a specific <T> (example: f32 vs. u32)
  泛型不只用在函数上，也能用在数据类型和关联方法上。必要时还可以为某个特定类型参数单独写专门实现，例如 f32 和 u32 走不同逻辑。

#[derive(Debug)] // We will discuss this later
struct Point<T> {
    x : T,
    y : T,
}
impl<T> Point<T> {
    fn new(x: T, y: T) -> Self {
        Point {x, y}
    }
    fn set_x(&mut self, x: T) {
         self.x = x;       
    }
    fn set_y(&mut self, y: T) {
         self.y = y;       
    }
}
impl Point<f32> {
    fn is_secret(&self) -> bool {
        self.x == 42.0
    }    
}
fn main() {
    let mut p = Point::new(2, 4); // i32
    let q = Point::new(2.0, 4.0); // f32
    p.set_x(42);
    p.set_y(43);
    println!("{p:?} {q:?} {}", q.is_secret());
}

这里 impl<T> Point<T> 表示“任何 T 都适用的通用实现”，而 impl Point<f32> 则表示“只给 Point<f32> 开的小灶”。
这点非常实用，因为它允许在保留通用接口的同时，对某些特殊类型加专用能力，而不需要把整个类型体系搞复杂。

Exercise: Generics
练习：泛型

🟢 Starter
🟢 基础练习

• Modify the Point type to use two different types (T and U) for x and y
  把 Point 改成 x 和 y 使用两种不同类型，也就是 T 和 U。

#[derive(Debug)]
struct Point<T, U> {
    x: T,
    y: U,
}

impl<T, U> Point<T, U> {
    fn new(x: T, y: U) -> Self {
        Point { x, y }
    }
}

fn main() {
    let p1 = Point::new(42, 3.14);        // Point<i32, f64>
    let p2 = Point::new("hello", true);   // Point<&str, bool>
    let p3 = Point::new(1u8, 1000u64);    // Point<u8, u64>
    println!("{p1:?}");
    println!("{p2:?}");
    println!("{p3:?}");
}
// Output:
// Point { x: 42, y: 3.14 }
// Point { x: "hello", y: true }
// Point { x: 1, y: 1000 }

Combining Rust traits and generics
把 trait 和泛型组合起来

• Traits can be used to place restrictions on generic types (constraints)
  trait 可以给泛型施加约束，也就是限制某个泛型参数必须具备哪些能力。
• The constraint can be specified using a : after the generic type parameter, or using where. The following defines a generic function get_area that takes any type T as long as it implements the ComputeArea trait
  约束既可以直接写在泛型参数后面，用 : 表示，也可以改写成 where 子句。下面这个例子表示 get_area 可以接收任意 T，只要它实现了 ComputeArea trait。

#![allow(unused)]
fn main() {
trait ComputeArea {
    fn area(&self) -> u64;
}
fn get_area<T: ComputeArea>(t: &T) -> u64 {
    t.area()
}
}

• ▶ Try it in the Rust Playground
  ▶ 在 Rust Playground 里试试

这一步就是 Rust 泛型真正开始发力的地方。泛型负责“可以适配很多类型”，trait bound 负责“但这些类型必须满足某种能力要求”。
也就是说，Rust 泛型不是无条件的“万物皆可塞”，而是带合同的抽象。

Multiple trait constraints
多个 trait 约束

• It is possible to have multiple trait constraints
  一个泛型参数当然可以同时受多个 trait 约束。

trait Fish {}
trait Mammal {}
struct Shark;
struct Whale;
impl Fish for Shark {}
impl Fish for Whale {}
impl Mammal for Whale {}
fn only_fish_and_mammals<T: Fish + Mammal>(_t: &T) {}
fn main() {
    let w = Whale {};
    only_fish_and_mammals(&w);
    let _s = Shark {};
    // Won't compile
    only_fish_and_mammals(&_s);
}

这段代码很好地展示了 Rust 的“能力组合”风格。一个类型不是因为继承了谁才合法，而是因为它同时实现了需要的 trait 组合。
这套模式比 C++ 里很多靠模板技巧和概念约束拼出来的写法更直接。

Trait constraints in data types
在数据类型里使用 trait 约束

• Trait constraints can be combined with generics in data types
  trait 约束也可以直接放到泛型数据类型上。
• In the following example, we define the PrintDescription trait and a generic struct Shape with a member constrained by the trait
  下面这个例子里，先定义 PrintDescription trait，再定义一个泛型结构体 Shape，其中成员类型受这个 trait 约束。

#![allow(unused)]
fn main() {
trait PrintDescription {
    fn print_description(&self);
}
struct Shape<S: PrintDescription> {
    shape: S,
}
// Generic Shape implementation for any type that implements PrintDescription
impl<S: PrintDescription> Shape<S> {
    fn print(&self) {
        self.shape.print_description();
    }
}
}

• ▶ Try it in the Rust Playground
  ▶ 在 Rust Playground 里试试

这类写法很常见，尤其是在想表达“这个容器或包装器只接受某类能力对象”时。
和传统面向对象里把基类指针塞进去相比，Rust 这边通常会优先用泛型加 trait bound，把约束放到编译期解决。

Exercise: Trait constraints and generics
练习：trait 约束与泛型

🟡 Intermediate
🟡 进阶

• Implement a struct with a generic member cipher that implements CipherText
  实现一个带泛型成员 cipher 的 struct，要求这个成员实现 CipherText。

#![allow(unused)]
fn main() {
trait CipherText {
    fn encrypt(&self);
}
// TO DO
//struct Cipher<>
}

• Next, implement a method called encrypt on the struct impl that invokes encrypt on cipher
  然后为这个结构体实现一个 encrypt 方法，内部调用成员 cipher 的 encrypt。

#![allow(unused)]
fn main() {
// TO DO
impl for Cipher<> {}
}

• Next, implement CipherText on two structs called CipherOne and CipherTwo (just println() is fine). Create CipherOne and CipherTwo, and use Cipher to invoke them
  接着再给 CipherOne 和 CipherTwo 两个结构体实现 CipherText，哪怕只是简单 println!() 也行。最后用 Cipher 包一层并调用它们。

trait CipherText {
    fn encrypt(&self);
}

struct Cipher<T: CipherText> {
    cipher: T,
}

impl<T: CipherText> Cipher<T> {
    fn encrypt(&self) {
        self.cipher.encrypt();
    }
}

struct CipherOne;
struct CipherTwo;

impl CipherText for CipherOne {
    fn encrypt(&self) {
        println!("CipherOne encryption applied");
    }
}

impl CipherText for CipherTwo {
    fn encrypt(&self) {
        println!("CipherTwo encryption applied");
    }
}

fn main() {
    let c1 = Cipher { cipher: CipherOne };
    let c2 = Cipher { cipher: CipherTwo };
    c1.encrypt();
    c2.encrypt();
}
// Output:
// CipherOne encryption applied
// CipherTwo encryption applied

Rust type-state pattern and generics
Rust 的 type-state 模式与泛型

• Rust types can be used to enforce state machine transitions at compile time
  Rust 类型系统可以在编译期强制状态机转换规则。

  • Consider a Drone with say two states: Idle and Flying. In the Idle state, the only permitted method is takeoff(). In the Flying state, we permit land()
    例如一个 Drone 有两个状态：Idle 和 Flying。在 Idle 状态只允许 takeoff()，在 Flying 状态只允许 land()。

• One approach is to model the state machine using something like the following
  最直接的办法，是先写一个普通枚举状态机：

#![allow(unused)]
fn main() {
enum DroneState {
    Idle,
    Flying
}
struct Drone {x: u64, y: u64, z: u64, state: DroneState}  // x, y, z are coordinates
}

• This requires a lot of runtime checks to enforce the state machine semantics — ▶ try it to see why
  但这样做仍然需要一堆运行时检查才能保证状态转移合法。可以 ▶ 自己试试，很快就会明白为什么这招不够硬。

Type-state with PhantomData<T>
用 PhantomData<T> 做 type-state

• Generics allow us to enforce the state machine at compile time. This requires using a special generic called PhantomData<T>
  泛型可以把状态机约束直接搬到编译期，常见办法就是使用 PhantomData<T>。
• PhantomData<T> is a zero-sized marker type. In this case, we use it to represent Idle and Flying, but it has zero runtime size
  PhantomData<T> 是零尺寸标记类型。这里可以用它表示 Idle 和 Flying 两种状态，而且不会引入额外运行时大小。
• Notice that the takeoff and land methods take self as a parameter. This is referred to as consuming. Once we call takeoff() on Drone<Idle>, we only get back a Drone<Flying> and vice versa
  注意 takeoff 和 land 都直接接收 self，也就是消费当前值。这样一来，Drone<Idle> 调用 takeoff() 后，只会得到 Drone<Flying>，反过来也一样。

#![allow(unused)]
fn main() {
struct Drone<T> {x: u64, y: u64, z: u64, state: PhantomData<T> }
impl Drone<Idle> {
    fn takeoff(self) -> Drone<Flying> {...}
}
impl Drone<Flying> {
    fn land(self) -> Drone<Idle> { ...}
}
}

• ▶ Try it in the Rust Playground
  ▶ 在 Rust Playground 里试试

Key takeaways for type-state
type-state 的关键结论

• States can be represented using structs (zero-size)
  状态可以用零尺寸结构体来表示。
• We can combine the state T with PhantomData<T> (zero-size)
  状态参数 T 可以通过 PhantomData<T> 挂到类型上。
• Implementing methods for a particular stage of the state machine is then just a matter of impl State<T>
  给某个状态提供专属方法，只需要针对对应类型参数写 impl 即可。
• Use a method that consumes self to transition from one state to another
  状态转换通常用消费 self 的方法来表达。
• This gives zero-cost abstractions. The compiler enforces the state machine at compile time and it’s impossible to call methods unless the state is right
  这就是零成本抽象：编译器会在编译期强制状态机规则，状态不对时连方法都调用不了。

Builder pattern and consuming self
builder 模式与消费 self

• Consuming self is also useful for builder patterns
  消费 self 的写法在 builder 模式里也特别常见。
• Consider a GPIO configuration with several dozen pins. The pins can be configured high or low, and the default is low
  例如一个 GPIO 配置对象里可能有几十个引脚，每个引脚能配成高电平或低电平，默认值是低。

#![allow(unused)]
fn main() {
#[derive(Default)]
enum PinState {
    #[default]
    Low,
    High,
} 
#[derive(Default)]
struct GPIOConfig {
    pin0: PinState,
    pin1: PinState,
    // ...
}
}

• The builder pattern can be used to construct a GPIO configuration by chaining — ▶ Try it
  这时候就很适合用链式 builder 一步步构造配置对象。▶ 可以自己试试

Rust 泛型这一章说到底就在讲一件事：抽象当然要有，但抽象最好让编译器看得懂、管得住、还能帮着生成高效代码。
这也是它和 C++ 模板世界最大的气质差别之一。Rust 不只是想给表达力，还想把表达力收拾得更规矩。

Rust From and Into traits
Rust 的 From 与 Into trait

What you’ll learn: Rust’s type conversion traits — From<T> and Into<T> for infallible conversions, TryFrom and TryInto for fallible ones. Implement From and get Into for free. Replaces C++ conversion operators and constructors.
本章将学到什么： Rust 的类型转换 trait，包括用于不会失败转换的 From<T> 和 Into<T>，以及用于可能失败转换的 TryFrom 和 TryInto。只要实现了 From，Into 就会自动可用。这一套基本可以替代 C++ 里的转换运算符和部分构造器用途。

• From and Into are complementary traits to facilitate type conversion
  From 和 Into 是一对互补的 trait，专门用来做类型转换。
• Types normally implement on the From trait. the String::from() converts from “&str” to String, and compiler can automatically derive &str.into
  通常都是给类型实现 From。例如 String::from() 会把 &str 转成 String，而编译器也会自动让 &str.into() 成立。

struct Point {x: u32, y: u32}
// Construct a Point from a tuple
impl From<(u32, u32)> for Point {
    fn from(xy : (u32, u32)) -> Self {
        Point {x : xy.0, y: xy.1}       // Construct Point using the tuple elements
    }
}
fn main() {
    let s = String::from("Rust");
    let x = u32::from(true);
    let p = Point::from((40, 42));
    // let p : Point = (40.42)::into(); // Alternate form of the above
    println!("s: {s} x:{x} p.x:{} p.y {}", p.x, p.y);   
}

Exercise: From and Into
练习：From 与 Into

• Implement a From trait for Point to convert into a type called TransposePoint. TransposePoint swaps the x and y elements of Point
  为 Point 实现一个 From trait，把它转换成一个叫 TransposePoint 的类型。TransposePoint 会把 Point 里的 x 和 y 对调。

struct Point { x: u32, y: u32 }
struct TransposePoint { x: u32, y: u32 }

impl From<Point> for TransposePoint {
    fn from(p: Point) -> Self {
        TransposePoint { x: p.y, y: p.x }
    }
}

fn main() {
    let p = Point { x: 10, y: 20 };
    let tp = TransposePoint::from(p);
    println!("Transposed: x={}, y={}", tp.x, tp.y);  // x=20, y=10

    // Using .into() — works automatically when From is implemented
    let p2 = Point { x: 3, y: 7 };
    let tp2: TransposePoint = p2.into();
    println!("Transposed: x={}, y={}", tp2.x, tp2.y);  // x=7, y=3
}
// Output:
// Transposed: x=20, y=10
// Transposed: x=7, y=3

Rust Default trait
Rust 的 Default trait

• Default can be used to implement default values for a type
  Default 可以为类型提供默认值。
  • Types can use the Derive macro with Default or provide a custom implementation
    类型既可以直接派生 Default，也可以手写自定义实现。

#[derive(Default, Debug)]
struct Point {x: u32, y: u32}
#[derive(Debug)]
struct CustomPoint {x: u32, y: u32}
impl Default for CustomPoint {
    fn default() -> Self {
        CustomPoint {x: 42, y: 42}
    }
}
fn main() {
    let x = Point::default();   // Creates a Point{0, 0}
    println!("{x:?}");
    let y = CustomPoint::default();
    println!("{y:?}");
}

Rust Default trait
Default trait 的常见用法

• Default trait has several use cases including
  Default trait 的常见用途包括：
  • Performing a partial copy and using default initialization for rest
    只覆盖部分字段，其余字段走默认初始化。
  • Default alternative for Option types in methods like unwrap_or_default()
    给 Option 一类类型提供默认回退值，例如 unwrap_or_default()。

#[derive(Debug)]
struct CustomPoint {x: u32, y: u32}
impl Default for CustomPoint {
    fn default() -> Self {
        CustomPoint {x: 42, y: 42}
    }
}
fn main() {
    let x = CustomPoint::default();
    // Override y, but leave rest of elements as the default
    let y = CustomPoint {y: 43, ..CustomPoint::default()};
    println!("{x:?} {y:?}");
    let z : Option<CustomPoint> = None;
    // Try changing the unwrap_or_default() to unwrap()
    println!("{:?}", z.unwrap_or_default());
}

Other Rust type conversions
Rust 的其他类型转换方式

• Rust doesn’t support implicit type conversions and as can be used for explicit conversions
  Rust 不支持隐式类型转换，需要显式转换时可以使用 as。
• as should be sparingly used because it’s subject to loss of data by narrowing and so forth. In general, it’s preferable to use into() or from() where possible
  as 要少用，因为它可能触发窄化转换，从而丢失数据。一般来说，能用 into() 或 from() 就尽量用它们。

fn main() {
    let f = 42u8;
    // let g : u32 = f;    // Will not compile
    let g = f as u32;      // Ok, but not preferred. Subject to rules around narrowing
let g : u32 = f.into(); // Most preferred form; infallible and checked by the compiler
    //let k : u8 = f.into();  // Fails to compile; narrowing can result in loss of data
    
    // Attempting a narrowing operation requires use of try_into
    if let Ok(k) = TryInto::<u8>::try_into(g) {
        println!("{k}");
    }
}

Closures §§ZH§§ 闭包

Rust closures
Rust 的闭包

What you’ll learn: Closures as anonymous functions, the three capture traits Fn、FnMut、FnOnce, move closures, and how Rust closures compare with C++ lambdas. The biggest difference is that Rust infers capture behavior automatically instead of making you manually juggle [&]、[=] and friends.
本章将学到什么： 闭包作为匿名函数的基本用法，三种捕获 trait Fn、FnMut、FnOnce，move 闭包，以及 Rust 闭包和 C++ lambda 的对照。最关键的差别在于：Rust 会自动推导捕获方式，而不是让人手动去摆弄 [&]、[=] 这些符号。

• Closures are anonymous functions that can capture values from the surrounding scope.
  闭包本质上就是能从外围作用域捕获值的匿名函数。
  • The closest C++ equivalent is a lambda such as [&](int x) { return x + 1; }.
    在 C++ 里，最接近的东西就是 lambda，例如 [&](int x) { return x + 1; }。
  • Rust has three closure traits, and the compiler picks the right one automatically.
    Rust 给闭包准备了 三种 trait，具体用哪一种由编译器自动判断。
  • C++ capture modes like [=]、[&]、[this] are manual and easy to misuse.
    C++ 的 [=]、[&]、[this] 这套捕获模式全靠手写，稍不留神就会写出危险代码。
  • Rust’s borrow checker prevents dangling captures at compile time.
    Rust 的借用检查器会在编译期阻止悬空捕获。
• Closures are introduced with ||, and parameter types can usually be inferred.
  闭包用 || 这对竖线引出来，参数类型大多数时候都能自动推导。
• Closures are frequently paired with iterators, which is why they show up everywhere in idiomatic Rust code.
  闭包和迭代器经常成套出现，所以在惯用 Rust 代码里会高频见到它们。

fn add_one(x: u32) -> u32 {
    x + 1
}
fn main() {
    let add_one_v1 = |x : u32| {x + 1}; // Explicitly specified type
    let add_one_v2 = |x| {x + 1};   // Type is inferred from call site
    let add_one_v3 = |x| x+1;   // Permitted for single line functions
    println!("{} {} {} {}", add_one(42), add_one_v1(42), add_one_v2(42), add_one_v3(42) );
}

这种语法最开始会让很多 C++ 程序员皱眉头，但熟悉之后会发现它其实更统一。参数放在 || 里，后面接表达式或代码块，没有额外的捕获列表样板。
The syntax may look odd at first, especially to C++ eyes, but it is actually very uniform: parameters go between pipes, then you write either an expression or a block. There is no extra capture-list ceremony to maintain.

Exercise: Closures and capturing
练习：闭包与捕获

🟡 Intermediate
🟡 进阶练习

• Create a closure that captures a String from the enclosing scope and appends to it.
  创建一个闭包，从外层作用域捕获一个 String，并往里面追加内容。
• Create a vector of closures Vec<Box<dyn Fn(i32) -> i32>> that add 1、multiply by 2、and square the input. Then iterate over the vector and apply each closure to 5.
  再创建一个闭包向量 Vec<Box<dyn Fn(i32) -> i32>>，里面分别放“加 1”“乘 2”“平方”三种闭包。随后遍历这个向量，把每个闭包都作用到数字 5 上。

fn main() {
    // Part 1: Closure that captures and appends to a String
    let mut greeting = String::from("Hello");
    let mut append = |suffix: &str| {
        greeting.push_str(suffix);
    };
    append(", world");
    append("!");
    println!("{greeting}");  // "Hello, world!"

    // Part 2: Vector of closures
    let operations: Vec<Box<dyn Fn(i32) -> i32>> = vec![
        Box::new(|x| x + 1),      // add 1
        Box::new(|x| x * 2),      // multiply by 2
        Box::new(|x| x * x),      // square
    ];

    let input = 5;
    for (i, op) in operations.iter().enumerate() {
        println!("Operation {i} on {input}: {}", op(input));
    }
}
// Output:
// Hello, world!
// Operation 0 on 5: 6
// Operation 1 on 5: 10
// Operation 2 on 5: 25

Rust iterators
Rust 的迭代器

• Iterators are one of Rust’s most powerful features. They provide elegant ways to filter, transform, search, and combine collection processing steps.
  迭代器是 Rust 最有力量的一批特性之一。无论是过滤、变换、查找还是组合处理集合，它们都能把代码写得非常顺。
• In the example below, |&x| *x >= 42 is a closure used by filter(), and |x| println!("{x}") is another closure used by for_each().
  下面例子里的 |&x| *x >= 42 是交给 filter() 的闭包，而 |x| println!("{x}") 则是交给 for_each() 的闭包。

fn main() {
    let a = [0, 1, 2, 3, 42, 43];
    for x in &a {
        if *x >= 42 {
            println!("{x}");
        }
    }
    // Same as above
    a.iter().filter(|&x| *x >= 42).for_each(|x| println!("{x}"))
}

Rust iterators are lazy
Rust 迭代器是惰性的

• A key property of iterators is laziness: most iterator chains do nothing until a consuming operation actually evaluates them.
  迭代器最关键的性质之一就是惰性。大多数链式操作在真正被消费之前，其实什么都不会做。
• For example, a.iter().filter(|&x| *x >= 42); by itself produces no output and performs no side-effect. The compiler even warns when it notices a lazy iterator chain that gets thrown away unused.
  例如 a.iter().filter(|&x| *x >= 42); 单独写在那里时，既不会输出，也不会产生副作用。编译器甚至会在发现这种“惰性链建好了却没用”的情况时主动警告。

fn main() {
    let a = [0, 1, 2, 3, 42, 43];
    // Add one to each element and print it
    let _ = a.iter().map(|x|x + 1).for_each(|x|println!("{x}"));
    let found = a.iter().find(|&x|*x == 42);
    println!("{found:?}");
    // Count elements
    let count = a.iter().count();
    println!("{count}");
}

collect() gathers results into a collection
collect() 用来把结果收集进集合

• collect() materializes the results of an iterator chain into a concrete collection such as Vec<T>.
  collect() 会把迭代器链最终“物化”成一个具体集合，比如 Vec<T>。
  • The _ in Vec<_> means “infer the element type from the iterator output”.
    Vec<_> 里的 _ 表示“元素类型交给编译器从迭代器输出里推导”。
  • The mapped type can be anything, including String.
    map() 后产出的新类型可以是任何东西，包括 String。

fn main() {
    let a = [0, 1, 2, 3, 42, 43];
    let squared_a : Vec<_> = a.iter().map(|x|x*x).collect();
    for x in &squared_a {
        println!("{x}");
    }
    let squared_a_strings : Vec<_> = a.iter().map(|x|(x*x).to_string()).collect();
    // These are actually string representations
    for x in &squared_a_strings {
        println!("{x}");
    }
}

Exercise: Rust iterators
练习：Rust 迭代器

🟢 Starter
🟢 基础练习

• Create an integer array containing both odd and even numbers. Iterate over it and split the values into two vectors.
  创建一个同时包含奇数和偶数的整数数组，把它拆分成两个向量，一个存偶数，一个存奇数。
• Can this be done in a single pass? Hint: try partition().
  能不能一趟完成？提示：试试 partition()。