Rust 编程语言

作者：Steve Klabnik、Carol Nichols 和 Chris Krycho，以及 Rust 社区的贡献者们

本书的这一版本假定你使用的是 Rust 1.90.0（发布于 2025-09-18）或更高版本，并在所有项目的 Cargo.toml 文件中设置 edition = "2024"，以配置它们使用 Rust 2024 版次（Edition）的惯用写法。请参阅第 1 章的“安装“章节获取安装或更新 Rust 的说明，并参阅附录 E了解关于版次的信息。

HTML 格式可通过在线方式访问 https://doc.rust-lang.org/stable/book/，也可通过 rustup 安装 Rust 后离线获取；运行 rustup doc --book 即可打开。

此外还提供了若干社区翻译版本。

本书还提供来自 No Starch Press 的平装本和电子书格式。

关于The Rust Programming Language | 《Rust 编程语言》 中文翻译的说明

译者注：

Rust是一门更新非常频繁的语言，从它的博客页面就能看出.仅2026年1月份到现在（5月），rust就完成了从1.93到1.95的版本号变化。平均算下来，它每几周就要更新一个版本。

因此，保持文档快捷的更新也是必要的。

所以我选择从头再次构建了这个文档，并在项目中细化了翻译、构建和贡献的流程，使得人人都可以部署和更新文档。当然，需要说明的是，此版The Rust Programming Language翻译是由AI机翻的。

最后，译者在此呼吁rust官方和社区尽快推进rust文档本地化功能完善的工作。

该翻译版本的项目地址：rustbook_zhcn

🚨 想要更具互动性的学习体验？试试 Rust 书的另一个版本，它包含：测验、高亮、可视化等功能：https://rust-book.cs.brown.edu

前言

Rust 编程语言在短短几年内走过了漫长的道路——从一个由少数新兴爱好者组成的小众社区创建和孵化，到成为世界上最受欢迎和最受需求的编程语言之一。回首过去，Rust 的强大和前景必然会吸引关注并在系统编程领域站稳脚跟，这是不可避免的。但并非必然的是，其在全球范围内通过开源社区渗透开来的兴趣与创新增长，以及在各个行业中催生的大规模采用。

此时此刻，我们很容易指出 Rust 所提供的精彩特性，来解释这种兴趣和采用的爆发式增长。谁会不想要内存安全性（memory safety）、以及高性能（fast performance）、以及友好的编译器（friendly compiler）、以及出色的工具链（great tooling）——除了众多其他精彩特性之外？你今天看到的 Rust 语言，结合了系统编程领域多年研究的成果，以及一个充满活力和热情的社区的实践智慧。这门语言是有目的性地设计、并精心打造的，为开发者提供了一款能更轻松编写安全、快速和可靠代码的工具。

但真正让 Rust 与众不同的，是它植根于赋能你——用户——去实现你的目标。这是一门希望你成功的语言，这种赋能（empowerment）的原则贯穿于构建、维护和倡导这门语言的社区核心之中。自从这本权威著作的上一个版本以来，Rust 已进一步发展成为真正全球化和值得信赖的语言。Rust 项目现在得到了 Rust 基金会（Rust Foundation）的有力支持，该基金会还投资于关键举措，以确保 Rust 的安全性、稳定性和可持续性。

这一版的 The Rust Programming Language（《Rust 编程语言》）是一次全面的更新，反映了该语言多年来的演变，并提供了宝贵的新的信息。但这不仅仅是一本关于语法和库的指南——它是一份邀请，邀请你加入一个重视质量、性能和深思熟虑的设计的社区。无论你是一位经验丰富的开发者想第一次探索 Rust，还是一位的资深 Rustacean（Rust 爱好者）想精进自己的技能，这一版都能为每个人提供有价值的内容。

Rust 之旅是一次协作、学习和迭代的过程。这门语言及其生态系统的成长，直接反映了其背后充满活力、多元化的社区。从核心语言设计者到偶尔的贡献者，成千上万开发者的贡献，正是使 Rust 成为如此独特而强大工具的原因。通过拿起这本书，你不仅是在学习一门新的编程语言——你更是在加入一场让软件变得更好、更安全、更有趣的运动。

欢迎来到 Rust 社区！

• Bec Rumbul，Rust 基金会执行董事

简介

注：本书的这一版与 No Starch Press 出版的 The Rust Programming Language 印刷版和电子书版内容相同。

欢迎阅读 The Rust Programming Language（《Rust 程序设计语言》），一本关于 Rust 的入门书籍。 Rust 编程语言能帮助你编写更快、更可靠的软件。 高级易用性（high-level ergonomics）和底层控制力（low-level control）在编程语言设计中常常相互矛盾；Rust 挑战了这一矛盾。通过平衡强大的技术能力和优秀的开发者体验，Rust 让你能够在没有传统底层控制所带来的种种麻烦的情况下，掌控底层细节（例如内存使用）。

Rust 的受众

Rust 因多种原因而适合许多人。让我们来看看其中几个最重要的群体。

开发者团队

Rust 已被证明是一个高效的协作工具，适用于具有不同系统编程知识水平的大型开发者团队。底层代码容易出现各种微妙的 bug（漏洞），在大多数其他语言中，这些 bug 只能通过大量测试和经验丰富的开发者的仔细代码审查（code review）才能发现。在 Rust 中，编译器扮演着守门人的角色，拒绝编译包含这些难以捉摸的 bug（包括并发 bug）的代码。通过与编译器协同工作，团队可以将时间集中在程序的逻辑上，而不是追查 bug。

Rust 还将现代开发者工具带到了系统编程领域：

• Cargo，内置的依赖管理器（dependency manager）和构建工具（build tool），使得在 Rust 生态系统中添加、编译和管理依赖变得轻松且一致。
• rustfmt 格式化工具确保了开发者之间一致的编码风格。
• Rust Language Server（RLS，Rust 语言服务器）为集成开发环境（IDE）提供了代码补全（code completion）和内联错误消息（inline error messages）的支持。

通过使用 Rust 生态系统中的这些工具以及其他工具，开发者在编写系统级代码时也能保持高效。

学生

Rust 适合学生以及那些有兴趣学习系统概念的人。许多人通过使用 Rust 学习了操作系统开发等主题。社区非常友好，乐于回答学生的问题。通过本书这样的努力，Rust 团队希望让更多人（尤其是编程新手）能够更容易地接触系统概念。

公司

数百家大大小小的公司将 Rust 用于生产环境中的各种任务，包括命令行工具（command line tools）、Web 服务（web services）、DevOps 工具、嵌入式设备（embedded devices）、音视频分析与转码（audio and video analysis and transcoding）、加密货币（cryptocurrencies）、生物信息学（bioinformatics）、搜索引擎（search engines）、物联网（IoT）应用、机器学习（machine learning），甚至 Firefox 浏览器的大部分核心功能。

开源开发者

Rust 适合那些想要构建 Rust 编程语言本身、社区、开发者工具和库的人。我们非常欢迎你为 Rust 语言做出贡献。

重视速度和稳定性的用户

Rust 适合那些追求语言的速度和稳定性的用户。所谓速度，我们既指 Rust 代码执行的速度，也指 Rust 让你编写程序的速度。Rust 编译器的检查确保了在添加功能和重构（refactoring）过程中的稳定性。相比之下，没有这些检查的语言中的脆弱遗留代码，开发者往往不敢轻易修改。通过追求零成本抽象（zero-cost abstractions）——即能够编译为与手写底层代码速度相当的高级特性——Rust 致力于让安全代码也成为快速代码。

Rust 语言也希望能支持许多其他用户；这里提到的只是其中一些最大的利益相关者。总的来说，Rust 最大的抱负是消除程序员几十年来所接受的权衡取舍，同时提供安全性 与 生产力、速度 与 易用性。试试 Rust，看看它的选择是否适合你。

本书的受众

本书假设你曾经用其他编程语言写过代码，但不对具体是哪一种语言做任何假设。我们努力使内容对来自各种编程背景的读者都具有广泛的易读性。我们不会花大量时间讨论编程 是什么 或如何思考编程。如果你是编程新手，那么阅读专门介绍编程入门的书籍会更合适。

如何使用本书

总的来说，本书假设你按照从前到后的顺序阅读。后面的章节建立在前面章节的概念之上，而前面的章节可能不会深入探讨某个特定主题的细节，但会在后面的章节中再次讨论。

你会在本书中找到两种章节：概念章节和项目章节。在概念章节中，你将学习 Rust 的某个方面。在项目章节中，我们将一起构建小型程序，应用你目前所学到的知识。第 2 章、第 12 章和第 21 章是项目章节；其余的是概念章节。

第 1 章 介绍如何安装 Rust、如何编写 “Hello, world!” 程序，以及如何使用 Cargo（Rust 的包管理器和构建工具）。第 2 章 是 Rust 编程的动手实践入门，让你构建一个猜数字游戏。在这里，我们高层次地介绍概念，后面的章节将提供更多细节。如果你想马上动手实践，第 2 章正合适。如果你是一个特别细致的学习者，喜欢在进入下一步之前掌握每一个细节，你可能想跳过第 2 章直接进入 第 3 章，其中介绍了 Rust 与其他编程语言相似的特性；然后，当你希望做一个应用所学细节的项目时，再回到第 2 章。

在 第 4 章 中，你将学习 Rust 的所有权（ownership）系统。第 5 章 讨论结构体（struct）和方法（method）。第 6 章 介绍枚举（enum）、match 表达式以及 if let 和 let...else 控制流结构。你将使用结构体和枚举来创建自定义类型。

在 第 7 章 中，你将学习 Rust 的模块（module）系统以及用于组织代码及其公有应用程序编程接口（API）的隐私规则。第 8 章 讨论标准库提供的一些常见集合数据结构：vector（向量）、字符串（string）和哈希 map（hash map）。第 9 章 探讨 Rust 的错误处理哲学和技术。

第 10 章 深入探讨泛型（generic）、trait（特质）和生命周期（lifetime），它们使你能够定义适用于多种类型的代码。第 11 章 全部关于测试（testing），即使有 Rust 的安全性保证，测试对于确保程序逻辑的正确性也是必要的。在 第 12 章 中，我们将自己实现 grep 命令行工具的部分功能，用于在文件中搜索文本。为此，我们将使用之前章节中讨论的许多概念。

第 13 章 探讨闭包（closure）和迭代器（iterator）：这些是 Rust 从函数式编程语言中借鉴的特性。在 第 14 章 中，我们将更深入地研究 Cargo，并讨论与他人共享库的最佳实践。第 15 章 讨论标准库提供的智能指针（smart pointer）以及实现其功能的 trait。

在 第 16 章 中，我们将介绍不同的并发编程模型，并讨论 Rust 如何帮助你在多线程中无畏地编程。在 第 17 章 中，我们在此基础上探索 Rust 的 async 和 await 语法，以及 task（任务）、future（未来）和 stream（流），以及它们所支持的轻量级并发模型。

第 18 章 探讨 Rust 的惯用写法与你可能熟悉的面向对象编程（object-oriented programming）原则的比较。第 19 章 是关于模式（pattern）和模式匹配（pattern matching）的参考，这是在 Rust 程序中表达思想的强大方式。第 20 章 包含了一系列有趣的高级主题，包括 unsafe Rust（不安全 Rust）、宏（macro），以及更多关于生命周期、trait、类型、函数和闭包的内容。

在 第 21 章 中，我们将完成一个项目，实现一个底层的多线程 Web 服务器！

最后，一些附录以更接近参考文档的格式提供了有关该语言的有用信息。附录 A 介绍 Rust 的关键字（keyword），附录 B 介绍 Rust 的运算符和符号，附录 C 介绍标准库中可派生（derivable）的 trait，附录 D 介绍一些有用的开发工具，附录 E 解释 Rust 的版本（edition）。在 附录 F 中，你可以找到本书的翻译版本，附录 G 将介绍 Rust 是如何制作的以及什么是 nightly Rust。

阅读本书没有错误的方式：如果你想跳着读，请便！如果遇到任何困惑，你可能需要回到前面的章节。但无论如何，选择适合你的方式。

学习 Rust 的一个重要部分是学习如何阅读编译器显示的错误消息：这些消息将引导你编写正确的代码。因此，我们将提供许多无法编译的示例，并附上编译器在每个情况下会显示的错误消息。请注意，如果你随意输入并运行某个示例，它可能无法编译！请确保你阅读了周围的文本，以确定你试图运行的示例是否本就应该出错。在大多数情况下，我们会引导你找到无法编译代码的正确版本。Ferris 也会帮助你区分哪些代码本就不该工作：

Ferris	含义
	此代码无法编译！
	此代码会 panic！
	此代码不会产生期望的行为。

在大多数情况下，我们会引导你找到无法编译代码的正确版本。

源代码

生成本书的源文件可以在 GitHub 上找到。

入门指南

让我们开始你的 Rust 之旅吧！有很多东西需要学习，但千里之行，始于足下。 在本章中，我们将讨论：

• 在 Linux、macOS 和 Windows 上安装 Rust
• 编写一个打印 Hello, world! 的程序
• 使用 cargo，Rust 的包管理器和构建系统

安装

安装

第一步是安装 Rust。我们将通过 rustup（一个用于管理 Rust 版本及相关工具的命令行工具）来下载 Rust。你需要联网才能下载。

注意：如果你出于某些原因不想使用 rustup，请参阅 其他 Rust 安装方法页面 了解更多选项。

以下步骤将安装最新稳定版的 Rust 编译器。 Rust 的稳定性保证确保本书中所有能编译的示例在更新的 Rust 版本中也能继续编译。不同版本之间的输出可能略有差异，因为 Rust 经常改进错误信息和警告。换句话说，你通过这些步骤安装的任何较新的稳定版 Rust 都应该能正常使用本书的内容。

在 Linux 或 macOS 上安装 rustup

如果你使用的是 Linux 或 macOS，打开终端并输入以下命令：

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

该命令会下载一个脚本并开始安装 rustup 工具，该工具会安装最新稳定版的 Rust。系统可能会提示你输入密码。如果安装成功，将显示以下内容：

Rust is installed now. Great!

你还需要一个 链接器（linker），它是 Rust 用来将其编译输出合并成一个文件的程序。你可能已经拥有一个。如果遇到链接器错误，你应该安装一个 C 编译器，它通常会包含链接器。C 编译器也很有用，因为一些常见的 Rust 包依赖 C 代码，因此需要 C 编译器。

在 macOS 上，你可以通过运行以下命令来获取 C 编译器：

$ xcode-select --install

Linux 用户通常应根据其发行版的文档安装 GCC 或 Clang。例如，如果你使用 Ubuntu，可以安装 build-essential 包。

在 Windows 上安装 rustup

在 Windows 上，请访问 https://www.rust-lang.org/tools/install 并按照说明安装 Rust。在安装过程中，系统会提示你安装 Visual Studio。这提供了编译程序所需的链接器和本地库。如果你在此步骤中需要更多帮助，请参阅 https://rust-lang.github.io/rustup/installation/windows-msvc.html。

本书的其余部分使用的命令在 cmd.exe 和 PowerShell 中都可运行。如果有特定差异，我们会说明应该使用哪一种。

故障排除

要检查 Rust 是否正确安装，打开终端并输入以下命令：

$ rustc --version

你应该会看到最新稳定版发布的版本号、提交哈希值（commit hash）和提交日期（commit date），格式如下：

rustc x.y.z (abcabcabc yyyy-mm-dd)

如果你看到了这些信息，说明 Rust 已成功安装！如果没有看到这些信息，请按照以下步骤检查 Rust 是否在你的 %PATH% 系统变量中。

在 Windows CMD 中，使用：

> echo %PATH%

在 PowerShell 中，使用：

> echo $env:Path

在 Linux 和 macOS 中，使用：

$ echo $PATH

如果这些都没问题但 Rust 仍然无法工作，你可以在多个地方获得帮助。请访问社区页面了解如何与其他 Rustaceans（我们对自已的一个昵称）取得联系。

更新与卸载

一旦通过 rustup 安装了 Rust，更新到新发布的版本就很容易了。在终端中运行以下更新脚本：

$ rustup update

要卸载 Rust 和 rustup，请在终端中运行以下卸载脚本：

$ rustup self uninstall

阅读本地文档

安装 Rust 时也会附带一份本地文档副本，方便你离线阅读。运行 rustup doc 即可在浏览器中打开本地文档。

每当标准库提供了某个类型或函数，而你不确定它的用途或使用方法时，可以查阅应用程序编程接口（API）文档来了解！

使用文本编辑器和 IDE

本书对你使用什么工具来编写 Rust 代码没有任何预设。几乎任何文本编辑器都能胜任！不过，许多文本编辑器和集成开发环境（IDE）都内置了对 Rust 的支持。你可以在 Rust 官网的工具页面上找到一份相当最新的编辑器及 IDE 列表。

离线使用本书

在几个示例中，我们会用到标准库之外的 Rust 包。要完成这些示例，你需要联网或提前下载这些依赖项。要提前下载依赖项，可以运行以下命令（我们稍后会详细解释 cargo 是什么以及这些命令各自的作用）：

$ cargo new get-dependencies
$ cd get-dependencies
$ cargo add rand@0.8.5 trpl@0.2.0

这将缓存这些包的下载内容，这样你就不需要之后再下载了。运行此命令后，你不需要保留 get-dependencies 文件夹。如果你已经运行过此命令，可以在本书后续的所有 cargo 命令中使用 --offline 标志，以使用这些缓存版本，而无需尝试联网。

Hello, World!

Hello, World!

现在你已经安装了 Rust，是时候编写你的第一个 Rust 程序了。学习一门新语言时，传统上都会编写一个在屏幕上打印 Hello, world! 的小程序，我们这里也一样！

注意：本书假定你对命令行有基本的了解。Rust 对你的编辑工具、开发工具或代码存放位置没有特别要求，因此如果你更喜欢使用 IDE 而不是命令行，请随意使用你喜欢的 IDE。许多 IDE 现在都已不同程度地支持 Rust；请查看相应 IDE 的文档以了解详情。Rust 团队一直致力于通过 rust-analyzer 提供出色的 IDE 支持。更多细节请参见附录 D。

创建项目目录

首先，创建一个目录来存放你的 Rust 代码。Rust 并不关心你的代码存放在哪里，但对于本书中的练习和项目，我们建议在你的 home 目录下创建一个 projects 目录，并将你所有的项目都保存在那里。

打开终端，输入以下命令来创建一个 projects 目录，并在 projects 目录下为“Hello, world!“项目创建一个子目录。

对于 Linux、macOS 和 Windows 上的 PowerShell，请输入：

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

对于 Windows CMD，请输入：

> mkdir "%USERPROFILE%\projects"
> cd /d "%USERPROFILE%\projects"
> mkdir hello_world
> cd hello_world

Rust 程序基础

接下来，创建一个新的源文件并命名为 main.rs。Rust 文件始终以 .rs 扩展名结尾。如果你的文件名包含多个单词，约定使用下划线来分隔它们。例如，使用 hello_world.rs 而不是 helloworld.rs。

现在打开你刚刚创建的 main.rs 文件，并输入示例 1-1 中的代码。

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

保存文件，然后返回到 ~/projects/hello_world 目录下的终端窗口。在 Linux 或 macOS 上，输入以下命令来编译并运行该文件：

$ rustc main.rs
$ ./main
Hello, world!

在 Windows 上，使用 .\main 代替 ./main：

> rustc main.rs
> .\main
Hello, world!

无论你使用什么操作系统，字符串 Hello, world! 都应该打印到终端上。如果你没有看到这个输出，请返回安装章节的“故障排除”部分，了解获取帮助的方法。

如果 Hello, world! 成功打印出来了，恭喜你！你已经正式编写了一个 Rust 程序。这意味着你已经是一名 Rust 程序员了——欢迎你！

Rust 程序剖析

让我们仔细回顾一下这个“Hello, world!“程序。以下是代码的第一部分：

fn main() {

}

这些代码定义了一个名为 main 的函数。main 函数很特殊：它始终是每个可执行 Rust 程序中第一个运行的代码。这里，第一行声明了一个名为 main 的函数，它没有参数，也没有返回值。如果有参数，它们会放在括号 () 内。

函数体被包裹在 {} 中。Rust 要求所有函数体都要用花括号括起来。好的代码风格是将开头的花括号放在函数声明的同一行，并在中间加一个空格。

注意：如果你想在 Rust 项目中保持统一的代码风格，可以使用名为 rustfmt 的自动格式化工具来按特定风格格式化代码（更多关于 rustfmt 的内容请参见附录 D）。Rust 团队已将该工具随标准 Rust 发行版一同提供，就像 rustc 一样，因此它应该已经安装在了你的电脑上！

main 函数体包含以下代码：

#![allow(unused)]
fn main() {
println!("Hello, world!");
}

这一行代码完成了这个小程序中的所有工作：它将文本打印到屏幕上。这里有三个重要的细节需要注意。

第一，println! 调用了一个 Rust 宏（macro）。如果它调用的是一个普通函数，那么应该写成 println（不带 !）。Rust 宏是一种编写生成代码以扩展 Rust 语法的方式，我们将在第 20 章中更详细地讨论它们。目前，你只需要知道使用 ! 意味着你在调用一个宏而不是普通函数，并且宏并不总是遵循与函数相同的规则。

第二，你看到了 "Hello, world!" 字符串。我们将这个字符串作为参数传递给 println!，然后该字符串被打印到屏幕上。

第三，我们用分号（;）结束这一行，这表明这个表达式已经结束，下一个表达式可以开始了。Rust 代码的大多数行都以分号结尾。

编译与执行

你刚刚运行了一个新创建的程序，现在让我们回顾一下这个过程的具体步骤。

在运行 Rust 程序之前，你必须使用 Rust 编译器进行编译，输入 rustc 命令并将源文件名作为参数传入，如下所示：

$ rustc main.rs

如果你有 C 或 C++ 背景，你会注意到这与 gcc 或 clang 类似。编译成功后，Rust 会输出一个二进制可执行文件。

在 Linux、macOS 和 Windows 的 PowerShell 上，可以通过在终端中输入 ls 命令来查看可执行文件：

$ ls
main  main.rs

在 Linux 和 macOS 上，你会看到两个文件。在 Windows 的 PowerShell 上，你会看到与使用 CMD 时相同的三个文件。在 Windows 的 CMD 上，需要输入以下命令：

> dir /B %= the /B option says to only show the file names =%
main.exe
main.pdb
main.rs

这里显示了扩展名为 .rs 的源代码文件、可执行文件（在 Windows 上是 main.exe，在其他平台上则是 main），以及在 Windows 上还有一个包含调试信息的 .pdb 文件。然后，你可以运行 main 或 main.exe 文件，如下所示：

$ ./main # or .\main on Windows

如果你的 main.rs 是“Hello, world!“程序，这行命令会将 Hello, world! 打印到终端上。

如果你更熟悉动态语言，比如 Ruby、Python 或 JavaScript，你可能不习惯将编译和运行分成两个步骤。Rust 是一种_预编译（ahead-of-time compiled）语言，这意味着你可以编译程序并将可执行文件交给别人，即使他们没有安装 Rust 也能运行。如果你给别人一个 .rb、.py_ 或 .js 文件，他们需要分别安装 Ruby、Python 或 JavaScript 的运行时环境。不过在这些语言中，你只需要一条命令就能编译并运行程序。语言设计中处处存在权衡。

对于简单的程序，仅用 rustc 编译就足够了，但随着项目的增长，你会希望管理所有选项并方便地共享代码。接下来，我们将向你介绍 Cargo 工具，它将帮助你编写真实的 Rust 程序。

Hello, Cargo!

Hello, Cargo!

Cargo 是 Rust 的构建系统和包管理器。大多数 Rustaceans（Rust 开发者）使用这个工具来管理他们的 Rust 项目，因为 Cargo 为你处理了许多任务，例如构建代码、下载代码所依赖的库以及构建这些库。（我们把代码所需要的库称为_依赖项（dependencies）_。）

最简单的 Rust 程序，比如我们目前编写的这个，没有任何依赖项。如果我们用 Cargo 构建“Hello, world!“项目，它只会用到 Cargo 中处理代码构建的部分。随着你编写更复杂的 Rust 程序，你会添加依赖项，而如果你从一开始就使用 Cargo 创建项目，添加依赖项就会变得容易得多。

因为绝大多数 Rust 项目都使用 Cargo，本书的其余部分也假设你使用 Cargo。如果你使用“安装”章节中讨论的官方安装程序安装了 Rust，那么 Cargo 会随 Rust 一同安装。如果你通过其他方式安装了 Rust，请在终端中输入以下命令来检查 Cargo 是否已安装：

$ cargo --version

如果你看到了版本号，说明已经安装成功！如果你看到类似 command not found 的错误信息，请查阅你的安装方式对应的文档，了解如何单独安装 Cargo。

使用 Cargo 创建项目

让我们使用 Cargo 创建一个新项目，并看看它与我们之前的“Hello, world!“项目有何不同。首先回到你的 projects 目录（或者你决定存放代码的任何位置）。然后，在任何操作系统上运行以下命令：

$ cargo new hello_cargo
$ cd hello_cargo

第一个命令创建了一个名为 hello_cargo 的新目录和项目。我们将项目命名为 hello_cargo，Cargo 会在同名目录中创建它的文件。

进入 hello_cargo 目录并列出文件。你会看到 Cargo 为我们生成了两个文件和一个目录：一个 Cargo.toml 文件和一个 src 目录，其中包含一个 main.rs 文件。

它同时还初始化了一个新的 Git 仓库以及一个 .gitignore 文件。如果你在已有的 Git 仓库中运行 cargo new，则不会生成 Git 文件；你可以通过使用 cargo new --vcs=git 来覆盖此行为。

注意：Git 是一种常见的版本控制系统。你可以通过 --vcs 标志改变 cargo new 使用的版本控制系统，或不使用任何版本控制系统。运行 cargo new --help 可查看可用选项。

用你选择的文本编辑器打开 Cargo.toml。它应该类似于示例 1-2 中的代码。

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2024"

[dependencies]

该文件采用 TOML（Tom’s Obvious, Minimal Language）格式，这是 Cargo 的配置格式。

第一行 [package] 是一个章节标题，表示接下来的语句是在配置一个包。随着我们向此文件添加更多信息，我们将添加其他章节。

接下来的三行设置了 Cargo 编译程序所需的配置信息：名称（name）、版本（version）和要使用的 Rust 版本（edition）。我们将在附录 E中讨论 edition 键。

最后一行 [dependencies] 是一个章节的开始，用于列出项目的所有依赖项。在 Rust 中，代码包被称为_crate_。这个项目不需要任何其他 crate，但在第 2 章的第一个项目中我们将会用到，到时我们会使用这个 dependencies 章节。

现在打开 src/main.rs 看一看：

Filename: src/main.rs

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

Cargo 已经为你生成了一个“Hello, world!“程序，就像我们在示例 1-1 中编写的一样！到目前为止，我们的项目与 Cargo 生成的项目的区别在于：Cargo 将代码放在了 src 目录中，并且我们在顶层目录中有一个 Cargo.toml 配置文件。

Cargo 期望你的源文件存放在 src 目录内。项目顶层目录只存放 README 文件、许可信息、配置文件以及与代码无关的其他内容。使用 Cargo 有助于你组织项目。每样东西都有其位置，所有东西都各就各位。

如果你启动的项目没有使用 Cargo，就像我们之前的“Hello, world!“项目一样，你可以将其转换为使用 Cargo 的项目。将项目代码移到 src 目录中，并创建一个合适的 Cargo.toml 文件。获取 Cargo.toml 文件的一个简单方法是运行 cargo init，它会自动为你创建该文件。

构建并运行 Cargo 项目

现在让我们看看使用 Cargo 构建和运行“Hello, world!“程序有什么不同！在 hello_cargo 目录下，输入以下命令来构建你的项目：

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

该命令会在 target/debug/hello_cargo（Windows 上是 target\debug\hello_cargo.exe）中创建一个可执行文件，而不是在当前目录中。因为默认构建是调试构建（debug build），Cargo 将二进制文件放在名为 debug 的目录中。你可以使用以下命令运行该可执行文件：

$ ./target/debug/hello_cargo # or .\target\debug\hello_cargo.exe on Windows
Hello, world!

如果一切顺利，Hello, world! 将打印到终端。首次运行 cargo build 还会使 Cargo 在顶层创建一个新文件：Cargo.lock。该文件用于跟踪项目中依赖项的确切版本。这个项目没有依赖项，所以该文件内容比较简单。你永远不需要手动修改这个文件；Cargo 会为你管理其内容。

我们刚刚用 cargo build 构建了项目，并用 ./target/debug/hello_cargo 运行了它，但我们也可以使用 cargo run 一次性编译代码并运行生成的可执行文件：

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

使用 cargo run 比记住先运行 cargo build 再输入完整的二进制文件路径要方便得多，因此大多数开发者使用 cargo run。

注意这次我们没有看到 Cargo 正在编译 hello_cargo 的输出。Cargo 发现文件没有改变，因此它没有重新构建，而是直接运行了二进制文件。如果你修改了源代码，Cargo 会在运行之前重新构建项目，你会看到如下输出：

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

Cargo 还提供了一个名为 cargo check 的命令。该命令会快速检查你的代码，确保它能编译，但不会生成可执行文件：

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

为什么你不需要可执行文件呢？通常，cargo check 比 cargo build 快得多，因为它跳过了生成可执行文件的步骤。如果你在编写代码时持续检查工作，使用 cargo check 可以加快你了解项目是否仍能编译的过程！因此，许多 Rustaceans 在编写程序时会定期运行 cargo check 以确保代码能编译。然后，当他们准备使用可执行文件时，再运行 cargo build。

让我们总结一下目前学到的关于 Cargo 的知识：

• 我们可以使用 cargo new 创建项目。
• 我们可以使用 cargo build 构建项目。
• 我们可以使用 cargo run 一步完成构建和运行项目。
• 我们可以使用 cargo check 在不生成二进制文件的情况下检查错误。
• Cargo 不会将构建结果保存在代码所在的目录中，而是存储在 target/debug 目录中。

使用 Cargo 的另一个优点是，无论你使用哪个操作系统，命令都是相同的。因此，从现在开始，我们将不再分别提供 Linux/macOS 与 Windows 的特定说明。

构建发布版本

当你的项目最终准备好发布时，你可以使用 cargo build --release 在优化模式下编译它。该命令会在 target/release 而不是 target/debug 中创建可执行文件。优化使你的 Rust 代码运行得更快，但启用优化会延长程序编译时间。这就是为什么有两种不同的配置：一种用于开发，当你需要频繁快速重建时使用；另一种用于构建最终提供给用户的程序，该程序不会被反复重建，并且会尽可能快地运行。如果你在基准测试（benchmarking）代码的运行时间，请务必运行 cargo build --release 并使用 target/release 中的可执行文件进行测试。

充分利用 Cargo 的约定

对于简单的项目，Cargo 相比直接使用 rustc 并没有提供太多优势，但随着程序变得越来越复杂，它会证明自己的价值。一旦程序增长到多个文件或需要依赖项时，让 Cargo 来协调构建会容易得多。

尽管 hello_cargo 项目很简单，但它现在使用了你将在 Rust 编程生涯中用到的大部分真实工具。实际上，要处理任何现有项目，你可以使用以下命令通过 Git 检出代码，切换到该项目的目录，然后进行构建：

$ git clone example.org/someproject
$ cd someproject
$ cargo build

有关 Cargo 的更多信息，请查看其文档。

总结

你的 Rust 之旅已经有了一个良好的开端！在本章中，你学会了如何：

• 使用 rustup 安装最新稳定版 Rust。
• 更新到更新的 Rust 版本。
• 打开本地安装的文档。
• 直接使用 rustc 编写并运行一个“Hello, world!“程序。
• 使用 Cargo 的约定创建并运行一个新项目。

现在是时候构建一个更充实的程序来熟悉阅读和编写 Rust 代码了。因此，在第 2 章中，我们将构建一个猜谜游戏程序。如果你更愿意先学习常见编程概念在 Rust 中的用法，可以阅读第 3 章，然后再回到第 2 章。

编写猜数字游戏

让我们通过一个动手项目一起深入 Rust！本章通过向你展示如何在实际程序中使用它们，介绍一些常见的 Rust 概念。你将学习 let、match、方法（methods）、关联函数（associated functions）、外部 crate 以及更多！在接下来的章节中，我们将更详细地探讨这些概念。在本章中，你只需练习基础知识。

我们将实现一个经典的初学者编程问题：猜数字游戏（guessing game）。它的工作原理如下：程序将生成一个 1 到 100 之间的随机整数。然后提示玩家输入一个猜测。输入猜测后，程序会提示猜测是太小还是太大。如果猜对了，游戏会打印祝贺信息并退出。

设置新项目

要设置新项目，请进入你在第 1 章中创建的 projects 目录，并使用 Cargo 创建一个新项目，如下所示：

$ cargo new guessing_game
$ cd guessing_game

第一个命令 cargo new 将项目名称（guessing_game）作为第一个参数。第二个命令切换到新项目的目录。

查看生成的 Cargo.toml 文件：

Filename: Cargo.toml

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2024"

[dependencies]

正如你在第 1 章中看到的，cargo new 会为你生成一个 “Hello, world!” 程序。查看 src/main.rs 文件：

文件名: src/main.rs

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

现在让我们编译这个 “Hello, world!” 程序并使用 cargo run 命令一步运行它：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/guessing_game`
Hello, world!

当你需要快速迭代项目时，run 命令非常方便，正如我们在这个游戏中所做的，在进入下一个迭代之前快速测试每个迭代。

重新打开 src/main.rs 文件。你将在此文件中编写所有代码。

处理猜测

猜数字游戏程序的第一部分将请求用户输入，处理该输入，并检查输入是否符合预期格式。首先，我们将允许玩家输入一个猜测。将清单 2-1 中的代码输入到 src/main.rs 中。

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

这段代码包含很多信息，让我们逐行来看。为了获取用户输入并将结果作为输出打印，我们需要将 io 输入/输出库引入作用域。io 库来自标准库（standard library），即 std：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

默认情况下，Rust 在标准库中定义了一组项，它会将这些项引入每个程序的作用域。这组项称为 prelude（预导入模块），你可以在标准库文档中查看其所有内容。

如果你要使用的类型不在 prelude 中，则必须使用 use 语句显式地将该类型引入作用域。使用 std::io 库可以为你提供许多有用的功能，包括接受用户输入的能力。

正如你在第 1 章中看到的，main 函数是程序的入口点：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

fn 语法声明了一个新函数；圆括号 () 表示没有参数；花括号 { 开始函数体。

正如你在第 1 章中也学到的，println! 是一个宏（macro），用于将字符串打印到屏幕：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

这段代码打印了一条提示信息，说明游戏的名称并请求用户输入。

使用变量存储值

接下来，我们将创建一个 变量（variable）来存储用户输入，如下所示：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

现在程序变得有趣了！这一小行代码中包含了很多内容。我们使用 let 语句来创建变量。下面是另一个例子：

let apples = 5;

这一行创建了一个名为 apples 的新变量，并将其绑定到值 5。在 Rust 中，变量默认是不可变的（immutable），这意味着一旦我们给变量赋值，该值就不会改变。我们将在第 3 章的\u201c变量与可变性\u201d 部分详细讨论这个概念。要使变量可变，我们在变量名之前添加 mut：

let apples = 5; // immutable
let mut bananas = 5; // mutable

注意：// 语法开始一个注释，该注释持续到行尾。Rust 会忽略注释中的所有内容。我们将在第 3 章 中更详细地讨论注释。

回到猜数字游戏程序，你现在知道 let mut guess 将引入一个名为 guess 的可变变量。等号（=）告诉 Rust 我们现在想将某些东西绑定到该变量。等号右侧是 guess 所绑定的值，即调用 String::new 的结果，该函数返回一个新的 String 实例。String 是标准库提供的一种字符串类型，是一种可增长的、UTF-8 编码的文本。

::new 行中的 :: 语法表示 new 是 String 类型的关联函数（associated function）。关联函数 是在类型上实现的函数，在本例中是 String 类型。这个 new 函数创建了一个新的空字符串。你会在许多类型上找到 new 函数，因为它是一种常见命名约定，用于创建某种类型的新值。

总的来说，let mut guess = String::new(); 这一行创建了一个可变变量，该变量当前绑定到一个新的空 String 实例。呼！

接收用户输入

回想一下，我们在程序的第一行使用 use std::io; 引入了标准库的输入/输出功能。现在我们将调用 io 模块中的 stdin 函数，这将允许我们处理用户输入：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

如果我们没有在程序开头使用 use std::io; 导入 io 模块，我们仍然可以通过将此函数调用写为 std::io::stdin 来使用该函数。stdin 函数返回一个 std::io::Stdin 实例，这是一种表示终端标准输入句柄的类型。

接下来，.read_line(&mut guess) 这一行调用了标准输入句柄上的 read_line 方法来获取用户输入。我们还将 &mut guess 作为参数传递给 read_line，告诉它将用户输入存储到哪个字符串中。read_line 的全部工作是将用户输入到标准输入中的任何内容追加到该字符串中（而不覆盖其内容），因此我们将该字符串作为参数传递。字符串参数需要是可变的，以便方法可以更改字符串的内容。

& 表示此参数是一个 引用（reference），它让你能够使代码的多个部分访问同一份数据，而无需多次将该数据复制到内存中。引用是一个复杂的功能，而 Rust 的主要优势之一就是使用引用既安全又容易。你不需要了解很多细节就能完成这个程序。现在，你只需要知道，像变量一样，引用默认也是不可变的。因此，你需要写 &mut guess 而不是 &guess 来使其可变。（第 4 章会更详细地解释引用。）

使用 Result 处理潜在的错误

我们还在处理这一行代码。我们现在正在讨论第三行文本，但请注意它仍然是单个逻辑代码行的一部分。下一部分是这个方法：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

我们本可以将这段代码写成：

io::stdin().read_line(&mut guess).expect("Failed to read line");

但是，一个长行难以阅读，所以最好将其拆分。当你使用 .method_name() 语法调用方法时，通常明智的做法是引入换行和其他空白来帮助分隔长行。现在让我们讨论这一行的作用。

如前所述，read_line 将用户输入的任何内容放入我们传递的字符串中，但它也会返回一个 Result 值。Result 是一个枚举（enumeration，通常称为 enum），它是一种可以有多种可能状态的类型。我们将每种可能的状态称为一个 变体（variant）。

第 6 章 将更详细地介绍枚举。这些 Result 类型的目的是编码错误处理信息。

Result 的变体是 Ok 和 Err。Ok 变体表示操作成功，并包含成功生成的值。Err 变体表示操作失败，并包含有关操作失败方式或原因的信息。

Result 类型的值，就像任何类型的值一样，都定义了方法。Result 实例有一个你可以调用的 expect 方法。如果这个 Result 实例是 Err 值，expect 将导致程序崩溃并显示你传递给 expect 作为参数的消息。如果 read_line 方法返回 Err，这很可能是底层操作系统出现错误的结果。如果这个 Result 实例是 Ok 值，expect 将获取 Ok 持有的返回值并仅将该值返回给你，以便你可以使用它。在这种情况下，该值是用户输入的字节数。

如果你不调用 expect，程序可以编译，但你会收到一个警告：

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
warning: unused `Result` that must be used
  --> src/main.rs:10:5
   |
10 |     io::stdin().read_line(&mut guess);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: `#[warn(unused_must_use)]` on by default
help: use `let _ = ...` to ignore the resulting value
   |
10 |     let _ = io::stdin().read_line(&mut guess);
   |     +++++++

warning: `guessing_game` (bin "guessing_game") generated 1 warning
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.59s

Rust 警告你没有使用 read_line 返回的 Result 值，表明程序没有处理可能的错误。

消除警告的正确方法是实际编写错误处理代码，但在我们的案例中，我们只希望在出现问题时使程序崩溃，因此我们可以使用 expect。你将在第 9 章 中学习如何从错误中恢复。

使用 println! 占位符打印值

除了右花括号之外，到目前为止的代码中还有一行需要讨论：

use std::io;

fn main() {
    println!("Guess the number!");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

这一行打印了现在包含用户输入的字符串。{} 花括号是一个占位符：可以将 {} 想象成小小的螃蟹钳子，它们将值固定在适当位置。打印变量的值时，变量名可以放在花括号内。打印表达式求值结果时，在格式字符串中放置空花括号，然后格式字符串后跟一个逗号分隔的表达式列表，按照相同的顺序打印到每个空花括号占位符中。在一次 println! 调用中打印变量和表达式的结果如下所示：

#![allow(unused)]
fn main() {
let x = 5;
let y = 10;

println!("x = {x} and y + 2 = {}", y + 2);
}

这段代码将打印 x = 5 and y + 2 = 12。

测试第一部分

让我们测试猜数字游戏的第一部分。使用 cargo run 运行它：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.44s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6

至此，游戏的第一部分完成了：我们从键盘获取输入然后打印出来。

生成一个秘密数字

接下来，我们需要生成一个秘密数字，玩家将尝试猜测它。秘密数字每次都应该不同，这样游戏才能多次玩耍仍然有趣。我们将使用 1 到 100 之间的随机数，这样游戏不会太难。Rust 的标准库中尚未包含随机数功能。但是，Rust 团队提供了一个包含此功能的 rand crate。

使用 crate 增加功能

记住，crate（包）是一个 Rust 源代码文件的集合。我们一直在构建的项目是一个二进制 crate（binary crate），它是一个可执行文件。rand crate 是一个库 crate（library crate），其中包含旨在用于其他程序的代码，不能独立执行。

Cargo 对外部 crate 的协调才是 Cargo 真正闪耀的地方。在我们可以编写使用 rand 的代码之前，需要修改 Cargo.toml 文件以将 rand crate 作为依赖包含进来。现在打开该文件，并在 Cargo 为你创建的 [dependencies] 部分标题下方添加以下行。请务必像我们这里一样精确指定 rand 及其版本号，否则本教程中的代码示例可能无法正常工作：

文件名: Cargo.toml

[dependencies]
rand = "0.8.5"

在 Cargo.toml 文件中，标题后的所有内容都是该部分的一部分，直到另一个部分开始。在 [dependencies] 中，你告诉 Cargo 你的项目依赖哪些外部 crate 以及你需要这些 crate 的哪些版本。在这种情况下，我们使用语义版本说明符 0.8.5 指定了 rand crate。Cargo 理解语义化版本（Semantic Versioning）（有时称为 SemVer），这是一种编写版本号的标准。说明符 0.8.5 实际上是 ^0.8.5 的简写，这意味着任何至少为 0.8.5 但低于 0.9.0 的版本。

Cargo 认为这些版本具有与 0.8.5 兼容的公共 API，并且此规范确保你将获得最新的补丁版本，该版本仍然可以与本章中的代码一起编译。任何 0.9.0 或更高版本都不能保证具有与以下示例相同的 API。

现在，在不更改任何代码的情况下，让我们构建项目，如清单 2-2 所示。

$ cargo build
  Updating crates.io index
   Locking 15 packages to latest Rust 1.85.0 compatible versions
    Adding rand v0.8.5 (available: v0.9.0)
 Compiling proc-macro2 v1.0.93
 Compiling unicode-ident v1.0.17
 Compiling libc v0.2.170
 Compiling cfg-if v1.0.0
 Compiling byteorder v1.5.0
 Compiling getrandom v0.2.15
 Compiling rand_core v0.6.4
 Compiling quote v1.0.38
 Compiling syn v2.0.98
 Compiling zerocopy-derive v0.7.35
 Compiling zerocopy v0.7.35
 Compiling ppv-lite86 v0.2.20
 Compiling rand_chacha v0.3.1
 Compiling rand v0.8.5
 Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
  Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.48s

你可能会看到不同的版本号（但由于 SemVer，它们都将与代码兼容！）和不同的行（取决于操作系统），并且行的顺序可能不同。

当我们包含一个外部依赖时，Cargo 会从 registry（注册表）获取该依赖所需的所有内容的最新版本，该注册表是来自 Crates.io 的数据副本。Crates.io 是 Rust 生态系统中的人们发布其开源 Rust 项目供他人使用的地方。

更新注册表后，Cargo 会检查 [dependencies] 部分，并下载任何尚未下载的已列出的 crate。在这种情况下，虽然我们只列出了 rand 作为依赖，但 Cargo 也获取了 rand 依赖的其他 crate 才能工作。下载完 crate 后，Rust 编译它们，然后编译可用的依赖项目。

如果你立即再次运行 cargo build 而不做任何更改，你将看不到除 Finished 行之外的任何输出。Cargo 知道它已经下载并编译了依赖项，并且你没有在 Cargo.toml 文件中更改它们。Cargo 也知道你没有更改任何代码，因此它也不会重新编译。无事可做，它就简单退出了。

如果你打开 src/main.rs 文件，做一个微不足道的更改，然后保存并再次构建，你将只看到两行输出：

$ cargo build
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s

这些行显示 Cargo 仅更新了构建，因为你对你对 src/main.rs 文件的小改动。你的依赖项没有改变，因此 Cargo 知道它可以重复使用已经下载和编译的内容。

确保可重现的构建

Cargo 有一个机制，可确保你或其他任何人每次构建代码时都能重建相同的工件：Cargo 将只使用你指定的依赖版本，直到你另有指示。例如，假设下周 rand crate 的 0.8.6 版本发布了，该版本包含一个重要错误修复，但也包含一个会破坏你的代码的回归。为了处理这种情况，Rust 会在你第一次运行 cargo build 时创建 Cargo.lock 文件，因此我们现在在 guessing_game 目录中有这个文件。

当你第一次构建项目时，Cargo 会找出符合条件的所有依赖版本，然后将它们写入 Cargo.lock 文件。当你将来构建项目时，Cargo 会看到 Cargo.lock 文件存在，并使用其中指定的版本，而不是重新做所有找出版本的工作。这让你自动获得可重现的构建。换句话说，多亏了 Cargo.lock 文件，你的项目将保持在 0.8.5 版本，直到你显式升级。由于 Cargo.lock 文件对于可重现的构建非常重要，它通常会与项目中的其余代码一起检入源代码管理。

更新 crate 以获取新版本

当你 确实 想要更新一个 crate 时，Cargo 提供了 update 命令，该命令将忽略 Cargo.lock 文件，并找出符合 Cargo.toml 中规范的所有最新版本。然后 Cargo 会将这些版本写入 Cargo.lock 文件。否则，默认情况下，Cargo 只会查找大于 0.8.5 且小于 0.9.0 的版本。如果 rand crate 发布了两个新版本 0.8.6 和 0.999.0，那么如果你运行 cargo update，你会看到以下内容：

$ cargo update
    Updating crates.io index
     Locking 1 package to latest Rust 1.85.0 compatible version
    Updating rand v0.8.5 -> v0.8.6 (available: v0.999.0)

Cargo 会忽略 0.999.0 版本。此时，你还会注意到 Cargo.lock 文件中的更改，表明你现在使用的 rand crate 版本是 0.8.6。要使用 rand 版本 0.999.0 或 0.999.x 系列中的任何版本，你需要将 Cargo.toml 文件更新为如下所示（不要实际进行此更改，因为以下示例假定你使用的是 rand 0.8）：

[dependencies]
rand = "0.999.0"

下次运行 cargo build 时，Cargo 将更新可用 crate 的注册表，并根据你指定的新版本重新评估你的 rand 需求。

关于 Cargo 及其生态系统，还有很多要说的，我们将在第 14 章讨论，但现在，这就是你需要知道的一切。Cargo 使得重用库变得非常容易，因此 Rustaceans 能够编写由多个包组装而成的更小项目。

生成一个随机数

让我们开始使用 rand 来生成一个要猜测的数字。下一步是更新 src/main.rs，如清单 2-3 所示。

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

首先，我们添加一行 use rand::Rng;。Rng trait（特征）定义了随机数生成器实现的方法，并且这个 trait 必须在作用域内，我们才能使用这些方法。第 10 章将详细介绍 trait。

接下来，我们在中间添加了两行。在第一行中，我们调用 rand::thread_rng 函数，该函数提供我们将要使用的特定随机数生成器：一个当前执行线程本地且由操作系统提供种子的生成器。然后，我们在随机数生成器上调用 gen_range 方法。这个方法由 Rng trait 定义，我们通过 use rand::Rng; 语句将其引入作用域。gen_range 方法接受一个范围表达式作为参数，并生成该范围内的一个随机数。我们在这里使用的范围表达式形式为 start..=end，包括上下限，因此我们需要指定 1..=100 来请求一个 1 到 100 之间的数字。

注意：你不会仅仅知道要使用哪些 trait 以及要从 crate 调用哪些方法和函数，因此每个 crate 都有带有使用说明的文档。Cargo 的另一个巧妙功能是运行 cargo doc --open 命令将在本地构建所有依赖项提供的文档，并在你的浏览器中打开它。例如，如果你对 rand crate 中的其他功能感兴趣，请运行 cargo doc --open 并单击左侧边栏中的 rand。

第二行新代码打印了秘密数字。这在开发程序时用于测试非常有用，但我们将在最终版本中删除它。如果程序一开始就打印答案，那就不太像游戏了！

尝试运行该程序几次：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 7
Please input your guess.
4
You guessed: 4

$ cargo run
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.02s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 83
Please input your guess.
5
You guessed: 5

你应该得到不同的随机数，而且它们都应该是 1 到 100 之间的数字。干得漂亮！

比较猜测与秘密数字

现在我们已经有了用户输入和一个随机数，可以比较它们了。这一步如清单 2-4 所示。请注意，这段代码暂时还不能编译，我们接下来会解释。

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    // --snip--
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

首先，我们添加另一个 use 语句，将标准库中一个名为 std::cmp::Ordering 的类型引入作用域。Ordering 类型是另一个枚举（enum），具有 Less、Greater 和 Equal 三个变体（variants）。这是比较两个值时可能出现的三种结果。

然后，我们在底部添加了五行新代码，使用了 Ordering 类型。cmp 方法比较两个值，可以在任何可比较的内容上调用。它接受一个对你想要比较的值的引用：在这里，它比较 guess 和 secret_number。然后，它返回我们通过 use 语句引入作用域的 Ordering 枚举的一个变体。我们使用一个 match 表达式来决定接下来做什么，基于调用 cmp 比较 guess 和 secret_number 的值后返回的 Ordering 变体。

一个 match 表达式由 分支（arms）组成。每个分支包含一个要匹配的 模式（pattern），以及当提供给 match 的值匹配该分支的模式时应运行的代码。Rust 获取提供给 match 的值，然后依次检查每个分支的模式。模式和 match 结构是强大的 Rust 特性：它们让你能够表达代码可能遇到的各种情况，并确保你处理了所有情况。这些特性将分别在第 6 章和第 19 章详细介绍。

让我们通过这里使用的 match 表达式来举例说明。假设用户猜了 50，而此次随机生成的秘密数字是 38。

当代码比较 50 和 38 时，cmp 方法将返回 Ordering::Greater，因为 50 大于 38。match 表达式获取 Ordering::Greater 值并开始检查每个分支的模式。它查看第一个分支的模式 Ordering::Less，发现值 Ordering::Greater 不匹配 Ordering::Less，因此忽略该分支中的代码并移至下一个分支。下一个分支的模式是 Ordering::Greater，它 确实 匹配了 Ordering::Greater！该分支中的关联代码将执行并在屏幕上打印 Too big!。match 表达式在第一个成功匹配后结束，因此在这种场景下它不会查看最后一个分支。

然而，清单 2-4 中的代码还不能编译。让我们试试：

$ cargo build
   Compiling libc v0.2.86
   Compiling getrandom v0.2.2
   Compiling cfg-if v1.0.0
   Compiling ppv-lite86 v0.2.10
   Compiling rand_core v0.6.2
   Compiling rand_chacha v0.3.0
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
error[E0308]: mismatched types
  --> src/main.rs:23:21
   |
23 |     match guess.cmp(&secret_number) {
   |                 --- ^^^^^^^^^^^^^^ expected `&String`, found `&{integer}`
   |                 |
   |                 arguments to this method are incorrect
   |
   = note: expected reference `&String`
              found reference `&{integer}`
note: method defined here
  --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/cmp.rs:979:8

For more information about this error, try `rustc --explain E0308`.
error: could not compile `guessing_game` (bin "guessing_game") due to 1 previous error

错误的核心表明存在 类型不匹配（mismatched types）。Rust 拥有强大的静态类型系统。然而，它也有类型推断（type inference）。当我们写 let mut guess = String::new() 时，Rust 能够推断出 guess 应该是一个 String，而不需要我们写出类型。而 secret_number 则是一个数字类型。Rust 的几种数字类型可以具有 1 到 100 之间的值：i32（32 位数字）、u32（无符号 32 位数字）、i64（64 位数字）等等。除非另有指定，Rust 默认使用 i32，这就是 secret_number 的类型，除非你在其他地方添加了类型信息导致 Rust 推断出不同的数字类型。错误的原因是 Rust 无法比较字符串和数字类型。

最终，我们想要将程序读取为输入的 String 转换为数字类型，以便我们可以将其与秘密数字进行数值比较。我们通过在 main 函数体中添加这一行来实现：

文件名: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    // --snip--

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

这一行是：

let guess: u32 = guess.trim().parse().expect("Please type a number!");

我们创建了一个名为 guess 的变量。但是等等，程序中不是已经有一个名为 guess 的变量了吗？是的，但 Rust 允许我们用新值覆盖 guess 的旧值，这很有用。遮蔽（Shadowing）让我们可以重用 guess 变量名，而不必强迫我们创建两个不同的变量，例如 guess_str 和 guess。我们将在第 3 章 中更详细地介绍这一点，但现在，要知道这个特性在你想要将值从一种类型转换为另一种类型时经常使用。

我们将这个新变量绑定到表达式 guess.trim().parse()。表达式中的 guess 指的是包含输入字符串的原始 guess 变量。String 实例上的 trim 方法将消除开头和结尾的任何空白，在将字符串转换为只能包含数字数据的 u32 之前，我们必须这样做。用户必须按下 enter 才能满足 read_line 并输入他们的猜测，这会在字符串中添加一个换行符。例如，如果用户输入 5 并按下 enter，guess 看起来像这样：5\n。\n 表示换行符（newline）。（在 Windows 上，按下 enter 会产生一个回车符和一个换行符，\r\n。）trim 方法会消除 \n 或 \r\n，结果只剩下 5。

字符串上的 parse 方法 将字符串转换为另一种类型。在这里，我们用它从字符串转换为数字。我们需要通过 let guess: u32 告诉 Rust 我们想要的精确数字类型。guess 后面的冒号（:）告诉 Rust 我们要标注变量的类型。Rust 有几种内置的数字类型；这里看到的 u32 是一个无符号 32 位整数。对于小的正数来说，这是一个很好的默认选择。你将在第 3 章 中了解其他数字类型。

此外，这个示例程序中的 u32 标注以及与 secret_number 的比较意味着 Rust 将推断 secret_number 也应该是 u32。所以，现在比较将在两个相同类型的值之间进行！

parse 方法只对可以逻辑转换为数字的字符有效，因此很容易导致错误。例如，如果字符串包含 A👍%，则无法将其转换为数字。因为它可能会失败，parse 方法返回一个 Result 类型，很像 read_line 方法（前面在“使用 Result 处理潜在的错误” 中讨论过）。我们将以同样的方式通过再次使用 expect 方法来处理这个 Result。如果 parse 因为无法从字符串创建数字而返回 Err Result 变体，expect 调用将使游戏崩溃并打印我们给它的消息。如果 parse 成功将字符串转换为数字，它将返回 Result 的 Ok 变体，而 expect 将返回我们想要从 Ok 值中获取的数字。

让我们现在运行程序：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.26s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
  76
You guessed: 76
Too big!

太棒了！即使在猜测前添加了空格，程序仍然能判断出用户猜了 76。多次运行程序以验证不同类型输入的不同行为：猜对数字、猜一个太大的数字、猜一个太小的数字。

现在游戏大部分已经可以运行了，但用户只能猜一次。让我们通过添加循环来改变这一点！

使用循环允许多次猜测

loop 关键字创建了一个无限循环。我们将添加一个循环，给用户更多猜测数字的机会：

文件名: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    // --snip--

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        // --snip--


        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => println!("You win!"),
        }
    }
}

如你所见，我们将从猜测输入提示开始的所有内容移到了一个循环中。确保将循环内的行再缩进四个空格，然后再次运行程序。程序现在会永远要求再猜一次，这实际上引入了一个新问题。用户似乎无法退出！

用户总是可以通过键盘快捷键 ctrl-C 中断程序。但还有另一种方法可以逃离这个永不满足的怪物，正如在 parse 讨论中提到的“比较猜测与秘密数字”：如果用户输入一个非数字的回答，程序将崩溃。我们可以利用这一点来允许用户退出，如下所示：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 59
Please input your guess.
45
You guessed: 45
Too small!
Please input your guess.
60
You guessed: 60
Too big!
Please input your guess.
59
You guessed: 59
You win!
Please input your guess.
quit

thread 'main' panicked at src/main.rs:28:47:
Please type a number!: ParseIntError { kind: InvalidDigit }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

输入 quit 将退出游戏，但你会注意到，输入任何其他非数字输入也会退出。至少可以说这不太理想；我们希望在猜对数字时游戏也能停止。

猜对后退出

让我们通过在用户获胜时添加 break 语句来编程让游戏退出：

文件名: src/main.rs

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = guess.trim().parse().expect("Please type a number!");

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

在 You win! 之后添加 break 行使得程序在用户猜对秘密数字时退出循环。退出循环也意味着退出程序，因为循环是 main 的最后一部分。

处理无效输入

为了进一步优化游戏的行为，我们让游戏忽略非数字输入，而不是在用户输入非数字时使程序崩溃，这样用户可以继续猜测。我们可以通过修改将 guess 从 String 转换为 u32 的那一行来实现，如清单 2-5 所示。

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        // --snip--

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        // --snip--

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

我们将 expect 调用切换为 match 表达式，从出错时崩溃转变为处理错误。回想一下，parse 返回一个 Result 类型，而 Result 是一个枚举，具有 Ok 和 Err 变体。我们在这里使用了 match 表达式，就像我们对 cmp 方法的 Ordering 结果所做的那样。

如果 parse 能够成功地将字符串转换为数字，它将返回一个包含结果数字的 Ok 值。该 Ok 值将匹配第一个分支的模式，match 表达式将直接返回 parse 产生并放入 Ok 值中的 num 值。该数字将正好位于我们在新创建的 guess 变量中想要的位置。

如果 parse 不能 将字符串转换为数字，它将返回一个包含有关错误的更多信息的 Err 值。Err 值不匹配第一个 match 分支中的 Ok(num) 模式，但它确实匹配第二个分支中的 Err(_) 模式。下划线 _ 是一个通配符（catch-all value）；在这个例子中，我们说我们想要匹配所有 Err 值，无论它们内部包含什么信息。因此，程序将执行第二个分支的代码 continue，这告诉程序进入 loop 的下一次迭代并请求另一个猜测。所以，实际上，程序忽略了 parse 可能遇到的所有错误！

现在程序中的所有内容都应该按预期工作了。让我们试试：

$ cargo run
   Compiling guessing_game v0.1.0 (file:///projects/guessing_game)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.13s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 61
Please input your guess.
10
You guessed: 10
Too small!
Please input your guess.
99
You guessed: 99
Too big!
Please input your guess.
foo
Please input your guess.
61
You guessed: 61
You win!

太棒了！再做一个小小的最后调整，我们就完成了猜数字游戏。回想一下，程序仍然在打印秘密数字。这在测试时效果很好，但会破坏游戏。让我们删除输出秘密数字的 println!。清单 2-6 显示了最终代码。

use std::cmp::Ordering;
use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        println!("You guessed: {guess}");

        match guess.cmp(&secret_number) {
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

至此，你已经成功构建了猜数字游戏。恭喜！

总结

这个项目是一个动手实践的方式，向你介绍了许多新的 Rust 概念：let、match、函数、使用外部 crate 等等。在接下来的几章中，你将更详细地学习这些概念。第 3 章涵盖大多数编程语言都有的概念，例如变量、数据类型和函数，并展示如何在 Rust 中使用它们。第 4 章探讨所有权（ownership），这是使 Rust 与其他语言不同的一个特性。第 5 章讨论结构体（structs）和方法语法，第 6 章解释枚举（enums）如何工作。

通用编程概念

本章涵盖了几乎所有编程语言中都出现的概念以及它们在 Rust 中的工作方式。许多编程语言在核心上有许多共同之处。本章中介绍的概念都不是 Rust 独有的，但我们将在 Rust 的背景下讨论它们，并解释使用它们的惯例。

具体来说，你将学习变量（variables）、基本类型（basic types）、函数（functions）、注释（comments）和控制流（control flow）。这些基础将会出现在每一个 Rust 程序中，尽早学习它们将为你打下坚实的基础。

变量与可变性

变量（Variables）与可变性（Mutability）

正如在“使用变量存储值”一节中提到的，默认情况下， 变量（variables）是不可变的（immutable）。这是 Rust 引导你利用其提供的安全性和轻松并发（concurrency）优势来编写代码的众多方式之一。 不过，你仍然可以选择让变量变为可变的（mutable）。 让我们来探讨 Rust 为何以及如何鼓励你倾向于使用不可变性（immutability），以及为什么有时你可能想要选择不使用它。

当一个变量不可变时，一旦值被绑定（bound）到一个名字上，你就无法改变 该值。为了说明这一点，在你的 projects 目录下使用 cargo new variables 生成一个名为 variables 的新项目。

然后，在你的新 variables 目录中，打开 src/main.rs 并将其代码替换为 以下代码，这段代码暂时还无法编译：

文件名：src/main.rs

fn main() {
    let x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

使用 cargo run 保存并运行该程序。你应该会收到一条关于 不可变性（immutability）错误的错误信息，如下所示：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0384]: cannot assign twice to immutable variable `x`
 --> src/main.rs:4:5
  |
2 |     let x = 5;
  |         - first assignment to `x`
3 |     println!("The value of x is: {x}");
4 |     x = 6;
  |     ^^^^^ cannot assign twice to immutable variable
  |
help: consider making this binding mutable
  |
2 |     let mut x = 5;
  |         +++

For more information about this error, try `rustc --explain E0384`.
error: could not compile `variables` (bin "variables") due to 1 previous error

这个例子展示了编译器如何帮助你找到程序中的错误。 编译器错误可能会令人沮丧，但实际上它们只是意味着你的程序 还没有安全地完成你想要它做的事情；它们并 不 意味着你不是 一个优秀的程序员！经验丰富的 Rustaceans 也会遇到编译器错误。

你收到的错误信息是 cannot assign twice to immutable variable `x`（不能对不可变变量 x 二次赋值），因为你试图给不可变的 x 变量赋予第二个值。

当我们试图更改一个被指定为不可变的值时，能够在编译时（compile-time）得到错误是很重要的，因为这种情况正是 bug（程序错误）的源头。如果代码的一部分假定某个值永远不会改变，而另一部分代码改变了该值，那么第一部分代码可能就无法按预期工作了。这类 bug 的原因在事后很难追踪，尤其是当第二段代码只是 有时 改变该值时。Rust 编译器保证，当你声明一个值不会改变时，它就真的不会改变，因此你无需自己追踪它。你的代码因此 更易于推理（reason）。

但是可变性（mutability）可能非常有用，并且可以让代码编写起来更便捷。 虽然变量默认是不可变的，但你仍然可以通过在变量名前添加 mut 来使其可变，就像你在第 2 章中所做的那样。添加 mut 还向未来的代码阅读者传达了意图，表明代码的其他部分将会改变这个变量的值。

例如，让我们将 src/main.rs 改为以下内容：

文件名：src/main.rs

fn main() {
    let mut x = 5;
    println!("The value of x is: {x}");
    x = 6;
    println!("The value of x is: {x}");
}

现在当我们运行这个程序时，会得到如下输出：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/variables`
The value of x is: 5
The value of x is: 6

当使用了 mut 时，我们可以将绑定到 x 的值从 5 改为 6。 最终，是否使用可变性取决于你，以及你认为在特定情况下哪种方式最清晰。

声明常量（Constants）

与不可变变量类似，常量（constants） 也是绑定到名字上且不允许改变的值，但常量与变量之间有几个不同之处。

首先，不允许对常量使用 mut。常量不仅仅是默认不可变——它们始终不可变。声明常量使用 const 关键字而不是 let 关键字，并且 必须 标注值的类型。我们将在下一节 “数据类型”中介绍类型和类型注解（type annotations），所以现在不必担心细节。只需知道你必须始终标注类型。

常量可以在任何作用域（scope）中声明，包括全局作用域（global scope），这使得它们对于代码中许多部分都需要知道的值非常有用。

最后一个区别是，常量只能设置为常量表达式（constant expression），而不能设置为只能在运行时计算得出的值。

以下是一个常量声明的示例：

#![allow(unused)]
fn main() {
const THREE_HOURS_IN_SECONDS: u32 = 60 * 60 * 3;
}

该常量的名称为 THREE_HOURS_IN_SECONDS，其值被设置为 60（一分钟的秒数）乘以 60（一小时的分钟数）再乘以 3（我们想计算的程序中的小时数）的结果。Rust 的常量命名约定（naming convention）是全部使用大写字母，单词之间用下划线分隔。编译器能够在编译时（compile time）评估有限的一组操作，这让我们可以选择以一种更易于理解和验证的方式写出这个值，而不是将该常量直接设置为 10,800。有关声明常量时可以使用哪些操作的更多信息，请参阅 Rust 参考手册中关于常量求值的部分。

常量在其声明的整个作用域内，在程序运行的整个过程都有效。这一特性使得常量对于应用程序域中多个部分可能需要知道的值非常有用，例如游戏中任何玩家允许获得的最高分数，或者光速。

将程序中使用的硬编码（hardcoded）值命名为常量，有助于向未来的代码维护者传达该值的含义。如果将来需要更新这个硬编码的值，它也只需修改代码中的一个地方即可。

隐藏（Shadowing）

正如你在第 2 章的猜谜游戏教程中看到的，你可以声明一个与之前变量同名的新变量。Rustaceans 说第一个变量被第二个变量 隐藏（shadowed） 了，这意味着当你使用该变量名时，编译器将看到的是第二个变量。实际上，第二个变量遮蔽（overshadows）了第一个变量，将变量名的所有使用都指向自身，直到它自己被隐藏或作用域结束。我们可以通过使用相同的变量名并重复使用 let 关键字来隐藏变量，如下所示：

文件名：src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

    {
        let x = x * 2;
        println!("The value of x in the inner scope is: {x}");
    }

    println!("The value of x is: {x}");
}

这个程序首先将 x 绑定到值 5。然后，通过重复 let x = 创建了一个新的变量 x，将原始值加上 1，使得 x 的值变为 6。接着，在用花括号创建的内部作用域（inner scope）中，第三个 let 语句也隐藏了 x 并创建了一个新变量，将之前的值乘以 2，使 x 的值为 12。当该作用域结束时，内部隐藏结束，x 恢复为 6。当我们运行这个程序时，它会输出以下内容：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/variables`
The value of x in the inner scope is: 12
The value of x is: 6

隐藏（shadowing）与将变量标记为 mut 不同，因为如果我们不小心尝试在不使用 let 关键字的情况下重新赋值给这个变量，就会得到一个编译时错误。通过使用 let，我们可以对一个值进行几次变换（transformations），但在这些变换完成后，变量仍然保持不可变。

mut 与隐藏之间的另一个区别是，由于我们在再次使用 let 关键字时实际上是创建了一个新变量，因此我们可以改变值的类型（type），同时复用相同的名称。例如，假设我们的程序要求用户通过输入空格字符来显示他们希望在文本之间有多少空格，然后我们希望将该输入存储为一个数字：

fn main() {
    let spaces = "   ";
    let spaces = spaces.len();
}

第一个 spaces 变量是字符串（string）类型，第二个 spaces 变量是数字（number）类型。因此，隐藏使我们不必想出不同的名称，比如 spaces_str 和 spaces_num；相反，我们可以复用更简单的 spaces 名称。然而，如果我们尝试对此使用 mut，如下所示，就会得到一个编译时错误：

fn main() {
    let mut spaces = "   ";
    spaces = spaces.len();
}

错误信息表明我们不允许改变变量的类型：

$ cargo run
   Compiling variables v0.1.0 (file:///projects/variables)
error[E0308]: mismatched types
 --> src/main.rs:3:14
  |
2 |     let mut spaces = "   ";
  |                      ----- expected due to this value
3 |     spaces = spaces.len();
  |              ^^^^^^^^^^^^ expected `&str`, found `usize`

For more information about this error, try `rustc --explain E0308`.
error: could not compile `variables` (bin "variables") due to 1 previous error

现在我们已经探讨了变量的工作方式，接下来让我们看看变量可以拥有的更多数据类型（data types）。

数据类型

数据类型（Data Types）

Rust 中的每个值都属于某种特定的数据类型（data type），这告诉 Rust 它所处理的是哪种数据，从而知道该如何处理这些数据。我们将讨论两种数据类型子集：标量类型（scalar）和复合类型（compound）。

请记住，Rust 是一门静态类型（statically typed）语言，这意味着它在编译时必须知道所有变量的类型。编译器通常可以根据值及其使用方式推断出我们想使用的类型。在可能存在多种类型的情况下，例如我们在第 2 章的“将猜测的数字与秘密数字进行比较”章节中，使用 parse 将 String 转换为数值类型时，我们必须添加一个类型注解（type annotation），如下所示：

#![allow(unused)]
fn main() {
let guess: u32 = "42".parse().expect("Not a number!");
}

如果我们在前面的代码中没有添加 : u32 类型注解，Rust 将显示以下错误，这意味着编译器需要更多信息来确定我们想要使用哪种类型：

$ cargo build
   Compiling no_type_annotations v0.1.0 (file:///projects/no_type_annotations)
error[E0284]: type annotations needed
 --> src/main.rs:2:9
  |
2 |     let guess = "42".parse().expect("Not a number!");
  |         ^^^^^        ----- type must be known at this point
  |
  = note: cannot satisfy `<_ as FromStr>::Err == _`
help: consider giving `guess` an explicit type
  |
2 |     let guess: /* Type */ = "42".parse().expect("Not a number!");
  |              ++++++++++++

For more information about this error, try `rustc --explain E0284`.
error: could not compile `no_type_annotations` (bin "no_type_annotations") due to 1 previous error

对于其他数据类型，你也会看到不同的类型注解。

标量类型（Scalar Types）

标量（scalar）类型表示单个值。Rust 有四种主要的标量类型：整数（integer）、浮点数（floating-point number）、布尔值（Boolean）和字符（character）。你可能从其他编程语言中认识它们。让我们来看看它们在 Rust 中是如何工作的。

整数类型（Integer Types）

整数（integer）是一个没有小数部分的数字。我们在第 2 章中使用了一种整数类型 u32。这种类型声明表明与其关联的值应该是一个占用 32 位空间的无符号整数（有符号整数类型以 i 开头，而不是 u）。表 3-1 展示了 Rust 中内置的整数类型。我们可以使用其中任何一种变体来声明整数值的类型。

表 3-1：Rust 中的整数类型

每种变体可以是有符号（signed）或无符号（unsigned），并且具有明确的大小。有符号（signed）和无符号（unsigned）指的是数字是否可能为负数——换句话说，就是数字是否需要带符号（有符号），还是它只会是正数因此可以不带符号表示（无符号）。这就像在纸上写数字：当符号很重要时，数字会带有加号或减号；然而，当可以安全地假定数字为正数时，就会不带符号显示。有符号数以补码形式存储。

每个有符号变体可以存储从 −(2^{n − 1}) 到 2^{n − 1} − 1（含）的数字，其中 n 是该变体使用的位数。因此，i8 可以存储从 −(2⁷) 到 2⁷ − 1 的数字，即 −128 到 127。无符号变体可以存储从 0 到 2ⁿ − 1 的数字，因此 u8 可以存储从 0 到 2⁸ − 1 的数字，即 0 到 255。

此外，isize 和 usize 类型取决于程序所运行的计算机架构：在 64 位架构上是 64 位，在 32 位架构上是 32 位。

你可以用表 3-2 中所示的任何一种形式来书写整数字面量（integer literal）。请注意，可以属于多种数值类型的数字字面量允许使用类型后缀（type suffix），例如 57u8，来指定类型。数字字面量还可以使用 _ 作为视觉分隔符，使数字更易于阅读，例如 1_000，它与指定 1000 具有相同的值。

表 3-2：Rust 中的整数字面量

那么如何知道该使用哪种整数类型呢？如果你不确定，Rust 的默认值通常是不错的起点：整数类型默认为 i32。使用 isize 或 usize 的主要情况是在对某种集合进行索引时。

浮点类型（Floating-Point Types）

Rust 还有两种浮点数（floating-point numbers）的原始类型，即带有小数点的数字。Rust 的浮点类型是 f32 和 f64，分别占 32 位和 64 位。默认类型是 f64，因为在现代 CPU 上，它的速度与 f32 大致相同，但精度更高。所有浮点类型都是有符号的。

下面是一个展示浮点数用法的示例：

文件名（Filename）: src/main.rs

fn main() {
    let x = 2.0; // f64

    let y: f32 = 3.0; // f32
}

浮点数按照 IEEE-754 标准表示。

数值运算（Numeric Operations）

Rust 支持你对所有数字类型所期望的基本数学运算：加法（addition）、减法（subtraction）、乘法（multiplication）、除法（division）和取余（remainder）。整数除法会向零截断（truncates toward zero）到最接近的整数。以下代码展示了如何在 let 语句中使用每种数值运算：

文件名（Filename）: src/main.rs

fn main() {
    // addition
    let sum = 5 + 10;

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

    // division
    let quotient = 56.7 / 32.2;
    let truncated = -5 / 3; // Results in -1

    // remainder
    let remainder = 43 % 5;
}

这些语句中的每个表达式都使用一个数学运算符，并求值为单个值，然后绑定到一个变量。附录 B包含了 Rust 提供的所有运算符的列表。

布尔类型（The Boolean Type）

与大多数其他编程语言一样，Rust 中的布尔类型有两个可能的值：true 和 false。布尔值的大小为一个字节。Rust 中的布尔类型使用 bool 指定。例如：

文件名（Filename）: src/main.rs

fn main() {
    let t = true;

    let f: bool = false; // with explicit type annotation
}

使用布尔值的主要方式是通过条件表达式，例如 if 表达式。我们将在“控制流”章节中介绍 if 表达式在 Rust 中是如何工作的。

字符类型（The Character Type）

Rust 的 char 类型是该语言最原始的字母类型。以下是一些声明 char 值的示例：

文件名（Filename）: src/main.rs

fn main() {
    let c = 'z';
    let z: char = 'ℤ'; // with explicit type annotation
    let heart_eyed_cat = '😻';
}

需要注意的是，我们使用单引号指定 char 字面量，而字符串字面量则使用双引号。Rust 的 char 类型大小为 4 字节，表示一个 Unicode 标量值（Unicode scalar value），这意味着它可以表示比 ASCII 多得多的内容。重音字母；中文、日文和韩文字符；表情符号（emoji）；以及零宽空格（zero-width space）在 Rust 中都是有效的 char 值。Unicode 标量值的范围是从 U+0000 到 U+D7FF 以及从 U+E000 到 U+10FFFF（含）。然而，“字符”在 Unicode 中并不是一个真正的概念，所以你对“字符”的人类直觉可能与 Rust 中的 char 并不完全一致。我们将在第 8 章的“使用字符串存储 UTF-8 编码的文本”中详细讨论这个主题。

复合类型（Compound Types）

复合类型（Compound types）可以将多个值组合成一个类型。Rust 有两种原始的复合类型：元组（tuple）和数组（array）。

元组类型（The Tuple Type）

元组（tuple）是一种将多个不同类型的值组合成一个复合类型的通用方式。元组具有固定长度：一旦声明，它们不能增长或缩小。

我们通过编写一个括号内的逗号分隔的值列表来创建元组。元组中的每个位置都有一个类型，并且元组中不同值的类型不必相同。在这个示例中，我们添加了可选的类型注解：

文件名（Filename）: src/main.rs

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
}

变量 tup 绑定到整个元组，因为元组被认为是一个单一的复合元素。要从元组中取出各个值，我们可以使用模式匹配（pattern matching）来解构（destructure）元组值，如下所示：

文件名（Filename）: src/main.rs

fn main() {
    let tup = (500, 6.4, 1);

    let (x, y, z) = tup;

    println!("The value of y is: {y}");
}

这个程序首先创建一个元组并将其绑定到变量 tup。然后它使用带有 let 的模式来获取 tup 并将其转换为三个独立的变量 x、y 和 z。这被称为解构（destructuring），因为它将单个元组拆分为三个部分。最后，程序打印 y 的值，即 6.4。

我们还可以直接使用句点（.）后跟要访问的值的索引来访问元组元素。例如：

文件名（Filename）: src/main.rs

fn main() {
    let x: (i32, f64, u8) = (500, 6.4, 1);

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

这个程序创建了元组 x，然后使用各自的索引访问元组的每个元素。与大多数编程语言一样，元组中的第一个索引是 0。

没有任何值的元组有一个特殊的名称，即单元（unit）。这个值及其对应的类型都写作 ()，表示一个空值或空返回类型。如果表达式不返回任何其他值，则隐式返回单元值。

数组类型（The Array Type）

另一种拥有多个值的集合方式是使用数组（array）。与元组不同，数组中的每个元素必须具有相同的类型。与其他一些编程语言中的数组不同，Rust 中的数组具有固定长度。

我们以方括号内的逗号分隔列表的形式来编写数组的值：

文件名（Filename）: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];
}

当你希望数据分配在栈（stack）上而不是堆（heap）上时（我们将在第 4 章中更详细地讨论栈和堆），或者当你希望确保始终有固定数量的元素时，数组非常有用。不过，数组不像 vector（向量）类型那样灵活。vector 是标准库提供的一种类似的集合类型，它的大小是允许增长或缩小的，因为其内容位于堆上。如果你不确定应该使用数组还是 vector，那么很可能应该使用 vector。第 8 章会更详细地讨论 vector。

然而，当你确定元素的数量不需要改变时，数组更有用。例如，如果你在程序中使用月份的名称，你可能更倾向于使用数组而不是 vector，因为你清楚它总是包含 12 个元素：

#![allow(unused)]
fn main() {
let months = ["January", "February", "March", "April", "May", "June", "July",
              "August", "September", "October", "November", "December"];
}

你可以使用方括号来编写数组的类型，其中包含每个元素的类型、分号以及数组中的元素数量，如下所示：

#![allow(unused)]
fn main() {
let a: [i32; 5] = [1, 2, 3, 4, 5];
}

这里，i32 是每个元素的类型。分号后面的数字 5 表示数组包含五个元素。

你还可以通过指定初始值，后跟分号，然后在方括号中指定数组的长度，来将数组初始化为每个元素都包含相同的值，如下所示：

#![allow(unused)]
fn main() {
let a = [3; 5];
}

名为 a 的数组将包含 5 个元素，这些元素最初都将被设置为值 3。这与编写 let a = [3, 3, 3, 3, 3]; 相同，但写法更简洁。

访问数组元素（Array Element Access）

数组是一块已知固定大小的连续内存，可以在栈上分配。你可以使用索引来访问数组中的元素，如下所示：

文件名（Filename）: src/main.rs

fn main() {
    let a = [1, 2, 3, 4, 5];

    let first = a[0];
    let second = a[1];
}

在这个示例中，名为 first 的变量将获得值 1，因为这是数组中索引 [0] 处的值。名为 second 的变量将从数组中的索引 [1] 获得值 2。

无效的数组元素访问（Invalid Array Element Access）

让我们看看如果尝试访问超出数组末尾的元素会发生什么。假设你运行这段代码（类似于第 2 章中的猜数游戏），从用户那里获取一个数组索引：

文件名（Filename）: src/main.rs

use std::io;

fn main() {
    let a = [1, 2, 3, 4, 5];

    println!("Please enter an array index.");

    let mut index = String::new();

    io::stdin()
        .read_line(&mut index)
        .expect("Failed to read line");

    let index: usize = index
        .trim()
        .parse()
        .expect("Index entered was not a number");

    let element = a[index];

    println!("The value of the element at index {index} is: {element}");
}

这段代码可以成功编译。如果你使用 cargo run 运行这段代码并输入 0、1、2、3 或 4，程序会打印出数组中该索引处的相应值。如果你输入一个超出数组末尾的数字，例如 10，你将看到类似如下的输出：

thread 'main' panicked at src/main.rs:19:19:
index out of bounds: the len is 5 but the index is 10
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

程序在使用无效值进行索引操作时发生了运行时错误。程序退出并显示一条错误消息，且没有执行最后的 println! 语句。当你尝试使用索引访问元素时，Rust 会检查你指定的索引是否小于数组长度。如果索引大于或等于长度，Rust 将发生恐慌（panic）。这个检查必须在运行时进行，尤其是在这种情况下，因为编译器无法知道用户稍后运行代码时会输入什么值。

这是 Rust 内存安全原则的实际体现。在许多底层语言中，不会进行这种检查，当你提供不正确的索引时，可能会访问到无效的内存。Rust 通过立即退出而不是允许内存访问并继续执行，来保护你免受此类错误的影响。第 9 章将进一步讨论 Rust 的错误处理，以及如何编写既不会恐慌也不会允许无效内存访问的可读、安全的代码。

函数

函数（Functions）

函数（Functions）在 Rust 代码中随处可见。你已经见过这门语言中最重要的函数之一：main 函数，它是许多程序的入口点（entry point）。你也见过 fn 关键字，它用来声明新函数。

Rust 代码使用 蛇形命名法（snake case） 作为函数和变量名称的常规风格，即所有字母都是小写，单词之间用下划线分隔。下面是一个包含示例函数定义的程序：

文件名：src/main.rs

fn main() {
    println!("Hello, world!");

    another_function();
}

fn another_function() {
    println!("Another function.");
}

在 Rust 中，我们通过输入 fn 后跟函数名和一对圆括号来定义函数。花括号告诉编译器函数体（function body）的开始和结束位置。

我们可以通过输入函数名后跟一对圆括号来调用任何已定义的函数。因为 another_function 在程序中被定义了，所以它可以从 main 函数内部被调用。注意，我们在源代码中是在 main 函数 之后 定义 another_function 的；我们也可以将其定义在之前。Rust 不关心你在哪里定义函数，只要它们定义在调用者能看到的某个作用域（scope）中即可。

让我们新建一个名为 functions 的二进制项目（binary project）来进一步探索函数。将 another_function 示例放入 src/main.rs 中并运行它。你应该会看到以下输出：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.28s
     Running `target/debug/functions`
Hello, world!
Another function.

各行代码按照它们在 main 函数中出现的顺序执行。首先打印 “Hello, world!” 消息，然后调用 another_function 并打印其消息。

参数（Parameters）

我们可以定义带有 参数（parameters） 的函数，参数是函数签名（signature）的一部分的特殊变量。当一个函数有参数时，你可以为这些参数提供具体的值。从技术上讲，这些具体的值被称为 实参（arguments），但在日常交流中，人们往往会混用 parameter 和 argument 这两个词来指代函数定义中的变量或调用函数时传入的具体值。

在这个版本的 another_function 中，我们添加了一个参数：

文件名：src/main.rs

fn main() {
    another_function(5);
}

fn another_function(x: i32) {
    println!("The value of x is: {x}");
}

尝试运行这个程序；你应该会得到以下输出：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.21s
     Running `target/debug/functions`
The value of x is: 5

another_function 的声明有一个名为 x 的参数。x 的类型被指定为 i32。当我们向 another_function 传入 5 时，println! 宏会将 5 放入格式字符串中含有一对花括号 x 的位置。

在函数签名（function signatures）中，你 必须 声明每个参数的类型。这是 Rust 设计中的一个深思熟虑的决定：要求在函数定义中进行类型注解（type annotation），意味着编译器几乎不需要你在代码的其他地方使用它们来推断你的类型。如果编译器知道函数期望什么类型，它也能给出更有帮助的错误信息。

当定义多个参数时，使用逗号分隔参数声明，就像这样：

文件名：src/main.rs

fn main() {
    print_labeled_measurement(5, 'h');
}

fn print_labeled_measurement(value: i32, unit_label: char) {
    println!("The measurement is: {value}{unit_label}");
}

这个例子创建了一个名为 print_labeled_measurement 的函数，它有两个参数。第一个参数名为 value，类型是 i32。第二个参数名为 unit_label，类型是 char。然后该函数打印包含 value 和 unit_label 的文本。

让我们尝试运行这段代码。将当前 functions 项目的 src/main.rs 文件中的程序替换为前面的示例，然后使用 cargo run 运行它：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/functions`
The measurement is: 5h

因为我们用 5 作为 value 的值，用 'h' 作为 unit_label 的值调用了该函数，所以程序输出包含了这些值。

语句与表达式（Statements and Expressions）

函数体（Function bodies）由一系列语句（statements）组成，并可选择以一个表达式（expression）结尾。到目前为止，我们介绍的函数都没有包含结尾表达式，但你已经见过作为语句一部分的表达式了。因为 Rust 是一门基于表达式（expression-based）的语言，这是一个需要理解的重要区别。其他语言没有同样的区分，所以让我们来看看什么是语句和表达式，以及它们的差异如何影响函数体。

• 语句（Statements） 是执行某些操作但不返回值的指令。
• 表达式（Expressions） 会计算并产生一个结果值。

让我们看一些例子。

实际上，我们已经使用过语句和表达式了。使用 let 关键字创建变量并为其赋值是一个语句。在示例 3-1 中，let y = 6; 就是一个语句。

fn main() {
    let y = 6;
}

函数定义也是语句；整个前面的例子本身就是一个语句。（不过，正如我们稍后将看到的，调用函数并不是一个语句。）

语句不返回值。因此，你不能将一个 let 语句赋值给另一个变量，就像下面的代码尝试做的那样；你会得到一个错误：

文件名：src/main.rs

fn main() {
    let x = (let y = 6);
}

当你运行这个程序时，你会看到如下错误：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error: expected expression, found `let` statement
 --> src/main.rs:2:14
  |
2 |     let x = (let y = 6);
  |              ^^^
  |
  = note: only supported directly in conditions of `if` and `while` expressions

warning: unnecessary parentheses around assigned value
 --> src/main.rs:2:13
  |
2 |     let x = (let y = 6);
  |             ^         ^
  |
  = note: `#[warn(unused_parens)]` on by default
help: remove these parentheses
  |
2 -     let x = (let y = 6);
2 +     let x = let y = 6;
  |

warning: `functions` (bin "functions") generated 1 warning
error: could not compile `functions` (bin "functions") due to 1 previous error; 1 warning emitted

let y = 6 语句不返回值，所以 x 没有可以绑定的东西。这与 C 和 Ruby 等其他语言不同，在这些语言中，赋值会返回赋值的值。在这些语言中，你可以写 x = y = 6 并让 x 和 y 都有值 6；但在 Rust 中并非如此。

表达式会计算出一个值，并且构成了你在 Rust 中编写的大部分其余代码。考虑一个数学运算，比如 5 + 6，这是一个计算结果为 11 的表达式。表达式可以是语句的一部分：在示例 3-1 中，语句 let y = 6; 中的 6 就是一个计算结果为 6 的表达式。调用函数是一个表达式。调用宏也是一个表达式。用花括号创建的新作用域块（scope block）也是一个表达式，例如：

文件名：src/main.rs

fn main() {
    let y = {
        let x = 3;
        x + 1
    };

    println!("The value of y is: {y}");
}

这个表达式：

{
    let x = 3;
    x + 1
}

是一个代码块，在这个例子中，它的计算结果为 4。该值作为 let 语句的一部分被绑定到 y。注意 x + 1 这一行末尾没有分号，这与你目前看到的大多数行不同。表达式不包含结尾的分号。如果你在表达式末尾加上分号，你就把它变成了一个语句，那么它将不再返回值。在接下来探索函数返回值（return values）和表达式时，请记住这一点。

具有返回值的函数（Functions with Return Values）

函数可以向调用它的代码返回值。我们不给返回值命名，但必须在箭头（->）之后声明其类型。在 Rust 中，函数的返回值（return value）与函数体（body）块中最后一个表达式的值同义。你可以通过使用 return 关键字并指定一个值来提前从函数返回，但大多数函数会隐式地返回最后一个表达式。下面是一个返回值的函数示例：

文件名：src/main.rs

fn five() -> i32 {
    5
}

fn main() {
    let x = five();

    println!("The value of x is: {x}");
}

在 five 函数中没有函数调用、宏、甚至 let 语句——只有数字 5 本身。这在 Rust 中是一个完全有效的函数。注意，函数的返回类型也被指定为 -> i32。尝试运行这段代码；输出应该如下所示：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/functions`
The value of x is: 5

five 中的 5 就是函数的返回值，这就是为什么返回类型是 i32。让我们更详细地分析一下。这里有两点很重要：首先，let x = five(); 这一行表明我们正在使用函数的返回值来初始化一个变量。因为函数 five 返回 5，所以这一行等同于以下代码：

#![allow(unused)]
fn main() {
let x = 5;
}

其次，five 函数没有参数并定义了返回值的类型，但函数体只有一个孤零零的 5，没有分号，因为它是一个表达式，我们想要返回它的值。

让我们看另一个例子：

文件名：src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1
}

运行这段代码将打印 The value of x is: 6。但是，如果我们在包含 x + 1 的那一行末尾加上一个分号，把它从一个表达式（expression）改为一个语句（statement），会发生什么呢？

文件名：src/main.rs

fn main() {
    let x = plus_one(5);

    println!("The value of x is: {x}");
}

fn plus_one(x: i32) -> i32 {
    x + 1;
}

编译这段代码会产生一个错误，如下所示：

$ cargo run
   Compiling functions v0.1.0 (file:///projects/functions)
error[E0308]: mismatched types
 --> src/main.rs:7:24
  |
7 | fn plus_one(x: i32) -> i32 {
  |    --------            ^^^ expected `i32`, found `()`
  |    |
  |    implicitly returns `()` as its body has no tail or `return` expression
8 |     x + 1;
  |          - help: remove this semicolon to return this value

For more information about this error, try `rustc --explain E0308`.
error: could not compile `functions` (bin "functions") due to 1 previous error

主要的错误信息 mismatched types（类型不匹配）揭示了这段代码的核心问题。函数 plus_one 的定义说明它将返回一个 i32，但语句不会计算出一个值，而是表达为 ()，即单元类型（unit type）。因此，什么也没有返回，这与函数定义相矛盾并导致了一个错误。在这段输出中，Rust 提供了一条可能有助于修正此问题的消息：它建议删除分号，这将修复这个错误。

注释

注释（Comments）

所有程序员都努力使他们的代码易于理解，但有时额外的解释也是必要的。在这种情况下，程序员会在源代码中留下 注释（comments），编译器会忽略它们，但阅读源代码的人可能会觉得它们很有用。

这是一个简单的注释：

#![allow(unused)]
fn main() {
// hello, world
}

在 Rust 中，惯用的注释风格是用两个斜杠开始一个注释，并且注释一直延续到行尾。对于超过一行的注释，你需要在每一行都包含 //，就像这样：

#![allow(unused)]
fn main() {
// So we're doing something complicated here, long enough that we need
// multiple lines of comments to do it! Whew! Hopefully, this comment will
// explain what's going on.
}

注释也可以放在包含代码的行的末尾：

文件名：src/main.rs

fn main() {
    let lucky_number = 7; // I'm feeling lucky today
}

但更常见的是以下面这种格式使用注释，将注释放在它所注解的代码上方的单独一行：

文件名：src/main.rs

fn main() {
    // I'm feeling lucky today
    let lucky_number = 7;
}

Rust 还有另一种注释，即文档注释（documentation comments），我们将在第 14 章的“将 Crate 发布到 Crates.io” 一节中讨论。

控制流

控制流（Control Flow）

根据条件是否为 true 来执行某些代码，以及在条件为 true 时重复执行某些代码，这些都是大多数编程语言的基本构建块（building blocks）。让你控制 Rust 代码执行流的最常见结构是 if 表达式（expressions）和循环（loops）。

if 表达式（if Expressions）

if 表达式允许你根据条件来分支代码。你提供一个条件，然后声明：“如果满足此条件，则运行此代码块。如果不满足条件，则不运行此代码块。”

在你的 projects 目录下创建一个名为 branches 的新项目来探索 if 表达式。在 src/main.rs 文件中输入以下内容：

文件名：src/main.rs

fn main() {
    let number = 3;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

所有 if 表达式都以关键字 if 开头，后跟一个条件。在这个例子中，条件检查变量 number 的值是否小于 5。如果条件为 true，我们将要执行的代码块紧跟在条件之后放在花括号内。与 if 表达式中的条件关联的代码块有时被称为 分支（arms），就像我们在第 2 章的“将猜测的数字与秘密数字进行比较” 一节中讨论的 match 表达式中的分支一样。

我们还可以选择包含一个 else 表达式，我们在这里也这样做了，以便在条件计算结果为 false 时给程序一个备选的代码块来执行。如果你没有提供 else 表达式且条件为 false，程序将直接跳过 if 代码块并继续执行下一段代码。

尝试运行这段代码；你应该会看到以下输出：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was true

让我们尝试将 number 的值改为使条件为 false 的值，看看会发生什么：

fn main() {
    let number = 7;

    if number < 5 {
        println!("condition was true");
    } else {
        println!("condition was false");
    }
}

再次运行该程序，并查看输出：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
condition was false

同样值得注意的是，这段代码中的条件 必须 是 bool 类型。如果条件不是 bool 类型，我们会得到一个错误。例如，尝试运行以下代码：

文件名：src/main.rs

fn main() {
    let number = 3;

    if number {
        println!("number was three");
    }
}

这次 if 条件计算出的值是 3，Rust 抛出了一个错误：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: mismatched types
 --> src/main.rs:4:8
  |
4 |     if number {
  |        ^^^^^^ expected `bool`, found integer

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

该错误表明 Rust 期望一个 bool 类型但得到了一个整数。与 Ruby 和 JavaScript 等语言不同，Rust 不会自动尝试将非布尔类型转换为布尔类型。你必须明确地始终为 if 提供一个布尔值作为其条件。例如，如果我们希望 if 代码块仅在一个数字不等于 0 时运行，我们可以将 if 表达式改为以下形式：

文件名：src/main.rs

fn main() {
    let number = 3;

    if number != 0 {
        println!("number was something other than zero");
    }
}

运行这段代码将打印 number was something other than zero。

使用 else if 处理多个条件（Handling Multiple Conditions with else if）

你可以通过在 else if 表达式中结合 if 和 else 来使用多个条件。例如：

文件名：src/main.rs

fn main() {
    let number = 6;

    if number % 4 == 0 {
        println!("number is divisible by 4");
    } else if number % 3 == 0 {
        println!("number is divisible by 3");
    } else if number % 2 == 0 {
        println!("number is divisible by 2");
    } else {
        println!("number is not divisible by 4, 3, or 2");
    }
}

这个程序有四个可能的执行路径。运行它之后，你应该会看到以下输出：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.31s
     Running `target/debug/branches`
number is divisible by 3

当这个程序执行时，它会依次检查每个 if 表达式，并执行第一个条件为 true 的分支体。请注意，尽管 6 可以被 2 整除，但我们没有看到输出 number is divisible by 2，也没有看到来自 else 块的 number is not divisible by 4, 3, or 2 文本。这是因为 Rust 只执行第一个为 true 条件对应的代码块，一旦找到这样一个条件，它甚至不会检查其余的条件。

使用过多的 else if 表达式会使你的代码变得杂乱，因此如果你有多个条件，你可能想要重构你的代码。第 6 章将介绍一种强大的 Rust 分支结构 match，适用于这些情况。

在 let 语句中使用 if（Using if in a let Statement）

因为 if 是一个表达式，我们可以在 let 语句的右侧使用它来将结果赋值给一个变量，如示例 3-2 所示。

fn main() {
    let condition = true;
    let number = if condition { 5 } else { 6 };

    println!("The value of number is: {number}");
}

number 变量将根据 if 表达式的结果绑定到一个值。运行这段代码看看会发生什么：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.30s
     Running `target/debug/branches`
The value of number is: 5

请记住，代码块的计算结果是其中的最后一个表达式，而数字本身也是表达式。在这种情况下，整个 if 表达式的值取决于哪个代码块被执行。这意味着 if 的每个分支可能产生的结果值必须是相同类型；在示例 3-2 中，if 分支和 else 分支的结果都是 i32 整数。如果类型不匹配，如下面的示例所示，我们会得到一个错误：

文件名：src/main.rs

fn main() {
    let condition = true;

    let number = if condition { 5 } else { "six" };

    println!("The value of number is: {number}");
}

当我们尝试编译这段代码时，会得到一个错误。if 和 else 分支的值类型不兼容，Rust 会精确地指出问题在程序中的位置：

$ cargo run
   Compiling branches v0.1.0 (file:///projects/branches)
error[E0308]: `if` and `else` have incompatible types
 --> src/main.rs:4:44
  |
4 |     let number = if condition { 5 } else { "six" };
  |                                 -          ^^^^^ expected integer, found `&str`
  |                                 |
  |                                 expected because of this

For more information about this error, try `rustc --explain E0308`.
error: could not compile `branches` (bin "branches") due to 1 previous error

if 块中的表达式计算为一个整数，而 else 块中的表达式计算为一个字符串。这行不通，因为变量必须只有一个类型，并且 Rust 需要在编译时明确知道 number 变量的类型。知道 number 的类型可以让编译器验证该类型在我们使用 number 的任何地方都是有效的。如果 number 的类型只在运行时才能确定，Rust 将无法做到这一点；如果编译器必须跟踪任何变量的多种假设类型，它将变得更加复杂，并且对代码的保证也会更少。

使用循环重复执行（Repetition with Loops）

多次执行同一段代码通常非常有用。为此，Rust 提供了几种 循环（loops），它们会运行循环体（loop body）内的代码直到末尾，然后立即从头开始。为了试验循环，让我们创建一个名为 loops 的新项目。

Rust 有三种循环：loop、while 和 for。让我们逐一尝试。

使用 loop 重复执行代码（Repeating Code with loop）

loop 关键字告诉 Rust 反复执行一段代码，要么永远执行下去，直到你明确告诉它停止。

例如，将 loops 目录中的 src/main.rs 文件修改为如下内容：

文件名：src/main.rs

fn main() {
    loop {
        println!("again!");
    }
}

当我们运行这个程序时，我们会看到 again! 不断地被打印出来，直到我们手动停止程序。大多数终端支持键盘快捷键 ctrl-C 来中断一个陷入持续循环的程序。试试看：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.08s
     Running `target/debug/loops`
again!
again!
again!
again!
^Cagain!

符号 ^C 表示你按下 ctrl-C 的位置。

你可能会或可能不会在 ^C 之后看到 again! 被打印出来，这取决于代码在收到中断信号时处于循环的哪个位置。

幸运的是，Rust 也提供了一种通过代码跳出循环的方法。你可以在循环中使用 break 关键字来告诉程序何时停止执行循环。回想一下，我们在第 2 章的“猜对后退出” 一节的猜谜游戏中就是这样做的，当用户猜对数字赢得游戏时退出程序。

我们还在猜谜游戏中使用了 continue，它在循环中告诉程序跳过本次循环迭代中剩余的代码，并进入下一次迭代。

从循环中返回值（Returning Values from Loops）

loop 的用途之一是重试你知道可能会失败的操作，例如检查线程是否已完成其任务。你可能还需要将该操作的结果从循环中传递给你代码的其余部分。为此，你可以在用来停止循环的 break 表达式之后添加你想要返回的值；该值将从循环中被返回，以便你可以使用它，如下所示：

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

        if counter == 10 {
            break counter * 2;
        }
    };

    println!("The result is {result}");
}

在循环之前，我们声明了一个名为 counter 的变量并将其初始化为 0。然后，我们声明了一个名为 result 的变量来保存从循环返回的值。在循环的每次迭代中，我们给 counter 变量加 1，然后检查 counter 是否等于 10。当它等于 10 时，我们使用 break 关键字并带上值 counter * 2。循环之后，我们使用分号结束将值赋给 result 的语句。最后，我们打印 result 中的值，在本例中为 20。

你也可以在循环内部使用 return。break 只退出当前循环，而 return 总是退出当前函数。

使用循环标签消除歧义（Disambiguating with Loop Labels）

如果你在循环中嵌套了循环，break 和 continue 将应用于该点最内层的循环。你可以选择在循环上指定一个 循环标签（loop label），然后你可以将它与 break 或 continue 一起使用，以指定这些关键字应用于带标签的循环，而不是最内层的循环。循环标签必须以单引号开头。下面是一个包含两个嵌套循环的例子：

fn main() {
    let mut count = 0;
    'counting_up: loop {
        println!("count = {count}");
        let mut remaining = 10;

        loop {
            println!("remaining = {remaining}");
            if remaining == 9 {
                break;
            }
            if count == 2 {
                break 'counting_up;
            }
            remaining -= 1;
        }

        count += 1;
    }
    println!("End count = {count}");
}

外层循环有标签 'counting_up，它将从 0 计数到 2。没有标签的内层循环从 10 向下计数到 9。第一个没有指定标签的 break 只会退出内层循环。break 'counting_up; 语句将退出外层循环。这段代码会打印：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.58s
     Running `target/debug/loops`
count = 0
remaining = 10
remaining = 9
count = 1
remaining = 10
remaining = 9
count = 2
remaining = 10
End count = 2

使用 while 简化条件循环（Streamlining Conditional Loops with while）

程序通常需要在循环内评估一个条件。当条件为 true 时，循环运行。当条件不再为 true 时，程序调用 break，停止循环。可以使用 loop、if、else 和 break 的组合来实现这种行为；如果你愿意，现在可以尝试在程序中这样做。然而，这种模式非常常见，以至于 Rust 为此内置了一个语言结构，称为 while 循环。在示例 3-3 中，我们使用 while 将程序循环三次，每次倒计时，然后在循环结束后打印一条消息并退出。

fn main() {
    let mut number = 3;

    while number != 0 {
        println!("{number}!");

        number -= 1;
    }

    println!("LIFTOFF!!!");
}

这种结构消除了如果你使用 loop、if、else 和 break 所需的大量嵌套，并且更加清晰。当条件为 true 时，代码运行；否则，它退出循环。

使用 for 遍历集合（Looping Through a Collection with for）

你可以选择使用 while 结构来遍历集合（如数组）中的元素。例如，示例 3-4 中的循环打印数组 a 中的每个元素。

fn main() {
    let a = [10, 20, 30, 40, 50];
    let mut index = 0;

    while index < 5 {
        println!("the value is: {}", a[index]);

        index += 1;
    }
}

这里，代码逐个遍历数组中的元素。它从索引 0 开始，然后循环直到到达数组中的最后一个索引（即当 index < 5 不再为 true 时）。运行这段代码将打印数组中的每个元素：

$ cargo run
   Compiling loops v0.1.0 (file:///projects/loops)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.32s
     Running `target/debug/loops`
the value is: 10
the value is: 20
the value is: 30
the value is: 40
the value is: 50

所有五个数组值都按预期出现在终端中。尽管 index 在某个时刻会达到值 5，但循环在尝试从数组中获取第六个值之前就停止了执行。

然而，这种方法容易出错；如果索引值或测试条件不正确，我们可能会导致程序恐慌（panic）。例如，如果你将数组 a 的定义改为有四个元素，但忘记将条件更新为 while index < 4，代码就会 panic。它也很慢，因为编译器会添加运行时代码来在每次循环迭代中检查索引是否在数组的边界内。

作为一种更简洁的替代方案，你可以使用 for 循环为集合中的每个项目执行一些代码。for 循环看起来像示例 3-5 中的代码。

fn main() {
    let a = [10, 20, 30, 40, 50];

    for element in a {
        println!("the value is: {element}");
    }
}

当我们运行这段代码时，我们会看到与示例 3-4 相同的输出。更重要的是，我们现在提高了代码的安全性，消除了因超出数组末尾或未达到足够位置而遗漏某些项目而导致错误的可能性。由 for 循环生成的机器码也可能更高效，因为不需要在每次迭代时将索引与数组长度进行比较。

使用 for 循环，如果你更改了数组中值的数量，你不需要像示例 3-4 中使用的方法那样记住更改任何其他代码。

for 循环的安全性和简洁性使其成为 Rust 中最常用的循环结构。即使在你想要运行某段代码一定次数的情况下，比如示例 3-3 中使用 while 循环的倒计时示例，大多数 Rustacean（Rust 开发者）也会使用 for 循环。实现这一点的方法是使用标准库提供的 Range（范围），它按顺序生成从一个数字开始到另一个数字之前结束的所有数字。

以下是使用 for 循环和我们尚未讨论的另一种方法 rev（用于反转范围）来实现倒计时的样子：

文件名：src/main.rs

fn main() {
    for number in (1..4).rev() {
        println!("{number}!");
    }
    println!("LIFTOFF!!!");
}

这段代码更优雅一些，不是吗？

总结（Summary）

你做到了！这是相当大的一章：你学习了变量（variables）、标量（scalar）和复合数据类型（compound data types）、函数（functions）、注释（comments）、if 表达式（expressions）和循环（loops）！为了练习本章讨论的概念，尝试编写程序来完成以下任务：

• 在华氏度和摄氏度之间转换温度。
• 生成第 n 个斐波那契数（Fibonacci number）。
• 打印圣诞颂歌《The Twelve Days of Christmas》的歌词，利用歌曲中的重复部分。

当你准备好继续前进时，我们将讨论 Rust 中一个在其他编程语言中 不 常见的概念：所有权（ownership）。

理解所有权（Understanding Ownership）

所有权（Ownership）是 Rust 最独特的特性，并对语言的其余部分有着深远的影响。它使 Rust 能够在不需要垃圾收集器（garbage collector）的情况下保证内存安全（memory safety），因此理解所有权的工作原理非常重要。在本章中，我们将讨论所有权以及几个相关的特性：借用（borrowing）、切片（slices）以及 Rust 如何在内存中布局数据。

什么是所有权？

什么是所有权？（What Is Ownership?）

所有权（Ownership） 是一组规则，用于管理 Rust 程序如何管理内存。 所有程序在运行时都必须管理它们使用计算机内存的方式。 有些语言具有垃圾回收机制（garbage collection），可以在程序运行时定期查找不再使用的内存； 而在其他语言中，程序员必须显式地分配（allocate）和释放（free）内存。 Rust 采用了第三种方式：通过一套由编译器检查的所有权规则来管理内存。 如果违反了任何规则，程序将无法编译。 所有权的任何特性都不会在运行时降低程序的速度。

因为所有权对许多程序员来说是一个新概念，确实需要一些时间来适应。 好消息是，随着你对 Rust 和所有权系统规则的了解越来越深入， 你就会越自然地编写出既安全又高效的代码。坚持下去！

当你理解了所有权，你就为理解 Rust 的独特特性奠定了坚实的基础。 在本章中，你将通过一些专注于一种非常常见的数据结构——字符串——的示例来学习所有权。

所有权规则（Ownership Rules）

首先，让我们来看看所有权的规则。在我们学习说明这些规则的示例时，请牢记这些规则：

• Rust 中的每个值都有一个所有者（owner）。
• 同一时间只能有一个所有者。
• 当所有者离开作用域（scope）时，该值将被丢弃（dropped）。

变量作用域（Variable Scope）

既然我们已经过了基础的 Rust 语法阶段，就不会在示例中包含所有 fn main() { 代码，所以如果你在跟着练习，请确保手动将以下示例放入 main 函数中。 这样一来，我们的示例会更加简洁，让我们能够专注于实际细节而不是样板代码。

作为所有权的第一个示例，我们来看看一些变量的作用域。 作用域（scope） 是程序中一个项（item）有效的范围。以下面的变量为例：

#![allow(unused)]
fn main() {
let s = "hello";
}

变量 s 引用了一个字符串字面量（string literal），其中字符串的值被硬编码在程序的文本中。 该变量从声明之处开始直到当前作用域结束都是有效的。示例 4-1 展示了一个程序及其注释， 标明了变量 s 在何处是有效的。

fn main() {
    {                      // s is not valid here, since it's not yet declared
        let s = "hello";   // s is valid from this point forward

        // do stuff with s
    }                      // this scope is now over, and s is no longer valid
}

换句话说，这里有两个重要的时间点：

• 当 s 进入作用域时，它是有效的。
• 它一直保持有效，直到它离开作用域。

至此，作用域与变量有效时间之间的关系与其他编程语言类似。 现在，我们将在此基础上通过引入 String 类型来进行进一步的学习。

String 类型（The String Type）

为了说明所有权（ownership）的规则，我们需要一个比第 3 章的“数据类型”部分所介绍的更为复杂的数据类型。 之前介绍的类型都是已知大小的，可以存储在栈上，并在其作用域结束时从栈中弹出， 并且如果需要代码的另一部分在不同的作用域中使用相同的值，可以快速、简单地复制以创建一个新的独立实例。 但我们想要看看存储在堆上的数据，并探索 Rust 如何知道何时清理这些数据， 而 String 类型正是一个很好的例子。

我们将重点讨论 String 中与所有权相关的部分。这些方面也适用于其他复杂的数据类型， 无论它们是标准库提供的还是你自己创建的。我们将在第 8 章中讨论 String 中与所有权无关的方面。

我们已经见过字符串字面量（string literal），即字符串值被硬编码（hardcoded）到程序中。 字符串字面量很方便，但它们并不适用于所有我们可能想要使用文本的场景。 一个原因是它们是不可变的（immutable）。另一个原因是并非每个字符串值在编写代码时就能确定： 例如，如果我们想要获取用户输入并存储它呢？正是为了应对这些情况，Rust 提供了 String 类型。 该类型管理在堆上分配的数据，因此能够存储在编译时未知大小的文本量。 你可以使用 from 函数从字符串字面量创建一个 String，如下所示：

#![allow(unused)]
fn main() {
let s = String::from("hello");
}

双冒号 :: 运算符允许我们将这个特定的 from 函数放在 String 类型的命名空间下， 而不是使用像 string_from 这样的名称。我们将在第 5 章的“方法”部分更详细地讨论这种语法， 并在第 7 章中讨论“用于在模块树中引用项的路径”时讲解模块的命名空间。

这种字符串是可以修改的：

fn main() {
    let mut s = String::from("hello");

    s.push_str(", world!"); // push_str() appends a literal to a String

    println!("{s}"); // this will print `hello, world!`
}

那么，这里的区别是什么呢？为什么 String 可以修改而字面量却不能？ 区别在于这两种类型处理内存的方式不同。

内存与分配（Memory and Allocation）

对于字符串字面量（string literal），我们在编译时就知道其内容，因此文本被直接硬编码（hardcoded）到最终的可执行文件中。 这就是字符串字面量快速且高效的原因。但这些特性仅仅源于字符串字面量的不可变性（immutability）。 不幸的是，对于每一段在编译时大小未知且可能在程序运行时改变大小的文本， 我们不能将一块内存放入二进制文件中。

对于 String 类型，为了支持可变（mutable）、可增长的文本片段， 我们需要在堆上分配一块在编译时大小未知的内存来存放内容。这意味着：

• 必须在运行时向内存分配器（memory allocator）请求内存。
• 当我们使用完 String 后，需要一种方式将这块内存返还给分配器。

第一部分由我们完成：当我们调用 String::from 时，其实现会请求它所需的内存。 这在编程语言中几乎是通用的。

然而，第二部分则有所不同。在拥有**垃圾回收器（garbage collector，GC）**的语言中， GC 会跟踪并清理不再使用的内存，我们无需考虑这个问题。 在没有 GC 的大多数语言中，我们有责任识别内存何时不再被使用并显式调用代码来释放它， 就像我们请求它一样。历史上，正确做到这一点一直是一个困难的编程问题。 如果我们忘记了，就会浪费内存。如果我们释放得太早，就会产生一个无效的变量。 如果我们释放两次，那也是一个错误。我们需要恰好配对一次 allocate 与一次 free。

Rust 采取了一条不同的路径：一旦拥有它的变量离开作用域（scope），内存就会被自动返回。 下面是我们使用 String 而非字符串字面量的作用域示例（来自示例 4-1）的一个版本：

fn main() {
    {
        let s = String::from("hello"); // s is valid from this point forward

        // do stuff with s
    }                                  // this scope is now over, and s is no
                                       // longer valid
}

有一个自然的时机可以将我们的 String 所需的内存返还给分配器：当 s 离开作用域时。 当变量离开作用域，Rust 会为我们调用一个特殊的函数。这个函数被称为 drop， String 的作者可以在其中放置返还内存的代码。 Rust 会在右花括号处自动调用 drop。

注意：在 C++ 中，这种在项（item）生命周期（lifetime）结束时释放资源的模式有时被称为 资源获取即初始化（Resource Acquisition Is Initialization，RAII）。 如果你使用过 RAII 模式，那么 Rust 中的 drop 函数会让你感到很熟悉。

这种模式对 Rust 代码的编写方式有着深远的影响。目前看来可能很简单， 但在更复杂的情况下，当我们希望有多个变量使用我们在堆上分配的数据时， 代码的行为可能会出乎意料。现在让我们探讨其中一些情况。

变量与数据的交互方式：移动（Variables and Data Interacting with Move）

多个变量可以在 Rust 中以不同的方式与相同的数据进行交互。 示例 4-2 展示了一个使用整数的示例。

fn main() {
    let x = 5;
    let y = x;
}

我们大概可以猜出这段代码的作用：“将值 5 绑定到 x；然后，复制 x 中的值并将其绑定到 y。” 现在我们有两个变量 x 和 y，且都等于 5。这确实就是发生的事情， 因为整数是具有已知、固定大小的简单值，这两个 5 值被推入栈中。

现在让我们看看 String 版本：

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;
}

这看起来非常相似，因此我们可能认为它的工作方式也是相同的： 也就是说，第二行会复制 s1 中的值并将其绑定到 s2。 但实际上并非如此。

看一下图 4-1，了解 String 在底层的实际运作方式。 一个 String 由三部分组成，如左侧所示：一个指向存放字符串内容的内存的指针（pointer）、一个长度（length）和一个容量（capacity）。 这组数据存储在栈上。右侧是堆上存放内容的内存。

图 4-1：一个持有值 "hello" 且绑定到 s1 的 String 在内存中的表示（The representation in memory of a String holding the value "hello" bound to s1）

长度（length）表示 String 的内容当前使用的内存字节数。 容量（capacity）表示 String 从分配器获得的内存总量。 长度和容量的差异在某些情况下很重要，但在此上下文中并不关键，因此目前可以忽略容量。

当我们将 s1 赋值给 s2 时，会复制 String 的数据，即复制栈上的指针、长度和容量。 我们不会复制指针所指向的堆上的数据。换句话说，内存中的数据表示如图 4-2 所示。

图 4-2：变量 s2 拥有 s1 的指针、长度和容量副本的内存表示（The representation in memory of the variable s2 that has a copy of the pointer, length, and capacity of s1）

该表示并非如图 4-3 所示，即如果 Rust 也复制了堆数据时的内存情况。 如果 Rust 这样做，那么当堆上的数据很大时，操作 s2 = s1 在运行时性能方面可能会非常昂贵。

图 4-3：如果 Rust 也复制了堆数据时 s2 = s1 可能采取的另一种情况（Another possibility for what s2 = s1 might do if Rust copied the heap data as well）

之前我们说过，当变量离开作用域时，Rust 会自动调用 drop 函数并清理该变量的堆内存。 但图 4-2 显示两个数据指针指向同一个位置。这就产生了一个问题： 当 s2 和 s1 离开作用域时，它们都会尝试释放同一块内存。 这就是所谓的**二次释放（double free）**错误，也是我们之前提到的内存安全 bug 之一。 两次释放内存可能导致内存损坏（memory corruption），进而可能引发安全漏洞。

为了确保内存安全，在 let s2 = s1; 这一行之后，Rust 认为 s1 不再有效。 因此，当 s1 离开作用域时，Rust 不需要释放任何东西。 看看当你尝试在创建 s2 后使用 s1 会发生什么；它将无法工作：

fn main() {
    let s1 = String::from("hello");
    let s2 = s1;

    println!("{s1}, world!");
}

你会得到这样的错误，因为 Rust 阻止你使用失效的引用：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0382]: borrow of moved value: `s1`
 --> src/main.rs:5:16
  |
2 |     let s1 = String::from("hello");
  |         -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait
3 |     let s2 = s1;
  |              -- value moved here
4 |
5 |     println!("{s1}, world!");
  |                ^^ value borrowed here after move
  |
  = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info)
help: consider cloning the value if the performance cost is acceptable
  |
3 |     let s2 = s1.clone();
  |                ++++++++

For more information about this error, try `rustc --explain E0382`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

如果你在其他语言中听说过浅拷贝（shallow copy）和深拷贝（deep copy）这两个术语， 那么复制指针、长度和容量而不复制数据的概念听起来可能像浅拷贝。 但由于 Rust 还会使第一个变量失效，这就不叫浅拷贝，而是被称为移动（move）。 在这个例子中，我们会说 s1 被**移动（moved）**到了 s2 中。因此，实际发生的情况如图 4-4 所示。

图 4-4：s1 被失效后的内存表示（The representation in memory after s1 has been invalidated）

这就解决了我们的问题！只有 s2 有效，当它离开作用域时，它将独自释放内存，一切就完成了。

此外，这还隐含着一个设计选择：Rust 永远不会自动创建数据的“深“拷贝。 因此，任何自动拷贝都可以被假定为在运行时性能方面是廉价的。

作用域与赋值（Scope and Assignment）

反过来，作用域、所有权以及通过 drop 函数释放内存之间的关系也同样成立。 当你为一个现有变量赋一个全新的值时，Rust 会调用 drop 并立即释放原值的内存。 例如，考虑下面的代码：

fn main() {
    let mut s = String::from("hello");
    s = String::from("ahoy");

    println!("{s}, world!");
}

我们首先声明了一个变量 s 并将其绑定到一个值为 "hello" 的 String。 然后，我们立即创建了一个值为 "ahoy" 的新 String 并将其赋值给 s。 此时，没有任何内容再指向堆上的原值。图 4-5 展示了现在的栈和堆数据：

图 4-5：初始值被完全替换后的内存表示（The representation in memory after the initial value has been replaced in its entirety）

因此，原始字符串立即离开作用域。Rust 会对其调用 drop 函数，其内存也会被立即释放。 当我们在最后打印该值时，它将是 "ahoy, world!"。

变量与数据的交互方式：克隆（Variables and Data Interacting with Clone）

如果我们确实想要深度复制 String 的堆数据，而不仅仅是栈数据， 我们可以使用一个名为 clone 的通用方法。我们将在第 5 章讨论方法语法， 但由于方法是许多编程语言中的常见特性，你可能之前已经见过它们。

下面是 clone 方法的一个示例：

fn main() {
    let s1 = String::from("hello");
    let s2 = s1.clone();

    println!("s1 = {s1}, s2 = {s2}");
}

这完全可行，并且明确地产生了图 4-3 所示的行为，其中堆数据确实被复制了。

当你看到对 clone 的调用时，你就知道正在执行一些任意代码，并且这些代码可能是昂贵的。 它是一个视觉指示器，表明有不同的事情正在发生。

仅栈数据：复制（Stack-Only Data: Copy）

还有一个我们尚未讨论的细节。下面这段使用整数的代码（其中的一部分已在示例 4-2 中展示）是有效的：

fn main() {
    let x = 5;
    let y = x;

    println!("x = {x}, y = {y}");
}

但这段代码似乎与我们刚刚学到的相矛盾：我们没有调用 clone， 但 x 仍然有效且并未被移动（moved）到 y 中。

原因是像整数这样在编译时具有已知大小的类型完全存储在栈上， 因此复制实际的值非常快速。这意味着我们没有理由要在创建变量 y 后阻止 x 仍然有效。 换句话说，在这里深拷贝和浅拷贝没有区别， 因此调用 clone 与通常的浅拷贝没有什么不同，我们可以省略它。

Rust 有一个特殊的标注（annotation）叫做 Copy trait（特征）， 我们可以将其放在存储在栈上的类型上，就像整数一样（我们将在第 10 章中更详细地讨论 trait）。 如果一个类型实现了 Copy trait，那么使用它的变量不会被移动，而是会被简单地复制， 这使得它们在赋值给另一个变量后仍然有效。

如果一个类型或其任何部分实现了 Drop trait，Rust 不会允许我们对该类型标注 Copy。 如果该类型在值离开作用域时需要做一些特殊的事情，而我们在该类型上添加了 Copy 标注， 就会得到一个编译时错误。要了解如何为你的类型添加 Copy 标注以实现该 trait， 请参阅附录 C 中的“可派生 trait”。

那么，哪些类型实现了 Copy trait？你可以查看给定类型的文档来确认， 但作为一般规则，任何一组简单的标量值都可以实现 Copy， 而任何需要分配或某种形式的资源则不能实现 Copy。以下是一些实现了 Copy 的类型：

• 所有整数类型，例如 u32。
• 布尔类型 bool，其值为 true 和 false。
• 所有浮点数类型，例如 f64。
• 字符类型 char。
• 元组（tuple），前提是它们只包含也实现了 Copy 的类型。例如， (i32, i32) 实现了 Copy，但 (i32, String) 则没有。

所有权与函数（Ownership and Functions）

将值传递给函数的机制与将值赋值给变量类似。 将变量传递给函数会进行移动（move）或复制（copy），就像赋值一样。 示例 4-3 是一个带有标注的示例，显示变量在何处进入和离开作用域。

fn main() {
    let s = String::from("hello");  // s comes into scope

    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope

    makes_copy(x);                  // Because i32 implements the Copy trait,
                                    // x does NOT move into the function,
                                    // so it's okay to use x afterward.

} // Here, x goes out of scope, then s. However, because s's value was moved,
  // nothing special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{some_string}");
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{some_integer}");
} // Here, some_integer goes out of scope. Nothing special happens.

如果在调用 takes_ownership 之后尝试使用 s，Rust 会抛出一个编译时错误。 这些静态检查保护我们免于犯错。尝试向 main 中添加使用 s 和 x 的代码， 看看在何处可以使用它们，以及在何处所有权规则会阻止你这样做。

返回值与作用域（Return Values and Scope）

返回值也可以转移所有权。示例 4-4 展示了一个返回某个值的函数示例， 并带有与示例 4-3 类似的标注。

fn main() {
    let s1 = gives_ownership();        // gives_ownership moves its return
                                       // value into s1

    let s2 = String::from("hello");    // s2 comes into scope

    let s3 = takes_and_gives_back(s2); // s2 is moved into
                                       // takes_and_gives_back, which also
                                       // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing
  // happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {       // gives_ownership will move its
                                       // return value into the function
                                       // that calls it

    let some_string = String::from("yours"); // some_string comes into scope

    some_string                        // some_string is returned and
                                       // moves out to the calling
                                       // function
}

// This function takes a String and returns a String.
fn takes_and_gives_back(a_string: String) -> String {
    // a_string comes into
    // scope

    a_string  // a_string is returned and moves out to the calling function
}

变量的所有权每次都遵循相同的模式：将一个值赋值给另一个变量会移动它。 当包含堆上数据的变量离开作用域时，该值将被 drop 清理，除非数据的所有权已经移动到另一个变量。

虽然这样可行，但在每个函数中获取所有权然后再返回所有权有点繁琐。 如果我们想让一个函数使用某个值但不获取所有权呢？ 如果我们想再次使用传入的值，除了函数体中可能想要返回的任何数据之外， 还需要将其传回来，这相当烦人。

Rust 确实允许我们使用元组（tuple）返回多个值，如示例 4-5 所示。

fn main() {
    let s1 = String::from("hello");

    let (s2, len) = calculate_length(s1);

    println!("The length of '{s2}' is {len}.");
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String

    (s, length)
}

但这对于一个本应常见的概念来说，仪式感太强，工作量也太大了。 幸运的是，Rust 有一个功能可以在不转移所有权的情况下使用值：引用（references）。

引用与借用

引用（References）与借用（Borrowing）

清单 4-5 中元组代码的问题在于，我们必须将 String 返回给调用函数，以便在调用 calculate_length 后仍能使用该 String，因为 String 被移动到了 calculate_length 中。相反，我们可以提供 String 值的一个引用（reference）。引用（reference）就像指针（pointer）一样，它是一个地址，我们可以通过它来访问存储在该地址的数据；这些数据由其他变量所拥有。与指针不同的是，引用保证在该引用的整个生命周期中都指向某个特定类型的有效值。

下面展示了如何定义并使用一个以对象引用作为参数（而非获取所有权）的 calculate_length 函数：

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

首先，注意变量声明和函数返回值中所有的元组代码都消失了。其次，注意我们将 &s1 传递给 calculate_length，并且在函数定义中，我们使用 &String 而非 String。这些与符号（ampersands）代表引用（reference），它们允许你引用某个值而不获取其所有权。图 4-6 展示了这一概念。

图 4-6：&String s 指向 String s1 的示意图

注意：与使用 & 进行引用（referencing）相反的操作是 解引用（dereferencing），它通过解引用运算符 * 来完成。我们将在第 8 章看到解引用运算符的一些用法，并在第 15 章详细讨论解引用。

让我们更仔细地看一下这里的函数调用：

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize {
    s.len()
}

&s1 语法让我们创建一个 引用（reference） s1 的值但不会拥有它。因为引用并不拥有该值，所以当引用停止使用时，它所指向的值不会被丢弃（dropped）。

同样地，函数的签名使用了 & 来表明参数 s 的类型是一个引用。让我们添加一些解释性的注释：

fn main() {
    let s1 = String::from("hello");

    let len = calculate_length(&s1);

    println!("The length of '{s1}' is {len}.");
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because s does not have ownership of what
  // it refers to, the String is not dropped.

变量 s 有效的作用域（scope）与任何函数参数的作用域相同，但当 s 停止使用时，引用所指向的值不会被丢弃，因为 s 没有所有权。当函数使用引用作为参数而不是实际值时，我们不需要返回值来交还所有权，因为我们从未拥有过所有权。

我们将创建引用的行为称为 借用（borrowing）。就像现实生活中，如果一个人拥有某样东西，你可以向他借用。当你用完时，你必须归还。你并不拥有它。

那么，如果我们试图修改正在借用的东西，会发生什么？试试清单 4-6 中的代码。剧透警告：它不会工作！

fn main() {
    let s = String::from("hello");

    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

以下是错误信息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference
 --> src/main.rs:8:5
  |
8 |     some_string.push_str(", world");
  |     ^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable
  |
help: consider changing this to be a mutable reference
  |
7 | fn change(some_string: &mut String) {
  |                         +++

For more information about this error, try `rustc --explain E0596`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

正如变量默认是不可变的（immutable）一样，引用也是如此。我们不允许修改我们拥有引用的东西。

可变引用（Mutable References）

我们可以通过一些小的调整来修复清单 4-6 中的代码，使其允许我们修改一个借用的值，即使用 可变引用（mutable reference）：

fn main() {
    let mut s = String::from("hello");

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

首先，我们将 s 改为 mut。然后，在调用 change 函数的地方使用 &mut s 创建一个可变引用，并更新函数签名以通过 some_string: &mut String 接受一个可变引用。这清楚地表明 change 函数将会改变它借用的值。

可变引用有一个很大的限制：如果你有一个对某个值的可变引用，你就不能再有对该值的其他引用。这段试图创建两个对 s 的可变引用的代码将会失败：

fn main() {
    let mut s = String::from("hello");

    let r1 = &mut s;
    let r2 = &mut s;

    println!("{r1}, {r2}");
}

以下是错误信息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0499]: cannot borrow `s` as mutable more than once at a time
 --> src/main.rs:5:14
  |
4 |     let r1 = &mut s;
  |              ------ first mutable borrow occurs here
5 |     let r2 = &mut s;
  |              ^^^^^^ second mutable borrow occurs here
6 |
7 |     println!("{r1}, {r2}");
  |                -- first borrow later used here

For more information about this error, try `rustc --explain E0499`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

这个错误说明此代码无效，因为我们不能在同一时间多次将 s 作为可变借用。第一个可变借用是在 r1 中，并且必须持续到它在 println! 中被使用，但在该可变引用的创建与其使用之间，我们试图在 r2 中创建另一个可变引用，该引用借用了与 r1 相同的数据。

这个限制——禁止同一时间对同一数据存在多个可变引用——允许进行修改，但以一种非常受控的方式进行。这是新的 Rustacean（Rust 学习者）常常感到困扰的地方，因为大多数语言允许你随时随地进行修改。拥有这个限制的好处是 Rust 能够在编译时防止数据竞争（data race）。数据竞争（data race） 类似于竞态条件（race condition），当以下三种行为同时发生时就会发生：

• 两个或更多指针同时访问同一数据。
• 至少有一个指针被用来写入数据。
• 没有使用任何机制来同步对数据的访问。

数据竞争会导致未定义行为（undefined behavior），并且在运行时追踪排查时很难诊断和修复；Rust 通过拒绝编译存在数据竞争的代码来防止这个问题！

和往常一样，我们可以使用花括号创建一个新的作用域（scope），允许有多个可变引用，只是不能 同时（simultaneous） 存在：

fn main() {
    let mut s = String::from("hello");

    {
        let r1 = &mut s;
    } // r1 goes out of scope here, so we can make a new reference with no problems.

    let r2 = &mut s;
}

Rust 对组合可变引用和不可变引用也实施了类似的规则。以下代码会导致错误：

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    let r3 = &mut s; // BIG PROBLEM

    println!("{r1}, {r2}, and {r3}");
}

以下是错误信息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:14
  |
4 |     let r1 = &s; // no problem
  |              -- immutable borrow occurs here
5 |     let r2 = &s; // no problem
6 |     let r3 = &mut s; // BIG PROBLEM
  |              ^^^^^^ mutable borrow occurs here
7 |
8 |     println!("{r1}, {r2}, and {r3}");
  |                -- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

呼！我们在拥有对同一个值的不可变引用时，也 不能拥有可变引用。

不可变引用的使用者并不期望值突然发生变化！然而，多个不可变引用是允许的，因为仅仅读取数据的人没有能力影响其他人对数据的读取。

请注意，引用的作用域从它被引入的地方开始，一直持续到该引用的最后一次使用。例如，以下代码可以编译，因为不可变引用的最后一次使用是在 println! 中，这发生在可变引用被引入之前：

fn main() {
    let mut s = String::from("hello");

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{r1} and {r2}");
    // Variables r1 and r2 will not be used after this point.

    let r3 = &mut s; // no problem
    println!("{r3}");
}

不可变引用 r1 和 r2 的作用域在它们最后被使用的 println! 之后结束，这发生在可变引用 r3 创建之前。这些作用域不重叠，因此这段代码是允许的：编译器可以在作用域结束之前的某个时间点判断出该引用已不再使用。

尽管借用错误有时可能会令人沮丧，但请记住，这是 Rust 编译器在早期（编译时而非运行时）指出潜在的 bug，并精确地告诉你问题所在。这样，你就不必在之后追踪为什么数据不是你所想的那样了。

悬垂引用（Dangling References）

在存在指针的语言中，很容易错误地创建 悬垂指针（dangling pointer）——即指向某个内存位置的指针，该内存可能已被分配给其他人——通过释放某些内存的同时却保留指向该内存的指针。相比之下，在 Rust 中，编译器保证引用永远不会是悬垂引用：如果你拥有对某些数据的引用，编译器将确保数据不会在引用之前超出作用域。

让我们尝试创建一个悬垂引用，看看 Rust 如何通过编译时错误来防止它们：

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String {
    let s = String::from("hello");

    &s
}

以下是错误信息：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn dangle() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

这个错误信息提到了一个我们尚未涉及的特性：生命周期（lifetimes）。我们将在第 10 章详细讨论生命周期。但是，如果你忽略关于生命周期的部分，该信息确实包含了为什么这段代码有问题的关键：

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

让我们更仔细地看看 dangle 代码的每个阶段具体发生了什么：

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope and is dropped, so its memory goes away.
  // Danger!

因为 s 是在 dangle 内部创建的，当 dangle 的代码执行完毕后，s 将被释放。但我们试图返回一个对它的引用。这意味着这个引用将指向一个无效的 String。这可不行！Rust 不允许我们这样做。

这里的解决方案是直接返回 String：

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

这样就能正常工作，没有任何问题。所有权被移出，没有任何东西被释放。

引用的规则

让我们回顾一下关于引用所讨论的内容：

• 在任意给定时间，你 要么 只能有一个可变引用，要么 只能有任意数量的不可变引用。
• 引用必须始终有效。

接下来，我们将介绍另一种引用：切片（slices）。

切片类型

切片（Slice）类型

切片（Slice） 让你可以引用集合中一段连续的元素序列。切片（Slice）是一种引用，因此它没有所有权。

这里有一个小编程问题：编写一个函数，它接收一个用空格分隔单词的字符串，并返回该字符串中找到的第一个单词。如果函数在字符串中没有找到空格，则整个字符串就是一个单词，所以应该返回整个字符串。

注意：为了介绍切片（Slice），本节仅假设使用 ASCII 字符；关于 UTF-8 处理的更详细讨论在第 8 章的“使用字符串存储 UTF-8 编码的文本”部分。

让我们先来思考一下，如果不使用切片（Slice），我们该如何编写这个函数的签名，以便理解切片（Slice）要解决的问题：

fn first_word(s: &String) -> ?

first_word 函数有一个 &String 类型的参数。我们不需要所有权，所以这没问题。（在惯用的 Rust 代码中，函数除非必要，否则不会获取参数的所有权，原因我们将在后续中逐渐明了。）但是我们应该返回什么呢？我们确实没有办法来描述字符串的一部分。不过，我们可以返回单词结尾的索引（Index），由空格来指示。让我们试试看，如示例 4-7 所示。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

因为我们需要逐元素地检查 String 中的值是否为空格，所以我们将使用 as_bytes 方法将 String 转换为字节数组。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

接下来，我们使用 iter 方法在字节数组上创建一个迭代器（Iterator）：

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

我们将在第 13 章中更详细地讨论迭代器（Iterator）。现在，你只需要知道 iter 是一个返回集合中每个元素的方法，而 enumerate 包装了 iter 的结果，将每个元素作为元组（Tuple）的一部分返回。enumerate 返回的元组中的第一个元素是索引（Index），第二个元素是对该元素的引用。这比我们自己计算索引要方便一些。

因为 enumerate 方法返回一个元组（Tuple），我们可以使用模式（Pattern）来解构这个元组。我们将在第 6 章中更多地讨论模式（Pattern）。在 for 循环中，我们指定了一个模式：元组中的索引使用 i，元组中的单个字节使用 &item。因为我们从 .iter().enumerate() 获取的是元素的引用，所以我们在模式中使用了 &。

在 for 循环内部，我们使用字节字面量语法来搜索代表空格的字节。如果找到空格，就返回该位置。否则，使用 s.len() 返回字符串的长度。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

现在我们有办法找出字符串中第一个单词结尾的索引（Index），但有一个问题。我们返回了一个单独的 usize，但它只有在 &String 的上下文中才是一个有意义的数字。换句话说，因为它是一个与 String 分离的值，无法保证它在未来仍然有效。请考虑示例 4-8 中的程序，它使用了示例 4-7 中的 first_word 函数。

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but s no longer has any content that we
    // could meaningfully use with the value 5, so word is now totally invalid!
}

这段程序编译时没有任何错误，而且在调用 s.clear() 之后使用 word 也不会有问题。因为 word 与 s 的状态完全没有关联，word 仍然包含值 5。我们可以用那个值 5 和变量 s 来尝试提取第一个单词，但这将是一个错误（Bug），因为自从我们将 5 保存到 word 中之后，s 的内容已经改变了。

担心 word 中的索引（Index）与 s 中的数据不同步是繁琐且容易出错的！如果我们编写一个 second_word 函数，管理这些索引（Index）会变得更加脆弱。它的签名必须像这样：

fn second_word(s: &String) -> (usize, usize) {

现在我们追踪的是起始_和_结束索引（Index），而且我们有更多的值是根据特定状态下的数据计算出来的，却完全没有与该状态绑定。我们有三个不相关的变量需要保持同步。

幸运的是，Rust 对此问题有一个解决方案：字符串切片（String Slice）。

字符串切片（String Slice）

字符串切片（String Slice） 是对 String 中一段连续元素的引用，它看起来像这样：

fn main() {
    let s = String::from("hello world");

    let hello = &s[0..5];
    let world = &s[6..11];
}

hello 不是对整个 String 的引用，而是对 String 一部分的引用，通过额外的 [0..5] 部分来指定。我们使用方括号内的范围（Range）来创建切片（Slice），通过指定 [starting_index..ending_index]，其中 starting_index 是切片（Slice）中的第一个位置，而 ending_index 是切片（Slice）中最后一个位置的下一个位置。在内部，切片（Slice）的数据结构存储了起始位置和切片（Slice）的长度，该长度对应于 ending_index 减去 starting_index。因此，对于 let world = &s[6..11]; 的情况，world 将是一个切片（Slice），它包含一个指向 s 中索引 6 处字节的指针，长度值为 5。

图 4-7 以图表形式展示了这一点。

图 4-7：引用 String 一部分的字符串切片（String Slice）

使用 Rust 的 .. 范围（Range）语法，如果你想从索引 0 开始，可以省略两个点之前的值。换句话说，以下是等价的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let slice = &s[0..2];
let slice = &s[..2];
}

同理，如果你的切片（Slice）包含 String 的最后一个字节，你可以省略尾部的数字。这意味着以下是等价的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

你也可以同时省略两个值来获取整个字符串的切片（Slice）。因此，以下是等价的：

#![allow(unused)]
fn main() {
let s = String::from("hello");

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

注意：字符串切片（String Slice）的范围（Range）索引必须位于有效的 UTF-8 字符边界上。如果你尝试在多字节字符的中间创建字符串切片，程序将退出并报错。

有了这些信息，我们来重写 first_word 以返回一个切片（Slice）。表示“字符串切片“的类型写作 &str：

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

我们使用与示例 4-7 相同的方式获取单词结尾的索引（Index）：寻找第一个出现的空格。当找到空格时，我们返回一个字符串切片（String Slice），以字符串的开头和空格的索引作为起始和结束索引。

现在当我们调用 first_word 时，我们返回一个与底层数据绑定的单一值。该值由指向切片（Slice）起始点的引用和切片中元素的数量组成。

返回切片（Slice）同样适用于 second_word 函数：

fn second_word(s: &String) -> &str {

现在我们有了一个更不易出错的直观 API，因为编译器会确保对 String 的引用保持有效。还记得示例 4-8 程序中的错误（Bug）吗？我们获取了第一个单词结尾的索引（Index），然后清空了字符串，导致索引失效？那段代码在逻辑上是错误的，但没有立即显示任何错误。如果我们继续尝试使用已清空字符串的第一个单词索引，问题会在之后暴露出来。切片（Slice）使这种错误（Bug）变得不可能，并让我们更早地知道代码存在问题。使用切片版本的 first_word 会抛出一个编译时错误：

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let mut s = String::from("hello world");

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

这是编译器错误：

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                   ---- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `ownership` (bin "ownership") due to 1 previous error

回顾一下借用规则（Borrowing Rules）：如果我们对某个值拥有不可变引用，就不能再获取可变引用。因为 clear 需要截断 String，它需要获取一个可变引用。而 clear 调用之后的 println! 使用了 word 中的引用，所以此时不可变引用必须仍然活跃。Rust 不允许 clear 中的可变引用和 word 中的不可变引用同时存在，因此编译失败。Rust 不仅让我们的 API 更易于使用，还在编译时消除了一整类错误！

字符串字面量（String Literal）作为切片（Slice）

回想一下，我们提到过字符串字面量（String Literal）存储在二进制文件中。既然我们已经了解了切片（Slice），就可以恰当地理解字符串字面量了：

#![allow(unused)]
fn main() {
let s = "Hello, world!";
}

这里 s 的类型是 &str：它是一个指向二进制文件中该特定点的切片（Slice）。这也是字符串字面量不可变的原因；&str 是一个不可变引用。

字符串切片（String Slice）作为参数

知道你可以获取字面量和 String 值的切片（Slice）后，我们对 first_word 有了进一步的改进，那就是它的签名：

fn first_word(s: &String) -> &str {

更有经验的 Rustacean 会编写如示例 4-9 所示的签名，因为它允许我们对 &String 值和 &str 值使用同一个函数。

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

如果我们有一个字符串切片（String Slice），可以直接传递它。如果我们有一个 String，可以传递 String 的切片或对 String 的引用。这种灵活性利用了解引用强制多态（Deref Coercion）的特性，我们将在第 15 章的“在函数和方法中使用解引用强制多态”部分介绍。

定义一个接受字符串切片（String Slice）而不是 String 引用的函数，使我们的 API 更加通用和有用，同时没有丢失任何功能：

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {
    let my_string = String::from("hello world");

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

其他切片（Slice）

你可以想象，字符串切片（String Slice）是针对字符串的。但也有更通用的切片类型。考虑这个数组：

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];
}

就像我们可能想要引用字符串的一部分一样，我们可能想要引用数组的一部分。我们可以这样做：

#![allow(unused)]
fn main() {
let a = [1, 2, 3, 4, 5];

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

这个切片（Slice）的类型是 &[i32]。它的工作方式与字符串切片相同，通过存储对第一个元素的引用和一个长度。你会在各种其他集合中使用这种切片。当我们谈到第 8 章的向量（Vector）时，我们将详细讨论这些集合。

总结

所有权（Ownership）、借用（Borrowing）和切片（Slice）这些概念确保了 Rust 程序在编译时的内存安全。Rust 语言像其他系统编程语言一样，让你能够控制内存使用。但是，当所有者（Owner）离开作用域时，数据的所有者会自动清理数据，这意味着你不需要为此编写和调试额外的代码。

所有权（Ownership）影响着 Rust 中许多其他部分的工作方式，因此我们将在本书的其余部分进一步讨论这些概念。让我们进入第 5 章，看看如何将数据片段组合到 struct 中。

使用结构体（Struct）组织相关数据

结构体（Struct），或结构（Structure），是一种自定义数据类型，它允许你将多个相关的值打包并命名，组成一个有意义的组合。如果你熟悉面向对象语言，结构体（Struct）就像对象的数据属性。在本章中，我们将比较和对照元组（Tuple）与结构体（Struct），在已有知识的基础上，展示何时使用结构体是更好的数据分组方式。

我们将演示如何定义和实例化结构体（Struct）。我们将讨论如何定义关联函数（Associated Function），特别是称为*方法（Method）*的那种关联函数，以指定与结构体类型相关联的行为。结构体（Struct）和枚举（Enum）（在第 6 章讨论）是在程序领域中创建新类型的基础构件，以充分利用 Rust 的编译时类型检查功能。

定义并实例化结构体

定义和实例化结构体（Struct）

结构体（Struct）与“元组类型”部分讨论的元组（Tuple）类似，两者都包含多个相关的值。与元组一样，结构体的各个部分可以是不同的类型。与元组不同的是，在结构体中你需要为每一段数据命名，以便清楚地表明这些值的含义。添加这些名称意味着结构体比元组更灵活：你不必依赖数据的顺序来指定或访问实例的值。

要定义一个结构体（Struct），我们输入关键字 struct 并为整个结构体命名。结构体的名称应该描述被组合在一起的数据片段的意义。然后，在花括号内，我们定义数据片段的名称和类型，我们称之为字段（Field）。例如，示例 5-1 展示了一个存储用户账户信息的结构体。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

在定义结构体之后，我们通过为每个字段指定具体的值来创建该结构体的实例（Instance）。我们通过写出结构体的名称，然后添加包含 key: value 对的花括号来创建实例，其中键是字段的名称，值是我们想要在这些字段中存储的数据。我们不必按照在结构体中声明字段时的相同顺序来指定字段。换句话说，结构体定义就像是该类型的通用模板，而实例则用特定的数据填充该模板来创建该类型的值。例如，我们可以像示例 5-2 那样声明一个特定的用户。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

要从结构体中获取特定值，我们使用点号（Dot）表示法。例如，要访问这个用户的电子邮件地址，我们使用 user1.email。如果实例是可变的，我们可以使用点号表示法并赋值给特定字段来改变值。示例 5-3 展示了如何更改可变 User 实例中 email 字段的值。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

注意，整个实例必须是可变的；Rust 不允许我们只将某些字段标记为可变。与任何表达式一样，我们可以将结构体的新实例构造为函数体中的最后一个表达式，以隐式返回该新实例。

示例 5-4 展示了一个 build_user 函数，它接收给定的 email 和 username 并返回一个 User 实例。active 字段的值为 true，sign_in_count 的值为 1。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

将函数参数命名为与结构体字段相同的名称是有意义的，但必须重复 email 和 username 字段名称和变量有点繁琐。如果结构体有更多字段，重复每个名称会更加烦人。幸运的是，有一个便捷的简写！

使用字段初始化简写（Field Init Shorthand）

因为在示例 5-4 中参数名称和结构体字段名称完全相同，我们可以使用*字段初始化简写（Field Init Shorthand）*语法重写 build_user，使其行为完全相同，但不需要重复 username 和 email，如示例 5-5 所示。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

这里，我们创建了一个新的 User 结构体实例，它有一个名为 email 的字段。我们想将 email 字段的值设置为 build_user 函数的 email 参数的值。因为 email 字段和 email 参数同名，我们只需要写 email 而不是 email: email。

使用结构体更新语法（Struct Update Syntax）创建实例

通常，创建一个新结构体实例是很有用的，它包含另一个同类型实例的大部分值，但改变其中的一部分。你可以使用结构体更新语法（Struct Update Syntax）来实现这一点。

首先，在示例 5-6 中，我们展示了如何以常规方式（不使用更新语法）在 user2 中创建一个新的 User 实例。我们为 email 设置了一个新值，但其他值使用了我们在示例 5-2 中创建的 user1 中的值。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

使用结构体更新语法（Struct Update Syntax），我们可以用更少的代码达到相同的效果，如示例 5-7 所示。.. 语法指定了未显式设置的其余字段应与给定实例中的字段具有相同的值。

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

示例 5-7 中的代码也在 user2 中创建了一个实例，它的 email 值不同，但 username、active 和 sign_in_count 字段的值与 user1 相同。..user1 必须放在最后，以指定任何剩余字段应从 user1 的对应字段中获取值，但我们可以选择以任何顺序为任意多个字段指定值，而不受结构体定义中字段顺序的限制。

注意，结构体更新语法（Struct Update Syntax）使用 = 就像赋值一样；这是因为它会移动数据，正如我们在“变量与数据交互的方式：移动”部分看到的那样。在这个例子中，创建 user2 后我们不能再使用 user1，因为 user1 的 username 字段中的 String 被移动到了 user2 中。如果我们为 user2 的 email 和 username 都提供了新的 String 值，从而只使用了 user1 中的 active 和 sign_in_count 值，那么 user2 创建后 user1 仍然有效。active 和 sign_in_count 都是实现了 Copy trait 的类型，因此我们在“栈（Stack）上的数据：Copy”部分讨论的行为将适用。在这个例子中，我们仍然可以使用 user1.email，因为它的值没有被移出 user1。

使用元组结构体（Tuple Struct）创建不同类型

Rust 还支持看起来类似于元组（Tuple）的结构体，称为元组结构体（Tuple Struct）。元组结构体具有结构体名称带来的额外含义，但与其字段没有关联的名称；相反，它们只有字段的类型。当你想要给整个元组一个名称并使该元组成为与其他元组不同的类型时，以及当像常规结构体那样命名每个字段会显得冗长或多余时，元组结构体（Tuple Struct）非常有用。

要定义一个元组结构体（Tuple Struct），以 struct 关键字和结构体名称开头，后跟元组中的类型。例如，这里我们定义并使用了两个名为 Color 和 Point 的元组结构体：

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

注意，black 和 origin 的值是不同类型，因为它们是不同元组结构体（Tuple Struct）的实例。你定义的每个结构体都是自己的类型，即使结构体内的字段可能具有相同的类型。例如，一个接受 Color 类型参数的函数不能接受 Point 作为参数，即使这两种类型都是由三个 i32 值组成的。除此之外，元组结构体实例与元组类似，你可以将它们解构为各个独立的部分，也可以使用 . 后跟索引来访问单个值。与元组不同，元组结构体在解构时需要你指定结构体的类型。例如，我们写 let Point(x, y, z) = origin; 来将 origin 点中的值解构为名为 x、y 和 z 的变量。

定义类单元结构体（Unit-Like Struct）

你还可以定义没有任何字段的结构体！这些被称为类单元结构体（Unit-Like Struct），因为它们的行为类似于 ()（我们在“元组类型”部分提到的单元类型）。当你需要在某个类型上实现 trait 但又不希望在该类型本身中存储任何数据时，类单元结构体（Unit-Like Struct）非常有用。我们将在第 10 章讨论 trait。下面是一个声明和实例化名为 AlwaysEqual 的类单元结构体的例子：

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

要定义 AlwaysEqual，我们使用 struct 关键字，后跟我们想要的名称，然后是一个分号。不需要花括号或圆括号！然后，我们可以用类似的方式在 subject 变量中获取 AlwaysEqual 的实例：使用我们定义的名称，不需要任何花括号或圆括号。想象一下，稍后我们将为这个类型实现行为，使得 AlwaysEqual 的每个实例总是与任何其他类型的每个实例相等，也许是出于测试目的而需要一个已知的结果。我们不需要任何数据来实现那个行为！你将在第 10 章中看到如何定义 trait 并在任何类型（包括类单元结构体）上实现它们。

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

使用结构体的示例程序

一个使用结构体（Struct）的示例程序

为了理解何时使用结构体（Struct），让我们编写一个计算矩形面积（Area）的程序。我们将从使用单个变量开始，然后重构程序，直到最终使用结构体。

让我们用 Cargo 创建一个名为 rectangles 的新二进制项目，它将接收以像素为单位指定的矩形的宽度（Width）和高度（Height），并计算矩形的面积。示例 5-8 展示了我们项目中 src/main.rs 的一个简短程序，它正是这样做的。

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

现在，使用 cargo run 运行这个程序：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

这段代码通过使用每个维度调用 area 函数成功计算了矩形的面积，但我们还可以做更多来使这段代码清晰易读。

这个问题在 area 的签名中很明显：

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

area 函数本应计算一个矩形的面积，但我们编写的函数有两个参数，而且在程序的任何地方都没有明确说明这些参数是相关的。将宽度和高度组合在一起会更易读和更易管理。我们在第 3 章的“元组类型”部分已经讨论过一种实现方式：使用元组（Tuple）。

使用元组（Tuple）重构

示例 5-9 展示了使用元组（Tuple）的另一个版本。

fn main() {
    let rect1 = (30, 50);

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

从某方面来说，这个程序更好。元组（Tuple）让我们增加了一些结构，现在我们只传递一个参数。但从另一方面来说，这个版本不够清晰：元组（Tuple）没有命名其元素，所以我们不得不通过索引来访问元组的各个部分，这使得我们的计算不够直观。

混淆宽度和高度对面积计算来说无关紧要，但如果我们想在屏幕上绘制矩形，那就重要了！我们必须记住 width 是元组索引 0，height 是元组索引 1。如果其他人要使用我们的代码，这将更难让他们弄清楚并记住。因为我们没有在代码中传达数据的含义，所以现在更容易引入错误。

使用结构体（Struct）重构

我们使用结构体（Struct）通过标记数据来增加含义。我们可以将目前使用的元组（Tuple）转换为一个结构体，为整体以及各个部分都赋予名称，如示例 5-10 所示。

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

这里，我们定义了一个名为 Rectangle 的结构体。在花括号内，我们将字段定义为 width 和 height，两者类型都是 u32。然后，在 main 中，我们创建了一个特定的 Rectangle 实例，其宽度为 30，高度为 50。

我们的 area 函数现在定义了一个参数，我们将其命名为 rectangle，其类型是 Rectangle 结构体实例的不可变借用。正如第 4 章中提到的，我们想要借用结构体而不是获取它的所有权。这样，main 保留了其所有权，可以继续使用 rect1，这就是我们在函数签名和调用函数时使用 & 的原因。

area 函数访问 Rectangle 实例的 width 和 height 字段（注意，访问借用的结构体实例的字段不会移动字段的值，这就是为什么你经常看到借用结构体的原因）。我们的 area 函数签名现在准确地表达了我们的意图：使用 Rectangle 的 width 和 height 字段计算其面积。这传达了宽度和高度是相互关联的，并且为值提供了描述性名称，而不是使用 0 和 1 这样的元组索引值。这在清晰性上是一个胜利。

使用派生 trait（Derived Trait）增加功能

能够在调试程序时打印 Rectangle 的实例并查看其所有字段的值将非常有用。示例 5-11 尝试使用我们之前章节中用过的 println! 宏。然而，这不会工作。

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1}");
}

当我们编译这段代码时，会得到以下核心错误信息：

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

println! 宏可以做多种类型的格式化，默认情况下，花括号告诉 println! 使用一种称为 Display 的格式化方式：即直接供最终用户使用的输出。到目前为止我们看到的基本类型默认实现了 Display，因为向用户展示 1 或任何其他基本类型只有一种方式。但对于结构体（Struct），println! 应该以何种方式格式化输出就不那么明确了，因为存在更多的显示可能性：你想要逗号还是不想要？你想要打印花括号吗？应该显示所有字段吗？由于这种歧义，Rust 不会试图猜测我们想要什么，结构体也没有提供 Display 的实现供 println! 和 {} 占位符使用。

如果继续阅读错误信息，我们会发现这个有用的提示：

   |                        |`Rectangle` cannot be formatted with the default formatter
   |                        required by this formatting parameter

让我们试试！println! 宏的调用现在看起来像 println!("rect1 is {rect1:?}");。将说明符 :? 放在花括号内告诉 println! 我们想要使用一种称为 Debug 的输出格式。Debug trait 使我们能够以对开发者有用的方式打印结构体，这样我们就可以在调试代码时看到它的值。

编译修改后的代码。哎呀！我们仍然得到一个错误：

error[E0277]: `Rectangle` doesn't implement `Debug`

但同样，编译器给了我们一个有用的提示：

   |                        required by this formatting parameter
   |

Rust 确实 包含了打印调试信息的功能，但我们需要显式地选择加入，才能使该功能对我们的结构体可用。为此，我们在结构体定义之前添加外部属性 #[derive(Debug)]，如示例 5-12 所示。

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

现在当我们运行程序时，不会得到任何错误，我们将看到以下输出：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

太好了！虽然它不是最漂亮的输出，但它显示了这个实例的所有字段的值，这在调试时肯定会有帮助。当我们有更大的结构体时，拥有更易读的输出会很有用；在这些情况下，我们可以在 println! 字符串中使用 {:#?} 而不是 {:?}。在这个例子中，使用 {:#?} 风格将输出以下内容：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

另一种使用 Debug 格式打印值的方法是使用 dbg! 宏，它获取表达式的所有权（与 println! 相反，后者获取引用），打印代码中 dbg! 宏调用所在位置的文件名和行号以及该表达式的结果值，并返回该值的所有权。

注意：调用 dbg! 宏会打印到标准错误控制台流（stderr），而 println! 打印到标准输出控制台流（stdout）。我们将在第 12 章的“将错误信息重定向到标准错误”部分更多地讨论 stderr 和 stdout。

下面是一个示例，我们关心分配给 width 字段的值，以及 rect1 中整个结构体的值：

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

我们可以将 dbg! 放在表达式 30 * scale 周围，由于 dbg! 返回表达式的值的所有权，width 字段将获得与没有 dbg! 调用时相同的值。我们不希望 dbg! 获取 rect1 的所有权，所以我们在下一个调用中使用对 rect1 的引用。以下示例的输出看起来像这样：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

我们可以看到，第一行输出来自 src/main.rs 的第 10 行，我们在那里调试表达式 30 * scale，其结果值为 60（为整数实现的 Debug 格式化只打印它们的值）。src/main.rs 第 14 行的 dbg! 调用输出了 &rect1 的值，即 Rectangle 结构体。这个输出使用了 Rectangle 类型的漂亮 Debug 格式化。当你试图弄清楚代码在做什么时，dbg! 宏真的很有用！

除了 Debug trait 之外，Rust 还提供了许多 trait 供我们与 derive 属性一起使用，这些 trait 可以为我们的自定义类型添加有用的行为。这些 trait 及其行为列在附录 C中。我们将在第 10 章中介绍如何以自定义行为实现这些 trait 以及如何创建自己的 trait。除了 derive 之外，还有许多其他属性；更多信息，请参阅 Rust 参考手册的“属性“部分。

我们的 area 函数非常特定：它只计算矩形的面积。将这个行为更紧密地绑定到我们的 Rectangle 结构体上会很有帮助，因为它不适用于任何其他类型。让我们看看如何通过将 area 函数转换为在 Rectangle 类型上定义的 area 方法来继续重构这段代码。

方法

方法（Methods）

方法（Method）与函数（Function）类似：我们用 fn 关键字和一个名称来声明它们， 它们可以有参数和返回值，并且包含一些在从其他地方调用该方法时运行的代码。 与函数不同的是，方法是在结构体（Struct）（或者枚举（Enum）或 trait 对象（Trait Object））的上下文中定义的， 我们分别在第 6 章和第 18 章中介绍， 并且它们的第一个参数始终是 self，它表示调用该方法的结构体实例。

方法语法（Method Syntax）

让我们将那个以 Rectangle 实例作为参数的 area 函数，改为一个定义在 Rectangle 结构体上的 area 方法， 如示例 5-13 所示。

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

为了在 Rectangle 的上下文中定义这个函数，我们为 Rectangle 启动一个 impl（implementation，实现）块。 这个 impl 块中的所有内容都将与 Rectangle 类型相关联。 然后，我们将 area 函数移到 impl 的花括号内，并将签名和函数体内部的第一个（在这里也是唯一一个）参数改为 self。 在 main 函数中，我们之前调用 area 函数并传入 rect1 作为参数的地方，现在可以改用*方法语法（Method Syntax）*来调用 Rectangle 实例上的 area 方法。 方法语法位于实例之后：我们加上一个点号，后跟方法名称、圆括号以及任何参数。

在 area 的签名中，我们使用 &self 而不是 rectangle: &Rectangle。 &self 实际上是 self: &Self 的简写。在 impl 块中，类型 Self 是该 impl 块所针对的类型的别名。 方法的第一个参数必须是一个名为 self、类型为 Self 的参数，因此 Rust 允许你在第一个参数位置只用 self 这个名字来缩写它。 请注意，我们仍然需要在 self 简写前面使用 & 来表明该方法借用了 Self 实例，就像我们在 rectangle: &Rectangle 中所做的那样。 方法可以获取 self 的所有权（Ownership），像我们这里所做的那样不可变地借用（Borrow）self，或者可变地借用 self， 就像它们对其他任何参数所做的那样。

我们在这里选择 &self 的原因与在函数版本中我们使用 &Rectangle 的原因相同： 我们不希望获取所有权，只是想读取结构体中的数据，而不是写入。如果我们想在该方法所做的事情中更改调用该方法的实例， 我们会使用 &mut self 作为第一个参数。让一个方法仅使用 self 作为第一个参数来获取实例的所有权是很少见的； 这种技术通常是在该方法将 self 转换为其他内容，并且你希望阻止调用方在转换后使用原始实例时使用。

使用方法而不是函数的主要原因，除了提供方法语法和不必在每个方法的签名中重复 self 的类型之外，是为了组织。 我们将对某个类型的实例可以做的所有事情都放在一个 impl 块中，而不是让我们代码的未来使用者在所提供库的各个地方搜索 Rectangle 的功能。

请注意，我们可以选择为方法赋予与结构体字段相同的名称。 例如，我们可以在 Rectangle 上定义一个也名为 width 的方法：

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

在这里，我们选择让 width 方法在实例的 width 字段的值大于 0 时返回 true，在值为 0 时返回 false： 我们可以在任何目的下在同名方法中使用字段。在 main 中，当我们在 rect1.width 后面跟上括号时，Rust 知道我们指的是方法 width。 当不使用括号时，Rust 知道我们指的是字段 width。

通常（但并非总是），当我们为方法赋予与字段相同的名称时，我们希望它只返回该字段的值，不做任何其他事情。 像这样的方法称为 getter 方法（Getter），Rust 不会像某些其他语言那样为结构体字段自动实现它们。 Getter 方法很有用，因为你可以将字段设为私有（Private）但方法设为公有（Public），从而作为类型公有 API 的一部分启用对该字段的只读访问。 我们将在第 7 章中讨论公有和私有的含义，以及如何将字段或方法指定为公有或私有。

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

带有更多参数的方法（Methods with More Parameters）

让我们通过在 Rectangle 结构体上实现第二个方法来练习使用方法。 这一次，我们希望 Rectangle 的一个实例接收另一个 Rectangle 实例作为参数， 如果第二个 Rectangle 能够完全放入 self（第一个 Rectangle）中，则返回 true；否则返回 false。 也就是说，一旦我们定义了 can_hold 方法，我们就能够编写如示例 5-14 所示的程序。

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

预期的输出如下所示，因为 rect2 的两个维度都小于 rect1 的维度，但 rect3 比 rect1 宽：

Can rect1 hold rect2? true
Can rect1 hold rect3? false

我们知道我们想要定义一个方法，因此它将位于 impl Rectangle 块中。 方法名将是 can_hold，它将接受另一个 Rectangle 的不可变借用（Immutable Borrow）作为参数。 我们可以通过查看调用该方法的代码来判断参数的类型： rect1.can_hold(&rect2) 传入了 &rect2，这是对 rect2（一个 Rectangle 实例）的不可变借用。 这是合理的，因为我们只需要读取 rect2（而不是写入，写入意味着我们需要可变借用）， 并且我们希望 main 保留 rect2 的所有权，以便在调用 can_hold 方法后可以再次使用它。 can_hold 的返回值将是一个布尔值（Boolean），其实现将分别检查 self 的宽度和高度是否大于另一个 Rectangle 的宽度和高度。 让我们将新的 can_hold 方法添加到示例 5-13 中的 impl 块中，如示例 5-15 所示。

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

当我们使用示例 5-14 中的 main 函数运行此代码时，我们将得到预期的输出。 方法可以接受多个参数，这些参数是在 self 参数之后添加到签名中的，并且这些参数的工作方式与函数中的参数一样。

关联函数（Associated Functions）

在 impl 块中定义的所有函数都称为关联函数（Associated Functions），因为它们与 impl 后面命名的类型相关联。 我们可以定义没有 self 作为第一个参数的关联函数（因此不是方法），因为它们不需要类型的实例来工作。 我们已经使用过一个这样的函数：定义在 String 类型上的 String::from 函数。

不是方法的关联函数通常用作构造函数（Constructor），它们将返回该结构体的新实例。 这些通常被称为 new，但 new 不是一个特殊的名称，也不是内建在语言中的。 例如，我们可以选择提供一个名为 square 的关联函数，它只有一个维度参数，并将其同时用作宽度和高度， 这样就能更容易地创建一个正方形 Rectangle，而不必指定两次相同的值：

文件名：src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

返回类型和函数体中的 Self 关键字是 impl 关键字后面出现的类型的别名，在本例中是 Rectangle。

要调用这个关联函数，我们使用结构体名称加上 :: 语法；例如 let sq = Rectangle::square(3);。 这个函数被结构体命名空间（Namespace）化：:: 语法既用于关联函数，也用于模块（Module）创建的命名空间。 我们将在第 7 章中讨论模块。

多个 impl 块（Multiple impl Blocks）

每个结构体允许拥有多个 impl 块。例如，示例 5-15 等价于示例 5-16 中所示的代码，其中每个方法都有自己的 impl 块。

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

在这里，将这些方法分离到多个 impl 块中没有任何理由，但这是有效的语法。 我们将在第 10 章中看到多个 impl 块有用的情况，届时我们将讨论泛型（Generic）类型和 trait。

总结（Summary）

结构体让你可以创建对你的领域有意义的自定义类型（Custom Type）。 通过使用结构体，你可以将相关联的数据片段保持彼此连接，并为每个片段命名，使你的代码清晰明了。 在 impl 块中，你可以定义与你的类型相关联的函数，而方法是关联函数的一种，让你可以指定结构体实例所具有的行为。

但结构体并不是创建自定义类型的唯一方式：让我们转向 Rust 的枚举（Enum）功能，为你的工具箱再添一件工具。

枚举与模式匹配（Enums and Pattern Matching）

在本章中，我们将研究枚举（Enumeration），也简称为 enum。 枚举允许你通过枚举其可能的变体（Variant）来定义一个类型。 首先，我们将定义并使用一个枚举，以展示枚举如何将含义与数据一起编码。 接下来，我们将探索一个特别有用的枚举，称为 Option，它表示一个值可以是某个东西，也可以什么都没有。 然后，我们将研究 match 表达式中的模式匹配（Pattern Matching）如何让我们轻松地为不同的枚举值运行不同的代码。 最后，我们将介绍 if let 结构，它是另一种方便而简洁的方式来处理代码中的枚举。

定义枚举

定义枚举（Defining an Enum）

结构体（Struct）为你提供了一种将相关字段和数据组合在一起的方式，比如 Rectangle 及其 width 和 height， 而枚举（Enum）则为你提供了一种表示某个值是一组可能取值中的一个的方式。 例如，我们可能想说 Rectangle 是一组可能的形状之一，其中还包括 Circle 和 Triangle。 为此，Rust 允许我们将这些可能性编码为一个枚举。

让我们看一个我们可能需要在代码中表达的场景，并了解为什么在这种情况下枚举比结构体更有用且更合适。 假设我们需要处理 IP 地址。目前，有两种主要的 IP 地址标准：第四版（Version Four）和第六版（Version Six）。 由于这些是我们的程序可能遇到的仅有的 IP 地址可能性，我们可以*枚举（Enumerate）*所有可能的变体（Variant）， 这正是“枚举“这个名称的由来。

任何 IP 地址要么是第四版地址，要么是第六版地址，但不能同时是两者。 IP 地址的这一特性使得枚举这种数据结构非常合适，因为枚举值只能是其变体之一。 第四版和第六版地址从根本上说仍然是 IP 地址，因此当代码处理适用于任何一种 IP 地址的情况时，它们应该被视为同一种类型。

我们可以在代码中通过定义一个 IpAddrKind 枚举并列出 IP 地址可能的类型——V4 和 V6——来表达这个概念。 这些就是该枚举的变体（Variant）：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind 现在是一个自定义数据类型（Custom Data Type），我们可以在代码的其他地方使用它。

枚举值（Enum Values）

我们可以像下面这样创建 IpAddrKind 的两个变体的实例：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

请注意，枚举的变体被命名空间化（Namespaced）在其标识符之下，我们使用双冒号来分隔两者。 这很有用，因为现在 IpAddrKind::V4 和 IpAddrKind::V6 这两个值都属于同一类型：IpAddrKind。 然后，我们可以例如定义一个接受任何 IpAddrKind 的函数：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

我们可以使用任一变体调用此函数：

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

使用枚举还有更多优势。进一步思考我们的 IP 地址类型，目前我们没有办法存储实际的 IP 地址数据（Data）； 我们只知道它的*类型（Kind）*是什么。鉴于你刚刚在第 5 章中学到了结构体，你可能会倾向于用结构体来解决这个问题， 如示例 6-1 所示。

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

在这里，我们定义了一个结构体 IpAddr，它有两个字段：一个类型为 IpAddrKind（我们之前定义的枚举）的 kind 字段， 和一个类型为 String 的 address 字段。我们有两个该结构体的实例。 第一个是 home，它的 kind 值为 IpAddrKind::V4，关联的地址数据为 127.0.0.1。 第二个实例是 loopback。它的 kind 值为 IpAddrKind 的另一个变体 V6，并关联了地址 ::1。 我们使用结构体将 kind 和 address 值捆绑在一起，因此现在变体与值相关联了。

然而，仅使用枚举来表示相同的概念更加简洁：与其在结构体中包含枚举，我们可以将数据直接放入每个枚举变体中。 这个新的 IpAddr 枚举定义表示 V4 和 V6 两个变体都将拥有关联的 String 值：

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

我们将数据直接附加到枚举的每个变体上，因此不需要额外的结构体。 在这里，也更容易看到枚举工作方式的另一个细节：我们定义的每个枚举变体的名称同时也会变成一个函数， 用于构造该枚举的实例。也就是说，IpAddr::V4() 是一个函数调用，它接受一个 String 参数并返回一个 IpAddr 类型的实例。 作为定义枚举的结果，我们会自动获得这个构造函数。

使用枚举而不是结构体还有另一个优势：每个变体可以拥有不同类型和数量的关联数据。 第四版 IP 地址总是有四个数值分量，其值介于 0 到 255 之间。 如果我们想将 V4 地址存储为四个 u8 值，但仍将 V6 地址表示为一个 String 值，用结构体是做不到的。 枚举可以轻松处理这种情况：

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

我们已经展示了几种不同的方式来定义数据结构来存储第四版和第六版 IP 地址。 然而，事实证明，存储 IP 地址并编码其类型是如此常见，以至于标准库已经有一个我们可以使用的定义！ 让我们看看标准库是如何定义 IpAddr 的。它具有与我们定义和使用的完全相同的枚举和变体， 但它将地址数据以两个不同结构体的形式嵌入到变体中，这两个结构体针对每个变体有不同的定义：

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

这段代码说明你可以在枚举变体中放入任何类型的数据：例如字符串、数值类型或结构体。 你甚至可以包含另一个枚举！此外，标准库中的类型通常不会比你想到的要复杂多少。

请注意，尽管标准库中包含 IpAddr 的定义，我们仍然可以创建和使用自己的定义而不会产生冲突， 因为我们尚未将标准库中的定义引入我们自己的作用域（Scope）。我们将在第 7 章中详细讨论将类型引入作用域。

让我们再看看示例 6-2 中的另一个枚举示例：这个枚举的变体中嵌入了多种多样的类型。

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

这个枚举有四个变体，具有不同的类型：

• Quit：完全没有关联数据
• Move：有命名字段（Named Field），就像结构体一样
• Write：包含一个单独的 String
• ChangeColor：包含三个 i32 值

定义像示例 6-2 中那样的带有变体的枚举，类似于定义不同类型的结构体定义， 只不过枚举不使用 struct 关键字，而且所有变体都组合在 Message 类型之下。 以下结构体可以持有与前面枚举变体相同的数据：

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

但是如果我们使用这些不同的结构体，每个结构体都有自己的类型，那么我们就无法像使用示例 6-2 中定义的 Message 枚举（它是一个单一类型）那样轻松地定义一个函数来接收任何这些类型的消息。

枚举和结构体之间还有一个相似之处：正如我们可以使用 impl 在结构体上定义方法一样， 我们也可以在枚举上定义方法。下面是一个我们可以在 Message 枚举上定义的名为 call 的方法：

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

方法体将使用 self 来获取我们调用该方法的值。在这个例子中，我们创建了一个变量 m， 其值为 Message::Write(String::from("hello"))，当 m.call() 运行时，self 在 call 方法体中就是这个值。

让我们来看看标准库中另一个非常常见且有用的枚举：Option。

Option 枚举（The Option Enum）

本节对 Option 进行案例研究，它是标准库定义的另一个枚举。 Option 类型编码了这样一种非常常见的场景：某个值可能是某个东西，也可能什么都不是。

例如，如果你请求一个非空列表（List）中的第一个项，你会得到一个值。 如果你请求一个空列表中的第一个项，你会什么也得不到。用类型系统来表达这个概念意味着编译器可以检查你是否处理了所有应该处理的情况； 这一功能可以防止在其他编程语言中极其常见的错误。

编程语言的设计通常被考虑为包含哪些特性，但排除哪些特性也同样重要。 Rust 没有许多其他语言拥有的 null 特性。Null 是一个表示没有值存在的值。 在有 null 的语言中，变量总是可能处于两种状态之一：null 或非 null。

在 2009 年的演讲“Null References: The Billion Dollar Mistake“（空引用：十亿美元的错误）中，null 的发明者 Tony Hoare 这样说：

我将其称为我的十亿美元错误。那时，我正在为一个面向对象语言设计第一个全面的引用类型系统。 我的目标是确保所有引用的使用都是绝对安全的，由编译器自动进行检查。 但我无法抗拒加入空引用的诱惑，仅仅因为它实现起来太容易了。 这导致了无数的错误、漏洞和系统崩溃，在过去四十年中可能造成了价值十亿美元的痛苦和损失。

null 值的问题在于，如果你尝试将 null 值作为非 null 值使用，你会得到某种错误。 由于这种 null 或非 null 的特性无处不在，因此极易犯此类错误。

然而，null 试图表达的概念仍然是有用的：null 是一个因某种原因当前无效或缺失的值。

问题实际上不在于概念，而在于具体的实现。因此，Rust 没有 null， 但它确实有一个可以编码值存在或缺失概念的枚举。这个枚举就是 Option<T>， 它由标准库定义如下：

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Option<T> 枚举非常有用，以至于它甚至被包含在预导入（Prelude）中；你无需显式地将其引入作用域。 它的变体也包含在预导入中：你可以直接使用 Some 和 None 而无需 Option:: 前缀。 Option<T> 枚举仍然只是一个普通的枚举，Some(T) 和 None 仍然是类型 Option<T> 的变体。

<T> 语法是 Rust 的一个我们尚未讨论过的特性。它是一个泛型类型参数（Generic Type Parameter）， 我们将在第 10 章中更详细地介绍泛型（Generic）。目前，你只需要知道 <T> 表示 Option 枚举的 Some 变体可以持有任意类型的一个数据， 而每个用于替代 T 的具体类型都会使整个 Option<T> 类型成为一个不同的类型。 以下是一些使用 Option 值来持有数字类型和字符类型的示例：

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

some_number 的类型是 Option<i32>。some_char 的类型是 Option<char>，这是一个不同的类型。 Rust 可以推断出这些类型，因为我们在 Some 变体中指定了值。对于 absent_number， Rust 要求我们标注整个 Option 类型：编译器无法仅通过查看 None 值来推断相应的 Some 变体将持有哪种类型。 在这里，我们告诉 Rust 我们打算让 absent_number 的类型为 Option<i32>。

当我们有一个 Some 值时，我们知道存在一个值，并且该值保存在 Some 中。 当我们有一个 None 值时，从某种意义上说，它与 null 含义相同：我们没有有效值。 那么，为什么拥有 Option<T> 比拥有 null 更好呢？

简而言之，因为 Option<T> 和 T（其中 T 可以是任何类型）是不同的类型，编译器不会允许我们将 Option<T> 值当作肯定有效的值来使用。 例如，这段代码无法编译，因为它试图将 i8 与 Option<i8> 相加：

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

如果我们运行以上代码的话，那么我们竟会得到以下错误:

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `enums` (bin "enums") due to 1 previous error

实际上，这个错误消息意味着 Rust 不知道如何将 i8 和 Option<i8> 相加，因为它们是不同的类型。 当我们在 Rust 中有一个像 i8 这样的类型的值时，编译器将确保我们始终有一个有效的值。 我们可以放心地继续使用，而不必在使用该值之前检查 null。 只有当我们有一个 Option<i8>（或者我们正在使用的任何类型的值）时，我们才需要担心可能没有值， 并且编译器会确保我们在使用该值之前处理了这种情况。

换句话说，你必须先将 Option<T> 转换为 T，然后才能对其执行 T 的操作。 通常，这有助于捕获 null 最常见的问题之一：假设某个东西不为 null，但实际上它是。

消除错误假定非 null 值的风险有助于你对自己的代码更有信心。 为了拥有一个可能为 null 的值，你必须通过将该值的类型设为 Option<T> 来显式选择加入。 然后，在使用该值时，你必须显式处理该值为 null 的情况。 只要一个值的类型不是 Option<T>，你就可以安全地假定该值不为 null。 这是 Rust 的一个刻意设计决策，旨在限制 null 的普遍性，并增强 Rust 代码的安全性。

那么，当你有一个类型为 Option<T> 的值时，如何从 Some 变体中获取 T 值以便使用该值呢？ Option<T> 枚举拥有大量在各种情况下都有用的方法；你可以在其文档中查看。 熟悉 Option<T> 上的方法将对你的 Rust 之旅极为有益。

一般而言，为了使用 Option<T> 值，你需要有处理每个变体的代码。 你需要一些仅在拥有 Some(T) 值时才会运行的代码，并且该代码可以使用内部的 T。 你需要另一些仅在拥有 None 值时才会运行的代码，而该代码没有可用的 T 值。 match 表达式是一个与枚举一起使用时就恰好能做到这一点的控制流构造（Control Flow Construct）： 它将根据枚举的变体来运行不同的代码，并且这些代码可以使用匹配值内部的数据。

match 控制流结构

match 控制流构造（The match Control Flow Construct）

Rust 有一个极其强大的控制流构造（Control Flow Construct）称为 match，它允许你将一个值与一系列模式（Pattern）进行比较，然后根据匹配的模式执行代码。 模式可以由字面量值（Literal Value）、变量名、通配符（Wildcard）和许多其他内容组成； 第 19 章涵盖了所有不同类型的模式及其功能。 match 的强大之处在于模式的表现力以及编译器会确认所有可能的情况都得到了处理。

将 match 表达式想象成一台硬币分拣机：硬币沿着带有各种大小孔洞的轨道滑下，每枚硬币都会从它遇到的第一个适合的孔洞中落下。 类似地，值会依次通过 match 中的每个模式，在值“适合“的第一个模式处，该值落入关联的代码块中并在执行期间被使用。

说到硬币，让我们用 match 以它们为例！我们可以编写一个函数，接收一枚未知的美国硬币， 以类似于计数机器的方式确定它是哪种硬币，并返回其面值（以美分为单位），如示例 6-3 所示。

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

让我们分解 value_in_cents 函数中的 match。首先，我们列出 match 关键字，后跟一个表达式， 在本例中是值 coin。这看起来与 if 使用的条件表达式非常相似，但有一个很大的区别： 对于 if，条件需要求值为一个布尔值（Boolean），但在这里它可以是任何类型。 本例中 coin 的类型是我们在第一行定义的 Coin 枚举。

接下来是 match 分支（Arm）。一个分支有两个部分：一个模式和一些代码。 这里的第一个分支有一个模式，即值 Coin::Penny，然后是 => 运算符，它将模式和要运行的代码分隔开。 本例中的代码就是值 1。每个分支用逗号与下一个分支分隔。

当 match 表达式执行时，它会将结果值按顺序与每个分支的模式进行比较。如果一个模式匹配该值，则执行与该模式关联的代码。如果该模式不匹配该值，则继续执行下一个分支，这与硬币分拣机非常相似。我们可以根据需要拥有任意多个分支：在示例 6-3 中，我们的 match 有四个分支。

每个分支关联的代码都是一个表达式（Expression），而匹配分支中表达式的结果值就是整个 match 表达式返回的值。

如果 match 分支代码很短，我们通常不会使用花括号，就像示例 6-3 中每个分支只是返回一个值那样。如果你想在 match 分支中运行多行代码，你必须使用花括号，并且分支后面的逗号是可选的。例如，以下代码在每次使用 Coin::Penny 调用该方法时都会打印“Lucky penny!”，但它仍然返回块的最后一个值 1：

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

绑定值的模式（Patterns That Bind to Values）

match 分支的另一个有用特性是它们可以绑定到与模式匹配的值的一部分。这就是我们可以从枚举变体中提取值的方式。

举个例子，让我们修改一个枚举变体，使其内部包含数据。从 1999 年到 2008 年，美国铸造的 25 美分硬币（quarters）在其中一个面印有 50 个州中每个州的不同图案。没有其他硬币拥有州图案，因此只有 25 美分硬币有这个额外值。我们可以通过将 Quarter 变体修改为包含一个存储在其中的 UsState 值来将这些信息添加到我们的 enum 中，我们在示例 6-4 中已经这样做了。

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

假设一个朋友正在努力收集全部 50 个州的 25 美分硬币。当我们按硬币类型分类零钱时，我们还会喊出每个 25 美分硬币关联的州名，这样如果朋友还没有这个州的硬币，他们就可以将其添加到收藏中。

在此代码的 match 表达式中，我们向匹配 Coin::Quarter 变体值的模式添加了一个名为 state 的变量。当匹配到 Coin::Quarter 时，state 变量将绑定到该 25 美分硬币的州的值。然后，我们可以在该分支的代码中使用 state，如下所示：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

如果我们调用 value_in_cents(Coin::Quarter(UsState::Alaska))，coin 将是 Coin::Quarter(UsState::Alaska)。当我们将该值与每个 match 分支进行比较时，直到 Coin::Quarter(state) 之前没有任何分支匹配。此时，state 的绑定将是值 UsState::Alaska。然后我们可以在 println! 表达式中使用该绑定，从而从 Quarter 的 Coin 枚举变体中取出内部的州值。

Option<T> 的 match 模式（The Option<T> match Pattern）

在上一节中，我们想要在使用 Option<T> 时从 Some 中取出内部的 T 值；我们也可以使用 match 来处理 Option<T>，就像我们对 Coin 枚举所做的那样！不再比较硬币，而是比较 Option<T> 的变体，但 match 表达式的工作方式保持不变。

假设我们想编写一个函数，它接收一个 Option<i32>，如果内部有值，则将该值加 1。如果内部没有值，则函数应返回 None 值，并且不尝试执行任何操作。

得益于 match，这个函数非常容易编写，如示例 6-5 所示。

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

让我们更详细地检查 plus_one 的第一次执行。当我们调用 plus_one(five) 时，plus_one 函数体中的变量 x 将具有值 Some(5)。然后我们将该值与每个 match 分支进行比较：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 值不匹配模式 None，因此我们继续到下一个分支：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 匹配 Some(i) 吗？匹配了！我们有相同的变体。i 绑定到 Some 中包含的值，因此 i 的值为 5。然后执行 match 分支中的代码，因此我们将 i 的值加 1，并创建一个新的 Some 值，其中包含我们的总数 6。

现在让我们考虑示例 6-5 中 plus_one 的第二次调用，其中 x 是 None。我们进入 match 并与第一个分支进行比较：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

匹配了！没有要加的值，因此程序停止并返回 => 右侧的 None 值。因为第一个分支已匹配，不再比较其他分支。

结合使用 match 和枚举在许多情况下都很有用。你会在 Rust 代码中经常看到这种模式：对枚举进行 match，将变量绑定到内部的数据，然后基于它执行代码。一开始可能有点棘手，但一旦你习惯了，你会希望所有语言都有这个特性。它一直是用户的最爱。

match 是穷尽的（Matches Are Exhaustive）

关于 match 还有一个方面需要讨论：分支的模式必须覆盖所有可能性。考虑我们 plus_one 函数的这个版本，它包含一个 bug，无法编译：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

我们没有处理 None 的情况，因此这段代码会导致 bug。幸运的是，这是 Rust 能够捕捉到的 bug。如果我们尝试编译这段代码，会得到以下错误：

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `enums` (bin "enums") due to 1 previous error

Rust 知道我们没有覆盖所有可能的情况，甚至知道我们忘记了哪个模式！Rust 中的 match 是穷尽的（exhaustive）：我们必须覆盖每一种可能性，代码才能有效。特别是在 Option<T> 的情况下，当 Rust 阻止我们忘记显式处理 None 情况时，它保护了我们不会在可能为 null 时假设我们有一个值，从而使之前讨论的十亿美元错误（billion-dollar mistake）变得不可能。

通配模式与 _ 占位符（Catch-All Patterns and the _ Placeholder）

使用枚举，我们还可以对少数特定值执行特殊操作，而对所有其他值执行一个默认操作。假设我们在实现一个游戏，如果掷骰子掷出 3，你的角色不会移动，而是获得一顶漂亮的新帽子。如果掷出 7，你的角色会失去一顶漂亮的帽子。对于所有其他值，你的角色在游戏板上移动相应数量的格子。下面是一个实现该逻辑的 match 表达式，掷骰子的结果是硬编码的而不是随机值，所有其他逻辑由没有函数体的函数表示，因为实际实现它们超出了本例的范围：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

对于前两个分支，模式是字面量值 3 和 7。对于覆盖所有其他可能值的最后一个分支，模式是我们选择命名为 other 的变量。other 分支运行的代码通过将该变量传递给 move_player 函数来使用它。

这段代码可以编译，尽管我们还没有列出 u8 可以拥有的所有可能值，因为最后一个模式将匹配所有未特别列出的值。这种通配模式满足了 match 必须穷尽的要求。请注意，我们必须将通配分支放在最后，因为模式是按顺序求值的。如果我们把通配分支放在前面，其他分支将永远不会运行，因此如果我们添加位于通配分支之后的分支，Rust 会发出警告！

Rust 也有一种模式，当我们想要通配但不想在通配模式中使用该值时可以使用：_ 是一个特殊模式，它匹配任何值但不会绑定到该值。这告诉 Rust 我们不打算使用该值，因此 Rust 不会警告我们有一个未使用的变量。

让我们修改游戏规则：现在，如果你掷出的数字不是 3 或 7，你必须重新掷。我们不再需要使用通配值，因此我们可以修改代码，使用 _ 代替名为 other 的变量：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

这个示例也满足了穷尽性要求，因为我们在最后一个分支中显式地忽略了所有其他值；我们没有忘记任何东西。

最后，我们再次修改游戏规则，这样如果你掷出的数字不是 3 或 7，你的回合就不会发生任何事情。我们可以通过使用单元值（unit value）（即我们在“元组类型（The Tuple Type）”章节中提到的空元组类型）作为 _ 分支的代码来表达这一点：

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

在这里，我们显式地告诉 Rust，我们不打算使用任何不匹配前面分支模式的其他值，并且我们不想在这种情况下运行任何代码。

关于模式和匹配的更多内容，我们将在第 19 章中介绍。现在，我们将继续学习 if let 语法，它在 match 表达式略显冗长的情况下可能很有用。

使用 if let 和 let...else 进行简洁的控制流

使用 if let 和 let...else 的简洁控制流（Concise Control Flow with if let and let...else）

if let 语法让你可以将 if 和 let 组合成一种更简洁的方式来处理匹配一种模式的值，同时忽略其余值。考虑示例 6-6 中的程序，它对 config_max 变量中的 Option<u8> 值进行匹配，但只在值为 Some 变体时才执行代码。

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

如果值是 Some，我们通过在模式中将值绑定到变量 max 来打印出 Some 变体中的值。我们不想对 None 值做任何处理。为了满足 match 表达式的要求，我们在只处理了一个变体之后必须加上 _ => ()，这是烦人的样板代码（Boilerplate Code）。

相反，我们可以使用 if let 以更短的方式编写。以下代码的行为与示例 6-6 中的 match 相同：

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

if let 语法接受一个模式和一个表达式，两者用等号分隔。它的工作方式与 match 相同，其中表达式被传递给 match，而模式则是其第一个分支。在这个例子中，模式是 Some(max)，max 绑定到 Some 内部的值。然后，我们可以在 if let 块的函数体中使用 max，就像在相应的 match 分支中使用 max 一样。if let 块中的代码只在值匹配该模式时才运行。

使用 if let 意味着更少的输入、更少的缩进和更少的样板代码。但是，你失去了 match 强制要求的穷尽性检查（Exhaustive Checking），该检查能确保你不会忘记处理任何情况。在 match 和 if let 之间进行选择取决于你在特定情况下的操作，以及简洁性的获得是否值得失去穷尽性检查。

换句话说，你可以将 if let 视为 match 的语法糖（Syntax Sugar），它在值匹配一个模式时运行代码，然后忽略所有其他值。

我们可以在 if let 中包含一个 else。与 else 配套的代码块等同于与 if let 和 else 等价的 match 表达式中 _ 分支的代码块。回顾示例 6-4 中的 Coin 枚举定义，其中 Quarter 变体还持有一个 UsState 值。如果我们想统计所有看到的非 25 美分硬币，同时公布 25 美分的州，我们可以使用 match 表达式来实现，如下所示：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

或者我们可以使用 if let 和 else 表达式，如下所示：

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

使用 let...else 保持在“快乐路径“上（Staying on the “Happy Path” with let...else）

一种常见的模式是当值存在时执行某些计算，否则返回默认值。继续我们带有 UsState 值的硬币示例，如果我们想根据 25 美分硬币上的州的历史年代说一些有趣的话，我们可能会在 UsState 上引入一个方法来检查州的年龄，如下所示：

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

然后，我们可能使用 if let 来匹配硬币的类型，在条件体内引入一个 state 变量，如示例 6-7 所示。

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

这样能完成任务，但它将工作推入了 if let 语句的函数体中，如果要完成的工作更复杂，可能很难看清楚顶层分支之间的关系。我们也可以利用表达式会产生值这一事实，要么从 if let 产生 state，要么提前返回，如示例 6-8 所示。（你也可以用 match 实现类似的效果。）

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

不过，这种方式也有点难以理解！if let 的一个分支产生一个值，而另一个分支则直接从函数中返回。

为了让这种常见模式更易于表达，Rust 提供了 let...else。let...else 语法在左侧接受一个模式，在右侧接受一个表达式，与 if let 非常相似，但它没有 if 分支，只有 else 分支。如果模式匹配，它会将模式中的值绑定到外部作用域。如果模式不匹配，程序将进入 else 分支，该分支必须从函数中返回。

在示例 6-9 中，你可以看到使用 let...else 代替 if let 时示例 6-8 的效果。

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

注意，通过这种方式，函数的主体保持在“快乐路径“（Happy Path）上，而不像 if let 那样两个分支具有明显不同的控制流。

如果你遇到程序逻辑过于冗长而无法用 match 表达的情况，请记住 if let 和 let...else 也在你的 Rust 工具箱中。

总结（Summary）

到目前为止，我们已经介绍了如何使用枚举（Enum）来创建自定义类型（Custom Type），这些类型可以是一组枚举值中的一个。我们已经展示了标准库的 Option<T> 类型如何帮助你使用类型系统来防止错误。当枚举值包含数据时，你可以使用 match 或 if let 来提取和使用这些值，具体取决于你需要处理多少种情况。

你的 Rust 程序现在可以使用结构体（Struct）和枚举来表达你所在领域的概念。创建自定义类型在 API 中使用可以确保类型安全：编译器将确保你的函数只获得每个函数所期望的类型的值。

为了向你的用户提供一个组织良好的 API，该 API 使用起来简单明了，并且只暴露你的用户真正需要的内容，现在让我们转向 Rust 的模块（Module）。

使用包（Package）、Crate 和模块（Module）管理不断增长的项目（Managing Growing Projects with Packages, Crates, and Modules）

随着你编写大型程序，组织代码将变得越来越重要。通过对相关功能进行分组，并分隔具有不同特性的代码，你将明确知道在哪里可以找到实现特定功能的代码，以及在哪里更改功能的工作方式。

我们目前编写的程序都放在一个文件中的一个模块中。随着项目增长，你应该将代码组织成多个模块，然后再分成多个文件。一个包（Package）可以包含多个二进制 crate，并可选择包含一个库 crate。随着包的增长，你可以将部分内容提取到单独的 crate 中，使其成为外部依赖。本章将涵盖所有这些技术。对于由一组相互关联且共同演进的包组成的大型项目，Cargo 提供了工作空间（Workspace），我们将在第 14 章的“Cargo 工作空间”中介绍。

我们还将讨论封装（Encapsulation）实现细节，这让你能够在更高层次上重用代码：一旦你实现了一个操作，其他代码可以通过其公共接口（Public Interface）调用你的代码，而无需知道实现的具体工作方式。编写代码的方式决定了哪些部分是供其他代码使用的公共部分，哪些是你保留修改权利的私有实现细节。这是另一种限制你需要记住的细节量的方法。

一个相关的概念是作用域（Scope）：代码编写的嵌套上下文中有一组被定义为“在作用域内“的名称。在阅读、编写和编译代码时，程序员和编译器需要知道特定位置的特定名称是指变量、函数、结构体（Struct）、枚举（Enum）、模块（Module）、常量还是其他项，以及该项的含义。你可以创建作用域，并更改哪些名称在作用域内或不在作用域内。你不能在同一个作用域中拥有两个同名的项；有工具可用于解决名称冲突。

Rust 有许多特性，可用于管理代码的组织，包括哪些细节被暴露、哪些细节是私有的，以及程序中每个作用域中有哪些名称。这些特性有时统称为模块系统（Module System），包括：

• 包（Package）：一种 Cargo 特性，用于构建、测试和共享 crate
• Crate：生成库（Library）或可执行文件（Executable）的模块树
• 模块（Module）和 use：允许你控制路径（Path）的组织、作用域和私有性（Privacy）
• 路径（Path）：命名某个项（Item）的方式，例如结构体、函数或模块

在本章中，我们将涵盖所有这些特性，讨论它们如何交互，并说明如何使用它们来管理作用域。到本章结束时，你应该对模块系统有扎实的理解，并能像专业人士一样处理作用域！

包与 Crate

包（Package）和 Crate（Packages and Crates）

我们将介绍的模块系统的第一部分是包（Package）和 crate。

Crate 是 Rust 编译器在单次处理中考虑的最小代码量。即使你运行 rustc 而不是 cargo，并传递单个源代码文件（正如我们在第 1 章的“Rust 程序基础”中所做的那样），编译器也会将该文件视为一个 crate。Crate 可以包含模块（Module），模块可以定义在其他文件中，并与 crate 一起编译，我们将在接下来的小节中看到。

Crate 有两种形式：二进制 crate（Binary Crate）或库 crate（Library Crate）。二进制 crate 是可以编译为可执行文件的程序，比如命令行程序或服务器。每个二进制 crate 必须有一个名为 main 的函数，定义可执行文件运行时发生什么。到目前为止，我们创建的所有 crate 都是二进制 crate。

库 crate 没有 main 函数，也不会编译为可执行文件。相反，它们定义了旨在与多个项目共享的功能。例如，我们在第 2 章中使用的 rand crate 提供了生成随机数的功能。大多数情况下，当 Rust 程序员说“crate“时，他们指的是库 crate，并且他们将“crate“与通用编程概念中的“库“（Library）混用。

Crate 根（Crate Root）是一个源代码文件，Rust 编译器从它开始，它构成了你的 crate 的根模块（Root Module）（我们将在“使用模块控制作用域和私有性”中深入讲解模块）。

包（Package）是一个或多个 crate 的集合，提供一组功能。一个包包含一个 Cargo.toml 文件，描述如何构建这些 crate。Cargo 本身实际上就是一个包，它包含了我们一直用来构建代码的命令行工具的二进制 crate。Cargo 包还包含一个该二进制 crate 所依赖的库 crate。其他项目可以依赖 Cargo 库 crate，来使用 Cargo 命令行工具所使用的相同逻辑。

一个包可以包含任意多的二进制 crate，但最多只能包含一个库 crate。一个包必须至少包含一个 crate，无论是库 crate 还是二进制 crate。

让我们看看创建包时会发生什么。首先，我们输入命令 cargo new my-project：

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

运行 cargo new my-project 后，我们使用 ls 来查看 Cargo 创建了什么。在 my-project 目录中，有一个 Cargo.toml 文件，这就是一个包。还有一个 src 目录，其中包含 main.rs。在文本编辑器中打开 Cargo.toml，注意其中没有提到 src/main.rs。Cargo 遵循一个约定，即 src/main.rs 是与包同名的二进制 crate 的 crate 根。同样，Cargo 知道如果包目录中包含 src/lib.rs，则该包包含一个与包同名的库 crate，并且 src/lib.rs 是其 crate 根。Cargo 将 crate 根文件传递给 rustc 来构建库或二进制文件。

在这里，我们有一个只包含 src/main.rs 的包，这意味着它只包含一个名为 my-project 的二进制 crate。如果一个包同时包含 src/main.rs 和 src/lib.rs，则它有两个 crate：一个二进制 crate 和一个库 crate，两者都与包同名。一个包可以通过在 src/bin 目录中放置文件来拥有多个二进制 crate：每个文件都将是一个单独的二进制 crate。

使用模块控制作用域与私有性

使用模块控制作用域和私有性（Control Scope and Privacy with Modules）

在本节中，我们将讨论模块（Module）和模块系统的其他部分，即路径（Path），它允许你命名项（Item）；use 关键字，将路径引入作用域；以及 pub 关键字，使项变为公共的。我们还将讨论 as 关键字、外部包（External Package）和全局运算符（Glob Operator）。

模块速查表（Modules Cheat Sheet）

在深入了解模块和路径的细节之前，我们在此提供一个快速参考，介绍模块、路径、use 关键字和 pub 关键字在编译器中的工作方式，以及大多数开发者如何组织他们的代码。我们将在本章中逐一举例说明每条规则，但这里是一个很好的参考位置，用于提醒模块的工作方式。

• 从 crate 根开始：在编译一个 crate 时，编译器首先在 crate 根文件（对于库 crate 通常是 src/lib.rs，对于二进制 crate 通常是 src/main.rs）中寻找要编译的代码。
• 声明模块：在 crate 根文件中，你可以声明新的模块；比如你用 mod garden; 声明一个 “garden” 模块。编译器会在以下位置寻找模块的代码：
  • 内联（Inline），在大括号内取代 mod garden 后面的分号
  • 在文件 src/garden.rs 中
  • 在文件 src/garden/mod.rs 中
• 声明子模块（Submodule）：在除 crate 根之外的任何文件中，你都可以声明子模块。例如，你可以在 src/garden.rs 中声明 mod vegetables;。编译器会在以父模块命名的目录中寻找子模块的代码，具体在以下位置：
  • 内联，直接跟在 mod vegetables 之后，在大括号内而不是分号
  • 在文件 src/garden/vegetables.rs 中
  • 在文件 src/garden/vegetables/mod.rs 中
• 模块中代码的路径：一旦一个模块成为你的 crate 的一部分，只要私有性规则允许，你可以使用代码的路径从该 crate 的任何其他位置引用该模块中的代码。例如，garden vegetables 模块中的 Asparagus 类型将位于 crate::garden::vegetables::Asparagus。
• 私有 vs. 公共：默认情况下，模块中的代码对其父模块是私有的。要使一个模块变为公共的，用 pub mod 而不是 mod 来声明它。要使公共模块中的项也变为公共的，在其声明前使用 pub。
• use 关键字：在一个作用域内，use 关键字创建项的快捷方式，以减少长路径的重复。在任何可以引用 crate::garden::vegetables::Asparagus 的作用域中，你可以用 use crate::garden::vegetables::Asparagus; 创建一个快捷方式，从此只需写 Asparagus 即可在该作用域中使用该类型。

在这里，我们创建一个名为 backyard 的二进制 crate 来说明这些规则。该 crate 的目录（同样命名为 backyard）包含以下文件和目录：

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

本例中的 crate 根文件是 src/main.rs，其内容如下：

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {plant:?}!");
}

pub mod garden; 这一行告诉编译器包含在 src/garden.rs 中找到的代码，该文件内容为：

pub mod vegetables;

在这里，pub mod vegetables; 表示 src/garden/vegetables.rs 中的代码也被包含进来。该代码为：

#[derive(Debug)]
pub struct Asparagus {}

现在让我们深入这些规则的细节并实际演示！

在模块中对相关代码进行分组（Grouping Related Code in Modules）

模块（Module）让我们在 crate 内组织代码，以提高可读性并便于重用。模块还允许我们控制项的私有性（Privacy），因为模块内的代码默认是私有的。私有项是内部实现细节，不可供外部使用。我们可以选择将模块及其内部的项设为公共的，从而将其暴露出来，允许外部代码使用和依赖它们。

举个例子，让我们编写一个提供餐厅功能的库 crate。我们将定义函数的签名（Signature），但函数体留空，以便专注于代码的组织而不是餐厅的实现。

在餐饮业中，餐厅的某些部分被称为前厅（Front of House），其他部分被称为后厨（Back of House）。前厅是顾客所在的地方；包括主人安排顾客就座、服务员接单和收款以及调酒师制作饮品的地方。后厨是厨师和烹饪人员在厨房工作、洗碗工清洁以及经理进行行政管理工作的地方。

为了以这种方式构建我们的 crate，我们可以将其函数组织到嵌套模块中。运行 cargo new restaurant --lib 创建一个名为 restaurant 的新库。然后将示例 7-1 中的代码输入到 src/lib.rs 中，以定义一些模块和函数签名；这段代码是前厅部分。

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

我们使用 mod 关键字后跟模块名（在本例中为 front_of_house）来定义一个模块。模块体则放在大括号内。在模块内部，我们可以放置其他模块，就像本例中的 hosting 和 serving 模块。模块还可以容纳其他项的定义，例如结构体（Struct）、枚举（Enum）、常量（Constant）、特质（Trait），以及如示例 7-1 中的函数。

通过使用模块，我们可以将相关的定义组合在一起，并说明它们为何相关。使用此代码的程序员可以基于分组来浏览代码，而不必通读所有定义，从而更容易找到与他们相关的定义。向此代码添加新功能的程序员知道将代码放在哪里以保持程序的组织有序。

之前，我们提到 src/main.rs 和 src/lib.rs 被称为 crate 根（Crate Root）。这样命名的原因是，这两个文件中任何一个的内容会在 crate 模块结构的根部形成一个名为 crate 的模块，该结构被称为模块树（Module Tree）。

示例 7-2 展示了示例 7-1 中结构的模块树。

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

这棵树展示了某些模块如何嵌套在其他模块内部；例如，hosting 嵌套在 front_of_house 内部。该树还显示某些模块是兄弟模块（Sibling），这意味着它们定义在同一个模块中；hosting 和 serving 是定义在 front_of_house 内部的兄弟模块。如果模块 A 包含在模块 B 内部，我们说模块 A 是模块 B 的子模块（Child），而模块 B 是模块 A 的父模块（Parent）。请注意，整个模块树都根植于名为 crate 的隐式模块之下。

模块树可能会让你想起计算机上文件系统的目录树；这是一个非常贴切的类比！就像文件系统中的目录一样，你使用模块来组织代码。就像目录中的文件一样，我们需要一种方法来找到我们的模块。

引用模块树中项的方式

引用模块树中项的路径（Paths for Referring to an Item in the Module Tree）

为了告诉 Rust 在模块树中的何处找到某个项（Item），我们使用路径，就像在文件系统中导航时使用路径一样。要调用一个函数，我们需要知道它的路径。

路径有两种形式：

• 绝对路径（Absolute Path）是从 crate 根开始的完整路径；对于来自外部 crate 的代码，绝对路径以 crate 名称开头，对于来自当前 crate 的代码，它以字面量 crate 开头。
• 相对路径（Relative Path）从当前模块开始，使用 self、super 或当前模块中的标识符。

绝对路径和相对路径后都跟着一个或多个由双冒号（::）分隔的标识符。

回到示例 7-1，假设我们要调用 add_to_waitlist 函数。这等同于问：add_to_waitlist 函数的路径是什么？示例 7-3 包含了示例 7-1，但删除了一些模块和函数。

我们将展示两种方式，从 crate 根中定义的新函数 eat_at_restaurant 调用 add_to_waitlist 函数。这些路径是正确的，但仍然存在另一个问题，会阻止该示例按原样编译。我们稍后会解释原因。

eat_at_restaurant 函数是我们库 crate 公共 API（Public API）的一部分，因此我们使用 pub 关键字标记它。在“使用 pub 关键字暴露路径”一节中，我们将更详细地介绍 pub。

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}
    }
}

pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

我们在 eat_at_restaurant 中第一次调用 add_to_waitlist 函数时，使用了绝对路径。add_to_waitlist 函数与 eat_at_restaurant 定义在同一个 crate 中，这意味着我们可以使用 crate 关键字来开始一个绝对路径。然后我们依次包含每个连续的模块，直到到达 add_to_waitlist。你可以想象一个具有相同结构的文件系统：我们会指定路径 /front_of_house/hosting/add_to_waitlist 来运行 add_to_waitlist 程序；使用 crate 名称从 crate 根开始，就像在 shell 中使用 / 从文件系统根开始一样。

我们在 eat_at_restaurant 中第二次调用 add_to_waitlist 时，使用了相对路径。路径以 front_of_house 开头，这是与 eat_at_restaurant 定义在同一模块树级别的模块名称。这里的文件系统等价物是使用路径 front_of_house/hosting/add_to_waitlist。以模块名开头意味着该路径是相对的。

选择使用相对路径还是绝对路径是一个基于项目做出的决定，取决于你是否更可能将项的定义代码与使用该项的代码分开移动还是一起移动。例如，如果我们将 front_of_house 模块和 eat_at_restaurant 函数移动到一个名为 customer_experience 的模块中，我们需要更新到 add_to_waitlist 的绝对路径，但相对路径仍然有效。但是，如果我们将 eat_at_restaurant 函数单独移动到一个名为 dining 的模块中，到 add_to_waitlist 调用的绝对路径将保持不变，但相对路径需要更新。我们通常倾向于指定绝对路径，因为我们更有可能希望彼此独立地移动代码定义和项调用。

让我们尝试编译示例 7-3，找出为什么它还不能编译！我们得到的错误如示例 7-4 所示。

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: module `hosting` is private
 --> src/lib.rs:9:28
  |
9 |     crate::front_of_house::hosting::add_to_waitlist();
  |                            ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
  |                            |
  |                            private module
  |
note: the module `hosting` is defined here
 --> src/lib.rs:2:5
  |
2 |     mod hosting {
  |     ^^^^^^^^^^^

error[E0603]: module `hosting` is private
  --> src/lib.rs:12:21
   |
12 |     front_of_house::hosting::add_to_waitlist();
   |                     ^^^^^^^  --------------- function `add_to_waitlist` is not publicly re-exported
   |                     |
   |                     private module
   |
note: the module `hosting` is defined here
  --> src/lib.rs:2:5
   |
 2 |     mod hosting {
   |     ^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

错误消息说 hosting 模块是私有的。换句话说，我们为 hosting 模块和 add_to_waitlist 函数使用了正确的路径，但 Rust 不允许我们使用它们，因为它无法访问私有部分。在 Rust 中，所有项（函数、方法、结构体、枚举、模块和常量）默认情况下对其父模块是私有的。如果你想让函数或结构体等项变为私有的，就把它放在一个模块中。

父模块中的项不能使用子模块中的私有项，但子模块中的项可以使用其祖先模块中的项。这是因为子模块包装并隐藏了它们的实现细节，但子模块可以看到它们定义所在的上下文。继续我们的比喻，可以将私有性规则想象成餐厅的后勤办公室：那里发生的事情对餐厅顾客来说是私有的，但办公室经理可以看到和做他们经营的餐厅中的一切。

Rust 选择让模块系统以这种方式运行，这样隐藏内部实现细节就是默认行为。这样，你就知道内部代码的哪部分可以在不破坏外部代码的情况下更改。但是，Rust 也赋予你使用 pub 关键字将子模块代码的内部部分暴露给外部祖先模块的能力。

使用 pub 关键字暴露路径（Exposing Paths with the pub Keyword）

让我们回到示例 7-4 中的错误，它告诉我们 hosting 模块是私有的。我们希望父模块中的 eat_at_restaurant 函数能够访问子模块中的 add_to_waitlist 函数，因此我们用 pub 关键字标记 hosting 模块，如示例 7-5 所示。

// ANCHOR: here
mod front_of_house {
    pub mod hosting {
        fn add_to_waitlist() {}
    }
}

// -- snip --
// ANCHOR_END: here
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

不幸的是，示例 7-5 中的代码仍然会导致错误，如示例 7-6 所示。

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:10:37
   |
10 |     crate::front_of_house::hosting::add_to_waitlist();
   |                                     ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

error[E0603]: function `add_to_waitlist` is private
  --> src/lib.rs:13:30
   |
13 |     front_of_house::hosting::add_to_waitlist();
   |                              ^^^^^^^^^^^^^^^ private function
   |
note: the function `add_to_waitlist` is defined here
  --> src/lib.rs:3:9
   |
 3 |         fn add_to_waitlist() {}
   |         ^^^^^^^^^^^^^^^^^^^^

For more information about this error, try `rustc --explain E0603`.
error: could not compile `restaurant` (lib) due to 2 previous errors

发生了什么？在 mod hosting 前面添加 pub 关键字使模块变为公共的。通过这次更改，如果我们可以访问 front_of_house，我们就可以访问 hosting。但 hosting 的内容仍然是私有的；将模块设为公共的并不会使其内容变为公共的。模块上的 pub 关键字只允许其祖先模块中的代码引用它，而不能访问其内部代码。因为模块只是一些容器；仅仅将模块设为公共的，并不能做什么。你需要进一步选择将模块中的一个或多个项也设为公共的。

示例 7-6 中的错误说 add_to_waitlist 函数是私有的。私有性规则适用于结构体、枚举、函数和方法以及模块。

让我们也通过在 add_to_waitlist 函数的定义前添加 pub 关键字来使其变为公共的，如示例 7-7 所示。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

// -- snip --
pub fn eat_at_restaurant() {
    // Absolute path
    crate::front_of_house::hosting::add_to_waitlist();

    // Relative path
    front_of_house::hosting::add_to_waitlist();
}

现在代码可以编译了！要了解为什么添加 pub 关键字让我们能在 eat_at_restaurant 中根据私有性规则使用这些路径，让我们看一下绝对路径和相对路径。

在绝对路径中，我们从 crate 开始，即 crate 模块树的根。front_of_house 模块定义在 crate 根中。虽然 front_of_house 不是公共的，但由于 eat_at_restaurant 函数与 front_of_house 定义在同一个模块中（即 eat_at_restaurant 和 front_of_house 是兄弟模块），我们可以从 eat_at_restaurant 引用 front_of_house。接下来是标记为 pub 的 hosting 模块。我们可以访问 hosting 的父模块，所以我们可以访问 hosting。最后，add_to_waitlist 函数标记为 pub，并且我们可以访问它的父模块，因此这个函数调用可以正常工作！

在相对路径中，逻辑与绝对路径相同，只是第一步不同：路径不是从 crate 根开始，而是从 front_of_house 开始。front_of_house 模块与 eat_at_restaurant 定义在同一个模块中，所以从定义 eat_at_restaurant 的模块开始的相对路径可以正常工作。然后，因为 hosting 和 add_to_waitlist 都标记为 pub，路径的其余部分也可以正常工作，这个函数调用是有效的！

如果你计划共享你的库 crate，以便其他项目可以使用你的代码，那么你的公共 API 就是你与 crate 用户之间的契约，决定了他们如何与你的代码交互。管理公共 API 更改有许多考虑因素，以使人们更容易依赖你的 crate。这些考虑因素超出了本书的范围；如果你对此主题感兴趣，请参阅 Rust API 指南。

使用 super 开始相对路径（Starting Relative Paths with super）

我们可以通过在路径开头使用 super 来构造从父模块开始的相对路径，而不是从当前模块或 crate 根开始。这就像用 .. 语法开始文件系统路径，表示转到父目录。使用 super 允许我们引用我们知道在父模块中的项，当模块与父模块紧密相关但父模块将来可能被移动到模块树的其他位置时，这可以使重新排列模块树更容易。

考虑示例 7-8 中的代码，该代码模拟了厨师修正错误订单并亲自将其带给顾客的情况。定义在 back_of_house 模块中的 fix_incorrect_order 函数通过指定以 super 开头的路径来调用定义在父模块中的 deliver_order 函数。

fn deliver_order() {}

mod back_of_house {
    fn fix_incorrect_order() {
        cook_order();
        super::deliver_order();
    }

    fn cook_order() {}
}

fix_incorrect_order 函数在 back_of_house 模块中，因此我们可以使用 super 转到 back_of_house 的父模块，在本例中即 crate，即根模块。从那里，我们寻找 deliver_order 并找到了它。成功！我们认为 back_of_house 模块和 deliver_order 函数可能保持彼此相同的关系，并且在我们决定重新组织 crate 的模块树时可能会一起移动。因此，我们使用了 super，这样如果此代码被移动到不同的模块，将来需要更新的位置就更少。

使结构体和枚举变为公共的（Making Structs and Enums Public）

我们也可以使用 pub 将结构体和枚举指定为公共的，但在结构体和枚举上使用 pub 有一些额外的细节。如果我们在结构体定义前使用 pub，我们将结构体变为公共的，但结构体的字段仍然是私有的。我们可以根据具体情况决定每个字段是否公共。在示例 7-9 中，我们定义了一个公共的 back_of_house::Breakfast 结构体，其中包含一个公共的 toast 字段和一个私有的 seasonal_fruit 字段。这模拟了餐厅中顾客可以选择餐点附带的面包类型，但厨师根据当季和库存情况决定搭配餐点的水果的情况。可用的水果变化很快，因此顾客不能选择水果，甚至看不到他们会得到什么水果。

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast.
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like.
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal.
    // meal.seasonal_fruit = String::from("blueberries");
}

因为 back_of_house::Breakfast 结构体中的 toast 字段是公共的，所以在 eat_at_restaurant 中，我们可以使用点号表示法（Dot Notation）来读写 toast 字段。请注意，我们不能在 eat_at_restaurant 中使用 seasonal_fruit 字段，因为 seasonal_fruit 是私有的。尝试取消注释修改 seasonal_fruit 字段值的那行代码，看看你会得到什么错误！

另外，请注意，因为 back_of_house::Breakfast 有一个私有字段，该结构体需要提供一个公共关联函数（Associated Function）来构造 Breakfast 的实例（我们在这里将其命名为 summer）。如果 Breakfast 没有这样的函数，我们就无法在 eat_at_restaurant 中创建 Breakfast 的实例，因为我们无法在 eat_at_restaurant 中设置私有字段 seasonal_fruit 的值。

相比之下，如果我们将一个枚举变为公共的，那么它的所有变体会自动变为公共的。我们只需要在 enum 关键字之前加上 pub，如示例 7-10 所示。

mod back_of_house {
    pub enum Appetizer {
        Soup,
        Salad,
    }
}

pub fn eat_at_restaurant() {
    let order1 = back_of_house::Appetizer::Soup;
    let order2 = back_of_house::Appetizer::Salad;
}

因为我们将 Appetizer 枚举设为公共的，所以我们可以在 eat_at_restaurant 中使用 Soup 和 Salad 变体。

除非枚举的变体是公共的，否则枚举并不是很有用；在每种情况下都必须为所有枚举变体添加 pub 注解是很烦人的，因此枚举变体默认是公共的。结构体在其字段不是公共的情况下通常也是有用的，因此结构体字段遵循默认情况下所有内容都是私有的通用规则，除非用 pub 注解。

还有一个涉及 pub 的情况我们尚未涵盖，那就是我们最后一个模块系统特性：use 关键字。我们将首先单独介绍 use，然后展示如何结合使用 pub 和 use。

使用 use 关键字将路径引入作用域

使用 use 关键字将路径引入作用域（Bringing Paths into Scope with the use Keyword）

必须写出完整的路径来调用函数可能会让人感到不便和重复。在示例 7-7 中，无论我们选择绝对路径还是相对路径来访问 add_to_waitlist 函数，每次我们想要调用 add_to_waitlist 时，都必须同时指定 front_of_house 和 hosting。幸运的是，有一种简化此过程的方法：我们可以使用 use 关键字一次性创建一条路径的快捷方式，然后在作用域中的其他地方使用较短的名称。

在示例 7-11 中，我们将 crate::front_of_house::hosting 模块引入 eat_at_restaurant 函数的作用域中，这样我们只需指定 hosting::add_to_waitlist 即可在 eat_at_restaurant 中调用 add_to_waitlist 函数。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

在作用域中添加 use 和路径，类似于在文件系统中创建符号链接（Symbolic Link）。通过在 crate 根中添加 use crate::front_of_house::hosting，hosting 现在是该作用域中的有效名称，就好像 hosting 模块已定义在 crate 根中一样。通过 use 引入作用域的路径也会像其他任何路径一样检查私有性。

请注意，use 只为其所在的特定作用域创建快捷方式。示例 7-12 将 eat_at_restaurant 函数移动到一个名为 customer 的新子模块中，该模块与 use 语句处于不同的作用域，因此函数体将无法编译。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting;

mod customer {
    pub fn eat_at_restaurant() {
        hosting::add_to_waitlist();
    }
}

编译器错误表明该快捷方式不再适用于 customer 模块：

$ cargo build
   Compiling restaurant v0.1.0 (file:///projects/restaurant)
error[E0433]: failed to resolve: use of unresolved module or unlinked crate `hosting`
  --> src/lib.rs:11:9
   |
11 |         hosting::add_to_waitlist();
   |         ^^^^^^^ use of unresolved module or unlinked crate `hosting`
   |
   = help: if you wanted to use a crate named `hosting`, use `cargo add hosting` to add it to your `Cargo.toml`
help: consider importing this module through its public re-export
   |
10 +     use crate::hosting;
   |

warning: unused import: `crate::front_of_house::hosting`
 --> src/lib.rs:7:5
  |
7 | use crate::front_of_house::hosting;
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = note: `#[warn(unused_imports)]` on by default

For more information about this error, try `rustc --explain E0433`.
warning: `restaurant` (lib) generated 1 warning
error: could not compile `restaurant` (lib) due to 1 previous error; 1 warning emitted

请注意，还有一个警告表明 use 在其作用域中不再被使用！要解决此问题，请将 use 也移动到 customer 模块中，或者在子模块 customer 中使用 super::hosting 引用父模块中的快捷方式。

创建惯用的 use 路径（Creating Idiomatic use Paths）

在示例 7-11 中，你可能想知道为什么我们指定 use crate::front_of_house::hosting，然后在 eat_at_restaurant 中调用 hosting::add_to_waitlist，而不是将 use 路径一直指定到 add_to_waitlist 函数以实现相同的结果，如示例 7-13 所示。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

use crate::front_of_house::hosting::add_to_waitlist;

pub fn eat_at_restaurant() {
    add_to_waitlist();
}

虽然示例 7-11 和示例 7-13 完成了相同的任务，但示例 7-11 是使用 use 将函数引入作用域的惯用（Idiomatic）方式。使用 use 将函数的父模块引入作用域，意味着我们在调用函数时必须指定父模块。在调用函数时指定父模块，清楚地表明该函数不是本地定义的，同时最大限度地减少了对完整路径的重复。而示例 7-13 中的代码则不清楚 add_to_waitlist 是在哪里定义的。

另一方面，当使用 use 引入结构体（Struct）、枚举（Enum）和其他项时，指定完整路径是惯用的做法。示例 7-14 展示了将标准库的 HashMap 结构体引入二进制 crate 作用域的惯用方式。

use std::collections::HashMap;

fn main() {
    let mut map = HashMap::new();
    map.insert(1, 2);
}

这种惯用做法背后没有强有力的理由：它只是一种逐渐形成的约定，人们已经习惯了以这种方式阅读和编写 Rust 代码。

这种惯用做法的例外是，如果我们使用 use 语句将两个同名的项引入作用域，因为 Rust 不允许这样做。示例 7-15 展示了如何将两个具有相同名称但父模块不同的 Result 类型引入作用域，以及如何引用它们。

use std::fmt;
use std::io;

fn function1() -> fmt::Result {
    // --snip--
    Ok(())
}

fn function2() -> io::Result<()> {
    // --snip--
    Ok(())
}

如你所见，使用父模块可以区分两个 Result 类型。如果我们改为指定 use std::fmt::Result 和 use std::io::Result，我们将在同一作用域中有两个 Result 类型，当我们使用 Result 时，Rust 将不知道我们指的是哪一个。

使用 as 关键字提供新名称（Providing New Names with the as Keyword）

使用 use 将两个同名的类型引入同一作用域时，还有另一种解决方案：在路径之后，我们可以指定 as 和该类型的一个新的本地名称，即别名（Alias）。示例 7-16 展示了另一种编写示例 7-15 中代码的方式，通过使用 as 重命名两个 Result 类型中的一个。

use std::fmt::Result;
use std::io::Result as IoResult;

fn function1() -> Result {
    // --snip--
    Ok(())
}

fn function2() -> IoResult<()> {
    // --snip--
    Ok(())
}

在第二个 use 语句中，我们为 std::io::Result 类型选择了新名称 IoResult，这不会与我们从 std::fmt 引入作用域的 Result 产生冲突。示例 7-15 和示例 7-16 都被认为是惯用的，因此你可以自行选择！

使用 pub use 重新导出名称（Re-exporting Names with pub use）

当我们使用 use 关键字将名称引入作用域时，该名称在我们导入它的作用域中是私有的。为了使该作用域之外的代码能够引用该名称，就好像它已定义在该作用域中一样，我们可以结合使用 pub 和 use。这种技术称为重新导出（Re-exporting），因为我们将一个项引入作用域，同时也使该项可供其他代码引入它们的作用域。

示例 7-17 展示了示例 7-11 中的代码，其中根模块中的 use 已更改为 pub use。

mod front_of_house {
    pub mod hosting {
        pub fn add_to_waitlist() {}
    }
}

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

在此更改之前，外部代码必须使用路径 restaurant::front_of_house::hosting::add_to_waitlist() 来调用 add_to_waitlist 函数，这还需要将 front_of_house 模块标记为 pub。现在，由于此 pub use 已从根模块重新导出了 hosting 模块，外部代码可以改用路径 restaurant::hosting::add_to_waitlist()。

当代码的内部结构与调用你的代码的程序员对领域的思考方式不同时，重新导出非常有用。例如，在这个餐厅比喻中，经营餐厅的人会想到“前厅“和“后厨“。但光顾餐厅的顾客可能不会以这些术语来看待餐厅的各个部分。通过 pub use，我们可以用一种结构编写代码，但暴露另一种结构。这样做使得我们的库对编写库的程序员和调用库的程序员来说都组织得井井有条。我们将在第 14 章的“导出便捷的公共 API”中再看一个 pub use 的示例，以及它如何影响 crate 的文档。

使用外部包（Using External Packages）

在第 2 章中，我们编写了一个猜谜游戏项目，该项目使用了一个名为 rand 的外部包（External Package）来获取随机数。为了在我们的项目中使用 rand，我们在 Cargo.toml 中添加了以下行：

rand = "0.8.5"

在 Cargo.toml 中将 rand 添加为依赖项（Dependency）会告诉 Cargo 从 crates.io 下载 rand 包及其任何依赖项，并使 rand 可用于我们的项目。

然后，为了将 rand 定义引入我们包的作用域，我们添加了一个以 crate 名称 rand 开头的 use 行，并列出了我们想要引入作用域的项。回想一下，在第 2 章的“生成随机数”中，我们将 Rng 特质（Trait）引入作用域，并调用了 rand::thread_rng 函数：

use std::io;

use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");
}

Rust 社区的成员在 crates.io 上提供了许多包，将其中任何一个引入你的包都涉及相同的步骤：在你的包的 Cargo.toml 文件中列出它们，并使用 use 将其 crate 中的项引入作用域。

请注意，标准库 std 也是一个相对于我们包的外部 crate。因为标准库随 Rust 语言一起发布，我们不需要更改 Cargo.toml 来包含 std。但我们确实需要使用 use 来引用它，以将那里的项引入我们包的作用域。例如，对于 HashMap，我们将使用以下行：

#![allow(unused)]
fn main() {
use std::collections::HashMap;
}

这是一个以标准库 crate 名称 std 开头的绝对路径。

使用嵌套路径整理 use 列表（Using Nested Paths to Clean Up use Lists）

如果我们使用定义在同一个 crate 或同一个模块中的多个项，将每个项列在单独的一行上会占用文件中大量的垂直空间。例如，我们在示例 2-4 的猜谜游戏中的这两个 use 语句将项从 std 引入作用域：

use rand::Rng;
// --snip--
use std::cmp::Ordering;
use std::io;
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

相反，我们可以使用嵌套路径（Nested Path）将相同的项在一行中引入作用域。我们通过指定路径的公共部分，后跟两个冒号，然后在大括号中列出路径中不同的部分来实现，如示例 7-18 所示。

use rand::Rng;
// --snip--
use std::{cmp::Ordering, io};
// --snip--

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    println!("The secret number is: {secret_number}");

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin()
        .read_line(&mut guess)
        .expect("Failed to read line");

    let guess: u32 = guess.trim().parse().expect("Please type a number!");

    println!("You guessed: {guess}");

    match guess.cmp(&secret_number) {
        Ordering::Less => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal => println!("You win!"),
    }
}

在较大的程序中，使用嵌套路径将许多来自相同 crate 或模块的项引入作用域，可以大大减少所需的单独 use 语句数量！

我们可以在路径的任何级别使用嵌套路径，这在组合两个共享子路径的 use 语句时非常有用。例如，示例 7-19 展示了两个 use 语句：一个将 std::io 引入作用域，另一个将 std::io::Write 引入作用域。

use std::io;
use std::io::Write;

这两个路径的公共部分是 std::io，这也是第一个路径的完整内容。要将这两个路径合并为一个 use 语句，我们可以在嵌套路径中使用 self，如示例 7-20 所示。

use std::io::{self, Write};

此行将 std::io 和 std::io::Write 引入作用域。

使用全局运算符导入项（Importing Items with the Glob Operator）

如果我们想将某个路径中定义的所有公共项引入作用域，可以指定该路径后跟 * 全局运算符（Glob Operator）：

#![allow(unused)]
fn main() {
use std::collections::*;
}

这个 use 语句将 std::collections 中定义的所有公共项引入当前作用域。使用全局运算符时要小心！全局运算符可能会使人更难分辨哪些名称在作用域中，以及程序中使用的某个名称是在哪里定义的。此外，如果依赖项更改了其定义，你导入的内容也会随之改变，这可能会在升级依赖项时导致编译器错误，例如依赖项添加了一个与你在同一作用域中的定义同名的定义。

全局运算符通常用于测试，将测试对象的所有内容引入 tests 模块；我们将在第 11 章的“如何编写测试”中讨论这一点。全局运算符有时也作为预导入模式（Prelude Pattern）的一部分使用：请参阅标准库文档了解更多关于该模式的信息。

将模块拆分为不同文件

将模块分离到不同文件中（Separating Modules into Different Files）

到目前为止，本章中的所有示例都在一个文件中定义了多个模块。当模块变得很大时，你可能希望将其定义移到单独的文件中，以使代码更容易浏览。

例如，让我们从示例 7-17 中包含多个餐厅模块的代码开始。我们将模块提取到文件中，而不是将所有模块定义在 crate 根文件中。在本例中，crate 根文件是 src/lib.rs，但此过程也适用于 crate 根文件为 src/main.rs 的二进制 crate。

首先，我们将 front_of_house 模块提取到自己的文件中。删除 front_of_house 模块大括号内的代码，只保留 mod front_of_house; 声明，这样 src/lib.rs 包含示例 7-21 中所示的代码。请注意，在我们创建示例 7-22 中的 src/front_of_house.rs 文件之前，这段代码不会编译。

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
}

接下来，将原来在大括号内的代码放入一个名为 src/front_of_house.rs 的新文件中，如示例 7-22 所示。编译器知道要在此文件中查找，因为它在 crate 根中遇到了名为 front_of_house 的模块声明。

pub mod hosting {
    pub fn add_to_waitlist() {}
}

请注意，你只需要在模块树中一次使用 mod 声明来加载一个文件。一旦编译器知道该文件是项目的一部分（并且因为 mod 语句的位置而知道代码在模块树中的位置），项目中的其他文件应使用指向其声明位置的路径来引用该已加载文件的代码，如“引用模块树中项的路径”一节所述。换句话说，mod 不是你在其他编程语言中可能见过的“include“操作。

接下来，我们将 hosting 模块提取到自己的文件中。这个过程略有不同，因为 hosting 是 front_of_house 的子模块，而不是根模块的子模块。我们将 hosting 的文件放在一个以其在模块树中的祖先命名的新目录中，在本例中为 src/front_of_house。

要开始移动 hosting，我们将 src/front_of_house.rs 更改为仅包含 hosting 模块的声明：

pub mod hosting;

然后，我们创建一个 src/front_of_house 目录和一个 hosting.rs 文件，以包含 hosting 模块中的定义：

pub fn add_to_waitlist() {}

如果我们将 hosting.rs 放在 src 目录中，编译器会期望 hosting.rs 中的代码位于 crate 根中声明的 hosting 模块中，而不是作为 front_of_house 模块的子模块声明。编译器用于检查哪些文件对应哪些模块代码的规则，意味着目录和文件与模块树更加匹配。

我们已将每个模块的代码移动到单独的文件中，而模块树保持不变。eat_at_restaurant 中的函数调用将无需任何修改即可正常工作，即使定义位于不同的文件中。这种技术让你可以在模块大小增长时将其移动到新文件中。

请注意，src/lib.rs 中的 pub use crate::front_of_house::hosting 语句也没有改变，use 也对哪些文件被编译为 crate 的一部分没有任何影响。mod 关键字声明模块，Rust 在与模块同名的文件中查找该模块中的代码。

总结（Summary）

Rust 允许你将一个包（Package）拆分为多个 crate，并将一个 crate 拆分为多个模块（Module），以便你可以从一个模块引用另一个模块中定义的项（Item）。你可以通过指定绝对路径或相对路径来实现这一点。这些路径可以通过 use 语句引入作用域，这样你可以在该作用域中多次使用该项时使用更短的路径。模块代码默认是私有的，但你可以通过添加 pub 关键字使定义变为公共的。

在下一章中，我们将介绍标准库中的一些集合（Collection）数据结构，你可以在组织良好的代码中使用它们。

常见集合（Common Collections）

Rust 的标准库包含一系列非常有用的数据结构，称为集合（collections）。大多数其他数据类型代表一个特定的值，但集合可以包含多个值。与内置的数组（array）和元组（tuple）类型不同，这些集合所指向的数据存储在堆（heap）上，这意味着数据量不需要在编译时确定，可以在程序运行时增长或缩小。每种集合都有不同的能力和开销，根据当前情况选择合适的一种是你需要随着时间培养的技能。在本章中，我们将讨论 Rust 程序中经常使用的三种集合：

• 向量（vector） 允许你存储可变数量的连续值。
• 字符串（string） 是字符的集合。我们之前已经提到过 String 类型，但在本章中，我们将深入讨论它。
• 哈希映射（hash map） 允许你将一个值与特定的键（key）关联起来。它是一种更通用的数据结构——映射（map）——的具体实现。

要了解标准库提供的其他类型的集合，请查阅文档。

我们将讨论如何创建和更新向量（vector）、字符串（string）和哈希映射（hash map），以及它们各自的特点。

使用 Vector 存储列表

使用向量（Vector）存储值列表

我们要介绍的第一个集合类型是 Vec<T>，也称为向量（vector）。向量允许你在一个数据结构中存储多个值，这些值在内存中连续排列。向量只能存储相同类型的值。当你有一列项目（例如文件中的文本行或购物车中商品的价格）时，它们非常有用。

创建新向量

要创建一个新的空向量，我们调用 Vec::new 函数，如示例 8-1 所示。

fn main() {
    let v: Vec<i32> = Vec::new();
}

注意，我们在这里添加了类型注解。因为我们没有向这个向量插入任何值，Rust 不知道我们打算存储什么类型的元素。这是一个重要的点。向量是使用泛型（generics）实现的；我们将在第 10 章介绍如何在自定义类型中使用泛型。现在，只需要知道标准库提供的 Vec<T> 类型可以持有任何类型。当我们创建一个持有特定类型的向量时，可以在尖括号中指定该类型。在示例 8-1 中，我们告诉 Rust v 中的 Vec<T> 将持有 i32 类型的元素。

更常见的情况是，你会使用初始值创建一个 Vec<T>，Rust 会推断出你想要存储的值类型，因此你很少需要做这种类型注解。Rust 方便地提供了 vec! 宏，它会创建一个包含你给定值的新向量。示例 8-2 创建了一个新的 Vec<i32>，其中包含值 1、2 和 3。整数类型是 i32，因为它是默认的整数类型，正如我们在第 3 章的“数据类型”部分所讨论的那样。

fn main() {
    let v = vec![1, 2, 3];
}

因为我们给出了初始的 i32 值，Rust 可以推断出 v 的类型是 Vec<i32>，因此类型注解不是必需的。接下来，我们将看看如何修改一个向量。

更新向量

要创建一个向量然后向其中添加元素，我们可以使用 push 方法，如示例 8-3 所示。

fn main() {
    let mut v = Vec::new();

    v.push(5);
    v.push(6);
    v.push(7);
    v.push(8);
}

与任何变量一样，如果我们想要更改它的值，需要使用 mut 关键字使其可变，如第 3 章所述。我们放入其中的数字都是 i32 类型，Rust 从数据中推断出这一点，因此我们不需要 Vec<i32> 注解。

读取向量的元素

有两种方法可以引用向量中存储的值：通过索引（indexing）或使用 get 方法。在以下示例中，我们注释了这些函数返回的值的类型，以便更清晰。

示例 8-4 展示了访问向量中值的两种方法：索引语法和 get 方法。

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let third: &i32 = &v[2];
    println!("The third element is {third}");

    let third: Option<&i32> = v.get(2);
    match third {
        Some(third) => println!("The third element is {third}"),
        None => println!("There is no third element."),
    }
}

这里有几个细节需要注意。我们使用索引值 2 来获取第三个元素，因为向量是按数字索引的，从零开始。使用 & 和 [] 会给我们一个指向索引处元素的引用。当我们使用 get 方法并将索引作为参数传入时，会得到一个 Option<&T>，我们可以与 match 配合使用。

Rust 提供了这两种引用元素的方式，以便你可以选择程序在尝试使用超出现有元素范围的索引值时的行为。举个例子，让我们看看当有一个包含五个元素的向量，然后尝试使用每种技术访问索引 100 处的元素时会发生什么，如示例 8-5 所示。

fn main() {
    let v = vec![1, 2, 3, 4, 5];

    let does_not_exist = &v[100];
    let does_not_exist = v.get(100);
}

当我们运行这段代码时，第一个 [] 方法会导致程序 panic，因为它引用了一个不存在的元素。当你希望在尝试访问向量末尾之后的元素时程序崩溃，这种方法最合适。

当向 get 方法传递一个超出向量范围的索引时，它返回 None 而不会 panic。如果在正常情况下的某些操作偶尔会访问超出向量范围的元素，你会使用这种方法。然后你的代码将包含处理 Some(&element) 或 None 的逻辑，如第 6 章所述。例如，索引可能来自用户输入的数字。如果他们不小心输入了一个太大的数字，程序得到了 None 值，你可以告诉用户当前向量中有多少项，并给他们另一次输入有效值的机会。这比因为一个输入错误就让程序崩溃要更加用户友好！

当程序拥有有效引用时，借用检查器（borrow checker）会强制执行所有权和借用规则（涵盖在第 4 章），以确保该引用以及对向量内容的任何其他引用保持有效。回忆一下那条规则——你不能在同一个作用域中同时拥有可变引用和不可变引用。这条规则适用于示例 8-6，其中我们持有一个指向向量第一个元素的不可变引用，并尝试在末尾添加一个元素。如果我们后来还尝试在该函数中引用那个元素，这个程序将无法运行。

fn main() {
    let mut v = vec![1, 2, 3, 4, 5];

    let first = &v[0];

    v.push(6);

    println!("The first element is: {first}");
}

编译这段代码将导致以下错误：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable
 --> src/main.rs:6:5
  |
4 |     let first = &v[0];
  |                  - immutable borrow occurs here
5 |
6 |     v.push(6);
  |     ^^^^^^^^^ mutable borrow occurs here
7 |
8 |     println!("The first element is: {first}");
  |                                      ----- immutable borrow later used here

For more information about this error, try `rustc --explain E0502`.
error: could not compile `collections` (bin "collections") due to 1 previous error

示例 8-6 中的代码看起来似乎是可行的：为什么对第一个元素的引用会关心向量末尾的变化？这个错误是由于向量的工作方式造成的：因为向量将值在内存中连续排列，所以如果在向量当前存储的位置没有足够的空间把所有元素连续放置，那么向末尾添加一个新元素可能需要分配新的内存并将旧元素复制到新空间。在这种情况下，对第一个元素的引用就会指向已释放的内存。借用规则防止程序陷入这种境地。

注意：有关 Vec<T> 类型实现细节的更多信息，请参阅“Rustonomicon”。

遍历向量中的值

要依次访问向量中的每个元素，我们可以遍历所有元素，而不是逐次使用索引访问。示例 8-7 展示了如何使用 for 循环获取 i32 值向量中每个元素的不可变引用并打印它们。

fn main() {
    let v = vec![100, 32, 57];
    for i in &v {
        println!("{i}");
    }
}

我们还可以遍历可变向量中每个元素的可变引用，以便对所有元素进行更改。示例 8-8 中的 for 循环将为每个元素加上 50。

fn main() {
    let mut v = vec![100, 32, 57];
    for i in &mut v {
        *i += 50;
    }
}

要更改可变引用所指向的值，我们必须使用 * 解引用运算符（dereference operator）来获取 i 中的值，然后才能使用 += 运算符。我们将在第 15 章的“跟随引用到值”部分进一步讨论解引用运算符。

由于借用检查器的规则，遍历向量（无论是不可变地还是可变地）是安全的。如果我们在示例 8-7 和示例 8-8 的 for 循环体中尝试插入或删除元素，我们会得到与示例 8-6 类似的编译器错误。 for 循环持有的对向量的引用会阻止对整个向量进行同时修改。

使用枚举存储多种类型

向量只能存储相同类型的值。这可能不太方便；确实有些用例需要存储不同类型值的列表。幸运的是，枚举的变体（variant）是在同一枚举类型下定义的，所以当我们需要一种类型来表示不同类型的元素时，我们可以定义并使用一个枚举！

例如，假设我们想要从电子表格中的一行获取值，该行中有些列包含整数，有些包含浮点数，还有些包含字符串。我们可以定义一个枚举，其变体将持有不同的值类型，并且所有枚举变体都将被视为相同类型：即该枚举的类型。然后，我们可以创建一个持有该枚举的向量，从而最终持有不同的类型。我们在示例 8-9 中演示了这一点。

fn main() {
    enum SpreadsheetCell {
        Int(i32),
        Float(f64),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell::Int(3),
        SpreadsheetCell::Text(String::from("blue")),
        SpreadsheetCell::Float(10.12),
    ];
}

Rust 需要在编译时知道向量中将包含哪些类型，以便它确切地知道需要在堆上分配多少内存来存储每个元素。我们还必须明确说明该向量中允许哪些类型。如果 Rust 允许一个向量持有任意类型，那么其中一种或多种类型可能会在对向量元素执行的操作中引发错误。使用枚举加 match 表达式意味着 Rust 会在编译时确保每个可能的情况都得到处理，如第 6 章所述。

如果你在编译时不知道程序运行时将存储在向量中的类型的完整集合，枚举技术就不起作用。相反，你可以使用 trait 对象（trait object），我们将在第 18 章中介绍。

现在我们已经讨论了一些使用向量的最常用方法，请务必查阅API 文档以了解标准库在 Vec<T> 上定义的所有有用的方法。例如，除了 push 之外，还有一个 pop 方法用于移除并返回最后一个元素。

释放向量即释放其元素

与任何其他 struct 一样，向量在其超出作用域时被释放，如示例 8-10 所示。

fn main() {
    {
        let v = vec![1, 2, 3, 4];

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

当向量被释放时，其所有内容也被释放，这意味着它持有的整数将被清理掉。借用检查器确保对向量内容的任何引用只在向量本身有效时使用。

接下来让我们讨论下一种集合类型：String！

使用字符串存储 UTF-8 编码文本

使用字符串（String）存储 UTF-8 编码的文本

我们在第 4 章讨论过字符串，但现在我们将更深入地研究它们。新 Rustaceans（Rust 初学者）经常在字符串问题上卡住，这是由于三个原因共同造成的：Rust 倾向于暴露可能的错误、字符串是一种比许多程序员所认为的更复杂的数据结构，以及 UTF-8。这些因素结合在一起，使得来自其他编程语言的人会感到困难。

我们在集合的语境下讨论字符串，因为字符串是作为字节集合实现的，再加上一些方法，用于在这些字节被解释为文本时提供有用的功能。在本节中，我们将讨论 String 上所有集合类型都具有的操作，例如创建、更新和读取。我们还将讨论 String 与其他集合的不同之处，即：由于人和计算机对 String 数据的解释方式不同，对 String 进行索引变得复杂。

定义字符串

我们首先定义一下术语*字符串（string）*的含义。Rust 核心语言中只有一种字符串类型，那就是字符串切片（string slice）str，通常以其借用形式 &str 出现。在第 4 章中，我们讨论过字符串切片，它是对存储在其他位置的某些 UTF-8 编码字符串数据的引用。例如，字符串字面量（string literal）存储在程序的二进制文件中，因此是字符串切片。

String 类型由 Rust 的标准库提供，而非核心语言内置，它是一种可增长的、可变的、拥有的、UTF-8 编码的字符串类型。当 Rustaceans 在 Rust 中提到“字符串“时，他们可能指的是 String 或字符串切片 &str 类型，而不仅仅是其中一种。尽管本节主要讨论 String，但两种类型在 Rust 标准库中都大量使用，并且 String 和字符串切片都是 UTF-8 编码的。

创建新字符串

Vec<T> 可用的许多操作同样适用于 String，因为 String 实际上是围绕一个字节向量（vector of bytes）实现的包装器，并带有一些额外的保证、限制和功能。一个对 Vec<T> 和 String 工作方式相同的函数的例子是用于创建实例的 new 函数，如示例 8-11 所示。

fn main() {
    let mut s = String::new();
}

这一行创建了一个名为 s 的新空字符串，然后我们可以向其中加载数据。通常，我们会有一些初始数据，希望用这些数据来初始化字符串。为此，我们使用 to_string 方法，该方法适用于任何实现了 Display trait 的类型，就像字符串字面量那样。示例 8-12 展示了两个例子。

fn main() {
    let data = "initial contents";

    let s = data.to_string();

    // The method also works on a literal directly:
    let s = "initial contents".to_string();
}

这段代码创建了一个包含 initial contents 的字符串。

我们也可以使用 String::from 函数从字符串字面量创建 String。示例 8-13 中的代码与使用 to_string 的示例 8-12 中的代码是等价的。

fn main() {
    let s = String::from("initial contents");
}

因为字符串用途广泛，所以我们可以使用许多不同的通用 API 来处理字符串，这为我们提供了大量选择。其中一些可能看起来是多余的，但它们都有各自的用武之地！在这种情况下，String::from 和 to_string 做的是同一件事，所以选择哪一个取决于风格和可读性。

请记住，字符串是 UTF-8 编码的，因此我们可以在其中包含任何正确编码的数据，如示例 8-14 所示。

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

所有这些都是有效的 String 值。

更新字符串

String 可以增大其大小，其内容也可以改变，就像 Vec<T> 一样，如果你向其中推入更多数据的话。此外，你可以方便地使用 + 运算符或 format! 宏来拼接 String 值。

使用 push_str 或 push 追加

我们可以使用 push_str 方法来追加一个字符串切片，从而使 String 增长，如示例 8-15 所示。

fn main() {
    let mut s = String::from("foo");
    s.push_str("bar");
}

经过这两行之后，s 将包含 foobar。push_str 方法接受一个字符串切片，因为我们不一定需要获取参数的所有权。例如，在示例 8-16 的代码中，我们希望将 s2 的内容追加到 s1 之后，仍然能够使用 s2。

fn main() {
    let mut s1 = String::from("foo");
    let s2 = "bar";
    s1.push_str(s2);
    println!("s2 is {s2}");
}

如果 push_str 方法获取了 s2 的所有权，我们就无法在最后一行打印它的值了。然而，这段代码正如我们所期望的那样工作！

push 方法接受单个字符作为参数，并将其添加到 String 中。示例 8-17 使用 push 方法向 String 添加字母 l。

fn main() {
    let mut s = String::from("lo");
    s.push('l');
}

结果，s 将包含 lol。

使用 + 或 format! 进行拼接

通常，你会想要合并两个现有的字符串。一种方法是使用 + 运算符，如示例 8-18 所示。

fn main() {
    let s1 = String::from("Hello, ");
    let s2 = String::from("world!");
    let s3 = s1 + &s2; // note s1 has been moved here and can no longer be used
}

字符串 s3 将包含 Hello, world!。s1 在加法之后不再有效的原因，以及我们使用 s2 的引用的原因，与使用 + 运算符时调用的方法的签名有关。+ 运算符使用了 add 方法，其签名大致如下：

fn add(self, s: &str) -> String {

在标准库中，你会看到 add 是通过泛型和关联类型（associated types）定义的。这里我们替换成了具体类型，也就是当我们将 String 值传入该方法时实际发生的情况。我们将在第 10 章讨论泛型。这个签名为我们提供了理解 + 运算符棘手之处所需的线索。

首先，s2 带有 &，意味着我们是将第二个字符串的引用添加到第一个字符串。这是因为 add 函数中的 s 参数：我们只能将字符串切片添加到 String；不能将两个 String 值相加。但是等等——&s2 的类型是 &String，而不是 add 第二个参数所指定的 &str。那么，为什么示例 8-18 能编译通过呢？

我们能够在调用 add 时使用 &s2 的原因是编译器可以将 &String 参数强制转换为 &str。当我们调用 add 方法时，Rust 使用了解引用强制多态（deref coercion），在这里它将 &s2 转换为 &s2[..]。我们将在第 15 章更深入地讨论解引用强制多态。因为 add 不获取 s 参数的所有权，所以 s2 在此操作之后仍然是有效的 String。

其次，我们在签名中可以看到 add 获取了 self 的所有权，因为 self 没有 &。这意味着示例 8-18 中的 s1 将被移入 add 调用中，并在那之后不再有效。因此，尽管 let s3 = s1 + &s2; 看起来像是会复制两个字符串并创建一个新的字符串，但实际上这个语句获取了 s1 的所有权，追加了 s2 内容的副本，然后返回结果的所有权。换句话说，它看起来像是在做大量的拷贝，但实际上并非如此；实现比复制更加高效。

如果我们需要拼接多个字符串，+ 运算符的行为将变得笨拙：

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = s1 + "-" + &s2 + "-" + &s3;
}

此时，s 将是 tic-tac-toe。有了所有这些 + 和 " 字符，很难看清楚发生了什么。对于更复杂的字符串组合，我们可以改用 format! 宏：

fn main() {
    let s1 = String::from("tic");
    let s2 = String::from("tac");
    let s3 = String::from("toe");

    let s = format!("{s1}-{s2}-{s3}");
}

这段代码也将 s 设置为 tic-tac-toe。format! 宏的工作方式类似于 println!，但它不是将输出打印到屏幕，而是返回一个包含内容的 String。使用 format! 的代码版本更易于阅读，并且 format! 宏生成的代码使用的是引用，因此该调用不会获取任何参数的所有权。

索引字符串

在许多其他编程语言中，通过索引引用字符串中的单个字符是一种有效且常见的操作。然而，如果你尝试在 Rust 中使用索引语法访问 String 的部分内容，你将得到一个错误。考虑示例 8-19 中无效的代码。

fn main() {
    let s1 = String::from("hi");
    let h = s1[0];
}

这段代码将导致以下错误：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
error[E0277]: the type `str` cannot be indexed by `{integer}`
 --> src/main.rs:3:16
  |
3 |     let h = s1[0];
  |                ^ string indices are ranges of `usize`
  |
  = help: the trait `SliceIndex<str>` is not implemented for `{integer}`
  = note: you can use `.chars().nth()` or `.bytes().nth()`
          for more information, see chapter 8 in The Book: <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>
  = help: the following other types implement trait `SliceIndex<T>`:
            `usize` implements `SliceIndex<ByteStr>`
            `usize` implements `SliceIndex<[T]>`
  = note: required for `String` to implement `Index<{integer}>`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `collections` (bin "collections") due to 1 previous error

错误说明了一切：Rust 字符串不支持索引。但为什么不支持呢？要回答这个问题，我们需要讨论 Rust 如何在内存中存储字符串。

内部表示

String 是对 Vec<u8> 的包装。让我们看看示例 8-14 中一些正确编码的 UTF-8 示例字符串。首先是这个：

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

在这种情况下，len 将是 4，这意味着存储字符串 "Hola" 的向量长度为 4 字节。这些字母每个在用 UTF-8 编码时占用 1 字节。然而，下面这一行可能会让你感到惊讶（注意，这个字符串以大写西里尔字母 Ze 开头，而不是数字 3）：

fn main() {
    let hello = String::from("السلام عليكم");
    let hello = String::from("Dobrý den");
    let hello = String::from("Hello");
    let hello = String::from("שלום");
    let hello = String::from("नमस्ते");
    let hello = String::from("こんにちは");
    let hello = String::from("안녕하세요");
    let hello = String::from("你好");
    let hello = String::from("Olá");
    let hello = String::from("Здравствуйте");
    let hello = String::from("Hola");
}

如果有人问你该字符串有多长，你可能会说 12。实际上，Rust 的答案是 24：这是用 UTF-8 编码“Здравствуйте“所需的字节数，因为该字符串中的每个 Unicode 标量值（Unicode scalar value）占用 2 字节的存储空间。因此，对字符串字节的索引并不总是与有效的 Unicode 标量值对应。为了说明这一点，请考虑以下无效的 Rust 代码：

let hello = "Здравствуйте";
let answer = &hello[0];

你已经知道 answer 不会是 З，即第一个字母。在用 UTF-8 编码时，З 的第一个字节是 208，第二个字节是 151，所以看起来 answer 实际上应该是 208，但 208 本身并不是一个有效的字符。返回 208 很可能不是用户想要的结果，当他们要求该字符串的第一个字母时；然而，这是 Rust 在字节索引 0 处所拥有的唯一数据。用户通常不希望返回字节值，即使字符串只包含拉丁字母也是如此：如果 &"hi"[0] 是返回字节值的有效代码，它将返回 104，而不是 h。

因此，答案是：为了避免返回意外值并可能导致无法立即发现的 bug，Rust 根本不会编译这段代码，并在开发过程的早期就防止误解。

字节、标量值和字素簇（Grapheme Cluster）

关于 UTF-8 的另一点是，从 Rust 的角度来看，实际上有三种相关的方式来看待字符串：作为字节（bytes）、作为标量值（scalar values）和作为字素簇（grapheme clusters，最接近我们所说的字母的概念）。

如果我们看看用天城文书写的印地语单词“नमस्ते“，它存储为如下所示的 u8 值向量：

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164,
224, 165, 135]

这是 18 个字节，也是计算机最终存储这些数据的方式。如果我们将其视为 Unicode 标量值——也就是 Rust 的 char 类型——这些字节看起来像这样：

['न', 'म', 'स', '्', 'त', 'े']

这里有六个 char 值，但第四个和第六个不是字母：它们是变音符号（diacritics），单独存在没有意义。最后，如果我们将其视为字素簇，就会得到人们所说的组成这个印地语单词的四个字母：

["न", "म", "स्", "ते"]

Rust 提供了不同的方式来解释计算机存储的原始字符串数据，以便每个程序可以选择它需要的解释方式，无论数据使用的是哪种人类语言。

Rust 不允许我们对 String 进行索引以获取字符的最后一个原因是，索引操作应该始终是常数时间（O(1)）。但是，对于 String 来说，无法保证这种性能，因为 Rust 必须从头遍历内容直到索引位置，以确定有多少有效字符。

切片字符串

对字符串进行索引通常不是一个好主意，因为不清楚字符串索引操作的返回类型应该是什么：一个字节值、一个字符、一个字素簇还是一个字符串切片。因此，如果你确实需要使用索引来创建字符串切片，Rust 要求你更具体一些。

与其使用带有单个数字的 [] 进行索引，不如使用带有范围的 [] 来创建包含特定字节的字符串切片：

#![allow(unused)]
fn main() {
let hello = "Здравствуйте";

let s = &hello[0..4];
}

在这里，s 将是一个 &str，包含字符串的前 4 个字节。之前，我们提到每个字符是 2 个字节，这意味着 s 将是 Зд。

如果我们尝试切割一个字符的部分字节，比如 &hello[0..1]，Rust 会在运行时 panic，就像在向量中访问了无效索引一样：

$ cargo run
   Compiling collections v0.1.0 (file:///projects/collections)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.43s
     Running `target/debug/collections`

thread 'main' panicked at src/main.rs:4:19:
byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `Здравствуйте`
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

在创建带有范围的字符串切片时应谨慎，因为这可能会导致程序崩溃。

遍历字符串

操作字符串片段的最佳方式是明确你想要的是字符还是字节。对于单个 Unicode 标量值，使用 chars 方法。对“Зд“调用 chars 会将它们分离并返回两个 char 类型的值，你可以遍历结果来访问每个元素：

#![allow(unused)]
fn main() {
for c in "Зд".chars() {
    println!("{c}");
}
}

这段代码将打印以下内容：

З
д

另外，bytes 方法返回每个原始字节，这可能适用于你的特定领域：

#![allow(unused)]
fn main() {
for b in "Зд".bytes() {
    println!("{b}");
}
}

这段代码将打印组成该字符串的 4 个字节：

208
151
208
180

但请务必记住，有效的 Unicode 标量值可能由超过 1 个字节组成。

从字符串中获取字素簇（如天城文脚本那样）是复杂的，因此标准库不提供此功能。如果这是你需要的功能，可以在 crates.io 上找到相关的 crate。

处理字符串的复杂性

总而言之，字符串是复杂的。不同的编程语言对于如何向程序员呈现这种复杂性做出了不同的选择。Rust 选择了让所有 Rust 程序的默认行为是正确处理 String 数据，这意味着程序员需要提前更多地思考如何处理 UTF-8 数据。这种权衡暴露了比其他编程语言更多的字符串复杂性，但它防止了你在开发生命周期的后期处理涉及非 ASCII 字符的错误。

好消息是，标准库提供了大量基于 String 和 &str 类型构建的功能，以帮助正确处理这些复杂情况。请务必查阅文档，了解有用的方法，例如用于在字符串中搜索的 contains 和用于将字符串的一部分替换为另一个字符串的 replace。

接下来让我们转向稍微不那么复杂的东西：哈希映射（hash maps）！

使用哈希映射存储键值对

在哈希映射（Hash Map）中存储键与值的关联

我们最后一个常见的集合是哈希映射（hash map）。HashMap<K, V> 类型使用*哈希函数（hashing function）*存储类型 K 的键到类型 V 的值的映射，该函数决定了它如何将这些键和值放入内存。许多编程语言都支持这种数据结构，但它们通常使用不同的名称，例如 hash、map、object、hash table、dictionary 或 associative array，仅举几例。

当你想要查找数据时，不是像向量那样使用索引，而是使用可以是任何类型的键，这时哈希映射就很有用。例如，在一个游戏中，你可以使用哈希映射来跟踪每个队伍的得分，其中每个键是队伍名称，值是每个队伍的得分。给定队伍名称，你可以检索其得分。

我们将在本节中介绍哈希映射的基本 API，但标准库在 HashMap<K, V> 上定义的函数中隐藏着更多好东西。和往常一样，请查阅标准库文档了解更多信息。

创建新哈希映射

创建空哈希映射的一种方法是使用 new，并使用 insert 添加元素。在示例 8-20 中，我们跟踪两个队伍（名为 Blue 和 Yellow）的得分。Blue 队从 10 分开始，Yellow 队从 50 分开始。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

注意，我们首先需要 use 标准库 collections 部分中的 HashMap。在我们的三种常见集合中，这是最不常用的，因此它没有被自动包含在 prelude（预导入）中。哈希映射从标准库获得的支持也较少；例如，没有内置的宏来构造它们。

与向量一样，哈希映射将其数据存储在堆上。这个 HashMap 的键是 String 类型，值是 i32 类型。与向量一样，哈希映射是同质的：所有键必须具有相同的类型，所有值必须具有相同的类型。

访问哈希映射中的值

我们可以通过将键提供给 get 方法来从哈希映射中获取值，如示例 8-21 所示。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    let team_name = String::from("Blue");
    let score = scores.get(&team_name).copied().unwrap_or(0);
}

在这里，score 将具有与 Blue 队关联的值，结果将是 10。get 方法返回一个 Option<&V>；如果哈希映射中没有该键对应的值，get 将返回 None。该程序通过调用 copied 来获得 Option<i32>（而不是 Option<&i32>），然后调用 unwrap_or 在 scores 中没有该键条目时将 score 设置为 0，以此方式处理 Option。

我们可以像处理向量一样，使用 for 循环以类似的方式遍历哈希映射中的每个键值对：

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);

    for (key, value) in &scores {
        println!("{key}: {value}");
    }
}

这段代码将以任意顺序打印每个键值对：

Yellow: 50
Blue: 10

哈希映射与所有权管理

对于实现了 Copy trait 的类型（如 i32），值会被复制到哈希映射中。对于拥有所有权的值（如 String），值将被移动，哈希映射将成为这些值的所有者，如示例 8-22 所示。

fn main() {
    use std::collections::HashMap;

    let field_name = String::from("Favorite color");
    let field_value = String::from("Blue");

    let mut map = HashMap::new();
    map.insert(field_name, field_value);
    // field_name and field_value are invalid at this point, try using them and
    // see what compiler error you get!
}

在变量 field_name 和 field_value 通过调用 insert 被移动到哈希映射中之后，我们无法再使用它们。

如果我们向哈希映射插入值的引用，这些值不会被移动到哈希映射中。引用所指向的值必须至少在哈希映射有效的整个期间内都有效。我们将在第 10 章的“使用生命周期（Lifetime）验证引用”中进一步讨论这些问题。

更新哈希映射

尽管键值对的数量是可以增长的，但每个唯一的键一次只能关联一个值（但反之则不然：例如，Blue 队和 Yellow 队都可以在 scores 哈希映射中存储值 10）。

当你想要更改哈希映射中的数据时，你必须决定如何处理键已有关联值的情况。你可以用新值替换旧值，完全忽略旧值。你可以保留旧值而忽略新值，仅在键尚未有关联值时添加新值。或者你可以合并旧值和新值。让我们看看如何实现每种情况！

覆盖一个值

如果我们向哈希映射插入一个键和一个值，然后又用不同的值插入同一个键，则该键关联的值将被替换。尽管示例 8-23 中的代码调用了两次 insert，但哈希映射只会包含一个键值对，因为我们两次插入的都是 Blue 队键的值。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();

    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Blue"), 25);

    println!("{scores:?}");
}

这段代码将打印 {"Blue": 25}。原来的值 10 已被覆盖。

仅在键不存在时添加键和值

通常需要检查哈希映射中是否已存在某个特定键及其值，然后执行以下操作：如果该键存在于哈希映射中，则保留现有值不变；如果该键不存在，则插入它及其值。

哈希映射有一个特殊的 API 用于此，称为 entry，它将要检查的键作为参数。entry 方法的返回值是一个名为 Entry 的枚举，它表示一个可能存在也可能不存在的值。假设我们想检查 Yellow 队键是否已有关联值。如果没有，我们想插入值 50；对于 Blue 队也是如此。使用 entry API，代码如示例 8-24 所示。

fn main() {
    use std::collections::HashMap;

    let mut scores = HashMap::new();
    scores.insert(String::from("Blue"), 10);

    scores.entry(String::from("Yellow")).or_insert(50);
    scores.entry(String::from("Blue")).or_insert(50);

    println!("{scores:?}");
}

Entry 上的 or_insert 方法被定义为：如果键存在，则返回对应 Entry 键的值的可变引用；如果不存在，则将参数作为该键的新值插入，并返回新值的可变引用。这种技术比我们自己编写逻辑要简洁得多，此外，它与借用检查器的配合也更好。

运行示例 8-24 中的代码将打印 {"Yellow": 50, "Blue": 10}。第一次调用 entry 将为 Yellow 队插入键与值 50，因为 Yellow 队还没有值。第二次调用 entry 不会更改哈希映射，因为 Blue 队已经有值 10。

基于旧值更新值

哈希映射的另一个常见用例是查找键的值，然后根据旧值更新它。例如，示例 8-25 显示了统计每个单词在文本中出现次数的代码。我们使用一个以单词为键的哈希映射，并递增值以跟踪我们看到该单词的次数。如果我们是第一次看到某个单词，我们会先插入值 0。

fn main() {
    use std::collections::HashMap;

    let text = "hello world wonderful world";

    let mut map = HashMap::new();

    for word in text.split_whitespace() {
        let count = map.entry(word).or_insert(0);
        *count += 1;
    }

    println!("{map:?}");
}

这段代码将打印 {"world": 2, "hello": 1, "wonderful": 1}。你可能会看到相同的键值对以不同的顺序打印：回想一下“访问哈希映射中的值”，遍历哈希映射是以任意顺序进行的。

split_whitespace 方法返回一个迭代器，遍历 text 中以空白分隔的子切片。or_insert 方法返回指定键的值的可变引用（&mut V）。在这里，我们将该可变引用存储在 count 变量中，因此为了给该值赋值，我们必须首先使用星号（*）解引用 count。可变引用在 for 循环结束时超出作用域，因此所有这些更改都是安全的，并且为借用规则所允许。

哈希函数

默认情况下，HashMap 使用一种名为 SipHash 的哈希函数，它可以抵抗涉及哈希表的拒绝服务（DoS）攻击¹。这不是可用的最快的哈希算法，但为了更好的安全性而降低性能，这种权衡是值得的。如果你对你的代码进行了性能分析，发现默认哈希函数对你的目的来说太慢，你可以通过指定一个不同的 hasher（哈希器）来切换到另一个函数。hasher 是一个实现了 BuildHasher trait 的类型。我们将在第 10 章讨论 trait 以及如何实现它们。你不一定需要从头开始实现自己的 hasher；crates.io 上有其他 Rust 用户共享的库，它们提供了实现许多常见哈希算法的 hasher。

总结

当你需要存储、访问和修改数据时，向量（vector）、字符串（string）和哈希映射（hash map）将在程序中提供所需的大量功能。以下是一些你现在应该能够解决的练习：

1. 给定一个整数列表，使用向量并返回该列表的中位数（排序后中间位置的值）和众数（出现频率最高的值；哈希映射在这里很有帮助）。
2. 将字符串转换为 Pig Latin（儿童黑话）。每个单词的第一个辅音（consonant）移到单词末尾，并加上 ay，因此 first 变成 irst-fay。以元音（vowel）开头的单词在末尾加上 hay（apple 变成 apple-hay）。请记住 UTF-8 编码的细节！
3. 使用哈希映射和向量，创建一个文本界面，允许用户向公司的某个部门添加员工姓名；例如，“Add Sally to Engineering“或“Add Amir to Sales”。然后，让用户检索某个部门的所有人员列表，或按部门检索公司的所有人员列表，并按键排序。

标准库 API 文档描述了向量、字符串和哈希映射具有的方法，这些方法对这些练习会有帮助！

我们正在进入更复杂的程序，其中操作可能会失败，因此现在是讨论错误处理的好时机。我们接下来将进行讨论！

1. https://en.wikipedia.org/wiki/SipHash ↩

错误处理（Error Handling）

错误是软件中不可避免的事实，因此 Rust 提供了许多功能来处理出错的情况。在许多情况下，Rust 要求你承认错误的可能性，并在代码编译之前采取一些行动。这一要求通过确保你在将代码部署到生产环境之前发现错误并适当处理它们，从而使你的程序更加健壮！

Rust 将错误分为两大类：可恢复的（recoverable）错误和不可恢复的（unrecoverable）错误。对于可恢复的错误，例如文件未找到错误，我们可能只想向用户报告问题并重试操作。不可恢复的错误总是 bug 的症状，例如试图访问数组末尾之后的位置，因此我们希望立即停止程序。

大多数语言不区分这两种错误，而是使用异常（exceptions）等机制以相同的方式处理它们。Rust 没有异常。相反，它有针对可恢复错误的 Result<T, E> 类型，以及当程序遇到不可恢复错误时停止执行的 panic! 宏。本章先介绍调用 panic!，然后讨论返回 Result<T, E> 值。此外，我们还将探讨在决定是尝试从错误中恢复还是停止执行时需要考虑的因素。

不可恢复的错误与 panic!

使用 panic! 的不可恢复错误

有时候你的代码中会发生糟糕的事情，而你对此无能为力。在这些情况下，Rust 提供了 panic! 宏。实际上有两种方式导致 panic：执行一个会导致我们的代码 panic 的操作（例如访问数组末尾之后的位置），或者显式调用 panic! 宏。在这两种情况下，我们都会导致程序中出现 panic。默认情况下，这些 panic 会打印一条失败消息，展开（unwind）、清理栈并退出。通过环境变量，你也可以让 Rust 在发生 panic 时显示调用栈，以便更容易地追踪 panic 的来源。

[profile.release]
panic = 'abort'

让我们在一个简单的程序中尝试调用 panic!：

fn main() {
    panic!("crash and burn");
}

当你运行这个程序时，你会看到类似这样的输出：

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.25s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

对 panic! 的调用导致了最后两行中包含的错误消息。第一行显示了我们的 panic 消息以及 panic 发生位置在源代码中的位置：src/main.rs:2:5 表示它是 src/main.rs 文件的第二行、第五个字符。

在这种情况下，所指出的行是我们代码的一部分，如果去查看那一行，我们会看到 panic! 宏调用。在其他情况下，panic! 调用可能在我们代码所调用的代码中，错误消息报告的文件名和行号将是调用 panic! 宏的其他人的代码，而不是最终导致 panic! 调用的我们自己的代码行。

我们可以使用 panic! 调用来源函数的回溯（backtrace）来找出导致问题的代码部分。为了理解如何使用 panic! 回溯，让我们来看另一个例子，看看当 panic! 调用来自库（由于我们代码中的 bug）而不是我们的代码直接调用宏时是什么样子。示例 9-1 中的代码尝试访问向量中超出有效索引范围的索引。

fn main() {
    let v = vec![1, 2, 3];

    v[99];
}

在这里，我们试图访问向量的第 100 个元素（因为索引从零开始，实际上是索引 99），但向量只有三个元素。在这种情况下，Rust 会 panic。使用 [] 应该返回一个元素，但如果你传递了一个无效的索引，Rust 无法返回任何正确的元素。

在 C 中，尝试读取数据结构末尾之后的内存是未定义行为（undefined behavior）。你可能会得到内存中对应于该数据结构中该元素位置的值，即使该内存不属于该数据结构。这被称为缓冲区过度读取（buffer overread），如果攻击者能够操纵索引以读取存储在该数据结构之后的不应被允许读取的数据，则可能导致安全漏洞。

为了保护你的程序免受此类漏洞的侵害，如果你尝试读取不存在的索引处的元素，Rust 将停止执行并拒绝继续。让我们试一下看看：

$ cargo run
   Compiling panic v0.1.0 (file:///projects/panic)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.27s
     Running `target/debug/panic`

thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

这个错误指向了 main.rs 的第 4 行，我们在那里尝试访问 v 中索引为 99 的元素。

note: 这一行告诉我们，我们可以设置 RUST_BACKTRACE 环境变量来获取一个回溯，精确地追踪到导致错误的原因。回溯（backtrace） 是一个列表，列出了到达此点所调用的所有函数。Rust 中的回溯与其他语言中的工作方式相同：阅读回溯的关键是从顶部开始，一直读到你看自己所写的文件。那就是问题起源的地方。该位置之上的行是你的代码所调用的代码；之下的行是调用你代码的代码。这些前后的行可能包括 Rust 核心代码、标准库代码或你正在使用的 crate。让我们尝试通过将 RUST_BACKTRACE 环境变量设置为除 0 之外的任何值来获取回溯。示例 9-2 显示了你将看到的类似输出。

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at src/main.rs:4:6:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/std/src/panicking.rs:692:5
   1: core::panicking::panic_fmt
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:75:14
   2: core::panicking::panic_bounds_check
             at /rustc/4d91de4e48198da2e33413efdcd9cd2cc0c46688/library/core/src/panicking.rs:273:5
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:274:10
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/slice/index.rs:16:9
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/alloc/src/vec/mod.rs:3361:9
   6: panic::main
             at ./src/main.rs:4:6
   7: core::ops::function::FnOnce::call_once
             at file:///home/.rustup/toolchains/1.85/lib/rustlib/src/rust/library/core/src/ops/function.rs:250:5
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

输出真多！你看到的确切输出可能因你的操作系统和 Rust 版本而异。为了获取具有此信息的回溯，必须启用调试符号（debug symbols）。在使用 cargo build 或 cargo run 而不带 --release 标志时，默认情况下启用调试符号，正如我们这里所做的那样。

在示例 9-2 的输出中，回溯的第 6 行指向了我们项目中导致问题的行：src/main.rs 的第 4 行。如果我们不希望程序 panic，我们应该从第一个提到我们写的文件的位置开始调查。在示例 9-1 中，我们故意编写了会导致 panic 的代码，修复 panic 的方法是不要请求超出向量索引范围的元素。将来当你的代码 panic 时，你需要找出代码使用了什么值执行了什么操作导致了 panic，以及代码应该怎么做。

我们将在本章后面的“是 panic! 还是不 panic!”部分回到 panic! 以及我们在处理错误情况时应该和不应该使用 panic! 的讨论。接下来，我们将看看如何使用 Result 从错误中恢复。

可恢复的错误与 Result

使用 Result 的可恢复错误

大多数错误并不严重到需要程序完全停止。有时当函数失败时，是由于一个你可以轻松解释并做出反应的原因。例如，如果你尝试打开一个文件，但由于文件不存在而失败，你可能想要创建文件而不是终止进程。

回想一下第 2 章中“使用 Result 处理潜在失败”部分，Result 枚举被定义为有两个变体（variant），Ok 和 Err，如下所示：

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

T 和 E 是泛型类型参数（generic type parameters）：我们将在第 10 章更详细地讨论泛型。你现在需要知道的是，T 表示在成功情况下 Ok 变体中将返回的值的类型，而 E 表示在失败情况下 Err 变体中将返回的错误类型。由于 Result 具有这些泛型类型参数，我们可以在许多不同的情况下使用 Result 类型及其上定义的函数，这些情况下我们想要返回的成功值和错误值可能不同。

让我们调用一个返回 Result 值的函数，因为该函数可能会失败。在示例 9-3 中，我们尝试打开一个文件。

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");
}

File::open 的返回类型是 Result<T, E>。泛型参数 T 已被 File::open 的实现填充为成功值的类型，即 std::fs::File，这是一个文件句柄（file handle）。错误值中使用的 E 的类型是 std::io::Error。这个返回类型意味着对 File::open 的调用可能成功并返回一个我们可以读取或写入的文件句柄。该函数调用也可能失败：例如，文件可能不存在，或者我们可能没有权限访问该文件。File::open 函数需要有一种方式来告诉我们它是否成功或失败，同时给我们文件句柄或错误信息。这正是 Result 枚举所传达的信息。

在 File::open 成功的情况下，变量 greeting_file_result 中的值将是一个包含文件句柄的 Ok 实例。在失败的情况下，greeting_file_result 中的值将是一个包含更多错误信息的 Err 实例。

我们需要向示例 9-3 中的代码添加一些内容，以根据 File::open 返回的值执行不同的操作。示例 9-4 展示了一种使用基本工具——我们在第 6 章讨论过的 match 表达式——来处理 Result 的方法。

use std::fs::File;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => panic!("Problem opening the file: {error:?}"),
    };
}

请注意，与 Option 枚举一样，Result 枚举及其变体已由 prelude（预导入）引入作用域，因此我们不需要在 match 分支中的 Ok 和 Err 变体前指定 Result::。

当结果是 Ok 时，这段代码将返回 Ok 变体中的内部 file 值，然后我们将该文件句柄值赋给变量 greeting_file。在 match 之后，我们可以使用文件句柄进行读取或写入。

match 的另一个分支处理我们从 File::open 得到 Err 值的情况。在这个例子中，我们选择了调用 panic! 宏。如果当前目录中没有名为 hello.txt 的文件，并且我们运行这段代码，我们将看到来自 panic! 宏的以下输出：

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.73s
     Running `target/debug/error-handling`

thread 'main' panicked at src/main.rs:8:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

和往常一样，这个输出准确地告诉我们出了什么问题。

对不同错误进行匹配

示例 9-4 中的代码无论 File::open 失败的原因是什么，都会 panic!。然而，我们想针对不同的失败原因采取不同的操作。如果 File::open 因为文件不存在而失败，我们希望创建该文件并返回新文件的句柄。如果 File::open 因任何其他原因失败——例如，因为我们没有打开文件的权限——我们仍然希望代码像示例 9-4 中那样 panic!。为此，我们添加一个内部的 match 表达式，如示例 9-5 所示。

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file_result = File::open("hello.txt");

    let greeting_file = match greeting_file_result {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Problem creating the file: {e:?}"),
            },
            _ => {
                panic!("Problem opening the file: {error:?}");
            }
        },
    };
}

File::open 在 Err 变体内部返回的值的类型是 io::Error，这是标准库提供的一个结构体。这个结构体有一个方法 kind，我们可以调用它来获取一个 io::ErrorKind 值。io::ErrorKind 枚举由标准库提供，其变体表示可能由 io 操作导致的各种错误类型。我们想要使用的变体是 ErrorKind::NotFound，它表示我们试图打开的文件尚不存在。因此，我们在 greeting_file_result 上进行匹配，但我们还在 error.kind() 上进行内部匹配。

我们在内部匹配中想要检查的条件是 error.kind() 返回的值是否是 ErrorKind 枚举的 NotFound 变体。如果是，我们尝试用 File::create 创建文件。然而，因为 File::create 也可能失败，所以我们需要内部 match 表达式中的第二个分支。当文件无法创建时，会打印不同的错误消息。外部 match 的第二个分支保持不变，因此除了文件缺失错误之外，任何其他错误都会导致程序 panic。

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Problem creating the file: {error:?}");
            })
        } else {
            panic!("Problem opening the file: {error:?}");
        }
    });
}

错误时 panic 的快捷方式

使用 match 效果很好，但它可能有点冗长，并且不一定能很好地传达意图。Result<T, E> 类型上定义了许多辅助方法，用于执行各种更具体的任务。unwrap 方法是一个快捷方式方法，其实现方式与我们写在示例 9-4 中的 match 表达式类似。如果 Result 值是 Ok 变体，unwrap 将返回 Ok 内部的值。如果 Result 是 Err 变体，unwrap 将为我们调用 panic! 宏。以下是 unwrap 在行动中的示例：

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt").unwrap();
}

如果我们没有 hello.txt 文件就运行这段代码，我们将看到来自 unwrap 方法调用的 panic! 的错误消息：

thread 'main' panicked at src/main.rs:4:49:
called `Result::unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

类似地，expect 方法让我们也可以选择 panic! 的错误消息。使用 expect 而不是 unwrap 并提供良好的错误消息可以传达你的意图，并使追踪 panic 的来源更容易。expect 的语法如下所示：

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")
        .expect("hello.txt should be included in this project");
}

我们使用 expect 的方式与 unwrap 相同：返回文件句柄或调用 panic! 宏。expect 在其调用 panic! 时使用的错误消息将是我们传递给 expect 的参数，而不是 unwrap 使用的默认 panic! 消息。以下是它的样子：

thread 'main' panicked at src/main.rs:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

在生产质量的代码中，大多数 Rustaceans 选择 expect 而不是 unwrap，并提供更多关于为什么该操作预期总是成功的上下文。这样，如果你的假设被证明是错误的，你在调试时就有更多信息可以使用。

传播错误

当函数的实现调用可能失败的内容时，你可以不在此函数内部处理错误，而是将错误返回给调用代码，以便它可以决定该怎么做。这被称为*传播（propagating）*错误，并赋予调用代码更多的控制权，因为调用代码可能拥有更多信息或逻辑来决定应如何处理错误，而不是在你的代码上下文中可用。

例如，示例 9-6 显示了一个从文件读取用户名的函数。如果文件不存在或无法读取，此函数将把这些错误返回给调用它的代码。

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let username_file_result = File::open("hello.txt");

    let mut username_file = match username_file_result {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut username = String::new();

    match username_file.read_to_string(&mut username) {
        Ok(_) => Ok(username),
        Err(e) => Err(e),
    }
}
}

这个函数可以用更简短的方式编写，但我们先手动做很多工作来探索错误处理；最后，我们将展示更简短的方式。首先看看函数的返回类型：Result<String, io::Error>。这意味着该函数返回一个 Result<T, E> 类型的值，其中泛型参数 T 已被具体类型 String 填充，泛型类型 E 已被具体类型 io::Error 填充。

如果此函数成功且没有任何问题，调用此函数的代码将收到一个包含 String 的 Ok 值——即此函数从文件中读取的 username。如果此函数遇到任何问题，调用代码将收到一个包含 io::Error 实例的 Err 值，其中包含有关问题所在的更多信息。我们选择 io::Error 作为此函数的返回类型，因为碰巧我们在此函数体中调用的两个可能失败的操作返回的错误值的类型都是它：File::open 函数和 read_to_string 方法。

函数体首先调用 File::open 函数。然后，我们使用 match 处理 Result 值，类似于示例 9-4 中的 match。如果 File::open 成功，模式变量 file 中的文件句柄成为可变变量 username_file 中的值，函数继续执行。在 Err 情况下，我们不调用 panic!，而是使用 return 关键字从函数中提前返回，并将 File::open 中的错误值（现在在模式变量 e 中）作为此函数的错误值传回给调用代码。

因此，如果在 username_file 中有一个文件句柄，则该函数在变量 username 中创建一个新的 String，并调用 username_file 中文件句柄上的 read_to_string 方法，将文件内容读入 username。read_to_string 方法也返回一个 Result，因为它可能失败，即使 File::open 成功了。所以，我们需要另一个 match 来处理那个 Result：如果 read_to_string 成功，那么我们的函数成功了，我们返回文件中的用户名（现在在 username 中），包裹在 Ok 中。如果 read_to_string 失败，我们以与处理 File::open 返回值的 match 中相同的错误值返回方式返回错误值。然而，我们不需要显式写出 return，因为这是函数中的最后一个表达式。

调用此代码的代码将随后处理得到包含用户名的 Ok 值或包含 io::Error 的 Err 值。由调用代码决定如何处理这些值。如果调用代码得到 Err 值，它可以调用 panic! 并使程序崩溃，使用默认用户名，或者从文件以外的其他地方查找用户名，等等。我们没有足够的信息知道调用代码实际想做什么，因此我们将所有成功或错误信息向上传播以供其适当处理。

这种错误传播模式在 Rust 中非常常见，以至于 Rust 提供了问号运算符 ? 来使其更容易。

? 运算符快捷方式

示例 9-7 展示了 read_username_from_file 的一个实现，它具有与示例 9-6 相同的功能，但此实现使用了 ? 运算符。

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username_file = File::open("hello.txt")?;
    let mut username = String::new();
    username_file.read_to_string(&mut username)?;
    Ok(username)
}
}

放在 Result 值后面的 ? 被定义为与我们在示例 9-6 中定义的用于处理 Result 值的 match 表达式几乎完全相同的方式工作。如果 Result 的值是 Ok，Ok 内部的值将从此表达式返回，程序继续执行。如果值是 Err，Err 将像我们使用了 return 关键字一样从整个函数返回，从而将错误值传播给调用代码。

示例 9-6 中的 match 表达式与 ? 运算符之间有一个区别：对其调用 ? 运算符的错误值会通过标准库中 From trait 定义的 from 函数，该函数用于将值从一种类型转换为另一种类型。当 ? 运算符调用 from 函数时，接收到的错误类型会被转换为当前函数返回类型中定义的错误类型。当一个函数返回一种错误类型来表示函数可能失败的所有方式时，即使某些部分可能因多种不同原因而失败，这非常有用。

例如，我们可以将示例 9-7 中的 read_username_from_file 函数改为返回我们定义的自定义错误类型 OurError。如果我们还定义了 impl From<io::Error> for OurError 来从 io::Error 构造一个 OurError 实例，那么 read_username_from_file 函数体中的 ? 运算符调用将调用 from 并转换错误类型，而无需向函数添加任何额外的代码。

在示例 9-7 的上下文中，File::open 调用末尾的 ? 将返回 Ok 内部的值给变量 username_file。如果发生错误，? 运算符将从整个函数提前返回，并将任何 Err 值交给调用代码。同样的情况也适用于 read_to_string 调用末尾的 ?。

? 运算符消除了大量样板代码，并使此函数的实现更简单。我们甚至可以通过在 ? 之后立即链式调用方法进一步缩短这段代码，如示例 9-8 所示。

#![allow(unused)]
fn main() {
use std::fs::File;
use std::io::{self, Read};

fn read_username_from_file() -> Result<String, io::Error> {
    let mut username = String::new();

    File::open("hello.txt")?.read_to_string(&mut username)?;

    Ok(username)
}
}

我们将 username 中新 String 的创建移到了函数的开头；这部分没有改变。我们没有创建变量 username_file，而是将对 read_to_string 的调用直接链式接到 File::open("hello.txt")? 的结果上。我们仍然在 read_to_string 调用的末尾有一个 ?，并且当 File::open 和 read_to_string 都成功而不是返回错误时，我们仍然返回一个包含 username 的 Ok 值。功能再次与示例 9-6 和示例 9-7 相同；这只是另一种更符合人体工程学（ergonomic）的编写方式。

示例 9-9 展示了使用 fs::read_to_string 使这段代码更简短的一种方式。

#![allow(unused)]
fn main() {
use std::fs;
use std::io;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}
}

将文件读入字符串是一个相当常见的操作，因此标准库提供了方便的 fs::read_to_string 函数，它打开文件、创建新的 String、读取文件内容、将内容放入该 String 并返回它。当然，使用 fs::read_to_string 没有给我们解释所有错误处理的机会，所以我们先用了较长的写法。

在哪里可以使用 ? 运算符

? 运算符只能用于返回类型与 ? 所使用的值兼容的函数中。这是因为 ? 运算符被定义为从函数中提前返回一个值，方式与我们在示例 9-6 中定义的 match 表达式相同。在示例 9-6 中，match 使用了一个 Result 值，并且提前返回的分支返回了一个 Err(e) 值。函数的返回类型必须是一个 Result，以便与这个 return 兼容。

在示例 9-10 中，让我们看看如果在返回类型与我们使用 ? 的值的类型不兼容的 main 函数中使用 ? 运算符，会得到什么错误。

use std::fs::File;

fn main() {
    let greeting_file = File::open("hello.txt")?;
}

这段代码打开一个文件，这可能会失败。? 运算符跟在 File::open 返回的 Result 值后面，但这个 main 函数的返回类型是 ()，而不是 Result。当我们编译这段代码时，会得到以下错误消息：

$ cargo run
   Compiling error-handling v0.1.0 (file:///projects/error-handling)
error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`)
 --> src/main.rs:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greeting_file = File::open("hello.txt")?;
  |                                                ^ cannot use the `?` operator in a function that returns `()`
  |
help: consider adding return type
  |
3 ~ fn main() -> Result<(), Box<dyn std::error::Error>> {
4 |     let greeting_file = File::open("hello.txt")?;
5 +     Ok(())
  |

For more information about this error, try `rustc --explain E0277`.
error: could not compile `error-handling` (bin "error-handling") due to 1 previous error

这个错误指出，我们只能在返回 Result、Option 或另一个实现了 FromResidual 的类型的函数中使用 ? 运算符。

要修复这个错误，你有两个选择。一种选择是更改函数的返回类型，使其与你使用 ? 运算符的值兼容，只要没有限制阻止你这样做。另一种选择是使用 match 或 Result<T, E> 方法之一以适当的任何方式处理 Result<T, E>。

错误消息还提到 ? 也可以与 Option<T> 值一起使用。与在 Result 上使用 ? 一样，你只能在返回 Option 的函数中对 Option 使用 ?。对 Option<T> 调用 ? 运算符时的行为与对 Result<T, E> 调用时的行为类似：如果值是 None，则 None 会在该点从函数中提前返回。如果值是 Some，Some 内部的值就是表达式的结果值，函数继续执行。示例 9-11 有一个函数的示例，该函数找到给定文本中第一行的最后一个字符。

fn last_char_of_first_line(text: &str) -> Option<char> {
    text.lines().next()?.chars().last()
}

fn main() {
    assert_eq!(
        last_char_of_first_line("Hello, world\nHow are you today?"),
        Some('d')
    );

    assert_eq!(last_char_of_first_line(""), None);
    assert_eq!(last_char_of_first_line("\nhi"), None);
}

此函数返回 Option<char>，因为可能存在字符，但也可能没有。这段代码接受 text 字符串切片参数，并在其上调用 lines 方法，该方法返回字符串中各行的一个迭代器（iterator）。因为这个函数想要检查第一行，它调用迭代器上的 next 来获取迭代器中的第一个值。如果 text 是空字符串，对 next 的调用将返回 None，在这种情况下我们使用 ? 停止并从 last_char_of_first_line 返回 None。如果 text 不是空字符串，next 将返回一个包含 text 中第一行字符串切片的 Some 值。

? 提取出字符串切片，我们可以在该字符串切片上调用 chars 来获取其字符的迭代器。我们对第一行中的最后一个字符感兴趣，所以我们调用 last 来返回迭代器中的最后一个元素。这是一个 Option，因为第一行可能是空字符串；例如，如果 text 以空行开头但其他行有字符，比如 "\nhi"。然而，如果第一行有最后一个字符，它将在 Some 变体中返回。中间的 ? 运算符给了我们一种简洁的方式来表达这个逻辑，允许我们在一行中实现该函数。如果我们不能在 Option 上使用 ? 运算符，我们就必须使用更多的方法调用或一个 match 表达式来实现这个逻辑。

请注意，你可以在返回 Result 的函数中对 Result 使用 ? 运算符，也可以在返回 Option 的函数中对 Option 使用 ? 运算符，但不能混合使用。? 运算符不会自动将 Result 转换为 Option，反之亦然；在这些情况下，你可以使用诸如 Result 上的 ok 方法或 Option 上的 ok_or 方法来显式地进行转换。

到目前为止，我们使用的所有 main 函数都返回 ()。main 函数是特殊的，因为它是可执行程序的入口点和出口点，并且对于程序按预期行为运行，其返回类型有哪些限制。

幸运的是，main 也可以返回 Result<(), E>。示例 9-12 有来自示例 9-10 的代码，但我们将 main 的返回类型更改为 Result<(), Box<dyn Error>>，并在末尾添加了一个返回值 Ok(())。这段代码现在可以编译了。

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let greeting_file = File::open("hello.txt")?;

    Ok(())
}

Box<dyn Error> 类型是一个 trait 对象（trait object），我们将在第 18 章的“使用 Trait 对象来抽象共享行为”中讨论。现在，你可以将 Box<dyn Error> 理解为“任何类型的错误“。在错误类型为 Box<dyn Error> 的 main 函数中对 Result 值使用 ? 是允许的，因为它允许任何 Err 值被提前返回。尽管这个 main 函数体只会返回 std::io::Error 类型的错误，但通过指定 Box<dyn Error>，即使向 main 函数体添加了返回其他错误的更多代码，此签名也仍然正确。

当 main 函数返回 Result<(), E> 时，如果 main 返回 Ok(())，可执行文件将以值 0 退出；如果 main 返回 Err 值，则以非零值退出。用 C 编写的可执行文件在退出时返回整数：成功退出的程序返回整数 0，出现错误的程序返回某个非 0 的整数。Rust 也从可执行文件返回整数以与此约定兼容。

main 函数可以返回任何实现了 std::process::Termination trait 的类型，该 trait 包含一个返回 ExitCode 的函数 report。请查阅标准库文档以获取有关为你自己的类型实现 Termination trait 的更多信息。

既然我们已经讨论了调用 panic! 或返回 Result 的细节，让我们回到在哪些情况下应该和不应该使用哪种方法的话题。

使用 panic! 还是不使用 panic!

是 panic! 还是不 panic!

那么，你如何决定何时应该调用 panic! 以及何时应该返回 Result？当代码 panic 时，就没有办法恢复了。你可以为任何错误情况调用 panic!，无论是否有恢复的可能，但这样做你就代表调用代码做出了一种情况不可恢复的决定。当你选择返回 Result 值时，你给了调用代码选择权。调用代码可以选择以其情况相适应的方式尝试恢复，或者也可以决定此情况下的 Err 值不可恢复，因此它可以调用 panic! 并将你的可恢复错误变为不可恢复错误。因此，在定义可能失败的函数时，返回 Result 是一个好的默认选择。

在示例、原型代码和测试等情况下，编写 panic 的代码比返回 Result 更合适。让我们探讨原因，然后讨论编译器无法判断失败是不可能的，但作为人类的你可以判断的情况。本章最后将以一些关于如何在库代码中决定是否 panic 的通用指南作为总结。

示例、原型代码和测试

当你编写示例来阐述某个概念时，包含健壮的错误处理代码可能会使示例不够清晰。在示例中，人们理解对 unwrap 等可能 panic 的方法的调用是一个占位符，代表你希望应用程序处理错误的方式，这取决于其余代码正在做什么。

类似地，unwrap 和 expect 方法在原型设计阶段非常方便，当你尚未准备好决定如何处理错误时。它们会在你的代码中留下清晰的标记，以便你准备好使程序更健壮时进行处理。

如果测试中的方法调用失败，你希望整个测试失败，即使该方法不是被测试的功能。因为 panic! 是测试被标记为失败的方式，所以调用 unwrap 或 expect 正是应该发生的事情。

当你比编译器拥有更多信息时

当你拥有一些其他逻辑确保 Result 将具有 Ok 值，但编译器不理解该逻辑时，调用 expect 也是合适的。你仍然有一个需要处理的 Result 值：无论你调用的是什么操作，通常仍然存在失败的可能性，即使在你的特定情况下逻辑上不可能。如果你可以通过手动检查代码来确定永远不会出现 Err 变体，那么完全可以调用 expect，并在参数文本中记录你认为永远不会出现 Err 变体的原因。以下是一个例子：

fn main() {
    use std::net::IpAddr;

    let home: IpAddr = "127.0.0.1"
        .parse()
        .expect("Hardcoded IP address should be valid");
}

我们通过解析一个硬编码的字符串来创建 IpAddr 实例。我们可以看到 127.0.0.1 是一个有效的 IP 地址，因此在这里使用 expect 是可以接受的。然而，拥有一个 hardcoded（硬编码的）、有效的字符串并不会改变 parse 方法的返回类型：我们仍然得到一个 Result 值，编译器仍然会让我们处理这个 Result，就好像 Err 变体有可能发生一样，因为编译器不够聪明，无法看出这个字符串始终是一个有效的 IP 地址。如果 IP 地址字符串来自用户而不是 hardcoded 在程序中，因此确实有失败的可能性，我们肯定会希望以更健壮的方式处理 Result。提及该 IP 地址是 hardcoded 这一假设会提示我们，如果将来需要从其他来源获取 IP 地址，我们应当将 expect 改为更好的错误处理代码。

错误处理指南

当你的代码有可能最终处于不良状态（bad state）时，建议让代码 panic。在此上下文中，不良状态是指某些假设、保证、契约（contract）或不变式（invariant）被破坏的情况，例如当无效值、矛盾值或缺失值被传递给您的代码时——再加上以下一个或多个条件：

• 不良状态是出乎意料的，而不是偶尔可能发生的事情（例如用户以错误格式输入数据）。
• 此点之后的代码需要依赖不处于此不良状态，而不是在每一步都检查问题。
• 没有很好的方法将此信息编码到你所使用的类型中。我们将在第 18 章的“将状态和行为编码为类型”中举例说明我们的意思。

如果有人调用你的代码并传入无意义的值，最好尽可能返回一个错误，以便库的用户可以决定他们在那种情况下想要做什么。然而，在继续执行可能不安全或有害的情况下，最好的选择可能是调用 panic! 并提醒使用你的库的人注意他们代码中的 bug，以便他们在开发过程中修复它。类似地，如果你调用了无法控制的外部代码，并且它返回了你无法修复的无效状态，那么 panic! 通常是合适的。

然而，当失败是可预期的时候，返回 Result 比调用 panic! 更合适。例如，解析器接收到格式错误的数据，或 HTTP 请求返回表示已达到速率限制的状态。在这些情况下，返回 Result 表明失败是一种预期可能性，调用代码必须决定如何处理。

当你的代码执行的操作在使用无效值调用时可能使用户面临风险时，你的代码应首先验证值的有效性，如果值无效则 panic。这主要是出于安全原因：尝试对无效数据进行操作可能会使你的代码暴露于漏洞中。这是标准库在你尝试越界内存访问时会调用 panic! 的主要原因：尝试访问不属于当前数据结构的内存是一个常见的安全问题。函数通常有契约（contracts）：只有在输入满足特定要求时，它们的行为才有保证。在违反契约时 panic 是有意义的，因为契约违规总是表明调用方的 bug，并且这不是你希望调用代码必须显式处理的那种错误。实际上，调用代码没有合理的方式可以恢复；调用方的程序员需要修复代码。函数的契约，特别是当违规会导致 panic 时，应在函数的 API 文档中加以说明。

然而，在所有函数中进行大量的错误检查会显得冗长且烦人。幸运的是，你可以利用 Rust 的类型系统（以及编译器进行的类型检查）为你完成许多检查。如果你的函数有一个特定类型的参数，你可以继续执行代码的逻辑，知道编译器已经确保你拥有一个有效值。例如，如果你使用的是某个类型而不是 Option，你的程序期望拥有某个值而不是什么也没有。然后你的代码就不必处理 Some 和 None 变体的两种情况：它只有一个明确有值的情况。试图将 nothing 传递给函数的代码甚至无法编译，因此你的函数不必在运行时检查这种情况。另一个例子是使用无符号整数类型（如 u32），它确保参数永远不会是负数。

用于验证的自定义类型

让我们将使用 Rust 的类型系统确保我们拥有有效值的想法再推进一步，看看如何创建一个用于验证的自定义类型。回想一下第 2 章中的猜数字游戏，其中我们的代码要求用户猜测一个介于 1 和 100 之间的数字。在与秘密数字进行比较之前，我们从未验证用户的猜测是否在这两个数字之间；我们只验证了猜测是正数。在这种情况下，后果并不严重：我们输出“太大了“或“太小了“仍然会是正确的。但是，引导用户进行有效猜测，并在用户猜测超出范围的数字与例如用户输入字母等情况下表现出不同的行为，将是一个有用的增强。

一种方法是将猜测解析为 i32 而不是仅 u32，以允许潜在负数，然后添加检查数字是否在范围内，如下所示：

use rand::Rng;
use std::cmp::Ordering;
use std::io;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1..=100);

    loop {
        // --snip--

        println!("Please input your guess.");

        let mut guess = String::new();

        io::stdin()
            .read_line(&mut guess)
            .expect("Failed to read line");

        let guess: i32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(_) => continue,
        };

        if guess < 1 || guess > 100 {
            println!("The secret number will be between 1 and 100.");
            continue;
        }

        match guess.cmp(&secret_number) {
            // --snip--
            Ordering::Less => println!("Too small!"),
            Ordering::Greater => println!("Too big!"),
            Ordering::Equal => {
                println!("You win!");
                break;
            }
        }
    }
}

if 表达式检查我们的值是否超出范围，告诉用户问题所在，并调用 continue 开始循环的下一次迭代并请求另一个猜测。在 if 表达式之后，我们可以继续进行 guess 与秘密数字之间的比较，因为我们知道 guess 介于 1 和 100 之间。

然而，这不是一个理想的解决方案：如果程序只能在 1 到 100 之间的值上运行是绝对关键的，并且有许多具有此要求的函数，那么在每一个函数中都进行这样的检查会非常繁琐（并且可能影响性能）。

相反，我们可以创建一个专用模块中的新类型，并将验证放在一个函数中以创建该类型的实例，而不是到处重复验证。这样，函数在其签名中使用新类型并自信地使用它们接收的值是安全的。示例 9-13 展示了一种定义 Guess 类型的方法，该类型仅在 new 函数接收到 1 到 100 之间的值时才创建 Guess 实例。

#![allow(unused)]
fn main() {
pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {value}.");
        }

        Guess { value }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}
}

请注意，src/guessing_game.rs 中的这段代码依赖于在 src/lib.rs 中添加一个模块声明 mod guessing_game;，我们这里没有展示。在这个新模块的文件中，我们定义了一个名为 Guess 的结构体，它具有一个名为 value 的字段，该字段持有一个 i32。这就是数字将被存储的地方。

然后，我们在 Guess 上实现了一个名为 new 的关联函数（associated function），用于创建 Guess 值的实例。new 函数被定义为一个参数 value（类型为 i32），并返回一个 Guess。new 函数体中的代码测试 value 以确保它在 1 到 100 之间。如果 value 未通过此测试，我们调用 panic!，这将提醒编写调用代码的程序员他们有一个需要修复的 bug，因为创建一个 value 超出此范围的 Guess 将违反 Guess::new 所依赖的契约。Guess::new 可能 panic 的条件应该在其公共 API 文档中讨论；我们将在第 14 章中介绍在 API 文档中标示可能发生 panic! 的文档约定。如果 value 通过了测试，我们创建一个新的 Guess，其 value 字段设置为 value 参数，并返回 Guess。

接下来，我们实现一个名为 value 的方法，它借用 self，没有其他参数，并返回一个 i32。这种方法有时被称为getter（获取器），因为其目的是从其字段中获取某些数据并返回它。这个公共方法是必要的，因为 Guess 结构体的 value 字段是私有的。value 字段是私有的这一点很重要，这样使用 Guess 结构体的代码就不允许直接设置 value：guessing_game 模块外部的代码必须使用 Guess::new 函数来创建 Guess 的实例，从而确保 Guess 的 value 不可能没有被 Guess::new 函数中的条件检查过。

一个具有参数或仅返回 1 到 100 之间的数字的函数，可以在其签名中声明它接受或返回一个 Guess 而不是 i32，并且不需要在其函数体中进行任何额外的检查。

总结

Rust 的错误处理功能旨在帮助你编写更健壮的代码。panic! 宏表示你的程序处于无法处理的状态，并让你通知进程停止，而不是试图使用无效或不正确的值继续执行。Result 枚举利用 Rust 的类型系统来指示操作可能以你的代码可以恢复的方式失败。你可以使用 Result 来通知调用你代码的代码也需要处理潜在的成功或失败。在适当的情况下使用 panic! 和 Result 将使你的代码在面对不可避免的问题时更加可靠。

现在你已经看到了标准库使用泛型与 Option 和 Result 枚举的有用方式，我们将讨论泛型的工作原理以及如何在你的代码中使用它们。

泛型类型、Trait 和生命周期（Generic Types, Traits, and Lifetimes）

每种编程语言都有有效处理概念重复的工具。在 Rust 中，其中一种工具是泛型（generics）：具体类型或其他属性的抽象替代物。我们可以在编译和运行代码时不知道具体内容的情况下，表达泛型的行为或它们与其他泛型的关联方式。

函数可以接受某种泛型类型的参数，而不是像 i32 或 String 这样的具体类型，就像它们接受具有未知值的参数以在多个具体值上运行相同的代码一样。事实上，我们已经在第 6 章中使用过 Option<T>，在第 8 章中使用过 Vec<T> 和 HashMap<K, V>，在第 9 章中使用过 Result<T, E>。在本章中，你将探索如何使用泛型定义自己的类型、函数和方法！

首先，我们将回顾如何提取一个函数来减少代码重复。然后，我们将使用相同的技术，从两个仅在参数类型上不同的函数中制作一个泛型函数。我们还将解释如何在结构体（struct）和枚举（enum）定义中使用泛型类型。

然后，你将学习如何使用 trait（特质）以泛型方式定义行为。你可以将 trait 与泛型类型结合使用，以约束泛型类型仅接受具有特定行为的类型，而不是任何类型。

最后，我们将讨论生命周期（lifetimes）：一种泛型变体，它为编译器提供有关引用之间如何相互关联的信息。生命周期允许我们给编译器提供关于借用值的足够信息，以便它能够确保引用在更多情况下比没有我们的帮助时更有效。

通过提取函数消除重复

泛型允许我们用代表多种类型的占位符替换特定类型，以消除代码重复。在深入泛型语法之前，让我们首先看看如何通过提取一个函数来消除重复，这种方式不涉及泛型类型，而是用代表多个值的占位符替换特定值。然后，我们将应用相同的技术来提取一个泛型函数！通过了解如何识别可以提取到函数中的重复代码，你将开始识别可以使用泛型的重复代码。

我们从示例 10-1 中的简短程序开始，该程序查找列表中的最大数字。

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
    assert_eq!(*largest, 100);
}

我们将一个整数列表存储在变量 number_list 中，并将指向列表中第一个数字的引用放在名为 largest 的变量中。然后，我们遍历列表中的所有数字，如果当前数字大于存储在 largest 中的数字，我们就替换该变量中的引用。然而，如果当前数字小于或等于迄今为止看到的最大数字，则变量不变，代码继续处理列表中的下一个数字。在考虑了列表中的所有数字之后，largest 应该指向最大的数字，在本例中为 100。

现在我们的任务是在两个不同的数字列表中找到最大的数字。为此，我们可以选择复制示例 10-1 中的代码，并在程序中的两个不同位置使用相同的逻辑，如示例 10-2 所示。

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let mut largest = &number_list[0];

    for number in &number_list {
        if number > largest {
            largest = number;
        }
    }

    println!("The largest number is {largest}");
}

尽管这段代码可以工作，但复制代码既繁琐又容易出错。当我们想要更改代码时，还必须记住在多个地方更新它。

为了消除这种重复，我们将通过定义一个函数来创建一种抽象，该函数对作为参数传入的任何整数列表进行操作。这个解决方案使我们的代码更清晰，并让我们抽象地表达在列表中查找最大数字的概念。

在示例 10-3 中，我们将查找最大数字的代码提取到一个名为 largest 的函数中。然后，我们调用该函数来查找示例 10-2 中两个列表的最大数字。我们也可以在将来可能拥有的任何其他 i32 值列表上使用该函数。

fn largest(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];

    let result = largest(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 6000);
}

largest 函数有一个名为 list 的参数，它表示我们可能传入函数的任何具体 i32 值切片。因此，当我们调用该函数时，代码会在我们传入的具体值上运行。

总之，以下是我们将代码从示例 10-2 更改为示例 10-3 所采取的步骤：

1. 识别重复代码。
2. 将重复代码提取到函数体中，并在函数签名中指定该代码的输入和返回值。
3. 更新两个重复代码实例以调用该函数而不是使用重复代码。

接下来，我们将使用相同的步骤与泛型一起减少代码重复。就像函数体可以对抽象的 list 而不是特定值进行操作一样，泛型允许代码对抽象类型进行操作。

例如，假设我们有两个函数：一个在 i32 值的切片中查找最大项，另一个在 char 值的切片中查找最大项。我们如何消除这种重复？让我们来找出答案！

泛型数据类型

泛型数据类型（Generic Data Types）

我们使用泛型来创建函数签名或结构体等项的定义，然后我们可以将这些定义用于许多不同的具体数据类型。让我们首先看看如何使用泛型定义函数、结构体、枚举和方法。然后，我们将讨论泛型如何影响代码性能。

在函数定义中

在定义使用泛型的函数时，我们将泛型放在函数签名中通常指定参数和返回值数据类型的位置。这样做使我们的代码更灵活，为函数的调用者提供更多功能，同时防止代码重复。

继续我们的 largest 函数，示例 10-4 展示了两个都在切片中查找最大值的函数。然后，我们将它们合并为一个使用泛型的函数。

fn largest_i32(list: &[i32]) -> &i32 {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn largest_char(list: &[char]) -> &char {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest_i32(&number_list);
    println!("The largest number is {result}");
    assert_eq!(*result, 100);

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest_char(&char_list);
    println!("The largest char is {result}");
    assert_eq!(*result, 'y');
}

largest_i32 函数是我们在示例 10-3 中提取的函数，用于在切片中查找最大的 i32。largest_char 函数用于在切片中查找最大的 char。函数体具有相同的代码，因此让我们通过在一个函数中引入泛型类型参数来消除重复。

要参数化新函数中的类型，我们需要命名类型参数，就像我们对函数的值参数所做的那样。你可以使用任何标识符作为类型参数名称。但我们将使用 T，因为按照惯例，Rust 中的类型参数名称很短，通常只有一个字母，并且 Rust 的类型命名约定是 UpperCamelCase。作为 type 的缩写，T 是大多数 Rust 程序员的默认选择。

当我们在函数体中使用参数时，必须在签名中声明参数名称，以便编译器知道该名称的含义。类似地，当我们在函数签名中使用类型参数名称时，必须在使用它之前声明类型参数名称。要定义泛型 largest 函数，我们将类型名称声明放在尖括号 <> 中，位于函数名称和参数列表之间，如下所示：

fn largest<T>(list: &[T]) -> &T {

我们将这个定义解读为：“函数 largest 在某种类型 T 上是泛型的。“这个函数有一个名为 list 的参数，它是类型 T 的值的切片。largest 函数将返回对相同类型 T 的值的引用。

示例 10-5 展示了在其签名中使用泛型数据类型的组合 largest 函数定义。该清单还展示了如何使用 i32 值切片或 char 值切片调用该函数。请注意，这段代码还不能编译。

fn largest<T>(list: &[T]) -> &T {
    let mut largest = &list[0];

    for item in list {
        if item > largest {
            largest = item;
        }
    }

    largest
}

fn main() {
    let number_list = vec![34, 50, 25, 100, 65];

    let result = largest(&number_list);
    println!("The largest number is {result}");

    let char_list = vec!['y', 'm', 'a', 'q'];

    let result = largest(&char_list);
    println!("The largest char is {result}");
}

如果我们现在编译这段代码，将得到以下错误：

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T` with trait `PartialOrd`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
  |             ++++++++++++++++++++++

For more information about this error, try `rustc --explain E0369`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

帮助文本提到了 std::cmp::PartialOrd，这是一个 trait，我们将在下一节讨论 trait。现在，要知道这个错误表明 largest 的函数体对于 T 可能的所有类型不能都工作。因为我们在函数体中想要比较 T 类型的值，我们只能使用其值可以排序的类型。为了启用比较，标准库提供了 std::cmp::PartialOrd trait，你可以在类型上实现它（有关此 trait 的更多信息，请参见附录 C）。要修复示例 10-5，我们可以遵循帮助文本的建议，将 T 的有效类型限制为仅实现了 PartialOrd 的类型。然后该清单将编译，因为标准库在 i32 和 char 上都实现了 PartialOrd。

在结构体定义中

我们也可以使用 <> 语法定义结构体，在一个或多个字段中使用泛型类型参数。示例 10-6 定义了一个 Point<T> 结构体，用于保存任何类型的 x 和 y 坐标值。

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 };
    let float = Point { x: 1.0, y: 4.0 };
}

在结构体定义中使用泛型的语法与在函数定义中使用的语法类似。首先，我们在结构体名称之后立即在尖括号内声明类型参数的名称。然后，我们在结构体定义中原本会指定具体数据类型的地方使用泛型类型。

请注意，因为我们只使用了一个泛型类型来定义 Point<T>，所以这个定义表明 Point<T> 结构体在某种类型 T 上是泛型的，并且字段 x 和 y 都是相同的类型，无论该类型可能是什么。如果我们创建一个具有不同类型的值的 Point<T> 实例，如示例 10-7 所示，我们的代码将无法编译。

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wont_work = Point { x: 5, y: 4.0 };
}

在这个例子中，当我们将整数值 5 赋给 x 时，我们让编译器知道泛型类型 T 对于这个 Point<T> 实例将是整数。然后，当我们为 y 指定 4.0（我们已经定义它与 x 具有相同的类型）时，我们将得到一个类型不匹配错误，如下所示：

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wont_work = Point { x: 5, y: 4.0 };
  |                                      ^^^ expected integer, found floating-point number

For more information about this error, try `rustc --explain E0308`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

要定义一个 Point 结构体，其中 x 和 y 都是泛型但可能具有不同的类型，我们可以使用多个泛型类型参数。例如，在示例 10-8 中，我们将 Point 的定义改为在类型 T 和 U 上是泛型的，其中 x 是类型 T，y 是类型 U。

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let both_integer = Point { x: 5, y: 10 };
    let both_float = Point { x: 1.0, y: 4.0 };
    let integer_and_float = Point { x: 5, y: 4.0 };
}

现在所示的所有 Point 实例都是允许的！你可以在定义中使用任意多个泛型类型参数，但使用多个会使你的代码难以阅读。如果你发现代码中需要大量泛型类型，可能表明你的代码需要重组为更小的部分。

在枚举定义中

与结构体一样，我们可以定义枚举在其变体中持有泛型数据类型。让我们再看一下标准库提供的 Option<T> 枚举，我们在第 6 章中使用过它：

#![allow(unused)]
fn main() {
enum Option<T> {
    Some(T),
    None,
}
}

这个定义现在对你来说应该更有意义了。如你所见，Option<T> 枚举在类型 T 上是泛型的，并且有两个变体：Some，它持有一个类型 T 的值，以及 None 变体，它不持有任何值。通过使用 Option<T> 枚举，我们可以表达可选值的抽象概念，并且因为 Option<T> 是泛型的，无论可选值的类型是什么，我们都可以使用这个抽象。

枚举也可以使用多个泛型类型。我们在第 9 章中使用的 Result 枚举的定义就是一个例子：

#![allow(unused)]
fn main() {
enum Result<T, E> {
    Ok(T),
    Err(E),
}
}

Result 枚举在两种类型 T 和 E 上是泛型的，并且有两个变体：Ok，它持有一个类型 T 的值，以及 Err，它持有一个类型 E 的值。这个定义使得在有一个可能成功（返回某种类型 T 的值）或失败（返回某种类型 E 的错误）的操作的任何地方使用 Result 枚举都很方便。实际上，这就是我们在示例 9-3 中打开文件时使用的，其中 T 被填充为类型 std::fs::File（当文件成功打开时），而 E 被填充为类型 std::io::Error（当打开文件出现问题时）。

当你在代码中识别出多个结构体或枚举定义仅在它们持有的值类型上有所不同时，你可以通过使用泛型类型来避免重复。

在方法定义中

我们可以在结构体和枚举上实现方法（就像我们在第 5 章中所做的那样），并在它们的定义中使用泛型类型。示例 10-9 显示了我们之前在示例 10-6 中定义的 Point<T> 结构体，以及在它上面实现的名为 x 的方法。

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

在这里，我们在 Point<T> 上定义了一个名为 x 的方法，它返回对字段 x 中数据的引用。

注意，我们必须在 impl 之后立即声明 T，以便我们可以使用 T 来指定我们正在为类型 Point<T> 实现方法。通过在 impl 之后将 T 声明为泛型类型，Rust 可以识别 Point 中尖括号内的类型是泛型类型而不是具体类型。我们可以为这个泛型参数选择与结构体定义中声明的泛型参数不同的名称，但使用相同的名称是惯例。如果你在声明了泛型类型的 impl 中编写方法，那么无论最终用哪种具体类型替换泛型类型，该方法都将在该类型的任何实例上定义。

我们也可以在定义类型上的方法时指定对泛型类型的约束。例如，我们可以仅在 Point<f32> 实例上实现方法，而不是在任何泛型类型的 Point<T> 实例上实现。在示例 10-10 中，我们使用了具体类型 f32，意味着我们在 impl 之后没有声明任何类型。

struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}

impl Point<f32> {
    fn distance_from_origin(&self) -> f32 {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

fn main() {
    let p = Point { x: 5, y: 10 };

    println!("p.x = {}", p.x());
}

这段代码意味着类型 Point<f32> 将有一个 distance_from_origin 方法；其他 T 不是 f32 类型的 Point<T> 实例将没有此方法定义。该方法测量我们的点距离坐标 (0.0, 0.0) 处的点有多远，并使用仅适用于浮点类型的数学运算。

结构体定义中的泛型类型参数并不总是与你在此结构体的方法签名中使用的相同。示例 10-11 为 Point 结构体使用泛型类型 X1 和 Y1，为 mixup 方法签名使用 X2 和 Y2，以使示例更清晰。该方法创建一个新的 Point 实例，其 x 值来自 self 的 Point（类型为 X1），y 值来自传入的 Point（类型为 Y2）。

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

impl<X1, Y1> Point<X1, Y1> {
    fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 };
    let p2 = Point { x: "Hello", y: 'c' };

    let p3 = p1.mixup(p2);

    println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
}

在 main 中，我们定义了一个 Point，其 x 为 i32（值为 5），y 为 f64（值为 10.4）。p2 变量是一个 Point 结构体，其 x 为字符串切片（值为 "Hello"），y 为 char（值为 c）。在 p1 上调用 mixup 并传入参数 p2 得到 p3，其 x 将为 i32，因为 x 来自 p1。p3 变量的 y 将为 char，因为 y 来自 p2。println! 宏调用将打印 p3.x = 5, p3.y = c。

此示例的目的是展示一种情况，其中一些泛型参数用 impl 声明，另一些用方法定义声明。在这里，泛型参数 X1 和 Y1 在 impl 之后声明，因为它们与结构体定义相关。泛型参数 X2 和 Y2 在 fn mixup 之后声明，因为它们仅与方法相关。

使用泛型的代码的性能

你可能想知道使用泛型类型参数是否会产生运行时开销。好消息是，使用泛型类型不会使你的程序比使用具体类型时运行得更慢。

Rust 通过在编译时对使用泛型的代码执行单态化（monomorphization）来实现这一点。*单态化（Monomorphization）*是通过填充编译时使用的具体类型，将泛型代码转换为特定代码的过程。在这个过程中，编译器执行与我们创建示例 10-5 中的泛型函数时使用的步骤相反的操作：编译器查看调用泛型代码的所有位置，并为调用泛型代码的具体类型生成代码。

让我们通过使用标准库的泛型 Option<T> 枚举来看看这是如何工作的：

#![allow(unused)]
fn main() {
let integer = Some(5);
let float = Some(5.0);
}

当 Rust 编译这段代码时，它会执行单态化。在这个过程中，编译器读取在 Option<T> 实例中使用的值，并识别出两种 Option<T>：一种是 i32，另一种是 f64。因此，它将 Option<T> 的泛型定义扩展为两个专门针对 i32 和 f64 的定义，从而用特化的定义替换了泛型定义。

单态化后的代码版本类似于以下内容（编译器使用的名称与我们在这里用来说明问题的名称不同）：

enum Option_i32 {
    Some(i32),
    None,
}

enum Option_f64 {
    Some(f64),
    None,
}

fn main() {
    let integer = Option_i32::Some(5);
    let float = Option_f64::Some(5.0);
}

泛型 Option<T> 被替换为由编译器创建的特定定义。因为 Rust 将泛型代码编译为在每个实例中指定了类型的代码，所以使用泛型不会产生运行时开销。当代码运行时，它的执行方式与我们手动复制每个定义时完全相同。单态化过程使 Rust 的泛型在运行时极为高效。

使用 Trait 定义共享行为

使用 Trait 定义共享行为（Shared Behavior）

trait 定义了一个特定类型所具有的、并可以与其它类型共享的功能。我们可以使用 trait 以抽象的方式定义共享行为。我们可以使用 trait 约束（trait bounds） 来指定泛型类型可以是任何具有特定行为的类型。

注意：Trait 类似于其他语言中通常称为 接口（interfaces） 的功能，尽管有一些差异。

定义 Trait

一个类型的行为包括我们可以对该类型调用的方法。如果我们能在所有这些类型上调用相同的方法，则不同类型共享相同的行为。Trait 定义是一种将方法签名组合在一起的方法，用于定义实现某个目的所需的一组行为。

例如，假设我们有多个结构体，它们持有各种类型和数量的文本：一个 NewsArticle 结构体，持有特定地点存档的新闻报道；一个 SocialPost，最多可以有 280 个字符，并带有元数据，指示它是新帖子、转发还是对另一帖子的回复。

我们想要创建一个名为 aggregator 的媒体聚合器库 crate，它可以显示可能存储在 NewsArticle 或 SocialPost 实例中的数据的摘要。为此，我们需要每个类型的摘要，我们将通过在实例上调用 summarize 方法来请求该摘要。示例 10-12 定义了一个公共的 Summary trait，它表达了这种行为。

pub trait Summary {
    fn summarize(&self) -> String;
}

在这里，我们使用 trait 关键字声明了一个 trait，然后是 trait 的名称，在本例中是 Summary。我们还声明了这个 trait 为 pub，以便依赖此 crate 的其他 crate 也可以使用这个 trait，我们将在几个示例中看到这一点。在花括号内，我们声明了方法签名，这些签名描述了实现此 trait 的类型的行为，在本例中是 fn summarize(&self) -> String。

在方法签名之后，我们不提供花括号内的实现，而是使用分号。实现此 trait 的每个类型必须为方法体提供自己的自定义行为。编译器将强制执行：任何具有 Summary trait 的类型都必须完全按照此签名定义 summarize 方法。

一个 trait 在其主体中可以拥有多个方法：方法签名每行列出一个，每行以分号结束。

在类型上实现 Trait

现在我们已经定义了 Summary trait 方法的期望签名，我们可以在媒体聚合器中的类型上实现它。示例 10-13 展示了在 NewsArticle 结构体上 Summary trait 的实现，它使用 headline、author 和 location 来创建 summarize 的返回值。对于 SocialPost 结构体，我们将 summarize 定义为用户名后接帖子的全文，假设帖子内容已经限制在 280 个字符以内。

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

在类型上实现 trait 类似于实现常规方法。区别在于，在 impl 之后，我们放入要实现的 trait 名称，然后使用 for 关键字，然后指定要为其实现 trait 的类型名称。在 impl 块内，我们放入 trait 定义已经定义的方法签名。不在每个签名后加分号，而是使用花括号并填充方法体，其中包含我们希望 trait 的方法为该特定类型具有的特定行为。

现在库已经在 NewsArticle 和 SocialPost 上实现了 Summary trait，crate 的用户可以像调用常规方法一样在 NewsArticle 和 SocialPost 实例上调用 trait 方法。唯一的区别是用户必须将 trait 与类型一起引入作用域。以下是一个二进制 crate 如何使用我们的 aggregator 库 crate 的示例：

use aggregator::{SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

这段代码打印 1 new post: horse_ebooks: of course, as you probably already know, people。

依赖于 aggregator crate 的其他 crate 也可以将 Summary trait 引入作用域，以在其自己的类型上实现 Summary。需要注意的一个限制是，只有当 trait 或类型（或两者）对于我们的 crate 是本地（local）的时候，我们才能在类型上实现 trait。例如，我们可以在自定义类型 SocialPost 上实现标准库 trait（如 Display），作为 aggregator crate 功能的一部分，因为类型 SocialPost 对于我们的 aggregator crate 是本地的。我们也可以在 aggregator crate 中的 Vec<T> 上实现 Summary，因为 trait Summary 对于我们的 aggregator crate 是本地的。

但我们不能对外部类型实现外部 trait。例如，我们不能在 aggregator crate 中的 Vec<T> 上实现 Display trait，因为 Display 和 Vec<T> 都在标准库中定义，而不是 aggregator crate 本地的。此限制是属于称为 连贯性（coherence） 的属性，更具体地说是 孤儿规则（orphan rule），之所以如此命名是因为父类型不存在。此规则确保其他人的代码不会破坏你的代码，反之亦然。如果没有这条规则，两个 crate 可以为同一类型实现相同的 trait，而 Rust 将不知道使用哪个实现。

使用默认实现

有时，为 trait 中的部分或全部方法提供默认行为是很有用的，而不是要求在每个类型上实现所有方法。然后，当我们在特定类型上实现 trait 时，我们可以保留或覆盖每个方法的默认行为。

在示例 10-14 中，我们为 Summary trait 的 summarize 方法指定了默认字符串，而不是像在示例 10-12 中那样仅定义方法签名。

pub trait Summary {
    fn summarize(&self) -> String {
        String::from("(Read more...)")
    }
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

要使用默认实现来摘要 NewsArticle 实例，我们指定一个空的 impl 块，其中包含 impl Summary for NewsArticle {}。

尽管我们不再直接在 NewsArticle 上定义 summarize 方法，但我们提供了一个默认实现，并指定 NewsArticle 实现了 Summary trait。因此，我们仍然可以在 NewsArticle 实例上调用 summarize 方法，如下所示：

use aggregator::{self, NewsArticle, Summary};

fn main() {
    let article = NewsArticle {
        headline: String::from("Penguins win the Stanley Cup Championship!"),
        location: String::from("Pittsburgh, PA, USA"),
        author: String::from("Iceburgh"),
        content: String::from(
            "The Pittsburgh Penguins once again are the best \
             hockey team in the NHL.",
        ),
    };

    println!("New article available! {}", article.summarize());
}

这段代码打印 New article available! (Read more...)。

创建默认实现不要求我们对示例 10-13 中 SocialPost 上的 Summary 实现进行任何更改。原因是覆盖默认实现的语法与实现没有默认实现的 trait 方法的语法相同。

默认实现可以调用同一 trait 中的其他方法，即使这些其他方法没有默认实现。这样，trait 可以提供大量有用的功能，并且只要求实现者指定其中的一小部分。例如，我们可以定义 Summary trait 有一个需要实现的 summarize_author 方法，然后定义一个 summarize 方法，该方法具有调用 summarize_author 方法的默认实现：

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

要使用此版本的 Summary，我们只需要在类型上实现 trait 时定义 summarize_author：

pub trait Summary {
    fn summarize_author(&self) -> String;

    fn summarize(&self) -> String {
        format!("(Read more from {}...)", self.summarize_author())
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize_author(&self) -> String {
        format!("@{}", self.username)
    }
}

在定义了 summarize_author 之后，我们可以对 SocialPost 结构体的实例调用 summarize，并且 summarize 的默认实现将调用我们提供的 summarize_author 的定义。因为我们实现了 summarize_author，Summary trait 给了我们 summarize 方法的行为，而不需要我们再写任何代码。这就是它的样子：

use aggregator::{self, SocialPost, Summary};

fn main() {
    let post = SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    };

    println!("1 new post: {}", post.summarize());
}

这段代码打印 1 new post: (Read more from @horse_ebooks...)。

请注意，无法从同一方法的覆盖实现中调用默认实现。

将 Trait 用作参数

现在你已经知道如何定义和实现 trait，我们可以探讨如何使用 trait 来定义接受许多不同类型参数的函数。我们将使用在示例 10-13 中 NewsArticle 和 SocialPost 类型上实现的 Summary trait，来定义一个 notify 函数，该函数调用其 item 参数上的 summarize 方法，该参数是某个实现了 Summary trait 的类型。为此，我们使用 impl Trait 语法，如下所示：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

pub fn notify(item: &impl Summary) {
    println!("Breaking news! {}", item.summarize());
}

对于 item 参数，我们不指定具体类型，而是指定 impl 关键字和 trait 名称。此参数接受任何实现了指定 trait 的类型。在 notify 的函数体中，我们可以调用 item 上来自 Summary trait 的任何方法，例如 summarize。我们可以调用 notify 并传入任何 NewsArticle 或 SocialPost 实例。使用任何其他类型（例如 String 或 i32）调用该函数的代码将无法编译，因为这些类型没有实现 Summary。

Trait 约束语法

impl Trait 语法适用于简单情况，但它实际上是较长形式的语法糖，称为 trait 约束（trait bound）；它看起来像这样：

pub fn notify<T: Summary>(item: &T) {
    println!("Breaking news! {}", item.summarize());
}

这种较长形式等同于上一节中的示例，但更冗长。我们将 trait 约束放在泛型类型参数的声明之后，在冒号和尖括号内。

impl Trait 语法在简单情况下方便且使代码更简洁，而更全面的 trait 约束语法可以在其他情况下表达更复杂的含义。例如，我们可以有两个实现 Summary 的参数。使用 impl Trait 语法这样做看起来像这样：

pub fn notify(item1: &impl Summary, item2: &impl Summary) {

如果我们希望此函数允许 item1 和 item2 具有不同的类型（只要两种类型都实现 Summary），使用 impl Trait 是合适的。然而，如果我们希望强制两个参数具有相同的类型，我们必须使用 trait 约束，如下所示：

pub fn notify<T: Summary>(item1: &T, item2: &T) {

指定为 item1 和 item2 参数类型的泛型类型 T 约束了该函数，使得作为 item1 和 item2 参数传入的值必须是相同的具体类型。

通过 + 语法指定多个 Trait 约束

我们还可以指定多个 trait 约束。假设我们希望 notify 在 item 上同时使用 display 格式化以及 summarize：我们在 notify 的定义中指定 item 必须同时实现 Display 和 Summary。我们可以使用 + 语法来实现：

pub fn notify(item: &(impl Summary + Display)) {

+ 语法也适用于泛型类型上的 trait 约束：

pub fn notify<T: Summary + Display>(item: &T) {

通过指定这两个 trait 约束，notify 的函数体可以调用 summarize 并使用 {} 来格式化 item。

通过 where 子句使 Trait 约束更清晰

使用太多的 trait 约束有其缺点。每个泛型都有自己的 trait 约束，因此具有多个泛型类型参数的函数可能会在函数名称和参数列表之间包含大量 trait 约束信息，使函数签名难以阅读。因此，Rust 提供了另一种在函数签名后的 where 子句中指定 trait 约束的语法。所以，不必写成这样：

fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {

我们可以使用 where 子句，如下所示：

fn some_function<T, U>(t: &T, u: &U) -> i32
where
    T: Display + Clone,
    U: Clone + Debug,
{
    unimplemented!()
}

这个函数的签名不那么杂乱：函数名称、参数列表和返回类型靠在一起，类似于没有大量 trait 约束的函数。

返回实现了 Trait 的类型

我们也可以在返回位置使用 impl Trait 语法，返回某种实现了 trait 的类型的值，如下所示：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable() -> impl Summary {
    SocialPost {
        username: String::from("horse_ebooks"),
        content: String::from(
            "of course, as you probably already know, people",
        ),
        reply: false,
        repost: false,
    }
}

通过使用 impl Summary 作为返回类型，我们指定 returns_summarizable 函数返回某种实现了 Summary trait 的类型，而不命名具体类型。在这种情况下，returns_summarizable 返回一个 SocialPost，但调用此函数的代码不需要知道这一点。

仅通过其实现的 trait 来指定返回类型的能力在闭包（closure）和迭代器（iterator）的上下文中特别有用，我们将在第 13 章中介绍。闭包和迭代器创建了只有编译器知道或非常长的类型。impl Trait 语法让你可以简洁地指定函数返回某种实现了 Iterator trait 的类型，而无需写出一个非常长的类型。

然而，只有当你返回单一类型时，才能使用 impl Trait。例如，返回一个 NewsArticle 或一个 SocialPost 并将返回类型指定为 impl Summary 的这段代码将无法工作：

pub trait Summary {
    fn summarize(&self) -> String;
}

pub struct NewsArticle {
    pub headline: String,
    pub location: String,
    pub author: String,
    pub content: String,
}

impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

pub struct SocialPost {
    pub username: String,
    pub content: String,
    pub reply: bool,
    pub repost: bool,
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}

fn returns_summarizable(switch: bool) -> impl Summary {
    if switch {
        NewsArticle {
            headline: String::from(
                "Penguins win the Stanley Cup Championship!",
            ),
            location: String::from("Pittsburgh, PA, USA"),
            author: String::from("Iceburgh"),
            content: String::from(
                "The Pittsburgh Penguins once again are the best \
                 hockey team in the NHL.",
            ),
        }
    } else {
        SocialPost {
            username: String::from("horse_ebooks"),
            content: String::from(
                "of course, as you probably already know, people",
            ),
            reply: false,
            repost: false,
        }
    }
}

由于 impl Trait 语法在编译器中的实现方式有限制，不允许返回 NewsArticle 或 SocialPost 两者之一。我们将在第 18 章的“使用 Trait 对象来抽象共享行为”部分介绍如何编写具有此行为的函数。

使用 Trait 约束有条件地实现方法

通过对使用泛型类型参数的 impl 块使用 trait 约束，我们可以有条件地为实现了指定 trait 的类型实现方法。例如，示例 10-15 中的 Pair<T> 类型始终实现了 new 函数以返回 Pair<T> 的新实例（回想一下第 5 章的“方法语法”部分，Self 是 impl 块类型的别名，在这种情况下是 Pair<T>）。但在下一个 impl 块中，Pair<T> 仅在其内部类型 T 实现了 PartialOrd trait（允许比较）和 Display trait（允许打印）时，才实现 cmp_display 方法。

use std::fmt::Display;

struct Pair<T> {
    x: T,
    y: T,
}

impl<T> Pair<T> {
    fn new(x: T, y: T) -> Self {
        Self { x, y }
    }
}

impl<T: Display + PartialOrd> Pair<T> {
    fn cmp_display(&self) {
        if self.x >= self.y {
            println!("The largest member is x = {}", self.x);
        } else {
            println!("The largest member is y = {}", self.y);
        }
    }
}

我们也可以有条件地为实现了另一个 trait 的任何类型实现一个 trait。对满足 trait 约束的任何类型的 trait 实现被称为覆盖实现（blanket implementations），并在 Rust 标准库中广泛使用。例如，标准库对任何实现了 Display trait 的类型实现 ToString trait。标准库中的 impl 块看起来类似于以下代码：

impl<T: Display> ToString for T {
    // --snip--
}

因为标准库有这个覆盖实现，我们可以在任何实现了 Display trait 的类型上调用由 ToString trait 定义的 to_string 方法。例如，我们可以将整数转换为其对应的 String 值，因为整数实现了 Display：

#![allow(unused)]
fn main() {
let s = 3.to_string();
}

覆盖实现出现在 trait 文档中的“Implementors“部分。

Trait 和 trait 约束使我们能够编写使用泛型类型参数来减少重复的代码，同时向编译器指定我们希望泛型类型具有特定的行为。然后编译器可以使用 trait 约束信息来检查与我们的代码一起使用的所有具体类型是否提供了正确的行为。在动态类型语言中，如果我们对未定义该方法的类型调用了该方法，我们会在运行时得到一个错误。但 Rust 将这些错误移到编译时，这样我们在代码甚至能够运行之前就被迫修复问题。此外，我们不必编写在运行时检查行为的代码，因为我们已经在编译时检查过了。这样做提高了性能，而不必放弃泛型的灵活性。

使用生命周期验证引用

使用生命周期（Lifetime）验证引用

生命周期是另一种我们已经在使用中的泛型。不同于确保类型具有我们想要的行为，生命周期确保引用在我们需要它们的时候一直有效。

我们在第 4 章的“引用与借用”部分没有讨论的一个细节是，Rust 中的每个引用都有一个生命周期（lifetime），也就是该引用有效的范围。大多数情况下，生命周期是隐式且可推断的，就像大多数情况下类型可以被推断一样。我们只在可能存在多种类型时才需要标注类型。类似地，当引用的生命周期可能以几种不同方式相互关联时，我们必须标注生命周期。Rust 要求我们使用泛型生命周期参数来标注这些关系，以确保运行时使用的实际引用绝对是有效的。

标注生命周期甚至不是大多数其他编程语言都有的概念，所以这可能会让人感到陌生。尽管我们不会在本章中完整地介绍生命周期，但我们将讨论你可能遇到的生命周期语法的常见方式，以便你能熟悉这个概念。

悬垂引用（Dangling References）

生命周期的主要目的是防止悬垂引用（dangling references），如果允许它们存在，程序会引用非其意图引用的数据。考虑示例 10-16 中的程序，它有一个外部作用域和一个内部作用域。

fn main() {
    let r;

    {
        let x = 5;
        r = &x;
    }

    println!("r: {r}");
}

注意：示例 10-16、10-17 和 10-23 中的示例声明了变量但未赋予初始值，因此变量名存在于外部作用域。乍一看，这似乎与 Rust 没有空值（null）相冲突。然而，如果我们尝试在给变量赋值之前使用它，我们会得到一个编译时错误，这表明 Rust 确实不允许空值。

外部作用域声明了一个名为 r 的变量，没有初始值，内部作用域声明了一个名为 x 的变量，初始值为 5。在内部作用域中，我们尝试将 r 的值设置为对 x 的引用。然后，内部作用域结束，我们尝试打印 r 中的值。这段代码无法编译，因为 r 所引用的值在我们尝试使用它之前已经离开了作用域。以下是错误消息：

$ cargo run
   Compiling chapter10 v0.1.0 (file:///projects/chapter10)
error[E0597]: `x` does not live long enough
 --> src/main.rs:6:13
  |
5 |         let x = 5;
  |             - binding `x` declared here
6 |         r = &x;
  |             ^^ borrowed value does not live long enough
7 |     }
  |     - `x` dropped here while still borrowed
8 |
9 |     println!("r: {r}");
  |                   - borrow later used here

For more information about this error, try `rustc --explain E0597`.
error: could not compile `chapter10` (bin "chapter10") due to 1 previous error

错误消息说变量 x “does not live long enough”。原因是当内部作用域在第 7 行结束时，x 将超出作用域。但 r 在外部作用域中仍然有效；因为它的作用域更大，我们说它“活得更长“。如果 Rust 允许这段代码工作，r 将引用当 x 超出作用域时已释放的内存，而我们尝试对 r 做的任何事情都不会正确工作。那么，Rust 如何确定这段代码是无效的呢？它使用了一个借用检查器。

借用检查器（Borrow Checker）