O'Reilly Media, Inc.介绍

O'Reilly 以“分享创新知识、改变世界”为己任。40 多年来我们一直向企业、个人提供成功所必需之技能及思想，激励他们创新并做得更好。

O'Reilly 业务的核心是独特的专家及创新者网络，众多专家及创新者通过我们分享知识。我们的在线学习（Online Learning）平台提供独家的直播培训、互动学习、认证体验、图书及视频等，使客户更容易获取业务成功所需的专业知识。几十年来 O'Reilly 图书一直被视为学习开创未来之技术的权威资料。我们所做的一切是为了帮助各领域的专业人士学习最佳实践，发现并塑造科技行业未来的新趋势。

我们的客户渴望做出推动世界前进的创新之举，我们希望能助他们一臂之力。

业界评论

“O'Reilly Radar 博客有口皆碑。”

—— Wired

“O'Reilly 凭借一系列非凡想法（真希望当初我也想到了）建立了数百万美元的业务。”

—— Business 2.0

“O'Reilly Conference 是聚集关键思想领袖的绝对典范。”

—— CRN

“一本 O'Reilly 的书就代表一个有用、有前途、需要学习的主题。”

—— Irish Times

“Tim 是位特立独行的商人，他不光放眼于最长远、最广阔的领域，并且切实地按照 Yogi Berra 的建议去做了：‘如果你在路上遇到岔路口，那就走小路。’回顾过去，Tim 似乎每一次都选择了小路，而且有几次都是一闪即逝的机会，尽管大路也不错。”

—— Linux Journal

专家推荐

这本书是深入探索 Rust 语言的权威指南，也是 Rust 编程思维的启示录。其最大价值是深入浅出地介绍了 Rust 的所有关键特性，从基本语法到并发和异步编程，每一章都配备了实用的示例代码和细致的解析。愿这本书引领你走进 Rust 的世界，体验其独特的魅力！

——陈天，Tubi SVP

非常高兴看到《Rust 程序设计（第 2 版）》引进出版。这本书对 Rust 知识做了全面而细致的介绍，特别花大量篇幅介绍了日常开发中用得最多的字符串、集合、迭代器等基础知识——对 Rust 初学者来说，这无疑是非常重要的。预祝这本书的面世为 Rust 语言在国内的普及打开新局面。

——唐刚（@Mike Tang），Rust 语言中文社区联合创始人

多年前，我们就被 Rust 的无 GC 内存安全和零开销抽象所吸引。2019 年以来，随着 Rust 的成熟，我们开始逐渐用 Rust 重写项目，以 Kata Agent 为例，从 Go 换成 Rust 之后代码体积缩小到了之前的 1/20 以下，这对任何系统软件来说都是无法拒绝的。在我的团队里，优秀的内核和系统开发人员都会毫不拒绝从 C、Go 或其他语言转向 Rust，并边开发边学习。但是，Rust 被公认是一门上手难的语言，尤其是对于很多初学者，一本系统的好书才是最佳的入门阶梯。非常开心图灵公司引进《Rust 程序设计（第 2 版）》，相信这本书对于大家学习 Rust，乃至提高国内系统程序的安全性，都会有很大的帮助。

——王旭，Kata Containers 项目联合发起人、开放基础设施基金会董事、

蚂蚁集团容器基础设施团队负责人

这本书是不可或缺的 Rust 编程资源，适合各个层次的开发者。书中深入解析了 Rust 的核心概念，如所有权、类型系统、并发等，配以实例代码，使得理解更为直观。如果你渴望深入探索 Rust，这本书将是你的最佳伙伴。

——张汉东，资深 Rust 独立咨询师、Rust 中文社区布道者、《Rust 编程之道》作者

我一直在寻找一本先实践后理论，能够提供有深度且实践性强的 Rust 编程知识的教程。当阅读这本书时，我发现了自己一直在寻找的东西。

——张炎泼，分布式系统专家

译者序

我曾是一名“前端”，在那之前，我是一名“后端”，而在刚入行的时候，我是一名系统程序员。现在，我是一名“锈儿”（Rust 的英文是“铁锈”的意思）。

在系统编程领域，一场变革正在悄然到来，而这次的主题，叫作“安全”。

2017 年，英国劳合社（Lloyd's of London）在一份报告中称，一场全球范围的大规模网络攻击造成的经济损失平均达 530 亿美元，这与一场特大自然灾害 [ 比如 2012 年的美国超级飓风桑迪（Sandy）] 造成的损失相当。而前几年轰动全球的勒索病毒 WannaCry，在单次事件中造成的直接经济损失就高达 80 亿美元。

这些，都还没有包含企业形象、政府形象等方面的无形损失，以及给受害者造成的次生灾害。

是时候改变这一切了。

与其四处漏水之后再“亡羊补牢”，不如从一开始就让安全内建在软件中。这个理念早已是业界共识。然而，好用的工具太少了，特别是对系统程序员来说，而系统程序恰恰是被攻击的重灾区。

造成这种局面的原因很多：一是系统程序往往工作在底层，容易获得很高的权限，一旦被突破，无论上层如何封堵也作用有限；二是系统程序普遍使用汇编、C、C++ 等语言编写，这些语言本身不仅过于复杂，也过于灵活，导致很难开发出全面的安全辅助工具；三是系统程序员数量少、任务重，很难抽出时间仔细思考安全问题。

中国的科技产业要想扎下根、扎稳根，必然要涉足系统程序开发的领域。如今，这种需求比以往更加紧迫。

作为 Thoughtworks 的咨询师，我服务过很多企业。前些年，我们的大部分客户是做上层应用开发的，特别是在互联网和金融方面；这些年，越来越多的制造业企业开始找到我们。这固然有我们市场品牌推广的功劳，但从另一个角度看，也说明制造业企业正在步入“深水区”，开始有意识地把软件能力融入自身的技术内核。

对制造业企业来说，管理软件固然重要，但是真正的“老大难问题”是嵌入式软件。这是因为只有这些代码才会真正运行在目标场景中，一旦出现问题，可能导致上百万乃至上千万元的损失，甚至会以生命为代价。所有人都知道有问题，但没有人敢动，也没有人知道该怎么动。这，就是无奈的现实！

然而，没有“银弹”。即使本书中介绍的 Rust，也只是候选工具箱中的一个。诚然，它打开了一扇新的大门，开启了一种新的思路，但这还远远不够。安全是一项系统工程，走向“内建安全”的变革更是一个混沌领域：技术、市场、人力、供应链等问题搅在一起，牵一发而动全身。任何人都无法以一己之力改变它，哪怕是总工程师、总经理，甚至董事长。但是我们应该从现在开始就进行知识储备和安全科普，一点点积累共识，逐渐形成变革的合力。

相对而言，编码方面的问题也许才是最单纯的。毕竟，只要能编译成机器码，CPU 才不会管那么多。编码，有机会成为变革的突破口——安全漏洞减少 => 开发效率提升 => 市场竞争力提升 => 利润提升 => 进一步投资于安全，开启一个良性循环。

产业升级的关键是先进制造业的升级，而先进制造业升级的第一步就是形成差异化竞争力。随着智能设备的爆发和万物互联的持续推进，网络攻击必然进一步广泛化，安全也必将在每个消费者的心中成为产品的核心属性。那时候的你，将是引领者还是跟随者呢？

千里之行，始于足下。是时候好好规划你的未来了。

愿本书能有幸成为你的上马石！

与君共勉！

最后是不可或缺的致谢环节。

致谢

首先当然要感谢我可爱的女儿冬冬，在枯燥的译书过程中，是她不时把我拉回现实世界，让我能站起来活动活动，进而规避了很多健康风险。译书期间正值春节，少了很多陪伴她的时间，就拿本书作为迟到的新年礼物吧。

接着要感谢我的爱人春娜，是她在生活中给了我很多支持，让我能把精力投入对翻译质量的追求上。

感谢我的老友叶志敏，在一些我拿不准的翻译上，他给了我很多帮助，并深度参与了本书前期的审阅和修订工作。

感谢我的朋友罗超然（Manonloki），他是全栈工程师，某浏览器产品负责人，主要从事 Tauri+Angular 的桌面端应用及浏览器开发。他和他的团队深度参与了审阅过程，并提出了一些宝贵意见。

感谢我的新朋友马申彦，他是腾讯文档桌面端技术负责人，也是 Rust 在国内的早期用户之一。在内部审阅过程中，他提出了一些很有价值的意见，为提高本书的翻译质量做出了很大的贡献。

感谢我的东家 Thoughtworks 和同事们，这里的技术氛围是我这种高龄码农仍能不断学习新技术的依托和动力。

感谢我所在的 Angular 中文社区，是社区中这群始终追求技术卓越的小伙伴让我得以在心态上永葆青春。

感谢后期审读团队的各位老师，是你们的博学与严谨让我见识了什么才叫专业！

最后要感谢人民邮电出版社图灵公司的策划编辑刘美英、项目编辑张海艳和其他工作人员，是他们让我接触到这本好书，并非常专业地完成了翻译工作。

值此新春佳节之际，祝我的父母和岳父母，身体健康，吉祥如意！祝天下的老人得享天年！

雪狼

2023 年春节

前言

Rust 是一门用于系统编程的语言。

事实上，大多数程序员并不熟悉系统编程，尽管它是我们日常工作的基础。

假设你合上了笔记本计算机，操作系统检测到这个行为，随即暂停了所有正在运行的程序、关闭屏幕，并让计算机进入睡眠状态。稍后，当你又打开笔记本计算机时，屏幕和其他组件再次启动，每个程序都能从断点处恢复运行。这些我们习以为常的功能，离不开系统程序员编写的大量系统程序。

系统编程用于：

• 操作系统
• 各种设备驱动程序
• 文件系统
• 数据库
• 在成本极低或可靠性要求极高的设备上运行的代码
• 加密解密
• 媒体编解码器（用于读取和写入音频、视频和图像文件的软件）
• 媒体处理（例如，语音识别或照片编辑软件）
• 内存管理（例如，实现垃圾回收器）
• 文本渲染（将文本和字体转换为像素）
• 实现高级编程语言（如 JavaScript 和 Python）
• 网络编程
• 虚拟化和软件容器
• 科学仿真
• 游戏

简而言之，系统编程是 资源受限 条件下的编程。每字节、每个 CPU 周期，对于程序正常运行都尤为重要。

即便是支持一个最基本的应用程序，涉及的系统代码量也是惊人的。

本书并不会教你如何进行系统编程。虽然本书涵盖了内存管理的许多细节，但是如果你还没有亲自做过系统编程，那么这些细节乍一看可能会有点儿过于深奥。如果你是一名经验丰富的系统程序员，就会看出 Rust 的卓尔不群：这种新工具可以解决困扰整个行业数十年的、众所周知的重大问题。

读者对象

如果你已经是系统程序员并且正准备物色一款 C++ 的替代品，那么本书适合你。如果你是任何一种编程语言的资深开发人员，无论是 C#、Java、Python、JavaScript，还是其他语言，那么本书同样适合你。

不过，你不能仅仅学习 Rust 语言本身。要充分发挥该语言的价值，还需要接触一些系统编程知识。我们建议你在阅读本书的同时，使用 Rust 实现一些系统编程领域的业余项目，利用 Rust 的速度、并发和安全，构建出你以前从未构建过的东西。开头那个主题列表应该会给你一些启发。

写作初衷

最初学习 Rust 时，我们曾期待有这样一本书，这正是本书的写作初衷。我们的目标是直面 Rust 中一些重大而新颖的概念，清晰而深入地呈现它们，从而减少学习中的试错成本。

浏览本书

本书前两章简要介绍了 Rust 的背景知识，接着在第 3 章开始介绍基本数据类型。第 4 章和第 5 章讨论了“所有权”和“引用”这两个核心概念。建议你按顺序通读前 5 章。

第 6 章到第 10 章涵盖了 Rust 这门语言的基础知识：表达式（第 6 章）、错误处理（第 7 章）、crate 与模块（第 8 章）、结构体（第 9 章），以及枚举与模式（第 10 章）。这几章可以稍微读快一些，但不要跳过第 7 章。

第 11 章介绍了特型与泛型，这是最后两个你需要了解的重要概念。特型就像 Java 或 C# 中的接口。它们也是 Rust 用来将你的类型集成到语言本身的主要方式。第 12 章展示了如何用特型支持运算符重载，第 13 章介绍了更多的实用工具特型。

了解特型和泛型可以帮你解锁本书其余部分的知识。不容错过的两个强大工具——闭包和迭代器，会分别在第 14 章和第 15 章中进行介绍。剩下的几章你可以按任意顺序阅读，或根据需要深入阅读。它们涵盖了这门语言的其余部分：集合（第 16 章）、字符串与文本（第 17 章）、输入与输出（第 18 章）、并发（第 19 章）、异步编程（第 20 章）、宏（第 21 章）、不安全代码（第 22 章），以及调用来自其他语言的函数（第 23 章）。

排版约定

本书使用以下排版约定。

黑体

表示新术语或重点强调的内容。

等宽字体（ constant width）

表示程序片段，以及正文中出现的变量名、函数名、数据库、数据类型、环境变量、语句和关键字等。

加粗等宽字体（ constant width bold）

表示应该由用户输入的命令或其他文本。

等宽斜体（ constant width italic）

表示应该由用户输入的值或根据上下文确定的值替换的文本。

此图标表示一般性注释。

使用代码示例

补充材料（代码示例、练习等）可在 https://github.com/ProgrammingRust 下载。

本书旨在帮助你完成工作。一般来说，你可以在自己的程序或文档中使用本书提供的示例代码。除非需要复制大量代码，否则无须联系我们获得许可。比如，使用本书中的几个代码片段编写程序无须获得许可，销售或分发 O'Reilly 图书的示例光盘则需要获得许可；引用本书中的示例代码回答问题无须获得许可，将本书中的大量示例代码放到你的产品文档中则需要获得许可。

我们很希望但并不强制要求你在引用本书内容时加上引用说明。引用说明一般包括书名、作者、出版社和 ISBN。比如“ Programming Rust, Second Edition by Jim Blandy, Jason Orendorff, and Leonora F. S. Tindall (O'Reilly ). Copyright 2021 Jim Blandy, Leonora F. S. Tindall, and Jason Orendorff, 978-1-492-05259-3”。

如果你对示例代码的用法超出了上述的许可范围，欢迎你通过 permissions@oreilly.com 与我们联系。

O'Reilly 在线学习平台（O'Reilly Online Learning）

40 多年来，O'Reilly Media 致力于提供技术和商业培训、知识和卓越见解，来帮助众多公司取得成功。

我们拥有独特的由专家和创新者组成的庞大网络，他们通过图书、文章和我们的在线学习平台分享他们的知识和经验。O'Reilly 在线学习平台让你能够按需访问现场培训课程、深入的学习路径、交互式编程环境，以及 O'Reilly 和 200 多家其他出版商提供的大量文本资源和视频资源。有关的更多信息，请访问 https://www.oreilly.com。

联系我们

如有与本书有关的评价或问题，请联系出版社。

美国：

O'Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

中国：

北京市西城区西直门南大街 2 号成铭大厦 C 座 807 室（100035）

奥莱利技术咨询（北京）有限公司

O'Reilly 的每一本书都有专属网页，你可以在那儿找到本书的相关信息，包括勘误表、示例代码1以及其他信息。本书的网页是 https://oreil.ly/programming-rust-2e。

对于本书的评论和技术性问题，请发送电子邮件至 errata@oreilly.com.cn。

要了解更多 O'Reilly 图书、培训课程和新闻的信息，请访问以下网站： https://www.oreilly.com。

我们在 Facebook 的地址如下： http://facebook.com/oreilly。

请关注我们的 Twitter 动态： http://twitter.com/oreillymedia。

我们的 YouTube 视频地址如下： http://www.youtube.com/oreillymedia。

致谢

本书得以面世得益于我们的官方技术审稿人的关注，感谢 Brian Anderson、Matt Brubeck、J. David Eisenberg、Ryan Levick、Jack Moffitt、Carol Nichols 和 Erik Nordin。还要感谢本书各语种版本的翻译人员：Hidemoto Nakada（中田秀基）（日语）、李松峰（简体中文第 1 版）、汪志成（简体中文第 2 版），以及 Adam Bochenek 和 Krzysztof Sawka（波兰语）。

另外，许多非官方审稿人也阅读了早期的草稿并提供了宝贵的反馈。感谢 Eddy Bruel、Nick Fitzgerald、Graydon Hoare、Michael Kelly、Jeffrey Lim、Jakob Olesen、Gian-Carlo Pascutto、Larry Rabinowitz、Jaroslav Šnajdr、Joe Walker 和 Yoshua Wuyts 对本书给出的深思熟虑的评论。Jeff Walden 和 Nicolas Pierron 花大量时间几乎审阅了全书。与任何编程冒险一样，编程书总是因高质量的错误报告而日益兴盛。感谢你们。

Mozilla 非常支持吉姆和贾森在这个项目上的工作，尽管这不属于我们的官方职责范围，并且一定程度上会分散我们的注意力。非常感谢吉姆和贾森的经理 Dave Camp、Naveed Ihsanullah、Tom Tromey 和 Joe Walker 的支持。他们从长远的角度看待 Mozilla 的意义，我们希望这些成果能证明他们对我们的信任是对的。

还要感谢 O'Reilly 出版社帮助这个项目取得成果的每一个人，尤其是我们极富耐心的编辑 Jeff Bleiel 和 Brian MacDonald，以及我们的策划编辑 Zan McQuade。

最重要的是，衷心感谢我们的家人，感谢他们坚定不移的爱、热情和耐心。

电子书

扫描如下二维码，即可购买本书中文版电子书。

中文版审读致谢

作为 Rust 与系统编程领域的经典，本书翻译难度较大。在此，诚挚地感谢在第 2 版中文版出版过程中参与公开审读活动的 30 位开发者（含一线专家与爱好者）。

各位审读专家针对译文提出了大量宝贵的意见与建议，你们严谨的治学态度和对 Rust 语言的深刻理解让译者与编辑受益匪浅，也让本书的译文质量更上一层楼。在此以表格形式列出 30 位审读专家的姓名（按姓氏字母排序），各章及章名与为之贡献的专家对应。

审读划分章名审读专家第 1~3 章第 1 章 系统程序员也能享受美好陈骜、姜子龙、尚卓燃（PsiACE）、唐刚（@Mike Tang）第 2 章 Rust 导览第 3 章 基本数据类型第 4~6 章第 4 章 所有权与移动陈翔（@翔翔的学习频道）、刘燚、陶叶港（@scruel）、杨思杰第 5 章 引用第 6 章 表达式第 7~9 章第 7 章 错误处理寸志、胡屹、苏胤榕、张卫滨第 8 章 crate 与模块第 9 章 结构体第 10~12 章第 10 章 枚举与模式刘久武、张鑫明、阴钰（@yxonic）第 11 章 特型与泛型第 12 章 运算符重载第 13~15 章第 13 章 实用工具特型曹洪伟、柳佳龙、尹钢、张罗东（@zhangll）第 14 章 闭包第 15 章 迭代器第 16~18 章第 16 章 集合Kyle C、杜小豆、钱宇超（@stdrc）、杨光宇第 17 章 字符串与文本第 18 章 输入与输出第 19~20 章第 19 章 并发耿腾、刘祺、逄振洲、赵梓淇（BugenZ）第 20 章 异步编程第 21~23 章第 21 章 宏艾尼、大妈（ZoomQuiet）、刘鑫第 22 章 不安全代码第 23 章 外部函数

本书虽已出版，但内容品质的提升不会终止。译者、编辑、审读专家虽已尽力，但疏漏可能在所难免，如果大家在阅读过程中发现任何问题，欢迎将其提交到图灵社区本书的勘误处（ituring.com.cn/book/2846）。勘误经编辑确认之后会更正在重印书中。

第 1 章 系统程序员也能享受美好

在某些情况（例如 Rust 的目标环境）下，比竞争对手快 10 倍，哪怕只快两倍就能成为决胜的关键。速度决定了一个系统在市场上的命运，就像在硬件市场上一样。

——Graydon Hoare

现在所有的计算机都支持并行……并行编程 就是 编程。

——《结构化并行程序设计：高效计算模式》，Michael McCool 等

就连 TrueType 解析器的缺陷都会被攻击者用于监视。安全性对所有软件都很重要。

——Andy Wingo

我们用这 3 条引言作为本书的开篇是别有深意的。但还是先从一个“谜题”开始吧。下面的 C 程序是做什么的？

int main(int argc, char **argv) {
 unsigned long a[1];
 a[3] = 0x7ffff7b36cebUL;
 return 0;
}

今天早上，这个程序在 Jim 的笔记本计算机上打印出了下列内容：

undef: Error: .netrc file is readable by others.
undef: Remove password or make file unreadable by others.

然后它就崩溃了。如果你在自己的机器上尝试运行这个程序，则可能会出现不一样的结果。这是怎么回事呢？

这个程序存在缺陷。数组 a 只有一个元素长，所以根据 C 编程语言标准，使用 a[3] 是 未定义行为（undefined behavior）1：

当使用一个不可移植的或错误的程序结构或者数据时，如果本国际标准对其行为没有强制要求，那么此行为就是未定义的。

未定义行为的后果不仅仅是产生难以预料的结果，事实上，它甚至会允许程序做 任何事。在我们的例子中，将这个奇怪的数值存储在数组 a 的第四个元素中恰好会破坏 main 函数的调用栈，这样，当从 main 函数返回时，它不会正常退出程序，而是会跳转到 C 标准库中用以从用户主目录的文件中获取密码的代码。这可不妙。

C 和 C++ 给出了数百条规则来规避未定义行为，其中大多数是常识，比如不要访问不应该访问的内存、不要让算术运算溢出、不要除以 0，等等。但是编译器并不会强制执行这些规则——它甚至没有义务去“揭露”这些明显的违规行为。事实上，前面的程序在编译时就没有抛出错误或发出警告。作为程序员，你需要打起十二分的精神来避免这种未定义行为。

从既往经验来看，作为程序员，我们在这方面可没有什么好记录。在犹他大学学习期间，研究员 Peng Li 修改了 C 编译器和 C++ 编译器，让它们“翻译”过的程序能报告自己是否执行了某种形式的未定义行为。他发现几乎所有程序都执行过某种未定义行为，包括那些一直以坚持高标准而声名卓著的项目。幻想靠自己就能避开 C 和 C++ 中的未定义行为，就像幻想只要知道了象棋的规则就能赢得比赛一样。

偶尔出现的奇怪消息或崩溃可能仅仅是质量问题，但自从 1988 年莫里斯（Morris）蠕虫利用类似上述内存越界的技术变体破译用户口令，继而在早期互联网上大规模扩散以来，未定义行为一直是造成各种安全漏洞的主要原因。

因此 C 和 C++ 将程序员置于这样一种尴尬的境地：这些语言是系统编程的行业标准，但它们对程序员的要求实在太高了，这就注定系统会源源不断地出现崩溃和安全问题。要解开这个“谜题”，只会引出一个更大的问题：难道我们不能做得更好吗？

1.1 Rust 为你负重前行

本章开头的 3 条引言给出了我们的答案。第三条引言来自关于震网（Stuxnet）病毒的报道，这是一种计算机蠕虫病毒，2010 年人们发现它入侵了工业控制设备。它使用许多技术来控制受害者的计算机，其中就包括负责解析文字处理软件中内嵌 TrueType 字体的相关代码的未定义行为。可以肯定的是，这段代码的作者并没有料到它以这种方式被利用，这表明需要担心安全问题的不仅仅是操作系统和服务器，任何可能处理“来源不可信数据”的软件都会成为漏洞利用的目标。

Rust 语言给了我们一个简单的承诺：只要程序通过了编译器的检查，就不会存在未定义行为。悬空指针、双重释放和空指针解引用都能在编译期捕获。数组引用则会受到编译期检查和运行期检查的双重保护，因此不会存在缓冲区溢出：想想那个不幸的 C 语言程序，它的 Rust 版代码会安全地退出并给出一条错误消息。

另外，Rust 的目标是既 安全 又 易用。为了更好地保障程序的行为，Rust 对代码施加了比 C 和 C++ 更多的限制，而只有靠实践和经验，我们才能逐渐适应这种限制。但就整体而言，这门语言还是灵活且富有表现力的。用 Rust 编写的代码范围之宽、应用领域之广就是证明。

根据我们的经验，如果该语言能发现更多错误，那么我们就可以尝试一些更具雄心的项目。如果内存管理和指针有效性问题已得到妥善处理，那么修改大型复杂程序时的风险就会降低。如果代码里的 bug 不会破坏程序中的其他部分，那么调试也会简单得多。

当然，仍然有很多 Rust 无法检测到的 bug。但实际上，只要从可能出现的问题清单中排除了未定义行为，就会让编程更美好。

1.2 高效并行编程

众所周知，在 C 和 C++ 中恰当使用并发的难度极大。通常只有在确信单线程代码无法达到预期的性能时，开发人员才会转向并发。但正如本章第二条引言所指出的，并行性对现代机器来说太重要了，不应该等到迫不得已时才考虑它。

事实证明，Rust 用来确保内存安全的那些限制同样能确保 Rust 程序避免产生数据竞争（data race）。只要数据不可变，你就可以在线程之间自由地共享这些数据。会发生变化的数据则只能使用同步原语访问。所有传统的并发工具仍然可用：互斥锁、条件变量、通道、原子等。Rust 只负责检查你是否正确地使用了它们。

这就让 Rust 成了一门能充分发挥现代多核机器能力的优秀语言。Rust 的生态系统提供了一些超乎于常规并发原语的库，可帮助你在处理器池之间均匀分布复杂负载、使用无锁同步机制（如读取-复制-更新）等。

1.3 性能毫不妥协

最后，正如本章第一条引言所说的那样，Rust 同样怀揣着 Bjarne Stroustrup 在他的论文“Abstraction and the C++ Machine Model”（抽象和 C++ 机器模型）中为 C++ 阐明的雄心。

通常，C++ 的各种实现会遵循零开销原则：没用到的，就没有开销；要用到的，你也无法手写出更好的代码。

系统编程通常会涉及极限压榨机器性能。对电子游戏来说，整台机器应该极力为玩家创造最佳体验。对浏览器来说，浏览器的效率决定了内容作者可用能力的上限。在机器的固有限制下，必须将尽可能多的内存和处理器能力留给内容本身。同样的原则也适用于操作系统：内核应该尽可能把机器资源留给用户程序，而不是自己来消耗它们。

但是当我们说 Rust“快”的时候，到底意味着什么呢？毕竟人们可以用任何通用语言来写出慢速代码。更准确一点儿说，如果你准备让程序充分发挥底层机器的能力，那么 Rust 就会为你提供支持。这门语言设计了一些“高性能”的默认选项，并赋予你自主控制内存使用和处理器算力分配方式的能力。

1.4 协作无边无界

本章的标题中还隐藏了第四条引言：“系统程序员也能享受美好”。这是指 Rust 对代码共享和复用的支持。

作为 Rust 的包管理器和构建工具，Cargo 能让你轻松使用别人在 Rust 的公共包存储库 crates.io 网站上发布的各种库。只需将库的名称和所需的版本号添加到文件中，Cargo 就会负责下载这个库以及它所用到的任何其他库，并将所有内容链接在一起。你可以将 Cargo 视为 Rust 下的 NPM 或 RubyGems，其侧重于实现健全的版本管理和可重现的构建。一些广为流行的 Rust 库提供了包括开箱即用的序列化功能、HTTP 客户端和服务器功能以及现代图形 API 功能在内的一切。

再进一步说，Rust 这门语言本身也旨在支持协作：借助 Rust 的特型（trait）2和泛型，我们可以创建具有灵活接口的库，将其用在许多不同的上下文中。Rust 的标准库提供了一组最核心的基本类型，这些类型为一些常见的情况建立了共享规约，以方便不同的库彼此协作。

第 2 章旨在通过介绍几个小的 Rust 程序来具体展示本章所述的这几点优势。

第 2 章 Rust 导览(1)

第 2 章 Rust 导览

写这样一本书并不容易：Rust 这门语言如此卓尔不群，我们固然有能力在一开始就展示出其独特的、令人惊叹的特性，但更为重要的是它的各个部分之间能够良好协作，共同服务于我们在第 1 章中设定的目标——安全、高性能的系统编程。该语言的每个部分都与其他部分配合得天衣无缝。

因此，我们并不打算每次讲透一个语言特性，而是准备了一些小而完备的程序作为导览，每个程序都会在其上下文中介绍该语言的更多特性。

• 作为暖场，我们会设计一个简单的程序，它可以解析命令行参数并进行简单计算，而且带有单元测试。这会展示 Rust 的一些核心类型并引入 特型 的概念。
• 接下来，我们一起构建一个 Web 服务器。我们将使用第三方库来处理 HTTP 的细节，并介绍字符串处理、闭包和错误处理功能。
• 第三个程序会绘制一张美丽的分形图，将计算工作分派到多个线程以提高效率。这包括一个泛型函数的示例，以说明该如何处理像素缓冲区之类的问题，并展示 Rust 对并发的支持。
• 最后，我们会展示一个强大的命令行工具，它利用正则表达式来处理文件。这展示了 Rust 标准库的文件处理功能，以及最常用的第三方正则表达式库。

Rust 承诺会在对性能影响最小的情况下防止未定义行为，这在潜移默化中引导着每个部分的设计——从标准数据结构（如向量和字符串）到使用第三方库的方式。关于如何做好这些的细节会贯穿全书。但就目前而言，我们只想向你证明 Rust 是一门功能强大且易于使用的语言。

当然，你要先在计算机上安装 Rust。

2.1 rustup 与 Cargo

安装 Rust 的最佳方式是使用 rustup。请转到 rustup.rs 网站并按照那里的说明进行操作。

还可以到 Rust 网站获取针对 Linux、macOS 和 Windows 的预构建包。Rust 也已经包含在某些操作系统的发行版中。建议使用 rustup，因为它是专门管理 Rust 安装的工具，就像 Ruby 中的 RVM 或 Node 中的 NVM。例如，当 Rust 发布新版本时，你就可以通过键入 rustup update 来实现一键升级。

无论采用哪种方式，完成安装之后，你的命令行中都会有 3 条新命令：

$ cargo --version
cargo 1.49.0 (d00d64df9 2020-12-05)
$ rustc --version
rustc 1.49.0 (e1884a8e3 2020-12-29)
$ rustdoc --version
rustdoc 1.49.0 (e1884a8e3 2020-12-29)

在这里， $ 是命令提示符，在 Windows 上，则会是 C:\> 之类的文本。在刚才的记录中，我们运行了 3 条已安装的命令，并要求每条命令报告其版本号。下面来逐个看看每条命令。

• cargo 是 Rust 的编译管理器、包管理器和通用工具。可以用 Cargo 启动新项目、构建和运行程序，并管理代码所依赖的任何外部库。
• rustc 是 Rust 编译器。通常 Cargo 会替我们调用此编译器，但有时也需要直接运行它。
• rustdoc 是 Rust 文档工具。如果你在程序源代码中以适当形式的注释编写文档，那么 rustdoc 就可以从中构建出格式良好的 HTML。与 rustc 一样，通常 Cargo 会替我们运行 rustdoc。

为便于使用，Cargo 可以为我们创建一个新的 Rust 包，并适当准备一些标准化的元数据：

$ cargo new hello
 Created binary (application) `hello` package

该命令会创建一个名为 hello 的新包目录，用于构建命令行可执行文件。

查看包的顶层目录：

$ cd hello
$ ls -la
total 24
drwxrwxr-x. 4 jimb jimb 4096 Sep 22 21:09 .
drwx------. 62 jimb jimb 4096 Sep 22 21:09 ..
drwxrwxr-x. 6 jimb jimb 4096 Sep 22 21:09 .git
-rw-rw-r--. 1 jimb jimb 7 Sep 22 21:09 .gitignore
-rw-rw-r--. 1 jimb jimb 88 Sep 22 21:09 Cargo.toml
drwxrwxr-x. 2 jimb jimb 4096 Sep 22 21:09 src

我们看到 Cargo 已经创建了一个名为 Cargo.toml 的文件来保存此包的元数据。目前这个文件还没有多少内容：

[package]
name = "hello"
version = "0.1.0"
edition = "2021"

# 请到“The Cargo Book”查看更多的键及其定义

[dependencies]

如果程序依赖于其他库，那么可以把它们记录在这个文件中，Cargo 将为我们下载、构建和更新这些库。第 8 章会详细介绍 Cargo.toml 文件。

Cargo 已将我们的包设置为与版本控制系统 git 一起使用，并为此创建了一个元数据子目录 .git 和一个 .gitignore 文件。可以通过在命令行中将 --vcs none 传给 cargo new 来要求 Cargo 跳过此步骤。

src 子目录包含实际的 Rust 代码：

$ cd src
$ ls -l
total 4
-rw-rw-r--. 1 jimb jimb 45 Sep 22 21:09 main.rs

Cargo 似乎已经替我们写好一部分程序了。main.rs 文件包含以下文本：

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

在 Rust 中，你甚至不需要编写自己的“Hello, World!”程序。这是 Rust 新程序样板的职责，该程序样板包括两个文件，总共 13 行代码。

可以在包内的任意目录下调用 cargo run 命令来构建和运行程序：

$ cargo run
 Compiling hello v0.1.0 (/home/jimb/rust/hello)
 Finished dev [unoptimized + debuginfo] target(s) in 0.28s
 Running `/home/jimb/rust/hello/target/debug/hello`
Hello, world!

这里 Cargo 先调用 Rust 编译器 rustc，然后运行了它生成的可执行文件。Cargo 将可执行文件放在此包顶层的 target 子目录中：

$ ls -l ../target/debug
total 580
drwxrwxr-x. 2 jimb jimb 4096 Sep 22 21:37 build
drwxrwxr-x. 2 jimb jimb 4096 Sep 22 21:37 deps
drwxrwxr-x. 2 jimb jimb 4096 Sep 22 21:37 examples
-rwxrwxr-x. 1 jimb jimb 576632 Sep 22 21:37 hello
-rw-rw-r--. 1 jimb jimb 198 Sep 22 21:37 hello.d
drwxrwxr-x. 2 jimb jimb 68 Sep 22 21:37 incremental
$ ../target/debug/hello
Hello, world!

完工之后，Cargo 还可以帮我们清理生成的文件。

$ cargo clean
$ ../target/debug/hello
bash: ../target/debug/hello: No such file or directory

2.2 Rust 函数

Rust 在语法设计上刻意减少了原创性。如果你熟悉 C、C++、Java 或 JavaScript，那么就能通过 Rust 程序的一般性构造找到自己的快速学习之道。这是一个使用欧几里得算法计算两个整数的最大公约数的函数。可以将这些代码添加到 src/main.rs 的末尾：

fn gcd(mut n: u64, mut m: u64) -> u64 {
 assert!(n != 0 && m != 0);
 while m != 0 {
 if m < n {
 let t = m;
 m = n;
 n = t;
 }
 m = m % n;
 }
 n
}

fn（发音为 /fʌn/）关键字引入了一个函数。这里我们定义了一个名为 gcd 的函数，它有两个参数（ n 和 m），每个参数都是 u64 类型，即一个无符号的 64 位整数。 -> 标记后面紧跟着返回类型，表示此函数返回一个 u64 值。4 空格缩进是 Rust 的标准风格。

Rust 的“机器整数类型名”揭示了它们的大小和符号： i32 是一个带符号的 32 位整数， u8 是一个无符号的 8 位整数（“字节”值），以此类推。 isize 类型和 usize 类型保存着恰好等于“指针大小”的有符号整数和无符号整数，在 32 位平台上是 32 位长，在 64 位平台上则是 64 位长。Rust 还有 f32 和 f64 这两种浮点类型，它们分别是 IEEE 单精度浮点类型和 IEEE 双精度浮点类型，就像 C 和 C++ 中的 float 和 double。

默认情况下，一经初始化，变量的值就不能再改变了，但是在参数 n 和 m 之前放置 mut（发音为 /mjuːt/，是 mutable 的缩写）关键字将会准许我们在函数体中赋值给它们。实际上，大多数变量是不需要被赋值的，而对于那些确实需要被赋值的变量， mut 关键字相当于用一个醒目的提示来帮我们阅读代码。

函数的主体始于一次 assert! 宏调用，以验证这两个参数都不为 0。这里的 ! 字符标明此句为宏调用，而不是函数调用。就像 C 和 C++ 中的 assert 宏一样，Rust 的 assert! 会检查其参数是否为真，如果非真，则终止本程序并提供一条有帮助的信息，其中包括导致本次检查失败的源代码位置。这种突然的终止在 Rust 中称为 panic。与可以跳过断言的 C 和 C++ 不同，Rust 总是会检查这些断言，而不管程序是如何编译的。还有一个 debug_assert! 宏，在编译发布版程序时会跳过其断言以提高速度。

这个函数的核心是一个包含 if 语句和赋值语句的 while 循环。与 C 和 C++ 不同，Rust 不需要在条件表达式周围使用圆括号，但必须在受其控制的语句周围使用花括号。

let 语句会声明一个局部变量，比如本函数中的 t。只要 Rust 能从变量的使用方式中推断出 t 的类型，就不需要标注其类型。在此函数中，通过匹配 m 和 n，可以推断出唯一适用于 t 的类型是 u64。Rust 只会推断函数体内部的类型，因此必须像之前那样写出函数参数的类型和返回值的类型。如果想明确写出 t 的类型，那么可以这样写：

let t: u64 = m;

Rust 有 return 语句，但这里的 gcd 函数并不需要。如果一个函数体以 没有 尾随着分号的表达式结尾，那么这个表达式就是函数的返回值。事实上，花括号包起来的任意代码块都可以用作表达式。例如，下面是一个打印了一条信息然后以 x.cos() 作为其值的表达式：

{
 println!("evaluating cos x");
 x.cos()
}

在 Rust 中，当控制流“正常离开函数的末尾”时，通常会以上述形式创建函数的返回值， return 语句只会用在从函数中间显式地提前返回的场景中。

2.3 编写与运行单元测试

Rust 语言内置了对测试的简单支持。为了测试 gcd 函数，可以在 src/main.rs 的末尾添加下面这段代码：

#[test]
fn test_gcd() {
 assert_eq!(gcd(14, 15), 1);

 assert_eq!(gcd(2 * 3 * 5 * 11 * 17,
 3 * 7 * 11 * 13 * 19),
 3 * 11);
}

这里我们定义了一个名为 test_gcd 的函数，该函数会调用 gcd 并检查它是否返回了正确的值。此定义顶部的 #[test] 将 test_gcd 标记为“测试函数”，在正常编译时会跳过它，但如果用 cargo test 命令运行我们的程序，则会自动包含并调用它。可以让测试函数分散在源代码树中，紧挨着它们所测试的代码， cargo test 会自动收集并运行它们。

#[test] 标记是 属性（attribute）的示例之一。属性是一个开放式体系，可以用附加信息给函数和其他声明做标记，就像 C++ 和 C# 中的属性或 Java 中的注解（annotation）一样。属性可用于控制编译器警告和代码风格检查、有条件地包含代码（就像 C 和 C++ 中的 #ifdef 一样）、告诉 Rust 如何与其他语言编写的代码互动，等等。后面还会介绍更多的属性示例。

将 gcd 和 test_gcd 的定义添加到本章开头创建的 hello 包中，如果当前目录位于此包子树中的任意位置，可以用如下方式运行测试。

$ cargo test
 Compiling hello v0.1.0 (/home/jimb/rust/hello)
 Finished test [unoptimized + debuginfo] target(s) in 0.35s
 Running unittests (/home/jimb/rust/hello/target/debug/deps/hello-2375...)

running 1 test
test test_gcd ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

第 2 章 Rust 导览(2)

2.4 处理命令行参数

为了让我们的程序接收一系列数值作为命令行参数并打印出它们的最大公约数，可以将 src/main.rs 中的 main 函数替换为以下内容：

use std::str::FromStr;
use std::env;

fn main() {
 let mut numbers = Vec::new();

 for arg in env::args().skip(1) {
 numbers.push(u64::from_str(&arg)
 .expect("error parsing argument"));
 }

 if numbers.len() == 0 {
 eprintln!("Usage: gcd NUMBER ...");
 std::process::exit(1);
 }

 let mut d = numbers[0];
 for m in &numbers[1..] {
 d = gcd(d, *m);
 }

 println!("The greatest common divisor of {:?} is {}",
 numbers, d);
}

我们来逐段分析一下：

use std::str::FromStr;
use std::env;

第一个 use 声明将标准库中的 FromStr 特型 引入了当前作用域。特型是可以由类型实现的方法集合。任何实现了 FromStr 特型的类型都有一个 from_str 方法，该方法会尝试从字符串中解析这个类型的值。 u64 类型实现了 FromStr，所以我们将调用 u64::from_str 来解析程序中的命令行参数。尽管我们从未在程序的其他地方用到 FromStr 这个名字，但仍然要 use（使用）它，因为要想使用某个特型的方法，该特型就必须在作用域内。第 11 章会详细介绍特型。

第二个 use 声明引入了 std::env 模块，该模块提供了与执行环境交互时会用到的几个函数和类型，包括 args 函数，该函数能让我们访问程序中的命令行参数。

继续看程序中的 main 函数：

fn main() {

main 函数没有返回值，所以可以简单地省略 -> 和通常会跟在参数表后面的返回类型。

let mut numbers = Vec::new();

我们声明了一个可变的局部变量 numbers 并将其初始化为空向量。 Vec 是 Rust 的可增长向量类型，类似于 C++ 的 std::vector、Python 的列表或 JavaScript 的数组。虽然从设计上说向量可以动态扩充或收缩，但仍然要标记为 mut，这样 Rust 才能把新值压入末尾。

numbers 的类型是 Vec<u64>，这是一个可以容纳 u64 类型的值的向量，但和以前一样，不需要把类型写出来。Rust 会推断它，一部分原因是我们将 u64 类型的值压入了此向量，另一部分原因是我们将此向量的元素传给了 gcd，后者只接受 u64 类型的值。

for arg in env::args().skip(1) {

这里使用了 for 循环来处理命令行参数，依次将变量 arg 指向每个参数并运行循环体。

std::env 模块的 args 函数会返回一个 迭代器，此迭代器会按需生成1每个参数，并在完成时给出提示。各种迭代器在 Rust 中无处不在，标准库中也包括一些迭代器，这些迭代器可以生成向量的元素、文件每一行的内容、通信信道上接收到的信息，以及几乎任何有意义的循环变量。Rust 的迭代器非常高效，编译器通常能将它们翻译成与手写循环相同的代码。第 15 章会展示迭代器的工作原理并给出相关示例。

除了与 for 循环一起使用，迭代器还包含大量可以直接使用的方法。例如， args 返回的迭代器生成的第一个值永远是正在运行的程序的名称。如果想跳过它，就要调用迭代器的 skip 方法来生成一个新的迭代器，新迭代器会略去第一个值。

numbers.push(u64::from_str(&arg)
 .expect("error parsing argument"));

这里我们调用了 u64::from_str 来试图将命令行参数 arg 解析为一个无符号的 64 位整数。 u64::from_str 并不是 u64 值上的某个方法，而是与 u64 类型相关联的函数，类似于 C++ 或 Java 中的静态方法。 from_str 函数不会直接返回 u64，而是返回一个指明本次解析已成功或失败的 Result 值。 Result 值是以下两种变体之一：

• 形如 Ok(v) 的值，表示解析成功了， v 是所生成的值；
• 形如 Err(e) 的值，表示解析失败了， e 是解释原因的错误值。

执行任何可能会失败的操作（例如执行输入或输出或者以其他方式与操作系统交互）的函数都会返回一个 Result 类型，其 Ok 变体会携带成功结果（传输的字节数、打开的文件等），而其 Err 变体会携带错误码，以指明出了什么问题。与大多数现代语言不同，Rust 没有异常（exception）：所有错误都使用 Result 或 panic 进行处理，详见第 7 章。

我们用 Result 的 expect 方法来检查本次解析是否成功。如果结果是 Err(e)，那么 expect 就会打印出一条包含 e 的消息并直接退出程序。但如果结果是 Ok(v)，则 expect 会简单地返回 v 本身，最终我们会将其压入这个数值向量的末尾。

if numbers.len() == 0 {
 eprintln!("Usage: gcd NUMBER ...");
 std::process::exit(1);
}

空数组没有最大公约数，因此要检查此向量是否至少包含一个元素，如果没有则退出程序并报错。这里我们用 eprintln! 宏将错误消息写入标准错误流。

let mut d = numbers[0];
for m in &numbers[1..] {
 d = gcd(d, *m);
}

该循环使用 d 作为其运行期间的值，不断地把它更新为已处理的所有数值的最大公约数。和以前一样，必须将 d 标记为可变，以便在循环中给它赋值。

这个 for 循环有两个值得注意的地方。首先，我们写了 for m in &numbers[1..]，那么这里的 & 运算符有什么用呢？其次，我们写了 gcd(d, *m)，那么 *m 中的 * 又有什么用呢？这两个细节是紧密相关的。

迄今为止，我们的代码只是在对简单的值（例如适合固定大小内存块的整数）进行操作。但现在我们要迭代一个向量，它可以是任意大小，而且可能会非常大。Rust 在处理这类值时非常慎重：它想让程序员控制内存消耗，明确每个值的生存时间，同时还要确保当不再需要这些值时能及时释放内存。

所以在进行迭代时，需要告诉 Rust，该向量的 所有权 应该留在 numbers 上，我们只是为了本次循环而 借用 它的元素。 &numbers[1..] 中的 & 运算符会从向量中借用从第二个元素开始的 引用。 for 循环会遍历这些被引用的元素，让 m 依次借出每个元素。 *m 中的 * 运算符会将 m 解引用，产生它所引用的值，这就是要传给 gcd 的下一个 u64。最后，由于 numbers 拥有着此向量，因此当 main 末尾的 numbers 超出作用域时，Rust 会自动释放它。

Rust 的所有权规则和引用规则是 Rust 内存管理和并发安全的关键所在，第 4 章和第 5 章会对此进行详细讨论。只有熟悉了这些规则，才算熟练掌握了 Rust。但是对于这个介绍性的导览，你只需要知道 &x 借用了对 x 的引用，而 *r 访问的是 r 所引用的值就足够了。

继续我们的程序：

println!("The greatest common divisor of {:?} is {}",
 numbers, d);

遍历 numbers 的元素后，程序会将结果打印到标准输出流。 println! 宏会接受一个模板字符串，在模板字符串中以 {...} 形式标出的位置按要求格式化并插入剩余的参数，最后将结果写入标准输出流。

C 和 C++ 要求 main 在程序成功完成时返回 0，在出现问题时返回非零的退出状态，而 Rust 假设只要 main 完全返回，程序就算成功完成。只有显式地调用像 expect 或 std::process::exit 这样的函数，才能让程序以表示错误的状态码终止。

cargo run 命令可以将参数传给程序，因此可以试试下面这些命令行处理：

$ cargo run 42 56
 Compiling hello v0.1.0 (/home/jimb/rust/hello)
 Finished dev [unoptimized + debuginfo] target(s) in 0.22s
 Running `/home/jimb/rust/hello/target/debug/hello 42 56`
The greatest common divisor of [42, 56] is 14
$ cargo run 799459 28823 27347
 Finished dev [unoptimized + debuginfo] target(s) in 0.02s
 Running `/home/jimb/rust/hello/target/debug/hello 799459 28823 27347`
The greatest common divisor of [799459, 28823, 27347] is 41
$ cargo run 83
 Finished dev [unoptimized + debuginfo] target(s) in 0.02s
 Running `/home/jimb/rust/hello/target/debug/hello 83`
The greatest common divisor of [83] is 83
$ cargo run
 Finished dev [unoptimized + debuginfo] target(s) in 0.02s
 Running `/home/jimb/rust/hello/target/debug/hello`
Usage: gcd NUMBER ...

本节使用了 Rust 标准库中的一些特性。如果你好奇还有哪些别的特性，强烈建议看看 Rust 的在线文档。它具有实时搜索功能，能让你的探索更容易，其中还包括指向源代码的链接。安装 Rust 时， rustup 命令会自动在你的计算机上安装一份文档副本。你既可以在 Rust 网站上查看标准库文档，也可以使用以下命令打开浏览器查看。

$ rustup doc --std

2.5 搭建 Web 服务器

Rust 的优势之一是在 crates.io 网站上发布的大量免费的可用包。 cargo 命令可以让你的代码轻松使用 crates.io 上的包：它将下载包的正确版本，然后会构建包，并根据用户的要求更新包。一个 Rust 包，无论是库还是可执行文件，都叫作 crate（发音为 /kreɪt/，意思是“板条箱”）2。Cargo 和 crates.io 的名字都来源于这个术语。

为了展示这种工作过程，我们将使用 actix-web（Web 框架 crate）、 serde（序列化 crate）以及它们所依赖的各种其他 crate 来组装出一个简单的 Web 服务器。如图 2-1 所示，该网站会提示用户输入两个数值并计算它们的最大公约数。

图 2-1：计算最大公约数的网页

首先，让 Cargo 创建一个新包，命名为 actix-gcd：

$ cargo new actix-gcd
 Created binary (application) `actix-gcd` package
$ cd actix-gcd

然后，编辑新项目的 Cargo.toml 文件以列出所要使用的包，其内容应该是这样的：

[package]
name = "actix-gcd"
version = "0.1.0"
edition = "2021"

# 请到“The Cargo Book”查看更多的键及其定义

[dependencies]
actix-web = "1.0.8"
serde = { version = "1.0", features = ["derive"] }

Cargo.toml 中 [dependencies] 部分的每一行都给出了 crates.io 上的 crate 名称，以及我们想要使用的那个 crate 的版本。在本例中，我们需要 1.0.8 版的 actix-web crate 和 1.0 版的 serde crate。crates.io 上这些 crate 的版本很可能比此处展示的版本新，但通过指明在测试此代码时所使用的特定版本，可以确保即使发布了新版本的包，这些代码仍然能继续编译。3第 8 章会更详细地讨论版本管理。

crate 可能具备某些可选特性：一部分接口或实现不是所有用户都需要的，但将其包含在那个 crate 中仍然有意义。例如， serde crate 就提供了一种非常简洁的方式来处理来自 Web 表单的数据，但根据 serde 的文档，只有选择了此 crate 的 derive 特性时它才可用，因此我们在 Cargo.toml 文件中请求了它。

请注意，只需指定要直接用到的那些 crate 即可， cargo 会负责把它们自身依赖的所有其他 crate 带进来。

在第一次迭代中，我们将实现此 Web 服务器的一个简单版本：它只会给出让用户输入要计算的数值的页面。actix-gcd/src/main.rs 的内容如下所示：

use actix_web::;

fn main() {
 let server = HttpServer::new(|| {
 App::new()
 .route("/", web::get().to(get_index))
 });

 println!("Serving on http://localhost:3000...");
 server
 .bind("127.0.0.1:3000").expect("error binding server to address")
 .run().expect("error running server");
}

fn get_index() -> HttpResponse {
 HttpResponse::Ok()
 .content_type("text/html")
 .body(
 r#"
 <title>GCD Calculator</title>
 <form action="/gcd" method="post">
 <input type="text" name="n"/>
 <input type="text" name="m"/>
 <button type="submit">Compute GCD</button>
 </form>
 "#,
 )
}

use 声明可以让来自 actix-web crate 的定义用起来更容易些。当我们写下 use actix_web::{...} 时，花括号中列出的每个名称都可以直接用在代码中，而不必每次都拼出全名，比如 actix_web::HttpResponse 可以简写为 HttpResponse。（稍后还会提及 serde crate。）

main 函数很简单：它调用 HttpServer::new 创建了一个响应单个路径 "/" 请求的服务器，打印了一条信息以提醒我们该如何连接它，然后监听本机的 TCP 端口 3000。

我们传给 HttpServer::new 的参数是 Rust 闭包 表达式 || { App::new() ... }。闭包是一个可以像函数一样被调用的值。这个闭包没有参数，如果有参数，那么可以将参数名放在两条竖线 || 之间。 { ... } 是闭包的主体。当我们启动服务器时，Actix 会启动一个线程池来处理传入的请求。每个线程都会调用这个闭包来获取 App 值的新副本，以告诉此线程该如何路由这些请求并处理它们。

闭包会调用 App::new 来创建一个新的空白 App，然后调用它的 route 方法为路径 "/" 添加一个路由。提供给该路由的处理程序 web::get().to(get_index) 会通过调用函数 get_index 来处理 HTTP 的 GET 请求。 route 方法的返回值就是调用它的那个 App，不过其现在已经有了新的路由。由于闭包主体的末尾没有分号，因此此 App 就是闭包的返回值，可供 HttpServer 线程使用。

get_index 函数会构建一个 HttpResponse 值，该值表示对 HTTP GET / 请求的响应。 HttpResponse::Ok() 表示 HTTP 200 OK 状态，意味着请求成功。我们会调用它的 content_type 方法和 body 方法来填入该响应的细节，每次调用都会返回在前一次基础上修改过的 HttpResponse。最后会以 body 的返回值作为 get_index 的返回值。

由于响应文本包含很多双引号，因此我们使用 Rust 的“原始字符串”语法来编写它：首先是字母 r、0 到多个井号（ #）标记、一个双引号，然后是字符串本体，并以另一个双引号结尾，后跟相同数量的 # 标记。任何字符都可以出现在原始字符串中而不被转义，包括双引号。事实上，Rust 根本不认识像 \" 这样的转义序列。我们总是可以在引号周围使用比文本内容中出现过的 # 更多的 # 标记，以确保字符串能在期望的地方结束。

编写完 main.rs 后，可以使用 cargo run 命令来执行为运行它而要做的一切工作：获取所需的 crate、编译它们、构建我们自己的程序、将所有内容链接在一起，最后启动 main.rs。

$ cargo run
 Updating crates.io index
 Downloading crates ...
 Downloaded serde v1.0.100
 Downloaded actix-web v1.0.8
 Downloaded serde_derive v1.0.100
...
 Compiling serde_json v1.0.40
 Compiling actix-router v0.1.5
 Compiling actix-http v0.2.10
 Compiling awc v0.2.7
 Compiling actix-web v1.0.8
 Compiling gcd v0.1.0 (/home/jimb/rust/actix-gcd)
 Finished dev [unoptimized + debuginfo] target(s) in 1m 24s
 Running `/home/jimb/rust/actix-gcd/target/debug/actix-gcd`
Serving on http://localhost:3000...

此刻，在浏览器中访问给定的 URL 就会看到图 2-1 所示的页面。

但很遗憾，单击“Compute GCD”除了将浏览器导航到一个空白页面外，没有做任何事。为了继续解决这个问题，可以往 App 中添加另一个路由，以处理来自表单的 POST 请求。

现在终于用到我们曾在 Cargo.toml 文件中列出的 serde crate 了：它提供了一个便捷工具来协助处理表单数据。首先，将以下 use 指令添加到 src/main.rs 的顶部：

use serde::Deserialize;

Rust 程序员通常会将所有的 use 声明集中放在文件的顶部，但这并非绝对必要：Rust 允许这些声明以任意顺序出现，只要它们出现在适当的嵌套级别即可。

接下来，定义一个 Rust 结构体类型，用以表示期望从表单中获得的值：

#[derive(Deserialize)]
struct GcdParameters {
 n: u64,
 m: u64,
}

上述代码定义了一个名为 GcdParameters 的新类型，它有两个字段（ n 和 m），每个字段都是一个 u64，这是我们的 gcd 函数想要的参数类型。

此 struct 定义上面的注解是一个属性，就像之前用来标记测试函数的 #[test] 属性一样。在类型定义之上放置一个 #[derive(Deserialize)] 属性会要求 serde crate 在程序编译时检查此类型并自动生成代码，以便从 HTML 表单 POST 提交过来的格式化数据中解析出此类型的值。事实上，该属性足以让你从几乎任何种类的结构化数据（ JSON、 YAML、 TOML 或许多其他文本格式和二进制格式中的任何一种）中解析 GcdParameters 的值。 serde crate 还提供了一个 Serialize 属性，该属性会生成代码来执行相反的操作，获取 Rust 值并以结构化的格式序列化它们。

有了这个定义，就可以很容易地编写处理函数了：

fn post_gcd(form: web::Form<GcdParameters>) -> HttpResponse {
 if form.n == 0 || form.m == 0 {
 return HttpResponse::BadRequest()
 .content_type("text/html")
 .body("Computing the GCD with zero is boring.");
 }

 let response =
 format!("The greatest common divisor of the numbers {} and {} \
 is <b>{}</b>\n",
 form.n, form.m, gcd(form.n, form.m));
 HttpResponse::Ok()
 .content_type("text/html")
 .body(response)
}

对于用作 Actix 请求处理程序的函数，其参数必须全都是 Actix 知道该如何从 HTTP 请求中提取出来的类型。 post_gcd 函数接受一个参数 form，其类型为 web::Form<GcdParameters>。当且仅当 T 可以从 HTML 表单提交过来的数据反序列化时，Actix 才能知道该如何从 HTTP 请求中提取任意类型为 web::Form<T> 的值。由于我们已经将 #[derive(Deserialize)] 属性放在了 GcdParameters 类型定义上，Actix 可以从表单数据中反序列化它，因此请求处理程序可以要求以 web::Form<GcdParameters> 值作为参数。这些类型和函数之间的关系都是在编译期指定的。如果使用了 Actix 不知道该如何处理的参数类型来编写处理函数，那么 Rust 编译器会直接向你报错。

来看看 post_gcd 内部，如果任何一个参数为 0，则该函数会先行返回 HTTP 400 BAD REQUEST 错误，因为如果它们为 0，我们的 gcd 函数将崩溃。同时， post_gcd 会使用 format! 宏来为此请求构造出响应体。 format! 与 println! 很像，但它不会将文本写入标准输出，而是会将其作为字符串返回。一旦获得响应文本， post_gcd 就会将其包装在 HTTP 200 OK 响应中，设置其内容类型，并将它返回给请求者。

还必须将 post_gcd 注册为表单处理程序。为此，可以将 main 函数替换成以下这个版本：

fn main() {
 let server = HttpServer::new(|| {
 App::new()
 .route("/", web::get().to(get_index))
 .route("/gcd", web::post().to(post_gcd))
 });

 println!("Serving on http://localhost:3000...");
 server
 .bind("127.0.0.1:3000").expect("error binding server to address")
 .run().expect("error running server");
}

这里唯一的变化是添加了另一个 route 调用，确立 web::post().to(post_gcd) 作为路径 "/gcd" 的处理程序。

最后剩下的部分是我们之前编写的 gcd 函数，它位于 actix-gcd/src/main.rs 文件中。有了它，你就可以中断运行中的服务器，重新构建并启动程序了：

$ cargo run
 Compiling actix-gcd v0.1.0 (/home/jimb/rust/actix-gcd)
 Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
 Running `target/debug/actix-gcd`
Serving on http://localhost:3000...

这一次，访问 http://localhost:3000，输入一些数值，然后单击“Compute GCD”按钮，应该会看到一些实质性结果，如图 2-2 所示。

图 2-2：展示计算最大公约数结果的网页

2.6 并发

Rust 的一大优势是它对并发编程的支持。Rust 中用来确保内存安全的那些规则也同样可以让线程在共享内存的时候避免数据竞争。

• 如果使用互斥锁来协调对共享数据结构进行更改的多个线程，那么 Rust 会确保只有持有锁才能访问这些数据，并会在完工后自动释放锁。而在 C 和 C++ 中，互斥锁和它所保护的数据之间的联系只能体现在注释中。
• 如果想在多个线程之间共享只读数据，那么 Rust 能确保你不会意外修改数据。而在 C 和 C++ 中，虽然类型系统也可以帮你解决这个问题，但很容易出错。
• 如果将数据结构的所有权从一个线程转移给另一个线程，那么 Rust 能确保你真的放弃了对它的所有访问权限。而在 C 和 C++ 中，要由你来检查发送线程上的任何代码是否会再次接触数据。如果你弄错了，那么后果可能取决于处理器缓存中正在发生什么，以及你最近对内存进行过多少次写入。我们或多或少都在这方面吃过一点儿苦头。

本节将引导你写出第二个多线程程序。

你已经写完了第一个程序：用 Actix Web 框架实现的最大公约数服务器，它使用线程池来运行请求处理函数。如果服务器同时收到多个请求，那么它就会在多个线程中同时运行 get_index 函数和 post_gcd 函数。这可能有点儿令人震撼，因为我们在编写这些函数时甚至都没有考虑过并发。但 Rust 能确保这样做是安全的，无论你的服务器变得多么复杂：只要程序编译通过了，就一定不会出现数据竞争。所有 Rust 函数都是线程安全的。

本节的程序绘制了曼德博集（一组分形几何图形，包括著名的海龟图等），这是一种对复数反复运行某个简单函数而生成的分形图。人们通常把“绘制曼德博集”称为 易并行 算法，因为其线程之间的通信模式非常简单，第 19 章会介绍更复杂的模式，但这里的任务已足以演示一些基本要素了。

首先，创建一个新的 Rust 项目：

$ cargo new mandelbrot
 Created binary (application) `mandelbrot` package
$ cd mandelbrot

所有代码都将放在 mandelbrot/src/main.rs 中，我们将向 mandelbrot/Cargo.toml 添加一些依赖项。

在进入并发曼德博实现之前，先来讲一下接下来将要执行的计算。

2.6.1 什么是曼德博集

在阅读代码时，具体了解一下它要执行的任务是很有帮助的，所以，我们可以稍微了解一点儿纯数学。先从一个简单的案例开始，然后添加复杂的细节，直到抵达曼德博集最核心的计算领域。

下面是一个使用 Rust 特有语法实现的 loop 语句无限循环：

fn square_loop(mut x: f64) {
 loop {
 x = x * x;
 }
}

在现实世界中，Rust 能看出 x 从未用来做任何事，因此不会计算它的值。但目前，假设代码能按编写的方式运行。那么 x 的值会如何变化呢？对任何小于 1 的数值求平方会使它变得更小，因此它会趋近于 0；1 的平方会得到 1；对大于 1 的数值求平方会使它变大，因此它会趋近于无穷大；对一个负数求平方会先使其变为正数，之后它的变化情况和前面的情况类似，如图 2-3 所示。

图 2-3：重复对数值求平方的效果

因此，根据传给 square_loop 的值， x 的取值为 0 或 1、趋近 0 或趋近无穷大。

现在考虑一个略有不同的循环：

fn square_add_loop(c: f64) {
 let mut x = 0.;
 loop {
 x = x * x + c;
 }
}

这一次， x 从 0 开始，我们通过对它求平方后再加上 c 来调整它在每次迭代中的进度。这更难看出 x 的变化情况了，但通过一些实验会发现，如果 c 大于 0.25 或小于 -2.0，那么 x 最终会变得无限大，否则，它就会停留在 0 附近的某个地方。

下一个问题：如果不再使用 f64 值而是改用复数做同样的循环会怎样？crates.io 上的 num crate 已经提供了开箱即用的复数类型，因此要在程序的 Cargo.toml 文件的 [dependencies] 部分添加一行 num。这是迄今为止的整个文件（稍后会添加更多）：

[package]
name = "mandelbrot"
version = "0.1.0"
edition = "2021"

# 请到“The Cargo Book”查看更多的键及其定义

[dependencies]
num = "0.4"

现在可以编写此循环的倒数第二个版本了：

use num::Complex;

fn complex_square_add_loop(c: Complex<f64>) {
 let mut z = Complex { re: 0.0, im: 0.0 };
 loop {
 z = z * z + c;
 }
}

传统上会用 z 来代表复数，因此我们重命名了循环变量。表达式 Complex { re: 0.0, im: 0.0 } 是使用 num crate 的 Complex 类型编写复数 0 的方式。 Complex 是一种 Rust 结构体类型（或 struct），其定义如下：

struct Complex<T> {
 /// 复数的实部
 re: T,

 /// 复数的虚部
 im: T,
}

上述代码定义了一个名为 Complex 的结构体，该结构体有两个字段，即 re 和 im。 Complex 是一种 泛型 结构体：可以把在类型名称之后的 <T> 读作“对于任意类型 T”。例如， Complex<f64> 是一个复数，其 re 字段和 im 字段为 f64 值， Complex<f32> 则使用 32 位浮点数，等等。根据此定义，像 Complex { re: 0.24, im: 0.3 } 这样的表达式就会生成一个 Complex 值，其 re 字段已初始化为 0.24， im 字段已初始化为 0.3。

num crate 支持用 *、 + 和其他算术运算符来处理 Complex 值，因此该函数的其余部分仍然像之前的版本那样工作，只是它会将数值视作复平面上而不是实数轴上的点进行运算。第 12 章会讲解如何让 Rust 的运算符与自定义类型协同工作。

我们终于抵达了纯数学之旅的终点。曼德博集的定义是：令 z 不会“飞到”无穷远的复数 c 的集合。我们最初的简单平方循环是可以预测的：任何大于 1 或小于 -1 的数值都会“飞”出去。把 + c 放入每次迭代中会使变化情况更难预测：正如前面所说，大于 0.25 或小于 -2.0 的 c 值会导致 z“飞”出去。但是将此游戏推广到复数就会生成真正奇异而美丽的图案，这就是我们所要绘制的分形图。

由于复数 c 具有实部 c.re 和虚部 c.im，因此可以把它们视为笛卡儿平面上某个点的 x 坐标和 y 坐标，如果 c 在曼德博集中，就在其中用黑色着色，否则就用浅色。因此，对于图像中的每个像素，必须在复平面上的相应点位运行前面的循环，看看它是逃逸到无穷远还是永远绕着原点运行，并相应地将其着色。

无限循环需要一段时间才能完成，但是对缺乏耐心的人来说有两个小技巧。首先，如果不再永远运行循环而只是尝试一些有限次数的迭代，事实证明仍然可以获得该集合的一个不错的近似值。我们需要多少次迭代取决于想要绘制的边界的精度。其次，业已证明，一旦 z 离开了以原点为中心的半径为 2 的圆，它最终就一定会“飞到”无穷远的地方。所以下面是循环的最终版本，也是程序的核心：

use num::Complex;

/// 尝试测定`c`是否位于曼德博集中，使用最多`limit`次迭代来判定
///
/// 如果`c`不是集合成员之一，则返回`Some(i)`，其中的`i`是`c`离开以原点
/// 为中心的半径为2的圆时所需的迭代次数。如果`c`似乎是集合成员之一（确
/// 切而言是达到了迭代次数限制但仍然无法证明`c`不是成员），则返回`None`
fn escape_time(c: Complex<f64>, limit: usize) -> Option<usize> {
 let mut z = Complex { re: 0.0, im: 0.0 };
 for i in 0..limit {
 if z.norm_sqr() > 4.0 {
 return Some(i);
 }
 z = z * z + c;
 }

 None
}

此函数会接受两个参数： c 是我们要测试其是否属于曼德博集的复数， limit 是要尝试的迭代次数上限，一旦超出这个次数就放弃并认为 c 可能是成员。

该函数的返回值是一个 Option<usize>。Rust 的标准库中对 Option 类型的定义如下所示：

enum Option<T> {
 None,
 Some(T),
}

Option 是一种 枚举类型（通常称为“枚举”， enum），因为它的定义枚举了这个类型的值可能是几种变体之一：对于任意类型 T， Option<T> 类型的值要么是 Some(v)，其中 v 的类型为 T；要么是 None，表示没有可用的 T 值。与之前讨论的 Complex 类型一样， Option 是一种泛型类型：你可以使用 Option<T> 来表示任何一种类型 T 的可选值。

在这个例子中， escape_time 返回一个 Option<usize> 来指示 c 是否在曼德博集中——如果不在，是迭代了多少次才发现的。如果 c 不在集合中，那么 escape_time 就会返回 Some(i)，其中 i 是 z 在离开半径为 2 的圆之前的迭代次数。否则， c 显然在集合中，并且 escape_time 返回 None。

for i in 0..limit {

前面的示例展示了如何用 for 循环遍历命令行参数和向量元素，这个 for 循环则只是遍历从 0 开始到 limit（不含）的整数范围。

z.norm_sqr() 方法调用会返回 z 与原点距离的平方。要判断 z 是否已经离开半径为 2 的圆，不必计算平方根，只需将此距离的平方与 4.0 进行比较即可，这样速度更快。

你可能已经注意到我们使用了 /// 来标记函数定义上方的注释行， Complex 结构体成员上方的注释同样以 /// 开头。这些叫作 文档型注释， rustdoc 实用程序知道如何解析它们和它们所描述的代码，并生成在线文档。Rust 的标准库文档就是以这种形式编写的。第 8 章会详细讲解文档型注释。

该程序的其余部分所“关心”的是决定以何种分辨率绘制此集合中的哪个部分，并将此项工作分发给多个线程以加快计算速度。

2.6.2 解析并配对命令行参数

该程序会接受几个命令行参数来控制我们要写入的图像的分辨率以及要绘制曼德博集里哪部分的图像。由于这些命令行参数遵循着一种共同的格式，因此我们写了一个解析它们的函数：

use std::str::FromStr;

/// 把字符串`s`（形如`"400x600"`或`"1.0,0.5"`）解析成一个坐标对
///
/// 具体来说，`s`应该具有<left><sep><right>的格式，其中<sep>是由`separator`
/// 参数给出的字符，而<left>和<right>是可以被`T::from_str`解析的字符串。
/// `separator`必须是ASCII字符
///
/// 如果`s`具有正确的格式，就返回`Some<(x, y)>`；如果无法正确解析，就返回`None`
fn parse_pair<T: FromStr>(s: &str, separator: char) -> Option<(T, T)> {
 match s.find(separator) {
 None => None,
 Some(index) => {
 match (T::from_str(&s[..index]), T::from_str(&s[index + 1..])) {
 (Ok(l), Ok(r)) => Some((l, r)),
 _ => None
 }
 }
 }
}

#[test]
fn test_parse_pair() {
 assert_eq!(parse_pair::<i32>("", ','), None);
 assert_eq!(parse_pair::<i32>("10,", ','), None);
 assert_eq!(parse_pair::<i32>(",10", ','), None);
 assert_eq!(parse_pair::<i32>("10,20", ','), Some((10, 20)));
 assert_eq!(parse_pair::<i32>("10,20xy", ','), None);
 assert_eq!(parse_pair::<f64>("0.5x", 'x'), None);
 assert_eq!(parse_pair::<f64>("0.5x1.5", 'x'), Some((0.5, 1.5)));
}

parse_pair 的定义是一个 泛型函数：

fn parse_pair<T: FromStr>(s: &str, separator: char) -> Option<(T, T)> {

可以把 <T: FromStr> 子句读作“对于实现了 FromStr 特型的任意类型 T……”，这样就能高效地一次定义出整个函数家族： parse_pair::<i32> 是能解析一对 i32 值的函数、 parse_pair::<f64> 是能解析一对 f64 浮点值的函数，等等。这很像 C++ 中的函数模板。Rust 程序员会将 T 称作 parse_pair 的 类型参数。当使用泛型函数时，Rust 通常能帮我们推断出类型参数，并且我们不必像这里的测试代码那样把它们明确写出来。

我们的返回类型是 Option<(T, T)>：它或者是 None，或者是一个值 Some((v1, v2))，其中 (v1, v2) 是由两个 T 类型的值构成的元组。 parse_pair 函数没有使用显式 return 语句，因此它的返回值是其函数体中最后一个（也是唯一的一个）表达式的值：

match s.find(separator) {
 None => None,
 Some(index) => {
 ...
 }
}

String 类型的 find 方法会在字符串中搜索与 separator 相匹配的字符。如果 find 返回 None，那么就意味着字符串中没有出现分隔符，这样整个 match 表达式的计算结果就为 None，表明解析失败。否则， index 值就是此分隔符在字符串中的位置。

match (T::from_str(&s[..index]), T::from_str(&s[index + 1..])) {
 (Ok(l), Ok(r)) => Some((l, r)),
 _ => None
}

这里初步展现了 match（匹配）表达式的强大之处。 match 的参数是如下元组表达式：

(T::from_str(&s[..index]), T::from_str(&s[index + 1..]))

表达式 &s[..index] 和 &s[index + 1..] 都是字符串的切片，分别位于分隔符之前和之后。类型参数 T 的关联函数 from_str 会获取其中的每一个元素并尝试将它们解析为类型 T 的值，从而生成结果元组。下面是我们要匹配的目标：

(Ok(l), Ok(r)) => Some((l, r)),

仅当此元组的两个元素都是 Result 类型的 Ok 变体时，该模式才能匹配上，这表明两个解析都成功了。如果是这样，那么 Some((l, r)) 就是匹配表达式的值，也就是函数的返回值。

_ => None

通配符模式 _ 会匹配任意内容并忽略其值。如果运行到此处，则表明 parse_pair 已然失败，因此其值为 None，并继而作为本函数的返回值。

现在有了 parse_pair，就很容易编写一个函数来解析一对浮点坐标并将它们作为 Complex<f64> 值返回：

/// 把一对用逗号分隔的浮点数解析为复数
fn parse_complex(s: &str) -> Option<Complex<f64>> {
 match parse_pair(s, ',') {
 Some((re, im)) => Some(Complex { re, im }),
 None => None
 }
}

#[test]
fn test_parse_complex() {
 assert_eq!(parse_complex("1.25,-0.0625"),
 Some(Complex { re: 1.25, im: -0.0625 }));
 assert_eq!(parse_complex(",-0.0625"), None);
}

parse_complex 函数调用了 parse_pair，如果坐标解析成功则构建一个 Complex 值，如果失败则传回给它的调用者。

如果你很细心，可能会注意到我们用了简写形式来构建 Complex 值。用同名变量来初始化结构体中的字段是很常见的写法，所以 Rust 不会强迫你写成 Complex { re: re, im: im }，而会让你简写成 Complex { re, im }。这是从 JavaScript 和 Haskell 中的类似写法借鉴来的。

2.6.3 从像素到复数的映射

我们的程序需要在两个彼此相关的坐标空间中运行：输出图像中的每个像素对应于复平面上的一个点。这两个空间之间的关系取决于要绘制曼德博集的哪一部分以及所请求图像的分辨率，这些都要通过命令行参数指定。以下函数会将 图像空间 转换为 复数空间：

/// 给定输出图像中像素的行和列，返回复平面中对应的坐标
///
/// `bounds`是一个`pair`，给出了图像的像素宽度和像素高度。`pixel`是表示该
/// 图像中特定像素的(column, row)二元组。`upper_left`参数和`lower_right`
/// 参数是在复平面中表示指定图像覆盖范围的点
 fn pixel_to_point(bounds: (usize, usize),
 pixel: (usize, usize),
 upper_left: Complex<f64>,
 lower_right: Complex<f64>)
 -> Complex<f64>
{
 let (width, height) = (lower_right.re - upper_left.re,
 upper_left.im - lower_right.im);
 Complex {
 re: upper_left.re + pixel.0 as f64 * width / bounds.0 as f64,
 im: upper_left.im - pixel.1 as f64 * height / bounds.1 as f64
 // 为什么这里要用减法？这是因为在屏幕坐标系中pixel.1是
 // 向下递增的，但复数的虚部是向上递增的
 }
}

#[test]
fn test_pixel_to_point() {
 assert_eq!(pixel_to_point((100, 200), (25, 175),
 Complex { re: -1.0, im: 1.0 },
 Complex { re: 1.0, im: -1.0 }),
 Complex { re: -0.5, im: -0.75 });
}

图 2-4 说明了 pixel_to_point 所执行的计算规则。

图 2-4：复平面与图像像素的对应关系

pixel_to_point 的代码只是简单的计算，就不详细解释了。但是，有几点需要指出一下。下列形式的表达式引用的是元组中的元素：

pixel.0

这里引用的是 pixel 元组的第一个元素。

pixel.0 as f64

这是 Rust 的类型转换语法：这会将 pixel.0 转换为 f64 值。与 C 和 C++ 不同，Rust 通常会拒绝在数值类型之间进行隐式转换，因此你必须写出所需的转换。这可能有些烦琐，但明确说明发生了哪些转换以及发生于何时是非常有帮助的。隐式整数转换看似“人畜无害”，但从历史上看，它们一直是现实世界 C 和 C++ 代码中缺陷和安全漏洞的常见来源。

2.6.4 绘制曼德博集

要绘制出曼德博集，只需对复平面上的每个点调用 escape_time，并根据其结果为图像中的像素着色：

/// 将曼德博集对应的矩形渲染到像素缓冲区中
///
/// `bounds`参数会给出缓冲区`pixels`的宽度和高度，此缓冲区的每字节都
/// 包含一个灰度像素。`upper_left`参数和 `lower_right`参数分别指定了
/// 复平面中对应于像素缓冲区左上角和右下角的点
fn render(pixels: &mut [u8],
 bounds: (usize, usize),
 upper_left: Complex<f64>,
 lower_right: Complex<f64>)
{
 assert!(pixels.len() == bounds.0 * bounds.1);

 for row in 0..bounds.1 {
 for column in 0..bounds.0 {
 let point = pixel_to_point(bounds, (column, row),
 upper_left, lower_right);
 pixels[row * bounds.0 + column] =
 match escape_time(point, 255) {
 None => 0,
 Some(count) => 255 - count as u8
 };
 }
 }
}

此刻，这一切看起来都很熟悉。

pixels[row * bounds.0 + column] =
 match escape_time(point, 255) {
 None => 0,
 Some(count) => 255 - count as u8
 };

如果 escape_time 认为该 point 属于本集合， render 就会将相应像素的颜色渲染为黑色 ( 0)。否则， render 会将需要更长时间才能逃离圆圈的数值渲染为较深的颜色。

2.6.5 写入图像文件

image crate 提供了读取和写入各种图像格式的函数，以及一些基本的图像处理函数。特别是，此 crate 包含一个 PNG 图像文件格式的编码器，该程序使用这个编码器来保存计算的最终结果。为了使用 image，请将下面这行代码添加到 Cargo.toml 的 [dependencies] 部分：

image = "0.13.0"

然后可以这样写：

use image::ColorType;
use image::png::PNGEncoder;
use std::fs::File;

/// 把`pixels`缓冲区（其尺寸由`bounds`给出）写入名为`filename`的文件中
fn write_image(filename: &str, pixels: &[u8], bounds: (usize, usize))
 -> Result<(), std::io::Error>
{
 let output = File::create(filename)?;

 let encoder = PNGEncoder::new(output);
 encoder.encode(pixels,
 bounds.0 as u32, bounds.1 as u32,
 ColorType::Gray(8))?;

 Ok(())
}

这个函数的操作一目了然：它打开一个文件并尝试将图像写入其中。我们给编码器传入来自 pixels 的实际像素数据、来自 bounds 的宽度和高度，然后是最后一个参数，以说明如何解释 pixels 中的字节：值 ColorType::Gray(8) 表示每字节都是一个 8 位的灰度值。

这些也同样一目了然。该函数值得一看的地方在于当出现问题时它是如何处理的。一旦遇到错误，就要将错误报告给调用者。正如之前提过的，Rust 中的容错函数应该返回一个 Result 值，成功时为 Ok(s)（其中 s 是成功值），失败时为 Err(e)（其中 e 是错误代码）。那么 write_image 的成功类型和错误类型是什么呢？

当一切顺利时， write_image 函数只是把所有值得一看的东西都写到了文件中，没有任何有用的返回值。所以它的成功类型就是 单元（unit）类型 ()，而如此命名是因为这个类型只有一个值 ()。单元类型类似于 C 和 C++ 中的 void。

如果发生错误，那么可能是因为 File::create 无法创建文件或 encoder.encode 无法将图像写入其中，此 I/O 操作就会返回错误代码。 File::create 的返回类型是 Result<std::fs::File, std::io::Error>，而 encoder.encode 的返回类型是 Result<(), std::io::Error>，所以两者共享着相同的错误类型，即 std::io::Error。 write_image 函数也应该这么做。在任何情况下，失败都应导致立即返回，并传出用以描述错误原因的 std::io::Error 值。

所以，为了正确处理 File::create 的结果，需要 match 它的返回值，如下所示：

let output = match File::create(filename) {
 Ok(f) => f,
 Err(e) => {
 return Err(e);
 }
};

成功时，就将 output 赋值为 Ok 值中携带的 File。失败时，就将错误透传给调用者。

这种 match 语句在 Rust 中是一种非常常见的模式，所以该语言提供了 ? 运算符作为它的简写形式。因此，与其每次在尝试可能失败的事情时都明确地写出这个逻辑，不如使用以下等效且更易读的语句：

let output = File::create(filename)?;

如果 File::create 失败，那么 ? 运算符就会从 write_image 返回，并传出此错误。否则， output 就会持有已成功打开的 File。

新手常犯的一个错误就是试图在 main 函数中使用 ?。但是，由于 main 本身不返回值，因此这样做行不通。应该使用 match 语句，或者像 unwrap 和 expect 这样的简写方法。还可以选择简单地把 main 改成返回一个 Result，稍后会介绍这种方式。

2.6.6 并发版曼德博程序

万事俱备，可以展示一下 main 函数了，我们可以在其中利用并发来完成任务。为简单起见，先来看一个非并发版本：

use std::env;

fn main() {
 let args: Vec<String> = env::args().collect();

 if args.len() != 5 {
 eprintln!("Usage: {} FILE PIXELS UPPERLEFT LOWERRIGHT",
 args[0]);
 eprintln!("Example: {} mandel.png 1000x750 -1.20,0.35 -1,0.20",
 args[0]);
 std::process::exit(1);
 }

 let bounds = parse_pair(&args[2], 'x')
 .expect("error parsing image dimensions");
 let upper_left = parse_complex(&args[3])
 .expect("error parsing upper left corner point");
 let lower_right = parse_complex(&args[4])
 .expect("error parsing lower right corner point");

 let mut pixels = vec![0; bounds.0 * bounds.1];

 render(&mut pixels, bounds, upper_left, lower_right);

 write_image(&args[1], &pixels, bounds)
 .expect("error writing PNG file");
}

将命令行参数收集到一个 String 向量中后，我们会解析每个参数，然后开始计算。

let mut pixels = vec![0; bounds.0 * bounds.1];

宏调用 vec![v; n] 创建了一个 n 元素长的向量，其元素会被初始化为 v，因此前面的代码创建了一个长度为 bounds.0 * bounds.1 的全零向量，其中 bounds 是从命令行解析得来的图像分辨率。我们将使用此向量作为单字节灰度像素值的矩形数组，如图 2-5 所示。

图 2-5：使用向量作为矩形像素阵列

下一行值得关注的代码是：

render(&mut pixels, bounds, upper_left, lower_right);

这会调用 render 函数来实际计算图像。表达式 &mut pixels 借用了一个对像素缓冲区的可变引用，以允许 render 用计算出来的灰度值填充它，不过 pixels 仍然是此向量的拥有者。其余的参数传入了图像的尺寸和要绘制的复平面矩形。

write_image(&args[1], &pixels, bounds)
 .expect("error writing PNG file");

最后，将这个像素缓冲区作为 PNG 文件写入磁盘。在这个例子中，我们向缓冲区传入了一个共享（不可变）引用，因为 write_image 不需要修改缓冲区的内容。

此时，可以在发布模式下构建和运行程序，它启用了许多强力的编译器优化，几秒后会在文件 mandel.png 中写入一个漂亮的图像：

$ cargo build --release
 Updating crates.io index
 Compiling autocfg v1.0.1
 ...
 Compiling image v0.13.0
 Compiling mandelbrot v0.1.0 ($RUSTBOOK/mandelbrot)
 Finished release [optimized] target(s) in 25.36s
$ time target/release/mandelbrot mandel.png 4000x3000 -1.20,0.35 -1,0.20
real 0m4.678s
user 0m4.661s
sys 0m0.008s

此命令会创建一个名为 mandel.png 的文件，你可以使用系统的图像查看器或在 Web 浏览器中查看该文件。如果一切顺利，它应该如图 2-6 所示。

图 2-6：并行曼德博程序的结果

在之前的记录中，我们使用过 Unix 的 time 程序来分析程序的运行时间——对图像的每个像素运行曼德博计算总共需要大约 5 秒。但是几乎所有的现代机器都有多个处理器核心，而这个程序只使用了一个。如果可以将此工作分派给机器提供的所有计算资源，则应该能更快地画完图像。

为此，可以将图像分成多个部分（每个处理器一个），并让每个处理器为分派给它的像素着色。为简单起见，可以将其分成一些水平条带，如图 2-7 所示。当所有处理器都完成后，可以将像素写入磁盘中。

图 2-7：将像素缓冲区划分为一些条带以进行并行渲染

crossbeam crate 提供了许多有价值的并发设施，包括这里正需要的一个 作用域线程 设施。要使用此设施，必须将下面这行代码添加到 Cargo.toml 文件中：

crossbeam = "0.8"

然后要找出调用 render 的代码行并将其替换为以下内容：

let threads = 8;
let rows_per_band = bounds.1 / threads + 1;

{
 let bands: Vec<&mut [u8]> =
 pixels.chunks_mut(rows_per_band * bounds.0).collect();
 crossbeam::scope(|spawner| {
 for (i, band) in bands.into_iter().enumerate() {
 let top = rows_per_band * i;
 let height = band.len() / bounds.0;
 let band_bounds = (bounds.0, height);
 let band_upper_left =
 pixel_to_point(bounds, (0, top), upper_left, lower_right);
 let band_lower_right =
 pixel_to_point(bounds, (bounds.0, top + height),
 upper_left, lower_right);

 spawner.spawn(move |_| {
 render(band, band_bounds, band_upper_left, band_lower_right);
 });
 }
 }).unwrap();
}

仍以刚才的方式分步进行讲解：

let threads = 8;
let rows_per_band = bounds.1 / threads + 1;

这里我们决定使用 8 个线程。4然后会计算每个条带应该有多少行像素。我们向上舍入行数以确保条带覆盖整个图像，即使其高度并不是 threads 的整数倍。

let bands: Vec<&mut [u8]> =
 pixels.chunks_mut(rows_per_band * bounds.0).collect();

这里我们将像素缓冲区划分为几个条带。缓冲区的 chunks_mut 方法会返回一个迭代器，该迭代器会生成此缓冲区的可变且不重叠的切片，每个切片都包含 rows_per_band * bounds.0 个像素，换句话说， rows_per_band 包含整行的像素。 chunks_mut 生成的最后一个切片包含的行数可能少一些，但每一行都包含同样数量的像素。最后，此迭代器的 collect 方法会构建一个向量来保存这些可变且不重叠的切片。

现在可以使用 crossbeam 库了：

crossbeam::scope(|spawner| {
 ...
}).unwrap();

参数 |spawner| { ... } 是 Rust 闭包，它需要一个参数 spawner。请注意，与使用 fn 声明的函数不同，无须声明闭包参数的类型，Rust 将推断它们及其返回类型。在这里， crossbeam::scope 调用了此闭包，并将一个值作为 spawner 参数传给闭包，以便闭包使用 spawner 来创建新线程。 crossbeam::scope 函数会等待所有线程执行完毕后返回。这种机制能让 Rust 确保这些线程不会在 pixels 超出作用域后再访问分配给自己的那部分，并能让我们确保当 crossbeam::scope 返回时，图像的计算已然完成。如果一切顺利，那么 crossbeam::scope 就会返回 Ok(())，但如果我们启动的任何线程发生了 panic，则它会返回一个 Err。我们会对该 Result 调用 unwrap，这样一来，在那种情况下我们也会发生 panic，并且用户会收到报告。

for (i, band) in bands.into_iter().enumerate() {

在这里，我们遍历了像素缓冲区的各个条带。 into_iter() 迭代器会为循环体的每次迭代赋予独占一个条带的所有权，确保一次只有一个线程可以写入它（第 5 章会详细解释 into_iter() 迭代器的工作原理）。然后，枚举适配器生成了一些元组，将向量中的元素与其索引配对。

let top = rows_per_band * i;
let height = band.len() / bounds.0;
let band_bounds = (bounds.0, height);
let band_upper_left =
 pixel_to_point(bounds, (0, top), upper_left, lower_right);

let band_lower_right =
 pixel_to_point(bounds, (bounds.0, top + height),
 upper_left, lower_right);

给定索引和条带的实际大小（回想一下，最后一个条带可能比其他条带矮），可以生成 render 需要的一个边界框，但它只会引用缓冲区的这个条带，而不是整个图像。同样，我们会重新调整渲染器的 pixel_to_point 函数的用途，以找出条带的左上角和右下角落在复平面上的位置。

spawner.spawn(move |_| {
 render(band, band_bounds, band_upper_left, band_lower_right);
});

最后，创建一个线程，运行 move |_| { ... } 闭包。前面的 move 关键字表示这个闭包会接手它所用变量的所有权，特别是，只有此闭包才能使用可变切片 band。参数列表 |_| 意味着闭包会接受一个参数，但不使用它（另一个用以启动嵌套线程的启动器）。

如前所述， crossbeam::scope 调用会确保所有线程在它返回之前都已完成，这意味着将图像保存到文件中是安全的，这就是我们下一步要做的。

2.6.7 运行曼德博绘图器

我们在这个程序中使用了几个外部 crate： num 用于复数运算， image 用于写入 PNG 文件， crossbeam 用于提供“作用域线程创建”原语。下面是包含所有这些依赖项的最终 Cargo.toml 文件：

[package]
name = "mandelbrot"
version = "0.1.0"
edition = "2021"

[dependencies]
num = "0.4"
image = "0.13"
crossbeam = "0.8"

接下来就可以构建并运行程序了：

$ cargo build --release
 Updating crates.io index
 Compiling crossbeam-queue v0.3.2
 Compiling crossbeam v0.8.1
 Compiling mandelbrot v0.1.0 ($RUSTBOOK/mandelbrot)
 Finished release [optimized] target(s) in #.## secs
$ time target/release/mandelbrot mandel.png 4000x3000 -1.20,0.35 -1,0.20
real 0m1.436s
user 0m4.922s
sys 0m0.011s

这里我们再次使用 time 来查看程序运行所需的时间，请注意，尽管我们仍然花费了将近 5 秒的处理器时间，但实际运行时间仅为 1.5 秒左右。你可以通过注释掉执行此操作的代码并再次进行测量来验证这部分时间是否花在了写入图像文件上。在测试此代码的笔记本计算机上，并发版本将曼德博计算时间缩短了近 3/4。第 19 章会展示如何对此做实质性改进。

和以前一样，该程序会创建一个名为 mandel.png 的文件。有了这个更快的版本，你就可以根据自己的喜好更改命令行参数，更轻松地探索曼德博集了。

2.6.8 大“安”无形

这个并行程序与用任何其他语言写出来的程序并没有本质区别：我们将像素缓冲区的片段分给不同的处理器，由每个处理器单独处理，并在它们都完工时展示结果。那么 Rust 的并发支持有什么独到之处呢？

这里并没有展示那些被编译器一票否决的 Rust 程序。本章中展示的代码能正确地在线程之间对缓冲区进行分区，但是这些代码的许多小型变体将无法正确进行分区（因此会导致数据竞争），不过这些变体里没有一个能逃过 Rust 编译器的静态检查。C 编译器或 C++ 编译器将乐于帮助你探索具有微妙数据竞争的广阔程序空间，而 Rust 会预先告诉你什么时候可能出错。

第 4 章和第 5 章会讲解 Rust 的内存安全规则。第 19 章会讲解这些规则如何确保适当的安全并发环境。

2.7 文件系统与命令行工具

Rust 在命令行工具领域构筑了重要的基本应用场景。作为一种现代、安全、快速的系统编程语言，它为程序员提供了一个工具箱，他们可以用这个工具箱组装出灵活的命令行界面，从而复现或扩展现有工具的功能。例如， bat 命令5就提供了一个支持语法高亮的替代方案 cat，并内置了对分页工具的支持，而 hyperfine 可以自动对任何通过命令或管道运行的程序执行基准测试。

虽然如此复杂的内容已经超出了本书的范畴，但 Rust 可以让你轻松步入符合工效学的命令行领域。本节将向你展示如何构建自己的搜索与替换工具，并内置丰富多彩的输出和友好的错误消息。

首先，创建一个新的 Rust 项目：

$ cargo new quickreplace
 Created binary (application) `quickreplace` package
$ cd quickreplace

我们的程序要用到另外两个 crate：用于在终端中创建彩色输出的 text-colorizer 以及执行实际搜索和替换的 regex。和以前一样，将这些 crate 放在 Cargo.toml 中，告诉 cargo 我们需要它们：

[package]
name = "quickreplace"
version = "0.1.0"
edition = "2021"

# 请到“The Cargo Book”查看更多的键及其定义

[dependencies]
text-colorizer = "1"
regex = "1"

凡是达到 1.0 版的 Rust crate 都会遵循“语义化版本控制”规则：在主版本号 1 发生变化之前，所有更新都应当在兼容前序版本的基础上扩展。因此，如果针对某个 crate 的 1.2 版测试过我们的程序，那它应该仍然适用于 1.3、1.4 等版本，但 2.0 版可能会引入不兼容的变更。如果在 Cargo.toml 文件中只是请求版本 "1" 的 crate，那么 Cargo 就会使用 2.0 之前的 crate 里最新的可用版本。

2.7.1 命令行界面

这个程序的界面非常简单。它有 4 个参数：要搜索的字符串（或正则表达式）、要替换成的字符串（或正则表达式）、输入文件的名称和输出文件的名称。我们将从包含这些参数的结构体开始写 main.rs 文件：

#[derive(Debug)]
struct Arguments {
 target: String,
 replacement: String,
 filename: String,
 output: String,
}

#[derive(Debug)] 属性会让编译器生成一些额外的代码，这能让我们在 println! 中使用 {:?} 来格式化 Arguments 结构体。

如果用户输入的参数个数不对，那么通常会打印出一份关于如何使用本程序的简单说明。我们会使用一个名为 print_usage 的简单函数来完成此操作，并从 text-colorizer 导入所有内容，以便为这些输出添加一些颜色：

use text_colorizer::*;

fn print_usage() {
 eprintln!("{} - change occurrences of one string into another",
 "quickreplace".green());
 eprintln!("Usage: quickreplace <target> <replacement> <INPUT> <OUTPUT>");
}

只要将 .green() 添加到字符串字面量的末尾，就可以生成包裹在适当 ANSI 转义码中的字符串，从而在终端模拟器中显示为绿色。然后，在打印之前将生成的字符串插到信息中的其他部分。

现在可以开始收集并处理程序的参数了：

use std::env;

fn parse_args() -> Arguments {
 let args: Vec<String> = env::args().skip(1).collect();

 if args.len() != 4 {
 print_usage();
 eprintln!("{} wrong number of arguments: expected 4, got {}.",
 "Error:".red().bold(), args.len());
 std::process::exit(1);
 }

 Arguments {
 target: args[0].clone(),
 replacement: args[1].clone(),
 filename: args[2].clone(),
 output: args[3].clone()
 }
}

为了获取用户输入的参数，我们会使用与前面例子中相同的 args 迭代器。 .skip(1) 会跳过迭代器的第一个值（正在运行的程序的名称），让结果中只含命令行参数。

首先 collect() 方法会生成一个 Vec 参数。然后我们会检查它的参数个数是否正确，如果不正确，则打印一条信息并以返回一个错误代码的形式退出。接下来我们再次对部分信息进行着色，并用 .bold() 把这段文本加粗。如果参数个数正确，就把它们放入一个 Arguments 结构体中，并返回该结构体。

下面添加一个只会调用 parse_args 并打印输出的 main 函数：

fn main() {
 let args = parse_args();
 println!("{:?}", args);
}

现在，运行本程序，可以看到它正常输出了错误消息：

$ cargo run
 Updating crates.io index
Compiling libc v0.2.82
Compiling lazy_static v1.4.0
Compiling memchr v2.3.4
Compiling regex-syntax v0.6.22
Compiling thread_local v1.1.0
Compiling aho-corasick v0.7.15
Compiling atty v0.2.14
Compiling text-colorizer v1.0.0
Compiling regex v1.4.3
Compiling quickreplace v0.1.0 (/home/jimb/quickreplace)
Finished dev [unoptimized + debuginfo] target(s) in 6.98s
Running `target/debug/quickreplace`
quickreplace - change occurrences of one string into another
Usage: quickreplace <target> <replacement> <INPUT> <OUTPUT>
Error: wrong number of arguments: expected 4, got 0

如果传给程序的参数个数正确，那么它就会打印出 Arguments 结构体的文本表示：

$ cargo run "find" "replace" file output
 Finished dev [unoptimized + debuginfo] target(s) in 0.01s
 Running `target/debug/quickreplace find replace file output`
Arguments { target: "find", replacement: "replace", filename: "file", output:
"output" }

这是一个很好的开端。这些参数都已被正确提取并放置在 Arguments 结构体的正确部分中。

2.7.2 读写文件

接下来，我们需要用某种方法从文件系统中实际获取数据，以便进行处理，并在完工后将数据写回去。Rust 有一套健壮的输入 / 输出工具，但标准库的设计者知道读写文件是很常用的操作，所以刻意简化了它。我们所要做的是导入模块 std::fs，然后就可以访问 read_to_string 函数和 write 函数了：

use std::fs;

std::fs::read_to_string 会返回一个 Result<String, std::io::Error>。如果此函数成功，就会生成一个 String；如果失败，就会生成一个 std::io::Error，这是标准库中用来表示 I/O 问题的类型。类似地， std::fs::write 会返回一个 Result<(), std::io::Error>：在成功的时候不返回任何内容，一旦出现问题就返回错误详情。

fn main() {
 let args = parse_args();

 let data = match fs::read_to_string(&args.filename) {
 Ok(v) => v,
 Err(e) => {
 eprintln!("{} failed to read from file '{}': {:?}",
 "Error:".red().bold(), args.filename, e);
 std::process::exit(1);
 }
 };

 match fs::write(&args.output, &data) {
 Ok(_) => {},
 Err(e) => {
 eprintln!("{} failed to write to file '{}': {:?}",
 "Error:".red().bold(), args.output, e);
 std::process::exit(1);
 }
 };
}

在这里，我们使用前面写好的 parse_args() 函数并将生成的文件名传给 read_to_string 和 write。对这些函数的输出使用 match 语句可以优雅地处理错误，打印出文件名、错误原因，并用一点儿醒目的颜色引起用户的注意。

有了这个改写后的 main 函数，运行程序时就可以看到下面这些了，当然，新旧文件的内容是完全相同的：

$ cargo run "find" "replace" Cargo.toml Copy.toml
 Compiling quickreplace v0.1.0 (/home/jimb/rust/quickreplace)
 Finished dev [unoptimized + debuginfo] target(s) in 0.01s
 Running `target/debug/quickreplace find replace Cargo.toml Copy.toml`

该程序 确实 读取了输入文件 Cargo.toml，也 确实 写入了输出文件 Copy.toml，但是由于我们尚未编写任何代码来实际进行查找和替换，因此输出中没有任何变化。通过运行 diff 命令轻松进行查验，该命令确实没有检测到任何差异。

$ diff Cargo.toml Copy.toml

2.7.3 查找并替换

这个程序的最后一步是实现它的实际功能：查找并替换。为此，我们将使用 regex crate，它会编译并执行正则表达式。它提供了一个名为 Regex 的结构体，表示已编译的正则表达式。 Regex 有一个 replace_all 方法，该方法名副其实：在一个字符串中搜索此正则表达式的所有匹配项，并用给定的替代字符串替换每个匹配项。可以将这段逻辑提取到一个函数中：

use regex::Regex;
fn replace(target: &str, replacement: &str, text: &str)
 -> Result<String, regex::Error>
{
 let regex = Regex::new(target)?;
 Ok(regex.replace_all(text, replacement).to_string())
}

注意看这个函数的返回类型。就像之前使用过的标准库函数一样， replace 也会返回一个 Result，但这次它携带着 regex crate 提供的错误类型。

Regex::new 会编译用户提供的正则表达式，如果给定的字符串无效，那么它就会失败。与曼德博程序中一样，我们使用 ? 符号在 Regex::new 失败的情况下短路它，但该函数将返回 regex crate 特有的错误类型。一旦正则表达式编译完成，它的 replace_all 方法就能用给定的替代字符串替换 text 中的任何匹配项。

如果 replace_all 找到了匹配项，那么它就会返回一个新的 String，而这些匹配项会被替换成我们给它的文本。否则， replace_all 就会返回指向原始文本的指针，以回避不必要的内存分配和复制。然而，在这个例子中，我们想要一个独立的副本，因此无论是哪种情况，都要使用 to_string 方法来获取 String 并返回包裹在 Result::Ok 中的字符串，就像其他函数中的做法一样。

现在，是时候将这个新函数合并到 main 代码中了：

fn main() {
 let args = parse_args();

 let data = match fs::read_to_string(&args.filename) {
 Ok(v) => v,
 Err(e) => {
 eprintln!("{} failed to read from file '{}': {:?}",
 "Error:".red().bold(), args.filename, e);
 std::process::exit(1);
 }
 };

 let replaced_data = match replace(&args.target, &args.replacement, &data) {
 Ok(v) => v,
 Err(e) => {
 eprintln!("{} failed to replace text: {:?}",
 "Error:".red().bold(), e);
 std::process::exit(1);
 }
 };

 match fs::write(&args.output, &replaced_data) {
 Ok(v) => v,
 Err(e) => {
 eprintln!("{} failed to write to file '{}': {:?}",
 "Error:".red().bold(), args.filename, e);
 std::process::exit(1);
 }
 };
}

完成了最后一步，程序已经就绪，你可以测试它了：

$ echo "Hello, world" > test.txt
$ cargo run "world" "Rust" test.txt test-modified.txt
 Compiling quickreplace v0.1.0 (/home/jimb/rust/quickreplace)
 Finished dev [unoptimized + debuginfo] target(s) in 0.88s
 Running `target/debug/quickreplace world Rust test.txt test-modified.txt`

$ cat test-modified.txt
Hello, Rust

错误处理做得也很到位，它优雅地向用户报告错误：

$ cargo run "[[a-z]" "0" test.txt test-modified.txt
 Finished dev [unoptimized + debuginfo] target(s) in 0.01s
 Running `target/debug/quickreplace '[[a-z]' 0 test.txt test-modified.txt`
Error: failed to replace text: Syntax(
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
regex parse error:
 [[a-z]
 ^
error: unclosed character class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
)

当然，这个简单的演示中还缺少许多特性，但已经“五脏俱全”。至此，你已经了解了如何读取和写入文件、传播和显示错误，以及为输出着色以提升终端程序里的用户体验。

在未来的章节中，我们将探讨应用程序开发中的高级技术，从数据的集合以及使用迭代器进行函数式编程到可实现高效并发的异步编程技术，但首先，你得在第 3 章的 Rust 基本数据类型方面打下坚实的基础。

第 3 章 基本数据类型

之所以世界上有很多很多类型的书，是因为世界上有很多很多类型的人，而每个人都在追求不同类型的知识。

——Lemony Snicket

在很大程度上，可以说 Rust 语言就是围绕其类型来设计的。Rust 对高性能代码的支持，源自它能让开发人员选择最适合当前场景的数据表示法，并在简单性和成本之间进行合理的权衡。Rust 的内存和线程安全保障也依赖于其类型系统的健全性，而 Rust 的灵活性则源于其泛型类型和特型。

本章涵盖了 Rust 用以表示值的基本数据类型。这些源代码级类型都有其对应的机器级表示法，具有可预测的成本和性能。尽管 Rust 无法保证会完全按你的要求去表示各项事物，但只有当它确信能做出可靠的改进时才会谨慎地偏离你的原始要求。

与 JavaScript 或 Python 等动态类型语言相比，Rust 需要你提前做出更多规划。你必须明确写出各个函数参数和返回值的类型、结构体字段以及一些其他结构体。然而，Rust 的以下两个特性让这项工作比你预想的要轻松一点儿。

• 基于已明确写出的类型，Rust 的 类型推断 会帮你推断出剩下的大部分类型。实际上，对于给定的变量或表达式，通常只会有一种恰当的类型，在这种情况下，Rust 允许你省略类型。例如，你可以明确写出函数中的每一种类型，如下所示。

  fn build_vector() -> Vec<i16> {
   let mut v: Vec<i16> = Vec::<i16>::new();
   v.push(10i16);
   v.push(20i16);
   v
  }
  

  但这既凌乱又啰唆。既然已知函数的返回类型，那么显然 v 只能是一个 Vec<i16>，也就是 16 位有符号整数的向量，其他类型都不行。由此可知该向量的每个元素都必须是 i16。这正是 Rust 的类型推断所擅长的那种推理方式，这样一来，你可以将上述代码改写成下面这样。

  fn build_vector() -> Vec<i16> {
   let mut v = Vec::new();
   v.push(10);
   v.push(20);
   v
  }
  

  这两个定义是完全等效的，无论采用哪种方式，Rust 都会生成相同的机器码。类型推断让 Rust 具备了与动态类型语言相近的易读性，并且仍然能在编译期捕获类型错误。

• 函数可以是 泛型 的：单个函数就可以处理许多不同类型的值。

  在 Python 和 JavaScript 中，所有函数都天生如此：函数可以对任何具备该函数所要求的属性和方法的值进行操作。（这就是通常称为 鸭子类型 的特征：如果它叫得像鸭子，走路像鸭子，那它就是鸭子。）但也正是这种灵活性让这些语言很难及早发现类型错误，而测试通常是发现此类错误的唯一途径。Rust 的泛型函数为该语言提供了一定程度的灵活性，而且仍然能在编译期捕获所有的类型错误。

  虽然泛型函数更灵活，但其效率仍然与非泛型函数一样高。相较于编写能处理所有整数的泛型函数，为每种整数编写一个专用的 sum 函数并没有性能方面的内在优势。第 11 章会详细讨论泛型函数。

本章的其余部分自下向上介绍了 Rust 的一些类型，从简单的数值类型（如整数和浮点值）开始，转而介绍包含更多数据的类型：Box、元组（tuple）、数组和字符串。

接下来是你将在 Rust 中看到的各种类型的摘要。表 3-1 展示了 Rust 的原始类型、标准库中一些最常见的类型以及一些用户定义类型的示例。

表 3-1：Rust 中的类型示例

类型

说明

值

i8、 i16、 i32、 i64、 i128、 u8、 u16、 u32、 u64、 u128

给定位宽的有符号整数和无符号整数

42、 -5i8、 0x400u16、 0o100i16、 20_922_789_888_000u64、 b'*'（ u8 字节字面量）

isize、 usize

与机器字（32 位或 64 位）一样大的有符号整数和无符号整数

137、 -0b0101_0010isize、 0xffff_fc00usize

f32、 f64

单精度 IEEE 浮点数和双精度 IEEE 浮点数

1.61803、 3.14f32、 6.0221e23f64

bool

布尔值

true、 false

char

Unicode 字符，32 位宽（4 字节）

'*'、 '\n'、 ' 字 '、 '\x7f'、 '\u'

(char, u8, i32)

元组，允许混合类型

('%', 0x7f, -1)

()

“单元”（空元组）

()

struct S { x: f32, y: f32 }

具名字段型结构体

S { x: 120.0, y: 209.0}

struct T(i32, char);

元组型结构体

T (120, 'X')

struct E;

单元型结构体，无字段

E

enum Attend { OnTime, Late(u32)}

枚举，或代数数据类型

Attend::Late(5)、 Attend::OnTime

Box<Attend>

Box：指向堆中值的拥有型指针

Box::new(Late(15))

&i32、 &mut i32

共享引用和可变引用：非拥有型指针，其生命周期不能超出引用目标

&s.y、 &mut v

String

UTF-8 字符串，动态分配大小

" ラ一メン : ramen".to_string()

&str

对 str 的引用：指向 UTF-8 文本的非拥有型指针

" そば : soba"、 &s[0..12]

[f64; 4]、 [u8; 256]

数组，固定长度，其元素类型都相同

[1.0, 0.0, 0.0, 1.0]、 [b' '; 256]

Vec<f64>

向量，可变长度，其元素类型都相同

vec![0.367, 2.718, 7.389]

&[u8]、 *mut [u8]

对切片（数组或向量某一部分）的引用，包含指针和长度

&v[10..20]、 &mut a[..]

Option<&str>

可选值：或者为 None（无值），或者为 Some(v)（有值，其值为 v）

Some("Dr."), None

Result<u64, Error>

可能失败的操作结果：或者为成功值 Ok(v)，或者为错误值 Err(e)

Ok(4096), Err(Error::last_os_error())

&dyn Any、 &mut dyn Read

特型对象，是对任何实现了一组给定方法的值的引用

value as &dyn Any、 &mut file as &mut dyn Read

fn(&str) -> bool

函数指针

str::is_empty

（闭包类型没有显式书写形式）

闭包

|a, b| a * a + b * b

本章会对上述大多数类型进行介绍，但以下类型除外。

• 结构体（ struct）类型（参见第 9 章）。
• 枚举类型（参见第 10 章）。
• 特型对象（参见第 11 章）。
• 函数和闭包类型（参见第 14 章）。
• String 和 &str 的更多细节（参见第 17 章）。

3.1 固定宽度的数值类型

Rust 类型系统的根基是一组固定宽度的数值类型，选用这些类型是为了匹配几乎所有现代处理器都已直接在硬件中实现的类型。

固定宽度的数值类型可能会溢出或丢失精度，但它们足以满足大多数应用程序的需求，并且要比任意精度整数和精确有理数等表示法快数千倍。如果需要后面提到的那些类型的数值的表示法，可以到 num crate 中找到它们。

Rust 中数值类型的名称都遵循着一种统一的模式，也就是以“位”数表明它们的宽度，以前缀表明它们的用法，如表 3-2 所示。

表 3-2：Rust 数值类型

大小（位）

无符号整数

有符号整数

浮点数

8

u8

i8

16

u16

i16

32

u32

i32

f32

64

u64

i64

f64

128

u128

i128

机器字

usize

isize

在这里， 机器字 是一个值，其大小等于运行此代码的机器上“地址”的大小，可能是 32 位，也可能是 64 位。

3.1.1 整型

Rust 的无符号整型会使用它们的完整范围来表示正值和 0，如表 3-3 所示。

表 3-3：Rust 无符号整型

类型

范围

u8

0 到 28-1（0 到 255）

u16

0 到 216-1（0 到 65 535）

u32

0 到 232-1（0 到 4 294 967 295）

u64

0 到 264-1（0 到 18 446 744 073 709 551 615 或 1844 京）

u128

0 到 2128-1（0 到大约 3.4×1038）

usize

0 到 232-1 或 264-1

Rust 的有符号整型会使用二进制补码表示，使用与相应的无符号类型相同的位模式来覆盖正值和负值的范围，如表 3-4 所示。

表 3-4：Rust 有符号整型

类型

范围

i8

-27 到 27-1（-128 到 127）

i16

-215 到 215-1（-32 768 到 32 767）

i32

-231 到 231-1（-2 147 483 648 到 2 147 483 647）

i64

-263 到 263-1（-9 223 372 036 854 775 808 到 9 223 372 036 854 775 807）

i128

-2127 到 2127-1（大约-1.7×1038 到 +1.7×1038）

isize

-231 到 231-1 或-263 到 263-1

Rust 会使用 u8 类型作为字节值。例如，从二进制文件或套接字中读取数据时会产生一个 u8 值构成的流。

与 C 和 C++ 不同，Rust 会把字符视为与数值截然不同的类型： char 既不是 u8，也不是 u32（尽管它确实有 32 位长）。稍后 3.3 节会详细讲解 Rust 的 char 类型。

usize 类型和 isize 类型类似于 C 和 C++ 中的 size_t 和 ptrdiff_t。它们的精度与目标机器上地址空间的大小保持一致，即在 32 位架构上是 32 位长，在 64 位架构上则是 64 位长。Rust 要求数组索引是 usize 值。用来表示数组或向量大小或某些数据结构中元素数量的值通常也是 usize 类型。

Rust 中的整型字面量可以带上一个后缀来指示它们的类型： 42u8 是 u8 类型， 1729isize 是 isize 类型。如果整型字面量没有带类型后缀，那么 Rust 就会延迟确定其类型，直到找出一处足以认定其类型的使用代码，比如存储在特定类型的变量中、传给期待特定类型的函数、与具有特定类型的另一个值进行比较，等等。最后，如果有多种候选类型，那么 Rust 就会默认使用 i32（如果是候选类型之一的话）。如果无法认定类型，那么 Rust 就会将此歧义报告为错误。

前缀 0x、 0o 和 0b 分别表示十六进制字面量、八进制字面量和二进制字面量。

为了让长数值更易读，可以在数字之间任意插入下划线。例如，可以将 u32 的最大值写为 4_294_967_295。下划线的具体位置无关紧要，因此也可以将十六进制数或二进制数按 4 位数字而非 3 位数字进行分组（如 0xffff_ffff），或分隔开数字的类型后缀（如 127_u8）。表 3-5 中展示了整型字面量的一些示例。

表 3-5：整型字面量示例

字面量

类型

十进制值

116i8

i8

116

0xcafeu32

u32

51966

0b0010_1010

推断

42

0o106

推断

70

尽管数值类型和 char 类型是不同的，但 Rust 确实为 u8 值提供了 字节字面量。与字符字面量类似， b'X' 表示以字符 X 的 ASCII 码作为 u8 值。例如，由于 A 的 ASCII 码是 65，因此字面量 b'A' 和 65u8 完全等效。只有 ASCII 字符才能出现在字节字面量中。

有几个字符不能简单地放在单引号后面，因为那样在语法上会有歧义或难以阅读。表 3-6 中的字符只能以反斜杠开头的替代符号来书写。

表 3-6：需要替代符号的字符

字符

字节字面量

等效的数值

单引号（ '）

b'\''

39u8

反斜杠（ \）

b'\\'

92u8

换行（ lf）

b'\n'

10u8

回车（ cr）

b'\r'

13u8

制表符（ tab）

b'\t'

9u8

对于难于书写或阅读的字符，可以将其编码改为十六进制。这种字节字面量形如 b'\xHH'，其中 HH 是任意两位十六进制数，表示值为 HH 的字节。例如，你可以将 ASCII 控制字符 escape 的字节字面量写成 b'\x1b'，因为 escape 的 ASCII 码为 27，即十六进制的 1B。由于字节字面量只是 u8 值的表示法之一，因此还应该考虑使用一个整型字面量是否更易读：只有当你要强调该值表示的是 ASCII 码时，才应该使用 b'\x1b' 而不是简单明了的 27。

可以使用 as 运算符将一种整型转换为另一种整型。6.14 节会详细讲解类型转换的原理，这里先举一些例子：

assert_eq!( 10_i8 as u16, 10_u16); // 范围内转换
assert_eq!( 2525_u16 as i16, 2525_i16); // 范围内转换

assert_eq!( -1_i16 as i32, -1_i32); // 带符号扩展
assert_eq!(65535_u16 as i32, 65535_i32); // 填零扩展

// 超出目标范围的转换生成的值等于原始值对2N取模的值，
// 其中N是按位算的目标宽度。有时这也称为“截断”
assert_eq!( 1000_i16 as u8, 232_u8);
assert_eq!(65535_u32 as i16, -1_i16);

assert_eq!( -1_i8 as u8, 255_u8);
assert_eq!( 255_u8 as i8, -1_i8);

标准库提供了一些运算，可以像整型的方法一样使用。例如：

assert_eq!(2_u16.pow(4), 16); // 求幂
assert_eq!((-4_i32).abs(), 4); // 求绝对值
assert_eq!(0b101101_u8.count_ones(), 4); // 求二进制1的个数

可以在在线文档中找到这些内容。但请注意，该文档在“ i32（原始类型）”和此类型的专有模块（搜索“ std::i32”）下的单独页面中分别含有此类型的信息。

在实际编码中，通常不必像刚才那样写出类型后缀，因为其上下文将决定类型。但是，如果没有类型后缀且无法决定类型，那么错误消息可能会令人惊讶。例如，以下代码无法编译：

println!("{}", (-4).abs());

Rust 会报错：

error: can't call method `abs` on ambiguous numeric type ``

这令人不解：明明所有的有符号整型都有一个 abs 方法，那么问题出在哪里呢？出于技术原因，Rust 在调用类型本身的方法之前必须确切地知道一个值属于哪种整型。只有在解析完所有方法调用后类型仍然不明确的时候，才会默认为 i32，但这里并没有其他方法可供解析，因此 Rust 提供不了帮助。解决方案是加上后缀或使用特定类型的函数来明确写出希望的类型：

println!("{}", (-4_i32).abs());
println!("{}", i32::abs(-4));

请注意，方法调用的优先级高于一元前缀运算符，因此在将方法应用于负值时要小心。如果第一个语句中 -4_i32 周围没有圆括号，则 -4_i32.abs() 会先针对正值 4 调用 abs 方法，生成正值 4，再根据负号取负，得到 -4。

3.1.2 检查算法、回绕算法、饱和算法和溢出算法

当整型算术运算溢出时，Rust 在调试构建中会出现 panic。而在发布构建中，运算会 回绕：它生成的值等于“数学意义上正确的结果”对“值类型范围”取模的值。（在任何情况下都不会像 C 和 C++ 中那样出现“溢出未定义”的行为。）

例如，以下代码在调试构建中会出现 panic：

let mut i = 1;
loop {
 i *= 10; // panic：试图进行可能溢出的乘法（但只会在调试构建中出现）
}

在发布构建中，此乘法会返回负数，并且循环会无限运行。

如果这种默认行为不是你想要的，则整型提供的某些方法可以让你准确地阐明自己期望的行为。例如，在任意构建中都会出现下列 panic：

let mut i: i32 = 1;
loop {
 // panic：乘法溢出（在任意构建中出现）
 i = i.checked_mul(10).expect("multiplication overflowed");
}

这些整型算术方法分为 4 大类。

• 检查 运算会返回结果的 Option 值：如果数学意义上正确的结果可以表示为该类型的值，那么就为 Some(v)，否则为 None。

  // 10与20之和可以表示为u8
  assert_eq!(10_u8.checked_add(20), Some(30));
  
  // 很遗憾，100与200之和不能表示为u8
  assert_eq!(100_u8.checked_add(200), None);
  
  // 做加法。如果溢出，则会出现panic
  let sum = x.checked_add(y).unwrap();
  
  // 奇怪的是，在某种特殊情况下，带符号的除法也会溢出。
  // 带符号的n位类型可以表示-2n-1，但不足以表示2n-1
  assert_eq!((-128_i8).checked_div(-1), None);
  
  

• 回绕 运算会返回与“数学意义上正确的结果”对“值类型范围”取模的值相等的值。

  // 第一个结果可以表示为u16，第二个则不能，所以会得到250000 对216的模
  assert_eq!(100_u16.wrapping_mul(200), 20000);
  assert_eq!(500_u16.wrapping_mul(500), 53392);
  
  // 对有符号类型的运算可能会回绕为负值
  assert_eq!(500_i16.wrapping_mul(500), -12144);
  
  // 在移位运算中，移位距离会在值的大小范围内回绕，
  // 所以在16位类型中移动17位就相当于移动了1位
  assert_eq!(5_i16.wrapping_shl(17), 10);
  
  

如前所述，这就是普通算术运算符在发布构建中的行为。这些方法的优点是它们在所有构建中的行为方式都是相同的。

• 饱和 运算会返回最接近“数学意义上正确结果”的可表达值。换句话说，结果“紧贴着”该类型可表达的最大值和最小值。

  assert_eq!(32760_i16.saturating_add(10), 32767);
  assert_eq!((-32760_i16).saturating_sub(10), -32768);
  

  不存在饱和除法1、饱和求余法2或饱和位移法3。

• 溢出 运算会返回一个元组 (result, overflowed)，其中 result 是函数的回绕版本所返回的内容，而 overflowed 是一个布尔值，指示是否发生过溢出。

  assert_eq!(255_u8.overflowing_sub(2), (253, false));
  assert_eq!(255_u8.overflowing_add(2), (1, true));
  

  overflowing_shl 和 overflowing_shr 稍微偏离了这种模式：只有当移位距离与类型本身的位宽一样大或比其更大时，它们才会为 overflowed 返回 true。实际应用的移位数是所请求的移位数对类型位宽取模的结果。

  // 移动17位对`u16`来说太大了，而17对16取模就是1
  assert_eq!(5_u16.overflowing_shl(17), (10, true));
  

前缀 checked_、 wrapping_、 saturating_ 或 overflowing_ 后面可以跟着的运算名称如表 3-7 所示。

表 3-7：运算名称

运算

名称后缀

例子

加法

add

100_i8.checked_add(27) == Some(127)

减法

sub

10_u8.checked_sub(11) == None

乘法

mul

128_u8.saturating_mul(3) == 255

除法

div

64_u16.wrapping_div(8) == 8

求余

rem

(-32768_i16).wrapping_rem(-1) == 0

取负

neg

(-128_i8).checked_neg() == None

绝对值

abs

(-32768_i16).wrapping_abs() == -32768

求幂

pow

3_u8.checked_pow(4) == Some(81)

按位左移

shl

10_u32.wrapping_shl(34) == 40

按位右移

shr

40_u64.wrapping_shr(66) == 10

3.1.3 浮点类型

Rust 提供了 IEEE 单精度浮点类型和 IEEE 双精度浮点类型。这些类型包括正无穷大和负无穷大、不同的正零值和负零值，以及 非数值。如表 3-8 所示。

表 3-8：IEEE 单精度浮点类型和 IEEE 双精度浮点类型

类型

精度

范围

f32

IEEE 单精度（至少 6 位小数）

大约 -3.4 × 1038 至 +3.4 × 1038

f64

IEEE 双精度（至少 15 位小数）

大约 -1.8 × 10308 至 +1.8 × 10308

Rust 的 f32 和 f64 分别对应于 C 和 C++（在支持 IEEE 浮点的实现中）以及 Java（始终使用 IEEE 浮点）中的 float 类型和 double 类型。

浮点字面量的一般化形式如图 3-1 所示。

图 3-1：浮点字面量

浮点数中整数部分之后的每个部分都是可选的，但必须至少存在小数部分、指数或类型后缀这三者中的一个，以将其与整型字面量区分开来。小数部分可以仅由一个单独的小数点组成，因此 5. 也是有效的浮点常量。

如果浮点字面量缺少类型后缀，那么 Rust 就会检查上下文以查看值的使用方式，这与整型字面量非常相似。如果它最终发现这两种浮点类型都适合，就会默认选择 f64。

为了便于类型推断，Rust 会将整型字面量和浮点字面量视为不同的大类：它永远不会把整型字面量推断为浮点类型，反之亦然。表 3-9 展示了浮点字面量的一些示例。

表 3-9：浮点字面量的例子

字面量

类型

数学值

-1.5625

自动推断

−(19/16)

2.

自动推断

2

0.25

自动推断

¼

1e4

自动推断

10 000

40f32

f32

40

9.109_383_56e-31f64

f64

大约 9.109 383 56 × 10-31

f32 类型和 f64 类型具有 IEEE 要求的一些特殊值的关联常量，比如 INFINITY（无穷大）、 NEG_INFINITY（负无穷大）、 NAN（非数值）以及 MIN（最小有限值）和 MAX（最大有限值）：

assert!((-1. / f32::INFINITY).is_sign_negative());
assert_eq!(-f32::MIN, f32::MAX);

f32 类型和 f64 类型提供了完备的数学计算方法，比如 2f64.sqrt() 就是 2 的双精度平方根。下面是一些例子：

assert_eq!(5f32.sqrt() * 5f32.sqrt(), 5.); // 按IEEE的规定，它精确等于5.0
assert_eq!((-1.01f64).floor(), -2.0);

再次提醒，方法调用的优先级高于前缀运算符，因此在对负值进行方法调用时，请务必正确地加上圆括号。

std::f32::consts 模块和 std::f64::consts 模块提供了各种常用的数学常量，比如 E、 PI 和 2 的平方根。

在搜索文档时，请记住这两种类型本身都有名为“ f32（原始类型）”和“ f64（原始类型）”的页面，以及每种类型的单独模块 std::f32 和 std::f64。

与整数一样，通常不必在实际代码中写出浮点字面量的类型后缀，但如果你想这么做，那么将类型放在字面量或函数上就可以：

println!("{}", (2.0_f64).sqrt());
println!("{}", f64::sqrt(2.0));

与 C 和 C++ 不同，Rust 几乎不会执行任何隐式的数值转换。如果函数需要 f64 参数，则传入 i32 型参数是错误的。事实上，Rust 甚至不会隐式地将 i16 值转换为 i32 值，虽然每个 i16 值都必然在 i32 范围内。不过，你随时可以用 as 运算符写出 显式 转换： i as f64 或 x as i32。

缺少隐式转换有时会让 Rust 表达式比类似的 C 或 C++ 代码更冗长。然而，隐式整数转换有着导致错误和安全漏洞的大量“前科”，特别是在用这种整数表示内存中某些内容的大小时，很可能发生意外溢出。根据以往的经验，Rust 这种要求明确写出数值类型转换的行为，会提醒我们注意到一些可能错过的问题。

6.14 节会解释各种类型转换的确切行为。

3.2 布尔类型

Rust 的布尔类型 bool 具有此类型常用的两个值 true 和 false。 ==、 < 等比较运算符会生成 bool 结果，比如 2 < 5 的值为 true。

许多语言对在要求布尔值的上下文中使用其他类型的值持宽松态度，比如 C 和 C++ 会把字符、整数、浮点数和指针隐式转换成布尔值，因此它们可以直接用作 if 语句或 while 语句中的条件。Python 允许在布尔上下文中使用字符串、列表、字典甚至 Set，如果这些值是非空的，则将它们视为 true。然而，Rust 非常严格：像 if 和 while 这样的控制结构要求它们的条件必须是 bool 表达式，短路逻辑运算符 && 和 || 也是如此。你必须写成 if x != 0 { ... }，而不能只写成 if x { ... }。

Rust 的 as 运算符可以将 bool 值转换为整型：

assert_eq!(false as i32, 0);
assert_eq!(true as i32, 1);

但是， as 无法进行另一个方向（从数值类型到 bool）的转换。相反，你必须显式地写出比较表达式，比如 x != 0。

尽管 bool 只需要用一个位来表示，但 Rust 在内存中会使用整字节来表示 bool 值，因此可以创建指向它的指针。

3.3 字符

Rust 的字符类型 char 会以 32 位值表示单个 Unicode 字符。

Rust 会对单独的字符使用 char 类型，但对字符串和文本流使用 UTF-8 编码。因此， String 会将其文本表示为 UTF-8 字节序列，而不是字符数组。

字符字面量是用单引号括起来的字符，比如 '8' 或 '!'。还可以使用全角 Unicode 字符： ' 錆 ' 是一个 char 字面量，表示日文汉字中的 sabi（rust）。

与字节字面量一样，有些字符需要用反斜杠转义，如表 3-10 所示。

表 3-10：需要用反斜杠转义的字符

字符

Rust 字符字面量

单引号（ '）

'\''

反斜杠（ \）

'\\'

换行（ lf）

'\n'

回车（ cr）

'\r'

制表（ tab）

'\t'

如果你愿意，还可以用十六进制写出字符的 Unicode 码点。

• 如果字符的码点在 U+0000 到 U+007F 范围内（也就是说，如果它是从 ASCII 字符集中提取的），就可以把字符写为 '\xHH'，其中 HH 是两个十六进制数。例如，字符字面量 '*' 和 '\x2A' 是等效的，因为字符 * 的码点是 42 或十六进制的 2A。
• 可以将任何 Unicode 字符写为 '\u' 形式，其中 HHHHHH 是最多 6 个十六进制数，可以像往常一样用下划线进行分组。例如，字符字面量 '\u' 表示字符“ಠ”，这是 Unicode 中用于表示反对的卡纳达语字符“ಠ_ಠ”。同样的字面量也可以简写成 'ಠ'。

char 总是包含 0x0000 到 0xD7FF 或 0xE000 到 0x10FFFF 范围内的 Unicode 码点。 char 永远不会是“半代用区”中的码点（0xD800 到 0xDFFF 范围内的码点，它们不能单独使用）或 Unicode 码点空间之外的值（大于 0x10FFFF 的值）。Rust 使用类型系统和动态检查来确保 char 值始终在允许的范围内。

Rust 不会在 char 和任何其他类型之间进行隐式转换。可以使用 as 转换运算符将 char 转换为整型，对于小于 32 位的类型，该字符值的高位会被截断：

assert_eq!('*' as i32, 42);
assert_eq!('ಠ' as u16, 0xca0);
assert_eq!('ಠ' as i8, -0x60); // U+0CA0截断到8位，有符号

从另一个方向来看， u8 是唯一能通过 as 运算符转换为 char 的类型，因为 Rust 刻意让 as 运算符只执行开销极低且可靠的转换，但是除 u8 之外的每个整型都可能包含 Unicode 码点之外的值，所以这些转换都要做运行期检查。作为替代方案，标准库函数 std::char::from_u32 可以接受任何 u32 值并返回一个 Option<char>：如果此 u32 不是允许的 Unicode 码点，那么 from_u32 就会返回 None，否则，它会返回 Some(c)，其中 c 是转换成 char 后的结果。

标准库为字符提供了一些有用的方法，你可以在“ char（原始类型）”和模块“ std::char”下的在线文档中找到这些方法。

assert_eq!('*'.is_alphabetic(), false);
assert_eq!('β'.is_alphabetic(), true);
assert_eq!('8'.to_digit(10), Some(8));
assert_eq!('ಠ'.len_utf8(), 3);
assert_eq!(std::char::from_digit(2, 10), Some('2'));

孤立的字符自然不如字符串和文本流那么有用。3.7 节会讲解 Rust 的标准 String 类型和文本处理。

3.4 元组

元组 是各种类型值的值对或三元组、四元组、五元组等（因此称为 n-元组 或 元组）。可以将元组编写为一个元素序列，用逗号隔开并包裹在一对圆括号中。例如， ("Brazil", 1985) 是一个元组，其第一个元素是一个静态分配的字符串，第二个元素是一个整数，它的类型是 (&str, i32)。给定一个元组值 t，可以通过 t.0、 t.1 等访问其元素。

元组有点儿类似于数组，即这两种类型都表示值的有序序列。许多编程语言混用或结合了这两个概念，但在 Rust 中，它们是截然不同的。一方面，元组的每个元素可以有不同的类型，而数组的元素必须都是相同的类型。另一方面，元组只允许用常量作为索引，比如 t.4。不能通过写成 t.i 或 t[i] 的形式来获取第 i 个元素。

Rust 代码通常会用元组类型从一个函数返回多个值。例如，字符串切片上的 split_at 方法会将字符串分成两半并返回它们，其声明如下所示：

fn split_at(&self, mid: usize) -> (&str, &str);

返回类型 (&str, &str) 是两个字符串切片构成的元组。可以用模式匹配语法将返回值的每个元素赋值给不同的变量：

let text = "I see the eigenvalue in thine eye";
let (head, tail) = text.split_at(21);
assert_eq!(head, "I see the eigenvalue ");
assert_eq!(tail, "in thine eye");

这样比其等效写法更易读：

let text = "I see the eigenvalue in thine eye";
let temp = text.split_at(21);
let head = temp.0;
let tail = temp.1;
assert_eq!(head, "I see the eigenvalue ");
assert_eq!(tail, "in thine eye");

你还会看到元组被用作一种超级小巧的结构体类型。例如，在第 2 章的曼德博程序中，我们要将图像的宽度和高度传给绘制它的函数并将其写入磁盘。为此可以声明一个具有 width 成员和 height 成员的结构体，但对如此显而易见的事情来说，这种写法相当烦琐，所以我们只用了一个元组：

/// 把`pixels`缓冲区（其尺寸由`bounds`给出）写入名为`filename`的文件中
fn write_image(filename: &str, pixels: &[u8], bounds: (usize, usize))
 -> Result<(), std::io::Error>
{ ... }

bounds 参数的类型是 (usize, usize)，这是一个包含两个 usize 值的元组。当然也可以写成单独的 width 参数和 height 参数，并且最终的机器码也基本一样。但重点在于思路的清晰度。应该把大小看作一个值，而不是两个，使用元组能更准确地记述这种意图。

另一种常用的元组类型是零元组 ()。传统上，这叫作 单元类型，因为此类型只有一个值，写作 ()。当无法携带任何有意义的值但其上下文仍然要求传入某种类型时，Rust 就会使用单元类型。

例如，不返回值的函数的返回类型为 ()。标准库的 std::mem::swap 函数就没有任何有意义的返回值，它只会交换两个参数的值。 std::mem::swap 的声明如下所示：

fn swap<T>(x: &mut T, y: &mut T);

这个 <T> 意味着 swap 是 泛型 的：可以将对任意类型 T 的值的引用传给它。但此签名完全省略了 swap 的返回类型，它是以下完整写法的简写形式：

fn swap<T>(x: &mut T, y: &mut T) -> ();

类似地，前面提到过的 write_image 示例的返回类型是 Result<(), std::io::Error>，这意味着该函数在出错时会返回一个 std::io::Error 值，但成功时不会返回任何值。

如果你愿意，可以在元组的最后一个元素之后跟上一个逗号：类型 (&str, i32,) 和 (&str, i32) 是等效的，表达式 ("Brazil", 1985,) 和 ("Brazil", 1985) 是等效的。Rust 始终允许在所有能用逗号的地方（函数参数、数组、结构体和枚举定义，等等）添加额外的尾随逗号。这对人类读者来说可能很奇怪，不过一旦在多行列表末尾添加或移除了条目（entry），在显示差异时就会更容易阅读。

为了保持一致性，甚至有包含单个值的元组。字面量 ("lonely hearts",) 就是一个包含单个字符串的元组，它的类型是 (&str,)。在这里，值后面的逗号是必需的，以用于区分单值元组和简单的括号表达式。

3.5 指针类型

Rust 有多种表示内存地址的类型。

这是 Rust 和大多数具有垃圾回收功能的语言之间一个重大的差异。在 Java 中，如果 class Rectangle 包含字段 Vector2D upperLeft;，那么 upperLeft 就是对另一个单独创建的 Vector2D 对象的引用。在 Java 中，一个对象永远不会包含其他对象的实际内容。

但 Rust 不一样。该语言旨在帮你将内存分配保持在最低限度。默认情况下值会嵌套。值 ((0, 0), (1440, 900)) 会存储为 4 个相邻的整数。如果将它存储在一个局部变量中，则会得到 4 倍于整数宽度的局部变量。堆中没有分配任何内容。

这可以帮我们高效利用内存，但代价是，当 Rust 程序需要让一些值指向其他值时，必须显式使用指针类型。好消息是，当使用这些指针类型时，安全的 Rust 会对其进行约束，以消除未定义的行为，因此指针在 Rust 中比在 C++ 中更容易正确使用。

接下来将讨论 3 种指针类型：引用、Box 和不安全指针。

3.5.1 引用

&String 类型的值（读作“ref String”）是对 String 值的引用， &i32 是对 i32 的引用，以此类推。

最简单的方式是将引用视为 Rust 中的基本指针类型。在运行期间，对 i32 的引用是一个保存着 i32 地址的机器字，这个地址可能位于栈或堆中。表达式 &x 会生成一个对 x 的引用，在 Rust 术语中，我们会说它 借用了对 x 的引用。给定一个引用 r，表达式 *r 会引用 r 指向的值。它们非常像 C 和 C++ 中的 & 运算符和 * 运算符，并且和 C 中的指针一样，当超出作用域时引用不会自动释放任何资源。

然而，与 C 指针不同，Rust 的引用永远不会为空：在安全的 Rust 中根本没有办法生成空引用。与 C 不同，Rust 会跟踪值的所有权和生命周期，因此早在编译期间就排除了悬空指针、双重释放和指针失效等错误。

Rust 引用有两种形式。

&T

一个不可变的共享引用。你可以同时拥有多个对给定值的共享引用，但它们是只读的：禁止修改它们所指向的值，就像 C 中的 const T* 一样。

&mut T

一个可变的、独占的引用。你可以读取和修改它指向的值，就像 C 中的 T* 一样。但是只要该引用还存在，就不能对该值有任何类型的其他引用。事实上，访问该值的唯一途径就是使用这个可变引用。

Rust 利用共享引用和可变引用之间的“二选一”机制来强制执行“单个写入者 或 多个读取者”规则：你或者独占读写一个值，或者让任意数量的读取者共享，但二者只能选择其一。这种由编译期检查强制执行的“二选一”规则是 Rust 安全保障的核心。第 5 章会解释 Rust 的安全引用的使用规则。

3.5.2 Box

在堆中分配值的最简单方式是使用 Box::new：

let t = (12, "eggs");
let b = Box::new(t); // 在堆中分配一个元组

t 的类型是 (i32, &str)，所以 b 的类型是 Box<(i32, &str)>。对 Box::new 的调用会分配足够的内存以在堆上容纳此元组。当 b 超出作用域时，内存会立即被释放，除非 b 已被 移动（move），比如返回它。移动对于 Rust 处理在堆上分配的值的方式至关重要，第 4 章会对此进行详细解释。

3.5.3 裸指针

Rust 也有裸指针类型 *mut T 和 *const T。裸指针实际上和 C++ 中的指针很像。使用裸指针是不安全的，因为 Rust 不会跟踪它指向的内容。例如，裸指针可能为空，或者它们可能指向已释放的内存或现在包含不同类型的值。C++ 的所有经典指针错误都可能“借尸还魂”。

但是，你只能在 unsafe 块中对裸指针解引用（dereference）。 unsafe 块是 Rust 高级语言特性中的可选机制，其安全性取决于你自己。如果代码中没有 unsafe 块（或者虽然有但编写正确），那么本书中强调的安全保证就仍然有效。有关详细信息，请参阅第 22 章。

3.6 数组、向量和切片

Rust 用 3 种类型来表示内存中的值序列。

• 类型 [T; N] 表示 N 个值的数组，每个值的类型为 T。数组的大小是在编译期就已确定的常量，并且是类型的一部分，不能追加新元素或缩小数组。
• 类型 Vec<T> 可称为 T 的向量，它是一个动态分配且可增长的 T 类型的值序列。向量的元素存在于堆中，因此可以随意调整向量的大小：压入新元素、追加其他向量、删除元素等。
• 类型 &[T] 和 &mut [T] 可称为 T 的共享切片 和 T 的可变切片，它们是对一系列元素的引用，这些元素是某个其他值（比如数组或向量）的一部分。可以将切片视为指向其第一个元素的指针，以及从该点开始允许访问的元素数量的计数。可变切片 &mut [T] 允许读取元素和修改元素，但不能共享；共享切片 &[T] 允许在多个读取者之间共享访问权限，但不允许修改元素。

给定这 3 种类型中任意一种类型的值 v，表达式 v.len() 都会给出 v 中的元素数，而 v[i] 引用的是 v 的第 i 个元素。 v 的第一个元素是 v[0]，最后一个元素是 v[v.len() - 1]。Rust 总是会检查 i 是否在这个范围内，如果没在，则此表达式会出现 panic。 v 的长度可能为 0，在这种情况下，任何对其进行索引的尝试都会出现 panic。 i 的类型必须是 usize，不能使用任何其他整型作为索引。

3.6.1 数组

编写数组值的方法有好几种，其中最简单的方法是在方括号内写入一系列值：

let lazy_caterer: [u32; 6] = [1, 2, 4, 7, 11, 16];
let taxonomy = ["Animalia", "Arthropoda", "Insecta"];

assert_eq!(lazy_caterer[3], 7);
assert_eq!(taxonomy.len(), 3);

对于要填充一些值的长数组的常见情况，可以写成 [V; N]，其中 V 是每个元素的值， N 是长度。例如， [true; 10000] 是一个包含 10 000 个 bool 元素的数组，其内容全为 true：

let mut sieve = [true; 10000];
for i in 2..100 {
 if sieve[i] {
 let mut j = i * i;
 while j < 10000 {
 sieve[j] = false;
 j += i;
 }
 }
}

assert!(sieve[211]);
assert!(!sieve[9876]);

你会看到用来声明固定大小缓冲区的语法： [0u8; 1024]，它是一个 1 KB 的缓冲区，用 0 填充。Rust 没有任何能定义未初始化数组的写法。（一般来说，Rust 会确保代码永远无法访问任何种类的未初始化值。）

数组的长度是其类型的一部分，并会在编译期固定下来。如果 n 是变量，则不能写成 [true; n] 以期得到一个包含 n 个元素的数组。当你需要一个长度在运行期可变的数组时（通常都是这样），请改用向量。

你在数组上看到的那些实用方法（遍历元素、搜索、排序、填充、过滤等）都是作为切片而非数组的方法提供的。但是 Rust 在搜索各种方法时会隐式地将对数组的引用转换为切片，因此可以直接在数组上调用任何切片方法：

let mut chaos = [3, 5, 4, 1, 2];
chaos.sort();
assert_eq!(chaos, [1, 2, 3, 4, 5]);

在这里， sort 方法实际上是在切片上定义的，但由于它是通过引用获取的操作目标，因此 Rust 会隐式地生成一个引用整个数组的 &mut [i32] 切片，并将其传给 sort 来进行操作。其实前面提到过的 len 方法也是切片的方法之一。3.6.3 节会更详细地介绍切片。

3.6.2 向量

向量 Vec<T> 是一个可调整大小的 T 类型元素的数组，它是在堆上分配的。

创建向量的方法有好几种，其中最简单的方法是使用 vec! 宏，它为我们提供了一个看起来非常像数组字面量的向量语法：

let mut primes = vec![2, 3, 5, 7];
assert_eq!(primes.iter().product::<i32>(), 210);

当然，这仍然是一个向量，而不是数组，所以可以动态地向它添加元素：

primes.push(11);
primes.push(13);
assert_eq!(primes.iter().product::<i32>(), 30030);

还可以通过将给定值重复一定次数来构建向量，可以再次使用模仿数组字面量的语法：

fn new_pixel_buffer(rows: usize, cols: usize) -> Vec<u8> {
 vec![0; rows * cols]
}

vec! 宏相当于调用 Vec::new 来创建一个新的空向量，然后将元素压入其中，这是另一种惯用法：

let mut pal = Vec::new();
pal.push("step");
pal.push("on");
pal.push("no");
pal.push("pets");
assert_eq!(pal, vec!["step", "on", "no", "pets"]);

还有一种可能性是从迭代器生成的值构建一个向量：

let v: Vec<i32> = (0..5).collect();
assert_eq!(v, [0, 1, 2, 3, 4]);

使用 collect 时，通常要指定类型（正如此处给 v 声明了类型），因为它可以构建出不同种类的集合，而不仅仅是向量。通过指定 v 的类型，我们明确表达了自己想要哪种集合。

与数组一样，可以对向量使用切片的方法：

// 回文！
let mut palindrome = vec!["a man", "a plan", "a canal", "panama"];
palindrome.reverse();
// 固然合理，但不符合预期：
assert_eq!(palindrome, vec!["panama", "a canal", "a plan", "a man"]);

在这里， reverse 方法实际上是在切片上定义的，但是此调用会隐式地从此向量中借用一个 &mut [&str] 切片并在其上调用 reverse。

Vec 是 Rust 的基本数据类型，它几乎可以用在任何需要动态大小的列表的地方，所以还有许多其他方法可以构建新向量或扩展现有向量。第 16 章会介绍这些方法。

Vec<T> 由 3 个值组成：指向元素在堆中分配的缓冲区（该缓冲区由 Vec<T> 创建并拥有）的指针、缓冲区能够存储的元素数量，以及它现在实际包含的数量（也就是它的长度）。当缓冲区达到其最大容量时，往向量中添加另一个元素需要分配一个更大的缓冲区，将当前内容复制到其中，更新向量的指针和容量以指向新缓冲区，最后释放旧缓冲区。

如果事先知道向量所需的元素数量，就可以调用 Vec::with_capacity 而不是 Vec::new 来创建一个向量，它的缓冲区足够大，可以从一开始就容纳所有元素。然后，可以逐个将元素添加到此向量中，而不会导致任何重新分配。 vec! 宏就使用了这样的技巧，因为它知道最终向量将包含多少个元素。请注意，这只会确定向量的初始大小，如果大小超出了你的预估，则向量仍然会正常扩大其存储空间。

许多库函数会寻求使用 Vec::with_capacity 而非 Vec::new 的机会。例如，在 collect 示例中，迭代器 0..5 预先知道它将产生 5 个值，并且 collect 函数会利用这一点以正确的容量来预分配它返回的向量。第 15 章会介绍其工作原理。

向量的 len 方法会返回它现在包含的元素数，而 capacity 方法则会返回在不重新分配的情况下可以容纳的元素数：

let mut v = Vec::with_capacity(2);
assert_eq!(v.len(), 0);
assert_eq!(v.capacity(), 2);

v.push(1);
v.push(2);
assert_eq!(v.len(), 2);
assert_eq!(v.capacity(), 2);

v.push(3);
assert_eq!(v.len(), 3);
// 通常会打印出"capacity is now 4":
println!("capacity is now {}", v.capacity());

最后打印出的容量不能保证恰好是 4，但至少大于等于 3，因为此向量包含 3 个值。

可以在向量中任意位置插入元素和移除元素，不过这些操作会将受影响位置之后的所有元素向前或向后移动，因此如果向量很长就可能很慢：

let mut v = vec![10, 20, 30, 40, 50];

// 在索引为3的元素处插入35
v.insert(3, 35);
assert_eq!(v, [10, 20, 30, 35, 40, 50]);

// 移除索引为1的元素
v.remove(1);
assert_eq!(v, [10, 30, 35, 40, 50]);

可以使用 pop 方法移除最后一个元素并将其返回。更准确地说，从 Vec<T> 中弹出一个值会返回 Option<T>：如果向量已经为空则为 None，如果其最后一个元素为 v 则为 Some(v)。

let mut v = vec!["Snow Puff", "Glass Gem"];
assert_eq!(v.pop(), Some("Glass Gem"));
assert_eq!(v.pop(), Some("Snow Puff"));
assert_eq!(v.pop(), None);

可以使用 for 循环遍历向量：

// 将命令行参数作为字符串的向量
let languages: Vec<String> = std::env::args().skip(1).collect();
for l in languages {
 println!("{}: {}", l,
 if l.len() % 2 == 0 {
 "functional"
 } else {
 "imperative"
 });
}

以编程语言列表为参数运行本程序就可以说明这个问题：

$ cargo run Lisp Scheme C C++ Fortran
 Compiling proglangs v0.1.0 (/home/jimb/rust/proglangs)
 Finished dev [unoptimized + debuginfo] target(s) in 0.36s
 Running `target/debug/proglangs Lisp Scheme C C++ Fortran`
Lisp: functional
Scheme: functional
C: imperative
C++: imperative
Fortran: imperative
$

终于可以对术语 函数式语言 做一个令人满意的定义了。

虽然扮演着基础角色，但 Vec 仍然是 Rust 中定义的普通类型，而没有内置在语言中。第 22 章会介绍实现这些类型所需的技术。

3.6.3 切片

切片（写作不指定长度的 [T]）是数组或向量中的一个区域。由于切片可以是任意长度，因此它不能直接存储在变量中或作为函数参数进行传递。切片总是通过引用传递。

对切片的引用是一个 胖指针：一个双字值，包括指向切片第一个元素的指针和切片中元素的数量。

假设你运行以下代码：

let v: Vec<f64> = vec![0.0, 0.707, 1.0, 0.707];
let a: [f64; 4] = [0.0, -0.707, -1.0, -0.707];

let sv: &[f64] = &v;
let sa: &[f64] = &a;

在最后两行中，Rust 自动把 &Vec<f64> 的引用和 &[f64; 4] 的引用转换成了直接指向数据的切片引用。

最后，内存布局如图 3-2 所示。

图 3-2：内存中的向量 v 和数组 a 分别被切片 sa 和 sv 引用

普通引用是指向单个值的非拥有型指针，而对切片的引用是指向内存中一系列连续值的非拥有型指针。如果要写一个对数组或向量进行操作的函数，那么切片引用就是不错的选择。例如，下面是打印一段数值的函数，每行一个：

fn print(n: &[f64]) {
 for elt in n {
 println!("{}", elt);
 }
}

print(&a); // 打印数组
print(&v); // 打印向量

因为此函数以切片引用为参数，所以也可以给它传入向量或数组。事实上，你以为属于向量或数组的许多方法其实是在切片上定义的，比如会对元素序列进行排序或反转的 sort 方法和 reverse 方法实际上是切片类型 [T] 上的方法。

你可以使用范围值对数组或向量进行索引，以获取一个切片的引用，该引用既可以指向数组或向量，也可以指向一个既有切片：

print(&v[0..2]); // 打印v的前两个元素
print(&a[2..]); // 打印从a[2]开始的元素
print(&sv[1..3]); // 打印v[1]和v[2]

与普通数组访问一样，Rust 会检查索引是否有效。尝试借用超出数据末尾的切片会导致 panic。

由于切片几乎总是出现在引用符号之后，因此通常只将 &[T] 或 &str 之类的类型称为“切片”，使用较短的名称来表示更常见的概念。

3.7 字符串类型

熟悉 C++ 的程序员应该还记得该语言中有两种字符串类型。字符串字面量的指针类型为 const char *。标准库还提供了一个 std::string 类，用于在运行期动态创建字符串。

Rust 中也有类似的设计。本节将首先展示所有编写字符串字面量的方法，然后介绍 Rust 的两种字符串类型。第 17 章会介绍有关字符串和文本处理的更多信息。

3.7.1 字符串字面量

字符串字面量要用双引号括起来，它们使用与 char 字面量相同的反斜杠转义序列：

let speech = "\"Ouch!\" said the well.\n";

但与 char 字面量不同，在字符串字面量中单引号不需要用反斜杠转义，而双引号需要。

一个字符串可能跨越多行：

println!("In the room the women come and go,
 Singing of Mount Abora");

该字符串字面量中的换行符是字符串的一部分，因此也会包含在输出中。第 2 行开头的空格也是如此。

如果字符串的一行以反斜杠结尾，那么就会丢弃其后的换行符和前导空格：

println!("It was a bright, cold day in April, and \
 there were four of us—\
 more or less.");

这会打印出单行文本。该字符串在“ and”和“ there”之间会有一个空格，因为在本程序中，第一个反斜杠之前有一个空格，而在破折号和“ more”之间则没有空格。

在少数情况下，需要双写字符串中的每一个反斜杠，这让人不胜其烦。（经典的例子是正则表达式和 Windows 路径。）对于这些情况，Rust 提供了 原始字符串。原始字符串用小写字母 r 进行标记。原始字符串中的所有反斜杠和空白字符都会逐字包含在字符串中。原始字符串不识别任何转义序列：

let default_win_install_path = r"C:\Program Files\Gorillas";

let pattern = Regex::new(r"\d+(\.\d+)*");

不能简单地在双引号前面放置一个反斜杠来包含原始字符串——别忘了，前面说过它 不识别 转义序列。但是，仍有办法解决。可以在原始字符串的开头和结尾添加 # 标记：

println!(r###"
 This raw string started with 'r###"'.
 Therefore it does not end until we reach a quote mark ('"')
 followed immediately by three pound signs ('###'):
"###);

可以根据需要添加任意多个井号，以标明原始字符串的结束位置。4

3.7.2 字节串

带有 b 前缀的字符串字面量都是 字节串。这样的字节串是 u8 值（字节）的切片而不是 Unicode 文本：

let method = b"GET";
assert_eq!(method, &[b'G', b'E', b'T']);

method 的类型是 &[u8; 3]：它是对 3 字节数组的引用，没有刚刚讨论过的任何字符串方法，最像字符串的地方就是其书写语法，仅此而已。

字节串可以使用前面展示过的所有其他的字符串语法：可以跨越多行、可以使用转义序列、可以使用反斜杠来连接行等。不过原始字节串要以 br" 开头。

字节串不能包含任意 Unicode 字符，它们只能使用 ASCII 和 \xHH 转义序列。

3.7.3 内存中的字符串

Rust 字符串是 Unicode 字符序列，但它们并没有以 char 数组的形式存储在内存中，而是使用了 UTF-8（一种可变宽度编码）的形式。字符串中的每个 ASCII 字符都会存储在单字节中，而其他字符会占用多字节。

图 3-3 展示了由以下代码创建的 String 值和 &str 值。

let noodles = "noodles".to_string();
let oodles = &noodles[1..];
let poodles = "ಠ_ಠ";

图 3-3： String、 &str 和 str

String 有一个可以调整大小的缓冲区，其中包含 UTF-8 文本。缓冲区是在堆上分配的，因此它可以根据需要或请求来调整大小。在示例中， noodles 是一个 String，它拥有一个 8 字节的缓冲区，其中 7 字节正在使用中。可以将 String 视为 Vec<u8>，它可以保证包含格式良好的 UTF-8，实际上， String 就是这样实现的。

&str（发音为 /stɜːr/ 或 string slice）是对别人拥有的一系列 UTF-8 文本的引用，即它“借用”了这个文本。在示例中， oodles 是对 noodles 拥有的文本的最后 6 字节的一个 &str 引用，因此它表示文本“oodles”。与其他切片引用一样， &str 也是一个胖指针，包含实际数据的地址及其长度。可以认为 &str 就是 &[u8]，但它能保证包含的是格式良好的 UTF-8。

字符串字面量是指预分配文本的 &str，它通常与程序的机器码一起存储在只读内存区。在前面的示例中， poodles 是一个字符串字面量，指向一块 7 字节的内存，它在程序开始执行时就已创建并一直存续到程序退出。

String 或 &str 的 .len() 方法会返回其长度。这个长度以字节而不是字符为单位：

assert_eq!("ಠ_ಠ".len(), 7);
assert_eq!("ಠ_ಠ".chars().count(), 3);

不能修改 &str：

let mut s = "hello";
s[0] = 'c'; // 错误：无法修改`&str`，并给出错误原因
s.push('\n'); // 错误：`&str`引用上没有找到名为`push`的方法

要在运行期创建新字符串，可以使用 String。

&mut str 类型确实存在，但它没什么用，因为对 UTF-8 的几乎所有操作都会更改其字节总长度，但切片不能重新分配其引用目标的缓冲区。事实上， &mut str 上唯一可用的操作是 make_ascii_uppercase 和 make_ascii_lowercase，根据定义，它们会就地修改文本并且只影响单字节字符。

3.7.4 String

&str 非常像 &[T]，是一个指向某些数据的胖指针。而 String 则类似于 Vec<T>，如表 3-11 所示。

表 3-11： Vec<T> 与 String 对比

Vec<T>

String

自动释放缓冲区

是

是

可增长

是

是

类型关联函数 ::new() 和 ::with_capacity()

是

是

.reserve() 方法和 .capacity() 方法

是

是

.push() 方法和 .pop() 方法

是

是

范围语法 v[start..stop]

是，返回 &[T]

是，返回 &str

自动转换

&Vec<T> 到 &[T]

&String 到 &str

继承的方法

来自 &[T]

来自 &str

与 Vec 一样，每个 String 都在堆上分配了自己的缓冲区，不会与任何其他 String 共享。当 String 变量超出作用域时，缓冲区将自动释放，除非这个 String 已经被移动。

以下是创建 String 的几种方法。

• .to_string() 方法会将 &str 转换为 String。这会复制此字符串。

  let error_message = "too many pets".to_string();
  

  .to_owned() 方法会做同样的事，也会以同样的方式使用。这种命名风格也适用于另一些类型，第 13 章中会讨论。

• format!() 宏的工作方式与 println!() 类似，但它会返回一个新的 String，而不是将文本写入标准输出，并且不会在末尾自动添加换行符。

  assert_eq!(format!("{}°{:02}′{:02}″N", 24, 5, 23),
   "24°05′23″N".to_string());
  

• 字符串的数组、切片和向量都有两个方法（ .concat() 和 .join(sep)），它们会从许多字符串中形成一个新的 String。

  let bits = vec!["veni", "vidi", "vici"];
  assert_eq!(bits.concat(), "venividivici");
  assert_eq!(bits.join(", "), "veni, vidi, vici");
  

有时要选择是使用 &str 类型还是使用 String 类型。第 5 章会详细讨论这个问题。这里仅指出一点： &str 可以引用任意字符串的任意切片，无论它是字符串字面量（存储在可执行文件中）还是 String（在运行期分配和释放）。这意味着如果希望允许调用者传递任何一种字符串，那么 &str 更适合作为函数参数。

3.7.5 使用字符串

字符串支持 == 运算符和 != 运算符。如果两个字符串以相同的顺序包含相同的字符（无论是否指向内存中的相同位置），则认为它们是相等的：

assert!("ONE".to_lowercase() == "one");

字符串还支持比较运算符 <、 <=、 > 和 >=，以及许多有用的方法和函数，你可以在“ str（原始类型）”或“ std::str”模块下的在线文档中找到它们（或直接翻到第 17 章）。下面是一些例子：

assert!("peanut".contains("nut"));
assert_eq!("ಠ_ಠ".replace("ಠ", "■"), "■_■");
assert_eq!(" clean\n".trim(), "clean");

for word in "veni, vidi, vici".split(", ") {
 assert!(word.starts_with("v"));
}

要记住，考虑到 Unicode 的性质，简单的逐字符比较 并不 总能给出预期的答案。例如，Rust 字符串 "th\u" 和 "the\u" 都是 thé（在法语中是“茶”的意思）的有效 Unicode 表示。Unicode 规定它们应该以相同的方式显示和处理，但 Rust 会将它们视为两个完全不同的字符串。类似地，Rust 的排序运算符（如 <）也使用基于字符码点值的简单字典顺序。这种排序方式只能说近似于在用户的语言和文化环境中对文本的正确排序方式。5第 17 章会更详细地讨论这些问题。

3.7.6 其他类似字符串的类型

Rust 保证字符串是有效的 UTF-8。有时程序确实需要处理 并非 有效 Unicode 的字符串。这种情况通常发生在 Rust 程序不得不与不强制执行此类规则的其他系统进行互操作时，例如，在大多数操作系统中，很容易创建一个名字不符合 Unicode 规则的文件。当 Rust 程序遇到这种文件名时应该怎么办呢？

Rust 的解决方案是为这些情况提供一些类似字符串的类型。

• 对于 Unicode 文本，坚持使用 String 和 &str。
• 当使用文件名时，请改用 std::path::PathBuf 和 &Path。
• 当处理根本不是 UTF-8 编码的二进制数据时，请使用 Vec<u8> 和 &[u8]。
• 当使用操作系统提供的原生形式的环境变量名和命令行参数时，请使用 OsString 和 &OsStr。
• 当和使用 null 结尾字符串的 C 语言库进行互操作时，请使用 std::ffi::CString 和 &CStr。

3.8 类型别名

与 C++ 中的 typedef 用法类似，可以使用 type 关键字来为现有类型声明一个新名称：

type Bytes = Vec<u8>;

这里声明的类型 Bytes 就是这种特定 Vec 的简写形式。

fn decode(data: &Bytes) {
 ...
}

3.9 前路展望

类型是 Rust 的核心部分。接下来本书会继续讨论类型并引入一些新的类型。特别是，Rust 的用户定义类型赋予了该语言很多特色，因为各种方法都是在此基础上定义的。用户定义类型共有 3 种，我们将用连续 3 章（第 9 章、第 10 章和第 11 章）介绍它们。

函数和闭包都有自己的类型，第 14 章中会介绍。构成标准库的类型贯穿全书。例如，第 16 章会介绍标准的集合类型。

不过，所有这些都还得再等等。在继续前进之前，我们必须先着手处理 Rust 安全规则的核心概念。

第 4 章 所有权与移动

谈及内存管理，我们希望编程语言能具备两个特点：

• 希望内存能在我们选定的时机及时释放，这使我们能控制程序的内存消耗；
• 在对象被释放后，我们绝不希望继续使用指向它的指针，这是未定义行为，会导致崩溃和安全漏洞。

但上述情景似乎难以兼顾：只要指向值的指针仍然存在，释放这个值就必然会让这些指针悬空。几乎所有主流编程语言都只能在两个阵营中“二选一”，这取决于它们从中放弃了哪一项。

• “安全优先”阵营会通过垃圾回收机制来管理内存，在所有指向对象的可达指针都消失后，自动释放对象。它通过简单地保留对象，直到再也没有指向它们的指针为止，来消除悬空指针。几乎所有现代语言都属于这个阵营，从 Python、JavaScript 和 Ruby 到 Java、C# 和 Haskell。

  但是依赖垃圾回收，就意味着放弃了对于释放对象时机的精准控制，完全委托给回收器代管。一般来说，垃圾回收器就像奇怪的野兽般难以捉摸，要理解内存为何没有在预期的时机被释放可能颇具挑战。

• “控制优先”阵营会让你自己负责释放内存。程序的内存消耗完全掌握在你的手中，但避免悬空指针也完全成了你的责任。C 和 C++ 是这个阵营中仅有的两种主流语言。

  如果你永不犯错，这当然是很好的选择，但事实证明，只要是人就会犯错。从已收集的安全报告数据来看，指针滥用一直都是引发问题的罪魁祸首。

Rust 的目标是既安全又高效，所以这两种妥协都是无法接受的。但如果很容易两者兼得，那应该早就有人做到了。看来我们需要做一些根本性的变革。

Rust 通过限制程序使用指针的方式出人意料地打破了这种困局。本章和第 5 章将专门解释这些限制是什么以及它们为什么能起作用。现在，只需要知道一些惯用的常见结构可能不符合这些限制规则，而你要寻找替代方案。施加这些限制的最终目的是在混沌中建立足够的秩序，以便让 Rust 的编译期检查器有能力验证程序中是否存在内存安全错误：悬空指针、重复释放、使用未初始化的内存等。在运行期，指针仅仅是内存中的地址，和在 C 与 C++ 中一样。而不一样的是，Rust 编译器已然证明你的代码在安全地使用它们。

这些规则同样构成了 Rust 支持安全并发编程的基础。使用 Rust 精心设计的线程原语，那些确保代码在正确使用内存的规则，同样可以用于证明代码中不存在数据竞争。Rust 程序中的缺陷不会导致一个线程破坏另一个线程的数据，进而在系统中的无关部分引入难以重现的故障。多线程代码中的固有不确定性被隔离到了那些专门设计来处理它们的线程特性（比如互斥锁、消息通道、原子值等）上，而不必出现在普通的内存引用中。用 C 和 C++ 编写的多线程代码饱受诟病，但 Rust 很好地改变了这种局面。

Rust 的激进“赌注”是其成功的基础和语言的根源。即使有这种限制，该语言依然足够灵活，可以完成几乎所有任务，并且可以消除各种内存管理和并发错误。这些优点将会证明你值得调整自己的风格来适应它。正是因为我们（本书作者）在 C 和 C++ 方面拥有丰富的经验，所以才更加看好 Rust。对我们来说，与 Rust 的这项交易非常划算。

Rust 的一些规则可能与你在其他编程语言中看到的截然不同。在我们看来，学习 Rust 的核心挑战，就是学习如何用好这些规则并转化为你的优势。在本章中，我们将首先展示同一个根本问题在不同语言中的表现形式，以深入了解 Rust 规则背后的逻辑和意图。然后，我们将详细解释 Rust 的规则，看看所有权在概念层和实现层分别意味着什么、如何在各种场景中跟踪所有权的变化，以及在哪些情况下要改变或打破其中的一些规则，以提供更大的灵活性。

4.1 所有权

如果你读过大量 C 或 C++ 代码，可能遇到过这样的注释，即某个类的实例 拥有 它指向的某个其他对象。通常，拥有对象意味着可以决定何时释放此对象：当销毁拥有者时，它拥有的对象也会随之销毁。

假如有如下 C++ 代码：

std::string s = "frayed knot";

通常，字符串 s 在内存中的表示如图 4-1 所示。

图 4-1：栈上的 C++ std::string 值，指向其在堆上分配的缓冲区

在这里，实际的 std::string 对象本身总是正好有 3 个机器字长，包括指向分配在堆上的缓冲区的指针、缓冲区的总容量（在不得不为字符串分配更大的缓冲区之前，文本可以增长到多大），以及当前持有的文本的长度。这些都是 std::string 类私有的字段，使用者无法访问。

std::string 拥有自己的缓冲区：当程序销毁字符串时，字符串的析构函数会释放缓冲区。以前，一些 C++ 库会在多个 std::string 值之间共享同一个缓冲区，通过引用计数来决定何时释放此缓冲区。但较新版本的 C++ 规范有效地杜绝了这种表示法，所有现代 C++ 库使用的都是这里展示的方法。

在这些情况下，人们普遍认为，虽然其他代码也可以创建指向所拥有内存的临时指针，但在拥有者决定销毁拥有的对象之前，其他代码有责任确保其指针已消失。也就是说，你可以创建一个指向 std::string 的缓冲区中的字符的指针，但是当字符串被销毁时，你也必须让你的指针失效，并且要确保不再使用它。拥有者决定被拥有者的生命周期，其他所有人都必须尊重其决定。

这里使用了 std::string 作为 C++ 中所有权的示例：它只是标准库通常遵循的规约，尽管 C++ 鼓励人们都遵循类似的做法，但说到底，如何设计自己的类型还是要由你自己决定。

然而，在 Rust 中，所有权这个概念内置于语言本身，并通过编译期检查强制执行。每个值都有决定其生命周期的唯一拥有者。当拥有者被释放时，它拥有的值也会同时被释放，在 Rust 术语中，释放的行为被称为 丢弃（drop）。这些规则便于通过检查代码确定任意值的生命周期，也提供了系统级语言本应支持的对生命周期的控制。

变量拥有自己的值，当控制流离开声明变量的块时，变量就会被丢弃，因此它的值也会一起被丢弃。例如：

fn print_padovan() {
 let mut padovan = vec![1,1,1]; // 在此分配
 for i in 3..10 {
 let next = padovan[i-3] + padovan[i-2];
 padovan.push(next);
 }
 println!("P(1..10) = {:?}", padovan);
} // 在此丢弃

变量 padovan 的类型为 Vec<i32>，即一个 32 位整数向量。在内存中， padovan 的最终值如图 4-2 所示。

图 4-2：栈上的 Vec<i32>，指向其在堆中的缓冲区

这和之前展示过的 C++ std::string 非常相似，不过缓冲区中的元素都是 32 位整数，而不是字符。请注意，保存 padovan 指针、容量和长度的字都直接位于 print_padovan 函数的栈帧中，只有向量的缓冲区才分配在堆上。

和之前的字符串 s 一样，此向量拥有保存其元素的缓冲区。当变量 padovan 在函数末尾超出作用域时，程序将会丢弃此向量。因为向量拥有自己的缓冲区，所以此缓冲区也会一起被丢弃。

Rust 的 Box 类型是所有权的另一个例子。 Box<T> 是指向存储在堆上的 T 类型值的指针。可以调用 Box::new(v) 分配一些堆空间，将值 v 移入其中，并返回一个指向该堆空间的 Box。因为 Box 拥有它所指向的空间，所以当丢弃 Box 时，也会释放此空间。

例如，可以像下面这样在堆中分配一个元组：

{
 let point = Box::new((0.625, 0.5)); // 在此分配了point
 let label = format!("{:?}", point); // 在此分配了label
 assert_eq!(label, "(0.625, 0.5)");
} // 在此全都丢弃了

当程序调用 Box::new 时，它会在堆上为由两个 f64 值构成的元组分配空间，然后将其参数 (0.625, 0.5) 移进去，并返回指向该空间的指针。当控制流抵达对 assert_eq! 的调用时，栈帧如图 4-3 所示。

图 4-3：两个局部变量，它们各自在堆中拥有内存

栈帧本身包含变量 point 和 label，其中每个变量都指向其拥有的堆中内存。当丢弃它们时，它们拥有的堆中内存也会一起被释放。

就像变量拥有自己的值一样，结构体拥有自己的字段，元组、数组和向量则拥有自己的元素。

struct Person { name: String, birth: i32 }

let mut composers = Vec::new();
composers.push(Person { name: "Palestrina".to_string(),
 birth: 1525 });
composers.push(Person { name: "Dowland".to_string(),
 birth: 1563 });
composers.push(Person { name: "Lully".to_string(),
 birth: 1632 });
for composer in &composers {
 println!("{}, born {}", composer.name, composer.birth);
}

在这里， composers 是一个 Vec<Person>，即由结构体组成的向量，每个结构体都包含一个字符串和数值。在内存中， composers 的最终值如图 4-4 所示。

图 4-4：更复杂的所有权树

这里有很多所有权关系，但每个都一目了然： composers 拥有一个向量，向量拥有自己的元素，每个元素都是一个 Person 结构体，每个结构体都拥有自己的字段，并且字符串字段拥有自己的文本。当控制流离开声明 composers 的作用域时，程序会丢弃自己的值并将整棵所有权树一起丢弃。如果还存在其他类型的集合（可能是 HashMap 或 BTreeSet），那么处理的方式也是一样的。

现在，回过头来思考一下刚刚介绍的这些所有权关系的重要性。每个值都有一个唯一的拥有者，因此很容易决定何时丢弃它。但是每个值可能会拥有许多其他值，比如向量 composers 会拥有自己的所有元素。这些值还可能拥有其他值： composers 的每个元素都各自拥有一个字符串，该字符串又拥有自己的文本。

由此可见，拥有者及其拥有的那些值形成了一棵 树：值的拥有者是值的父节点，值拥有的值是值的子节点。每棵树的总根都是一个变量，当该变量超出作用域时，整棵树都将随之消失。可以在 composers 的图中看到这样的所有权树：它既不是“搜索树”那种数据结构意义上的“树”，也不是由 DOM 元素构成的 HTML 文档。相反，我们有一棵由混合类型构建的树，Rust 的单一拥有者规则将禁止任何可能让它们排列得比树结构更复杂的可能性。Rust 程序中的每一个值都是某棵树的成员，树根是某个变量。

Rust 程序通常不需要像 C 程序和 C++ 程序那样显式地使用 free 和 delete 来丢弃值。在 Rust 中丢弃一个值的方式就是从所有权树中移除它：或者离开变量的作用域，或者从向量中删除一个元素，或者执行其他类似的操作。这样一来，Rust 就会确保正确地丢弃该值及其拥有的一切。

从某种意义上说，Rust 确实不如其他语言强大：其他所有实用的编程语言都允许你构建出任意复杂的对象图，这些对象可以用你认为合适的方式相互引用。但正是因为 Rust 不那么强大，所以编辑器对你的程序所进行的分析才能更强大。Rust 的安全保证之所以可行，是因为在你的代码中可能出现的那些关系都更可控。这是之前提过的 Rust 的“激进赌注”的一部分：实际上，Rust 声称，解决问题的方式通常是灵活多样的，因此总是会有一些完美的解决方案能同时满足它所施加的限制。

迄今为止，我们已经解释过的这些所有权概念仍然过于严格，还处理不了某些场景。Rust 从几个方面扩展了这种简单的思想。

• 可以将值从一个拥有者转移给另一个拥有者。这允许你构建、重新排列和拆除树形结构。
• 像整数、浮点数和字符这样的非常简单的类型，不受所有权规则的约束。这些称为 Copy 类型。
• 标准库提供了引用计数指针类型 Rc 和 Arc，它们允许值在某些限制下有多个拥有者。
• 可以对值进行“借用”（borrow），以获得值的引用。这种引用是非拥有型指针，有着受限的生命周期。

这些策略中的每一个策略都为所有权模型带来了灵活性，同时仍然坚持着 Rust 的那些承诺。接下来我们将依次解释这几种方式，并会在第 5 章中介绍一些参考资料。

4.2 移动

在 Rust 中，对大多数类型来说，像为变量赋值、将其传给函数或从函数返回这样的操作都不会复制值，而是会 移动 值。源会把值的所有权转移给目标并变回未初始化状态，改由目标变量来控制值的生命周期。Rust 程序会以每次只移动一个值的方式建立和拆除复杂的结构。

你可能惊讶于 Rust 会改变这些基本操作的含义，确实如此，历史发展到今天，赋值应该已经是含义最明确的操作了。但是，如果仔细观察不同的语言处理赋值操作的方式，你会发现不同的编程流派之间实际上存在着相当明显的差异。对比这些差异也能很容易看出 Rust 做出这种选择的意义及其重要性。

考虑以下 Python 代码：

s = ['udon', 'ramen', 'soba']
t = s
u = s

每个 Python 对象都有一个引用计数，以用于跟踪当前正引用着此值的数量。因此，在对 s 赋值之后，程序的状态如图 4-5 所示。（请注意，这里忽略了一些字段。）

图 4-5：Python 如何在内存中表示字符串列表

由于只有 s 指向列表，因此该列表的引用计数为 1。由于列表是唯一指向这些字符串的对象，因此它们各自的引用计数也是 1。

当程序执行对 t 和 u 的赋值时会发生什么？Python 会直接让目标指向与源相同的对象，并增加对象的引用计数来实现赋值。所以程序的最终状态如图 4-6 所示。

图 4-6：在 Python 中将 s 赋值给 t 和 u 的结果

Python 已经将指针从 s 复制到 t 和 u，并将此列表的引用计数更新为 3。Python 中的赋值开销极低，但因为它创建了对对象的新引用，所以必须维护引用计数才能知道何时可以释放该值。

现在考虑类似的 C++ 代码：

using namespace std;
vector<string> s = { "udon", "ramen", "soba" };
vector<string> t = s;
vector<string> u = s;

s 的原始值在内存中如图 4-7 所示。

图 4-7：C++ 如何表示内存中的字符串向量

当程序将 s 赋值给 t 和 u 时会发生什么？在 C++ 中，把 std::vector 赋值给其他元素会生成一个向量的副本， std::string 的行为也类似。所以当程序执行到这段代码的末尾时，它实际上已经分配了 3 个向量和 9 个字符串，如图 4-8 所示。

图 4-8：在 C++ 中将 s 赋值给 t 和 u 的结果

理论上，如果涉及某些特定的值，那么 C++ 中的赋值可能会消耗超乎想象的内存和处理器时间。然而，其优点是程序很容易决定何时释放这些内存：当变量超出作用域时，此处分配的所有内容都会自动清除。

从某种意义上说，C++ 和 Python 选择了相反的权衡：Python 以需要引用计数（以及更广泛意义上的垃圾回收）为代价，让赋值的开销变得非常低。C++ 则选择让全部内存的所有权保持清晰，而代价是在赋值时要执行对象的深拷贝。一般来说，C++ 程序员不太热衷这种选择：深拷贝的开销可能很昂贵，而且通常有更实用的替代方案。

那么类似的程序在 Rust 中会怎么做呢？请看如下代码：

let s = vec!["udon".to_string(), "ramen".to_string(), "soba".to_string()];
let t = s;
let u = s;

与 C 和 C++ 一样，Rust 会将纯字符串字面量（如 "udon"）放在只读内存中，因此为了与 C++ 示例和 Python 示例进行更清晰的比较，此处调用了 to_string 以获取堆上分配的 String 值。

在执行了 s 的初始化之后，由于 Rust 和 C++ 对向量和字符串使用了类似的表示形式，因此情况看起来就和 C++ 中一样，如图 4-9 所示。

图 4-9：Rust 如何表示内存中的字符串向量

但要记住，在 Rust 中，大多数类型的赋值会将值从源 转移 给目标，而源会回到未初始化状态。因此在初始化 t 之后，程序的内存如图 4-10 所示。

图 4-10：Rust 中将 s 赋值给 t 的结果

这里发生了什么？初始化语句 let t = s; 将向量的 3 个标头字段从 s 转移给了 t，现在 t 拥有此向量。向量的元素保持原样，字符串也没有任何变化。每个值依然只有一个拥有者，尽管其中一个已然易手。整个过程中没有需要调整的引用计数，不过编译器现在会认为 s 是未初始化状态。

那么当我们执行初始化语句 let u = s; 时会发生什么呢？这会将尚未初始化的值 s 赋给 u。Rust 明智地禁止使用未初始化的值，因此编译器会拒绝此代码并报告如下错误：

error: use of moved value: `s`
 |
7 | let s = vec!["udon".to_string(), "ramen".to_string(), "soba".to_string()];
 | - move occurs because `s` has type `Vec<String>`,
 | which does not implement the `Copy` trait
8 | let t = s;
 | - value moved here
9 | let u = s;
 | ^ value used here after move

思考一下 Rust 在这里使用移动语义的影响。与 Python 一样，赋值操作开销极低：程序只需将向量的三字标头从一个位置移到另一个位置即可。但与 C++ 一样，所有权始终是明确的：程序不需要引用计数或垃圾回收就能知道何时释放向量元素和字符串内容。

代价是如果需要同时访问它们，就必须显式地要求复制。如果想达到与 C++ 程序相同的状态（每个变量都保存一个独立的结构副本），就必须调用向量的 clone 方法，该方法会执行向量及其元素的深拷贝：

let s = vec!["udon".to_string(), "ramen".to_string(), "soba".to_string()];
let t = s.clone();
let u = s.clone();

还可以使用 Rust 的引用计数来实现与 Python 类似的操作，4.4 节会简要讨论这些内容。

4.2.1 更多移动类操作

在先前的例子中，我们已经展示了如何初始化工作——在变量进入 let 语句的作用域时为它们提供值。给变量赋值则与此略有不同，如果你将一个值转移给已初始化的变量，那么 Rust 就会丢弃该变量的先前值。例如：

let mut s = "Govinda".to_string();
s = "Siddhartha".to_string(); // 在这里丢弃了值"Govinda"

在上述代码中，当程序将字符串 "Siddhartha" 赋值给 s 时，它的先前值 "Govinda" 会首先被丢弃。但请考虑以下代码：

let mut s = "Govinda".to_string();
let t = s;
s = "Siddhartha".to_string(); // 这里什么也没有丢弃

这一次， t 从 s 接手了原始字符串的所有权，所以当给 s 赋值时，它是未初始化状态。这种情况下不会丢弃任何字符串。

我们在这个例子中使用了初始化和赋值，因为它们很简单，但 Rust 还将“移动”的语义应用到了几乎所有对值的使用上。例如，将参数传给函数会将所有权转移给函数的参数、从函数返回一个值会将所有权转移给调用者、构建元组会将值转移给元组。

你现在可以更好地理解 4.1 节的示例中到底发生过什么了。例如，我们在构建 composers 向量时，是这样写的：

struct Person { name: String, birth: i32 }

let mut composers = Vec::new();
composers.push(Person { name: "Palestrina".to_string(),
 birth: 1525 });

这段代码展示了除初始化和赋值之外发生移动的几个地方。

从函数返回值

调用 Vec::new() 构造一个新向量并返回，返回的不是指向此向量的指针，而是向量本身：它的所有权从 Vec::new 转移给了变量 composers。同样， to_string 调用返回的是一个新的 String 实例。

构造出新值

新 Person 结构体的 name 字段是用 to_string 的返回值初始化的。该结构体拥有这个字符串的所有权。

将值传给函数

整个 Person 结构体（不是指向它的指针）被传给了向量的 push 方法，此方法会将该结构体移动到向量的末尾。向量接管了 Person 的所有权，因此也间接接手了 name 这个 String 的所有权。

像这样移动值乍一看可能效率低下，但有两点需要牢记。首先，移动的永远是值本身，而不是这些值拥有的堆存储。对于向量和字符串， 值本身 就是指单独的“三字标头”，幕后的大型元素数组和文本缓冲区仍然位于它们在堆中的位置。其次，Rust 编译器在生成代码时擅长“看穿”这一切动作。在实践中，机器码通常会将值直接存储在它应该在的位置。2

4.2.2 移动与控制流

前面的例子中都有非常简单的控制流，那么该如何在更复杂的代码中移动呢？一般性原则是，如果一个变量的值有可能已经移走，并且从那以后尚未明确赋予其新值，那么它就可以被看作是未初始化状态。如果一个变量在执行了 if 表达式中的条件后仍然有值，那么就可以在这两个分支中使用它：

let x = vec![10, 20, 30];
if c {
 f(x); // ……可以在这里移动x
} else {
 g(x); // ……也可以在这里移动x
}
h(x); // 错误：只要任何一条路径用过它，x在这里就是未初始化状态

出于类似的原因，禁止在循环中进行变量移动：

let x = vec![10, 20, 30];
while f() {
 g(x); // 错误：x已经在第一次迭代中移动出去了，在第二次迭代中，它成了未初始化状态
}

也就是说，除非在下一次迭代中明确赋予 x 一个新值，否则就会出错。

let mut x = vec![10, 20, 30];
while f() {
 g(x); // 从x移动出去了
 x = h(); // 赋予x一个新值
}
e(x);

4.2.3 移动与索引内容

前面提到过，移动会令其来源变成未初始化状态，因为目标将获得该值的所有权。但并非值的每种拥有者都能变成未初始化状态。例如，考虑以下代码：

// 构建一个由字符串"101"、"102"……"105"组成的向量
let mut v = Vec::new();
for i in 101 .. 106 {
 v.push(i.to_string());
}

// 从向量中随机抽取元素
let third = v[2]; // 错误：不能移动到Vec索引结构之外3
let fifth = v[4]; // 这里也一样

3注意这里写的是 v[2] 而非 &v[2]。——译者注

为了解决这个问题，Rust 需要以某种方式记住向量的第三个元素和第五个元素是未初始化状态，并要跟踪该信息直到向量被丢弃。通常的解决方案是，让每个向量都携带额外的信息来指示哪些元素是活动的，哪些元素是未初始化的。这显然不是系统编程语言应该做的。向量应该只是向量，不应该携带额外的信息或状态。事实上，Rust 会拒绝前面的代码并报告如下错误：

error: cannot move out of index of `Vec<String>`
 |
14 | let third = v[2];
 | ^^^^
 | |
 | move occurs because value has type `String`,
 | which does not implement the `Copy` trait
 | help: consider borrowing here: `&v[2]`

移动第五个元素时 Rust 也会报告类似的错误。在这条错误消息中，Rust 还建议使用引用，因为你可能只是想访问该元素而不是移动它，这通常确实是你想要做的。但是，如果真想将一个元素移出向量该怎么办呢？需要找到一种在遵循类型限制的情况下执行此操作的方法。以下是 3 种可能的方法：

// 构建一个由字符串"101"、"102"……"105"组成的向量
let mut v = Vec::new();
for i in 101 .. 106 {
 v.push(i.to_string());
}

// 方法一：从向量的末尾弹出一个值：
let fifth = v.pop().expect("vector empty!");
assert_eq!(fifth, "105");

// 方法二：将向量中指定索引处的值与最后一个值互换，并把前者移动出来：
let second = v.swap_remove(1);
assert_eq!(second, "102");

// 方法三：把要取出的值和另一个值互换：
let third = std::mem::replace(&mut v[2], "substitute".to_string());
assert_eq!(third, "103");

// 看看向量中还剩下什么
assert_eq!(v, vec!["101", "104", "substitute"]);

每种方法都能将一个元素移出向量，但仍会让向量处于完全填充状态，只是向量可能会变小。

像 Vec 这样的集合类型通常也会提供在循环中消耗所有元素的方法：

let v = vec!["liberté".to_string(),
 "égalité".to_string(),
 "fraternité".to_string()];

for mut s in v {
 s.push('!');
 println!("{}", s);
}

当我们将向量直接传给循环（如 for ... in v）时，会将向量从 v 中 移动 出去，让 v 变成未初始化状态。 for 循环的内部机制会获取向量的所有权并将其分解为元素。在每次迭代中，循环都会将另一个元素转移给变量 s。由于 s 现在拥有字符串，因此可以在打印之前在循环体中修改它。在循环的过程中，向量本身对代码不再可见，因此也就无法观察到它正处在某种部分清空的状态。4

如果需要从拥有者中移出一个编译器无法跟踪的值，那么可以考虑将拥有者的类型更改为能动态跟踪自己是否有值的类型。例如，下面是前面例子的一个变体：

struct Person { name: Option<String>, birth: i32 }

let mut composers = Vec::new();
composers.push(Person { name: Some("Palestrina".to_string()),
 birth: 1525 });

但不能像下面这样做：

let first_name = composers[0].name;

这只会引发与前面一样的“无法移动到索引结构之外”错误。但是因为已将 name 字段的类型从 String 改成了 Option<String>，所以这意味着 None 也是该字段要保存的合法值。因此，可以像下面这样做：

let first_name = std::mem::replace(&mut composers[0].name, None);
assert_eq!(first_name, Some("Palestrina".to_string()));
assert_eq!(composers[0].name, None);

replace 调用会移出 composers[0].name 的值，将 None 留在原处，并将原始值的所有权转移给其调用者。事实上，这种使用 Option 的方式非常普遍，所以该类型专门为此提供了一个 take 方法，以便更清晰地写出上述操作，如下所示：

let first_name = composers[0].name.take();

这个 take 调用与之前的 replace 调用具有相同的效果。

4.3 Copy 类型：关于移动的例外情况

迄今为止，本章所展示的值移动示例都涉及向量、字符串和其他可能占用大量内存且复制成本高昂的类型。移动能让这些类型的所有权清晰且赋值开销极低。但对于像整数或字符这样的简单类型，如此谨小慎微的处理方式确实没什么必要。

下面来比较一下用 String 进行赋值和用 i32 进行赋值时内存中有什么不同：

let string1 = "somnambulance".to_string();
let string2 = string1;

let num1: i32 = 36;
let num2 = num1;

运行这段代码后，内存如图 4-11 所示。

图 4-11：用 String 赋值会移动值，而用 i32 赋值会复制值

与前面的向量一样，赋值会将 string1 转移给 string2，这样就不会出现两个字符串负责释放同一个缓冲区的情况。但是， num1 和 num2 的情况有所不同。 i32 只是内存中的几字节，它不拥有任何堆资源，也不会实际依赖除本身的字节之外的任何内存。当我们将它的每一位转移给 num2 时，其实已经为 num1 制作了一个完全独立的副本。

移动一个值会使移动的源变成未初始化状态。不过，尽管将 string1 视为未初始化变量确实符合其基本意图，但以这种方式对待 num1 毫无意义，继续使用 num1 也不会造成任何问题。移动在这里并无好处，反而会造成不便。

之前我们谨慎地说过， 大多数 类型会被移动，现在该谈谈例外情况了，即那些被 Rust 指定成 Copy 类型 的类型。对 Copy 类型的值进行赋值会复制这个值，而不会移动它。赋值的源仍会保持已初始化和可用状态，并且具有与之前相同的值。把 Copy 类型传给函数和构造器的行为也是如此。

标准的 Copy 类型包括所有机器整数类型和浮点数类型、 char 类型和 bool 类型，以及某些其他类型。 Copy 类型的元组或固定大小的数组本身也是 Copy 类型。

只有那些可以通过简单地复制位来复制其值的类型才能作为 Copy 类型。前面解释过， String 不是 Copy 类型，因为它拥有从堆中分配的缓冲区。出于类似的原因， Box<T> 也不是 Copy 类型，因为它拥有从堆中分配的引用目标。代表操作系统文件句柄的 File 类型不是 Copy 类型，因为复制这样的值需要向操作系统申请另一个文件句柄。类似地， MutexGuard 类型表示一个互斥锁，它也不是 Copy 类型：复制这种类型毫无意义，因为每次只能有一个线程持有互斥锁。

根据经验，任何在丢弃值时需要做一些特殊操作的类型都不能是 Copy 类型： Vec 需要释放自身元素、 File 需要关闭自身文件句柄、 MutexGuard 需要解锁自身互斥锁，等等。对这些类型进行逐位复制会让我们无法弄清哪个值该对原始资源负责。

那么自定义类型呢？默认情况下， struct 类型和 enum 类型不是 Copy 类型：

struct Label { number: u32 }

fn print(l: Label) { println!("STAMP: {}", l.number); }
let l = Label { number: 3 };
print(l);
println!("My label number is: {}", l.number);

这无法编译。Rust 会报错：

error: borrow of moved value: `l`
 |
10 | let l = Label { number: 3 };
 | - move occurs because `l` has type `main::Label`,
 | which does not implement the `Copy` trait
11 | print(l);
 | - value moved here
12 | println!("My label number is: {}", l.number);
 | ^^^^^^^^
 | value borrowed here after move

由于 Label 不是 Copy 类型，因此将它传给 print 会将值的所有权转移给 print 函数，然后在返回之前将其丢弃。这样做显然是愚蠢的， Label 中只有一个 u32，因此没有理由在将 l 传给 print 时移动这个值。

但是用户定义的类型不是 Copy 类型这一点只是默认情况而已。如果此结构体的所有字段本身都是 Copy 类型，那么也可以通过将属性 #[derive(Copy, Clone)] 放置在此定义之上来创建 Copy 类型，如下所示：

#[derive(Copy, Clone)]
struct Label { number: u32 }

经过此项更改，前面的代码可以顺利编译了。但是，如果试图在一个其字段不全是 Copy 类型的结构体上这样做，则仍然行不通。假设要编译如下代码：

#[derive(Copy, Clone)]
struct StringLabel { name: String }

那么就会引发如下错误：

error: the trait `Copy` may not be implemented for this type
 |
7 | #[derive(Copy, Clone)]
 | ^^^^
8 | struct StringLabel { name: String }
 | ------------ this field does not implement `Copy`

为什么符合条件的用户定义类型不能自动成为 Copy 类型呢？这是因为类型是否为 Copy 对于在代码中使用它的方式有着重大影响： Copy 类型更灵活，因为赋值和相关操作不会把原始值变成未初始化状态。但对类型的实现者而言，情况恰恰相反： Copy 类型可以包含的类型非常有限，而非 Copy 类型可以在堆上分配内存并拥有其他种类的资源。因此，创建一个 Copy 类型代表着实现者的郑重承诺：如果以后确有必要将其改为非 Copy 类型，则使用它的大部分代码可能需要进行调整。

虽然 C++ 允许重载赋值运算符以及定义专门的复制构造函数和移动构造函数，但 Rust 并不允许这种自定义行为。在 Rust 中，每次移动都是字节级的一对一浅拷贝，并让源变成未初始化状态。复制也是如此，但会保留源的初始化状态。这确实意味着 C++ 类可以提供 Rust 类型所无法提供的便捷接口，比如可以在看似普通的代码中隐式调整引用计数、把昂贵的复制操作留待以后进行，或使用另一些复杂的实现技巧。

但这种灵活性的代价是，作为一门语言，C++ 的基本操作（比如赋值、传参和从函数返回值）变得更难预测。例如，本章的前半部分展示过在 C++ 中将一个变量赋值给另一个变量时可能需要任意数量的内存和处理器时间。Rust 的一个原则是：各种开销对程序员来说应该是显而易见的。基本操作必须保持简单，而潜在的昂贵操作应该是显式的，比如前面例子中对 clone 的调用就是在对向量及其包含的字符串进行深拷贝。

本节用复制（ Copy）和克隆（ Clone）这两个模糊的术语描述了某个类型可能具备的特征。它们实际上是 特型 的示例。特型是 Rust 语言中的开放式工具，用于根据你对类型可以执行的操作来对类型进行分类。第 11 章会对特型做一般性讲解，第 13 章会专门讲解 Copy 和 Clone 这两个特型。

4.4 Rc 与 Arc：共享所有权

尽管在典型的 Rust 代码中大多数值会有唯一的拥有者，但在某些情况下，很难为每个值都找到具有所需生命周期的单个拥有者，你会希望某个值只要存续到每个人都用完它就好。对于这些情况，Rust 提供了引用计数指针类型 Rc 和 Arc [ Arc 是 原子引用计数(atomic reference count) 的缩写 ]。正如你对 Rust 的期待一样，这些类型用起来完全安全：你不会忘记调整引用计数，不会创建 Rust 无法注意到的指向引用目标的其他指针，也不会偶遇那些常与 C++ 中的引用计数指针如影随形的各种问题。

Rc 类型和 Arc 类型非常相似，它们之间唯一的区别是 Arc 可以安全地在线程之间直接共享，而普通 Rc 会使用更快的非线程安全代码来更新其引用计数。如果不需要在线程之间共享指针，则没有理由为 Arc 的性能损失“埋单”，因此应该使用 Rc，Rust 能防止你无意间跨越线程边界传递它。这两种类型在其他方面都是等效的，所以本节的其余部分只会讨论 Rc。

之前我们展示过 Python 如何使用引用计数来管理值的生命周期。你可以使用 Rc 在 Rust 中获得类似的效果。考虑以下代码：

use std::rc::Rc;

// Rust能推断出所有这些类型，这里写出它们只是为了讲解时清晰
let s: Rc<String> = Rc::new("shirataki".to_string());
let t: Rc<String> = s.clone();
let u: Rc<String> = s.clone();

对于任意类型 T， Rc<T> 值是指向附带引用计数的在堆上分配的 T 型指针。克隆一个 Rc<T> 值并不会复制 T，相反，它只会创建另一个指向它的指针并递增引用计数。所以前面的代码在内存中会生成图 4-12 所示的结果。

图 4-12：具有 3 个引用的引用计数字符串

这 3 个 Rc<String> 指针指向了同一个内存块，其中包含引用计数和 String 本身的空间。通常的所有权规则适用于 Rc 指针本身，当丢弃最后一个现有 Rc 时，Rust 也会丢弃 String。

可以直接在 Rc<String> 上使用 String 的任何常用方法：

assert!(s.contains("shira"));
assert_eq!(t.find("taki"), Some(5));
println!("{} are quite chewy, almost bouncy, but lack flavor", u);

Rc 指针拥有的值是不可变的。如果你试图将一些文本添加到字符串的末尾：

s.push_str(" noodles");

那么 Rust 会拒绝：

error: cannot borrow data in an `Rc` as mutable
 |
13 | s.push_str(" noodles");
 | ^ cannot borrow as mutable
 |

Rust 的内存和线程安全保证的基石是：确保不会有任何值是既共享又可变的。Rust 假定 Rc 指针的引用目标通常都可以共享，因此就不能是可变的。第 5 章会解释为什么这个限制很重要。

使用引用计数管理内存的一个众所周知的问题是，如果有两个引用计数的值是相互指向的，那么其中一个值就会让另一个值的引用计数保持在 0 以上，因此这些值将永远没机会释放，如图 4-13 所示。

图 4-13：循环引用计数——这些对象都没机会释放

以这种方式在 Rust 中造成值的泄漏也是有可能的，但这种情况非常少见。只要不在某个时刻让旧值指向新值，就无法建立循环。这显然要求旧值是可变的。由于 Rc 指针会保证其引用目标不可变，因此通常不可能建立这种循环引用。但是，Rust 确实提供了创建其他不可变值中的可变部分的方法，这称为 内部可变性，9.11 节会详细介绍。如果将这些技术与 Rc 指针结合使用，则确实可以建立循环并造成内存泄漏。

有时可以通过对某些链接使用 弱引用指针 std::rc::Weak 来避免建立 Rc 指针循环。但是，本节不会介绍这些内容，有关详细信息，请参阅标准库的文档。

移动和引用计数指针是缓解所有权树严格性问题的两种途径。在第 5 章中，我们将研究第三种途径：借用对值的引用。一旦你熟悉了所有权和借用这两个概念，就已经翻越了 Rust 学习曲线中最陡峭的部分，并为发挥 Rust 的独特优势做好了准备。

第 5 章 引用

图书馆（库）1无法弥补个人（程序员）能力的不足。

——Mark Miller

迄今为止，我们看到的所有指针类型（无论是简单的 Box<T> 堆指针，还是 String 值和 Vec 值内部的指针）都是拥有型指针，这意味着当拥有者被丢弃时，它的引用目标也会随之消失。Rust 还有一种名为 引用（reference）的非拥有型指针，这种指针对引用目标的生命周期毫无影响。

事实上，影响是反过来的：引用的生命周期绝不能超出其引用目标。你的代码必须遵循这样的规则，即任何引用的生命周期都不可能超出它指向的值。为了强调这一点，Rust 把创建对某个值的引用的操作称为 借用（borrow）那个值：凡是借用，终须归还。

如果在读到“你的代码必须遵循这样的规则”这句话的时候不知道如何是好，那么你并非特例。引用本身确实没什么特别之处——说到底，它们只是地址而已。但用以让引用保持安全的规则，对 Rust 来说是一种创新，除了一些研究性语言，你不可能在其他编程语言中见到类似的规则。尽管这些规则是 Rust 中掌握起来最费心力的部分，但它们在防止经典的、常见的错误方面的覆盖度令人叹为观止，它们对多线程编程的影响也是革命性的。这又是 Rust 的“激进赌注”。

本章将介绍引用在 Rust 中的工作方式，我们会展开讲解引用、函数和自定义类型是如何通过包含生命周期信息来确保它们被安全使用的，并阐明这些努力为何能在编译期就避免一些常见类别的缺陷，而不必在运行期付出性能方面的代价。

5.1 对值的引用

假设我们要创建一张表格，列出文艺复兴时期某一特定类型的艺术家和他们的作品。Rust 的标准库包含一个哈希表类型，所以可以像下面这样定义我们的类型：

use std::collections::HashMap;

type Table = HashMap<String, Vec<String>>;

换句话说，这是一个将 String 值映射到 Vec<String> 值的哈希表，用于将艺术家的名字对应到他们作品名称的列表中。由于可以使用 for 循环遍历 HashMap 的条目，因此需要编写一个函数来打印 Table 的内容：

fn show(table: Table) {
 for (artist, works) in table {
 println!("works by {}:", artist);
 for work in works {
 println!(" {}", work);
 }
 }
}

构建和打印这个表格的代码也一目了然：

fn main() {
 let mut table = Table::new();
 table.insert("Gesualdo".to_string(),
 vec!["many madrigals".to_string(),
 "Tenebrae Responsoria".to_string()]);
 table.insert("Caravaggio".to_string(),
 vec!["The Musicians".to_string(),
 "The Calling of St. Matthew".to_string()]);
 table.insert("Cellini".to_string(),
 vec!["Perseus with the head of Medusa".to_string(),
 "a salt cellar".to_string()]);

 show(table);
}

一切正常：

$ cargo run
 Running `/home/jimb/rust/book/fragments/target/debug/fragments`
works by Gesualdo:
 many madrigals
 Tenebrae Responsoria
works by Cellini:
 Perseus with the head of Medusa
 a salt cellar
works by Caravaggio:
 The Musicians
 The Calling of St. Matthew
$

但是，如果你已经阅读过第 4 章关于“移动”的部分，就会对 show 这个函数的定义产生一些疑问。特别是， HashMap 不是 Copy 类型——也不可能是，因为它拥有能动态分配大小的表格。所以当程序调用 show(table) 时，整个结构就移动到了函数中，而变量 table 变成了未初始化状态。（而且它还会以乱序迭代其内容，所以如果你看到的顺序与这里不同，请不要担心，这是正常现象。）现在如果调用方代码试图使用 table，则会遇到麻烦：

...
show(table);
assert_eq!(table["Gesualdo"][0], "many madrigals");

Rust 会报错说 table 不再可用：

error: borrow of moved value: `table`
 |
20 | let mut table = Table::new();
 | --------- move occurs because `table` has type
 | `HashMap<String, Vec<String>>`,
 | which does not implement the `Copy` trait
...
31 | show(table);
 | ----- value moved here
32 | assert_eq!(table["Gesualdo"][0], "many madrigals");
 | ^^^^^ value borrowed here after move

事实上，如果查看 show 的定义，你会发现外层的 for 循环获取了哈希表的所有权并完全消耗掉了，并且内部的 for 循环对每个向量执行了相同的操作。（之前我们在 4.2.3 节的示例中看到过这种行为。）由于移动的语义特点，我们只是想把它打印出来，却完全破坏了整个结构。Rust，你可“真行”！

处理这个问题的正确方式是使用引用。引用能让你在不影响其所有权的情况下访问值。引用分为以下两种。

• 共享引用 允许你读取但不能修改其引用目标。但是，你可以根据需要同时拥有任意数量的对特定值的共享引用。表达式 &e 会产生对 e 值的共享引用，如果 e 的类型为 T，那么 &e 的类型就是 &T，读作“ref T”。共享引用是 Copy 类型。
• 可变引用 允许你读取和修改值。但是，一旦一个值拥有了可变引用，就无法再对该值创建其他任何种类的引用了。表达式 &mut e 会产生一个对 e 值的可变引用，可以将其类型写成 &mut T，读作“ref mute T”。可变引用不是 Copy 类型。

可以将共享引用和可变引用之间的区别视为在编译期强制执行“多重读取”或“单一写入”规则的一种手段。事实上，这条规则不仅适用于引用，也适用于所引用值的拥有者。只要存在对一个值的共享引用，即使是它的拥有者也不能修改它，该值会被锁定。当 show 正在使用 table 时，没有人可以修改它。类似地，如果有某个值的可变引用，那么它就会独占对该值的访问权，在可变引用消失之前，即使拥有者也根本无法使用该值。事实证明，让共享和修改保持完全分离对于内存安全至关重要，本章会在稍后内容中讨论原因。

我们示例中的打印函数不需要修改表格，只需读取其内容即可。所以调用者可以向它传递一个对表的共享引用，如下所示：

show(&table);

引用是非拥有型指针，因此 table 变量仍然是整个结构的拥有者， show 刚刚只是借用了一会儿。当然，我们需要调整 show 的定义来匹配它，但必须仔细观察才能看出差异：

fn show(table: &Table) {
 for (artist, works) in table {
 println!("works by {}:", artist);
 for work in works {
 println!(" {}", work);
 }
 }
}

show 中的 table 参数的类型已从 Table 变成了 &Table：现在不再按值传入 table（那样会将所有权转移到函数中），而是传入了共享引用。这是代码上的唯一变化。但是当我们深入函数体了解其工作原理时，这会有怎样的影响呢？

在以前的版本中，外部 for 循环获取了此 HashMap 的所有权并消耗掉了它，但在新版本中，它收到了对 HashMap 的共享引用。迭代中对 HashMap 的共享引用就是对每个条目的键和值的共享引用： artist 从 String 变成了 &String，而 works 从 Vec<String> 变成了 &Vec<String>。

内层循环也有类似的改变。迭代中对向量的共享引用就是对其元素的共享引用，因此 work 现在是 &String。此函数的任何地方都没有发生过所有权转移，它只会传递非拥有型引用。

现在，如果想写一个函数来按字母顺序排列每位艺术家的作品，那么只通过共享引用是不够的，因为共享引用不允许修改。而这个排序函数需要对表进行可变引用：

fn sort_works(table: &mut Table) {
 for (_artist, works) in table {
 works.sort();
 }
}

于是我们需要传入一个：

sort_works(&mut table);

这种可变借用使 sort_works 能够按照向量的 sort 方法的要求读取和修改此结构。

当通过将值的所有权转移给函数的方式将这个值传给函数时，就可以说 按值 传递了它。如果改为将值的引用传给函数，就可以说 按引用 传递了它。例如，我们刚刚修复了 show 函数，将其改为按引用而不是按值接受 table。许多语言中也有这种区分，但在 Rust 中这尤为重要，因为它阐明了所有权是如何受到影响的。

5.2 使用引用

前面的示例展示了引用的一个非常典型的用途：允许函数在不获取所有权的情况下访问或操纵某个结构。但引用比这要灵活得多，下面我们通过一些示例来更详细地了解引用的用法。

5.2.1 Rust 引用与 C++ 引用

如果熟悉 C++ 中的引用，你就会知道它们确实与 Rust 引用有某些共同点。最重要的是，它们都只是机器级别的地址。但在实践中，Rust 的引用会给人截然不同的感觉。

在 C++ 中，引用是通过类型转换隐式创建的，并且是隐式解引用的：

// C++代码！
int x = 10;
int &r = x; // 初始化时隐式创建引用
assert(r == 10); // 对r隐式解引用，以查看x的值
r = 20; // 把20存入x，r本身仍然指向x

在 Rust 中，引用是通过 & 运算符显式创建的，同时要用 * 运算符显式解引用：

// 从这里开始回到Rust代码
let x = 10;
let r = &x; // &x是对x的共享引用
assert!(*r == 10); // 对r显式解引用

要创建可变引用，可以使用 &mut 运算符：

let mut y = 32;
let m = &mut y; // &muty是对y的可变引用
*m += 32; // 对m显式解引用，以设置y的值
assert!(*m == 64); // 来看看y的新值

也许你还记得，当我们修复 show 函数以通过引用而非值来获取艺术家表格时，并未使用过 * 运算符。这是为什么呢？

由于引用在 Rust 中随处可见，因此 . 运算符就会按需对其左操作数隐式解引用：

struct Anime { name: &'static str, bechdel_pass: bool }
let aria = Anime { name: "Aria: The Animation", bechdel_pass: true };
let anime_ref = &aria;
assert_eq!(anime_ref.name, "Aria: The Animation");

// 与上一句等效，但把解引用过程显式地写了出来
assert_eq!((*anime_ref).name, "Aria: The Animation");

show 函数中使用的 println! 宏会展开成使用 . 运算符的代码，因此它也能利用这种隐式解引用的方式。

在进行方法调用时， . 运算符也可以根据需要隐式借用对其左操作数的引用。例如， Vec 的 sort 方法就要求参数是对向量的可变引用，因此这两个调用是等效的：

let mut v = vec![1973, 1968];
v.sort(); // 隐式借用对v的可变引用
(&mut v).sort(); // 等效，但是更烦琐

简而言之，C++ 会在引用和左值（引用内存中位置的表达式）之间隐式转换，并且这种转换会出现在任何需要转换的地方，而在 Rust 中要使用 & 运算符和 * 运算符来创建引用（借用）和追踪引用（解引用），不过 . 运算符不需要做这种转换，它会隐式借用和解引用。

5.2.2 对引用变量赋值

把引用赋值给某个引用变量会让该变量指向新的地方：

let x = 10;
let y = 20;
let mut r = &x;

if b { r = &y; }

assert!(*r == 10 || *r == 20);

引用 r 最初指向 x。但如果 b 为 true，则代码会把它改为指向 y，如图 5-1 所示。

图 5-1：引用 r 现在指向 y 而不再是 x

乍一看，这种行为可能太显而易见，不值一提：现在 r 当然会指向 y，因为我们在其中存储了 &y。但特意指出这一点是因为 C++ 引用的行为与此截然不同：如前所述，在 C++ 中对引用赋值会将新值存储在其引用目标中而非指向新值。C++ 的引用一旦完成初始化，就无法再指向别处了。

5.2.3 对引用进行引用

Rust 允许对引用进行引用：

struct Point { x: i32, y: i32 }
let point = Point { x: 1000, y: 729 };
let r: &Point = &point;
let rr: &&Point = &r;
let rrr: &&&Point = &rr;

（为了让讲解更清晰，我们标出了引用的类型，但你可以省略它们，这里没有什么是 Rust 无法自行推断的。） . 运算符会追踪尽可能多层次的引用来找到它的目标：

assert_eq!(rrr.y, 729);

在内存中，引用的排列方式如图 5-2 所示。

图 5-2：对引用的引用链

在这里，表达式 rrr.y 根据 rrr 的类型的指引遍历了 3 层引用才取到相应 Point 的 y 字段。

5.2.4 比较引用

就像 . 运算符一样，Rust 的比较运算符也能“看穿”任意数量的引用：

let x = 10;
let y = 10;

let rx = &x;
let ry = &y;

let rrx = ℞
let rry = &ry;

assert!(rrx <= rry);
assert!(rrx == rry);

虽然 rrx 和 rry 指向的是不同的值（ rx 和 ry），这里的断言最终仍然会成功，因为 == 运算符会追踪所有引用并对它们的最终目标 x 和 y 进行比较。这几乎总是你期望的行为，尤其是在编写泛型函数时。如果你真想知道两个引用是否指向同一块内存，可以使用 std::ptr::eq，它会将两者作为地址进行比较：

assert!(rx == ry); // 它们引用的目标值相等
assert!(!std::ptr::eq(rx, ry)); // 但所占据的地址（自身的值）不同

但要注意，比较运算符的操作数（包括引用型操作数）必须具有完全相同的类型。

assert!(rx == rrx); // 错误：`&i32`与`&&i32`的类型不匹配
assert!(rx == *rrx); // 这样没问题

5.2.5 引用永不为空

Rust 的引用永远都不会为空。与 C 的 NULL 或 C++ 的 nullptr 类似的东西是不存在的。引用没有默认初始值（在初始化之前不能使用任何变量，无论其类型如何），并且 Rust 不会将整数转换为引用（在 unsafe 代码外）。因此，不能将 0 转换成引用。

C 代码和 C++ 代码通常会使用空指针来指示值的缺失：当可用内存充足时， malloc 函数会返回指向新内存块的指针，否则会返回 nullptr。在 Rust 中，如果需要用一个值来表示对某个“可能不存在”事物的引用，请使用类型 Option<&T>。在机器码级别，Rust 会将 None 表示为空指针，将 Some(r) 表示为非零地址（其中 r 是 &T 型的值），因此 Option<&T> 与 C 或 C++ 中的可空指针一样高效，但更安全：它的类型要求你在使用之前必须检查它是否为 None。

5.2.6 借用任意表达式结果值的引用

C 和 C++ 只允许将 & 运算符应用于某些特定种类的表达式，而 Rust 允许借用任意种类的表达式结果值的引用：

fn factorial(n: usize) -> usize {
 (1..n+1).product()
}
let r = &factorial(6);
// 数学运算符可以“看穿”一层引用
assert_eq!(r + &1009, 1729);

在这种情况下，Rust 会创建一个匿名变量来保存此表达式的值，并让该引用指向它。这个匿名变量的生命周期取决于你对引用做了什么。

• 在 let 语句中，如果立即将引用赋值给某个变量（或者使其成为立即被赋值的某个结构体或数组的一部分），那么 Rust 就会让匿名变量存在于 let 初始化此变量期间。在前面的示例中，Rust 就会对 r 的引用目标这样做。
• 否则，匿名变量会一直存续到所属封闭语句块的末尾。在我们的示例中，为保存 1009 而创建的匿名变量只会存续到 assert_eq! 语句的末尾。

如果你习惯于使用 C 或 C++，那么这可能听起来很容易出错。但别忘了，Rust 永远不会让你写出可能生成悬空引用的代码。只要引用可能在匿名变量的生命周期之外被使用，Rust 就一定会在编译期间报告问题，然后你就可以通过将引用保存在具有适当生命周期的命名变量中来修复代码。

5.2.7 对切片和特型对象的引用

迄今为止，我们展示的引用全都是简单地址。但是，Rust 还包括两种 胖指针，即携带某个值地址的双字值，以及要正确使用该值所需的某些额外信息。

对切片的引用就是一个胖指针，携带着此切片的起始地址及其长度。第 3 章详细讲解过切片。

Rust 的另一种胖指针是 特型对象，即对实现了指定特型的值的引用。特型对象会携带一个值的地址和指向适用于该值的特型实现的指针，以便调用特型的方法。11.1.1 节会详细介绍特型对象。

除了会携带这些额外数据，切片和特型对象引用的行为与本章中已展示过的其他引用是一样的：它们并不拥有自己的引用目标、它们的生命周期也不允许超出它们的引用目标、它们可能是可变的或共享的，等等。

5.3 引用安全

正如前面介绍过的那样，引用看起来很像 C 或 C++ 中的普通指针。但普通指针是不安全的，Rust 又如何保持对引用的全面控制呢？或许了解规则的最佳方式就是尝试打破规则。

为了传达基本思想，我们将从最简单的案例开始，展示 Rust 如何确保在单个函数体内正确使用引用。然后我们会看看如何在函数之间传递引用并将它们存储到数据结构中。这需要为函数和数据类型提供 生命周期参数（稍后会对其进行解释）。最后我们会介绍 Rust 提供的一些简写形式，以简化常见的使用模式。在整个过程中，我们将展示 Rust 如何找出损坏的代码，并不时提出解决方案。

5.3.1 借用局部变量

这是一个非常浅显的案例。你不能借用对局部变量的引用并将其移出变量的作用域：

{
 let r;
 {
 let x = 1;
 r = &x;
 }
 assert_eq!(*r, 1); // 错误：试图读取`x`所占用的内存
}

Rust 编译器会拒绝此程序，并显示详细的错误消息：

error: `x` does not live long enough
 |
7 | r = &x;
 | ^^ borrowed value does not live long enough
8 | }
 | - `x` dropped here while still borrowed
9 | assert_eq!(*r, 1); // 错误：试图读取`x`所占用的内存
10 | }

Rust 报错说 x 只能存续至内部块的末尾，而引用（ r）会一直存续至外部块的末尾，这就让它成了悬空指针，这是被禁止的。

虽然对人类读者来说这个程序很明显是错误的，但还是值得研究一下 Rust 本身如何得出的这个结论。即使是这么简单的例子，也能展示出 Rust 用来检查更复杂代码的一些逻辑工具。

Rust 会尝试为程序中的每个引用类型分配一个 生命周期，以表达根据其使用方式应施加的约束。生命周期是程序的一部分，可以确保引用在下列位置都能被安全地使用：语句中、表达式中、某个变量的作用域中等。生命周期完全是 Rust 在编译期虚构的产物。在运行期，引用只是一个地址，它的生命周期只是其类型的一部分，不存在运行期表示。

在这个例子中，我们要分析 3 个生命周期之间的关系。变量 r 和 x 都有各自的生命周期，从它们被初始化的时间点一直延续到足以让编译器断定不再使用它们的时间点。第三个生命周期是引用类型，即借用了 x 并存储在 r 中的引用类型。

这里有一个显而易见的约束：如果有一个变量 x，那么对 x 的引用的生命周期不能超出 x 本身，如图 5-3 所示。

图 5-3： &x 的容许生命周期

当 x 超出作用域时，其引用将是一个悬空指针。为此，我们说变量的生命周期必须 涵盖 借用过它的引用的生命周期。

这是另一个约束：如果将引用存储在变量 r 中，则引用类型必须在变量 r 从初始化到最后一次使用的整个生命周期内都可以访问，如图 5-4 所示。

图 5-4：存储在 r 中的引用的容许生命周期

如果引用的生命周期不能至少和变量 r 一样长，那么在某些时候变量 r 就会变成悬空指针。为此，我们说引用的生命周期必须涵盖变量 r 的生命周期。

第一个约束限制了引用的生命周期可以有多大，而第二个约束则限制了它可以有多小。Rust 会尝试找出能让每个引用都满足这两个约束的生命周期。然而我们的示例中并不存在这样的生命周期，如图 5-5 所示。

图 5-5：引用的生命周期，其各项约束存在矛盾

现在来看一个不一样的例子，这次就行得通了。还是同样的约束：引用的生命周期必须包含在 x 中，但也要完全涵盖 r 的生命周期。因为现在 r 的生命周期变小了，所以会有一个生命周期满足这些约束，如图 5-6 所示。

图 5-6：引用的生命周期涵盖了 r 的生命周期且同时位于 x 的作用域内

当你借用大型数据结构中某些部分（比如向量的元素）的引用时，会自然而然地应用这些规则：

let v = vec![1, 2, 3];
let r = &v[1];

由于 v 拥有一个向量，此向量又拥有自己的元素，因此 v 的生命周期必须涵盖 &v[1] 引用类型的生命周期。类似地，如果将一个引用存储于某个数据结构中，则此引用的生命周期也必须涵盖那个数据结构的生命周期。如果构建一个由引用组成的向量，则所有这些引用的生命周期都必须涵盖拥有该向量的变量的生命周期。

这是 Rust 用来处理所有代码的过程的本质。引入更多的语言特性（比如数据结构和函数调用），必然会引入一些全新种类的约束，但基本原则保持不变：首先，要了解程序中使用各种引用的方式带来的约束；其次，找出能同时满足这些约束的生命周期。这与 C 和 C++ 程序员不得不人工担负的过程没有多大区别，唯一的区别是 Rust 知道这些规则并会强制执行。

5.3.2 将引用作为函数参数

当我们传递对函数的引用时，Rust 要如何确保函数能安全地使用它呢？假设我们有一个函数 f，它会接受一个引用并将其存储在全局变量中。我们需要对此进行一些修改，下面是第一个版本：

// 这段代码有一系列问题，无法编译
static mut STASH: &i32;
fn f(p: &i32) { STASH = p; }

在 Rust 中，全局变量的等价物称为 静态变量（static）：它是在程序启动时就会被创建并一直存续到程序终止时的值。（与任何其他声明一样，Rust 的模块系统会控制静态变量在何处可见，因此这只表示它们的生命周期是“全局”的，并不表示它们全局可见。）第 8 章会介绍静态变量，现在我们只讲一下刚才展示的代码违反了哪些规则。

• 每个静态变量都必须初始化。
• 可变静态变量本质上不是线程安全的（毕竟，任何线程都可以随时访问静态变量），即使在单线程的程序中，它们也可能成为一些另类可重入性问题的牺牲品。由于这些原因，你只能在 unsafe 块中访问可变静态变量。在这个例子中，我们并不关心那几个具体问题，所以只是把可变静态变量扔到了一个 unsafe 块中。

经过这些修改，现在我们有了以下内容：

static mut STASH: &i32 = &128;
fn f(p: &i32) { // 仍然不够理想
 unsafe {
 STASH = p;
 }
}

就快完工了。要查看剩下的问题，就要把 Rust 替我们省略的一些代码写出来。此处所写的 f 的签名实际上是以下内容的简写：

fn f<'a>(p: &'a i32) { ... }

这里，生命周期 'a（读作“tick A”）是 f 的 生命周期参数。 <'a> 的意思是“对于任意生命周期 'a”，因此当我们编写 fn f<'a>(p: &'a i32) 时，就定义了一个函数，该函数能接受对具有任意生命周期 'a 的 i32 型引用。

因为必须允许 'a 是任意生命周期，所以如果它是可能的最小生命周期（一个恰好涵盖对 f 调用的生命周期），那么问题就能轻易解决。接下来赋值语句就成了争论的焦点：

STASH = p;

由于 STASH 会存续在程序的整个执行过程中，因此它所持有的引用类型必须具有等长的生命周期，Rust 将此称为 'static 生命周期。但是指向 p 的引用的生命周期是 'a，它可以是任何能涵盖对 f 调用的生命周期。所以，Rust 拒绝了我们的代码：

error: explicit lifetime required in the type of `p`
 |
5 | STASH = p;
 | ^ lifetime `'static` required

在这个时间点，很明显我们的函数不能接受任意引用作为参数。但正如 Rust 指出的那样，它应当接受具有 'static 生命周期的引用：在 STASH 中存储这样的引用不会创建悬空指针。事实上，下面的代码就编译得很好：

static mut STASH: &i32 = &10;

fn f(p: &'static i32) {
 unsafe {
 STASH = p;
 }
}

这一次， f 的签名指出 p 必须是生命周期为 'static 的引用，因此将其存储在 STASH 中不会再有任何问题。我们只能用对其他静态变量的引用来调用 f，但这是唯一一种肯定不会让 STASH 悬空的方式。所以可以像下面这样写：

static WORTH_POINTING_AT: i32 = 1000;
f(&WORTH_POINTING_AT);

由于 WORTH_POINTING_AT 是静态变量，因此 &WORTH_POINTING_AT 的类型是 &'static i32，将该类型传给 f 是安全的。

不过，可以退后一步，来看看在修改成正确方法时， f 的签名发生了哪些变化：原来的 f(p: &i32) 最后变成了 f(p: &'static i32)。换句话说，我们无法编写在全局变量中潜藏一个引用却不在函数签名中明示该意图的函数。在 Rust 中，函数的签名总会揭示出函数体的行为。

相反，如果确实看到一个带有 g(p: &i32) 签名的函数（或者带着生命周期写成 g<'a>(p: &'a i32)），那么就可以肯定它 没有 将其参数 p 藏在任何超出此调用点的地方。无须查看 g 的具体定义，签名本身就可以告诉我们 g 用它的参数能做什么，不能做什么。当你尝试为函数调用建立安全保障时，这一认知会非常有价值。

5.3.3 把引用传给函数

我们刚刚揭示了函数签名与其函数体的关系，下面再来看一下函数签名与其调用者的关系。假设你有以下代码：

// 这个函数可以简写为fn g(p: &i32)，但这里还是把它的生命周期写出来了
fn g<'a>(p: &'a i32) { ... }

let x = 10;
g(&x);

只要看看 g 的签名，Rust 就知道它不会将 p 保存在生命周期可能超出本次调用的任何地方：包含本次调用的任何生命周期都必须符合 'a 的要求。所以 Rust 为 &x 选择了尽可能短的生命周期，即调用 g 时的生命周期。这满足所有约束：它的生命周期不会超出 x，并且会涵盖对 g 的完整调用。所以这段代码通过了审核。

请注意，虽然 g 有一个生命周期参数 'a，但调用 g 时并不需要提及它。只要在定义函数和类型时关心生命周期参数就够了，使用它们时，Rust 会为你推断生命周期。

如果试着将 &x 传给之前要求其参数存储在静态变量中的函数 f 会怎样呢？

fn f(p: &'static i32) { ... }

let x = 10;
f(&x);

这无法编译：引用 &x 的生命周期不能超出 x，但通过将它传给 f，又限制了它必须至少和 'static 一样长。没办法做到两全其美，所以 Rust 只好拒绝了这段代码。

5.3.4 返回引用

函数通常会接收某个数据结构的引用，然后返回对该结构的某个部分的引用。例如，下面是一个函数，它会返回对切片中最小元素的引用：

// v应该至少有一个元素
fn smallest(v: &[i32]) -> &i32 {
 let mut s = &v[0];
 for r in &v[1..] {
 if *r < *s { s = r; }
 }
 s
}

我们依惯例在该函数的签名中省略了生命周期。当函数以单个引用作为参数并返回单个引用时，Rust 会假定两者具有相同的生命周期。如果把生命周期明确地写出来，则能看得更清楚：

fn smallest<'a>(v: &'a [i32]) -> &'a i32 { ... }

假设我们是这样调用 smallest 的：

let s;
{
 let parabola = [9, 4, 1, 0, 1, 4, 9];
 s = smallest(&parabola);
}
assert_eq!(*s, 0); // 错误：指向了已被丢弃的数组的元素

从 smallest 的签名可以看出它的参数和返回值必须具有相同的生命周期 'a。在我们的调用中，参数 &parabola 的生命周期不得超出 parabola 本身，但 smallest 的返回值的生命周期必须至少和 s 一样长。生命周期 'a 不可能同时满足这两个约束，因此 Rust 拒绝执行这段代码：

error: `parabola` does not live long enough
 |
11 | s = smallest(&parabola);
 | -------- borrow occurs here
12 | }
 | ^ `parabola` dropped here while still borrowed
13 | assert_eq!(*s, 0); // 错误：指向了已被丢弃的数组的元素
 | - borrowed value needs to live until here
14 | }

移动 s，让其生命周期完全包含在 parabola 内就可以解决问题：

{
 let parabola = [9, 4, 1, 0, 1, 4, 9];
 let s = smallest(&parabola);
 assert_eq!(*s, 0); // 很好：parabola仍然“活着”
}

函数签名中的生命周期能让 Rust 评估你传给函数的引用与函数返回的引用之间的关系，并确保安全地使用它们。

5.3.5 包含引用的结构体

Rust 如何处理存储在数据结构中的引用呢？下面仍然是之前那个出错的程序，但这次我们将引用“藏”在了结构体中：

// 这无法编译
struct S {
 r: &i32
}

let s;
{
 let x = 10;
 s = S { r: &x };
}
assert_eq!(*s.r, 10); // 错误：从已被丢弃的`x`中读取

Rust 对引用的安全约束不会因为我们将引用“藏”在结构体中而神奇地消失。无论如何，这些约束最终也必须应用在 S 上。的确，Rust 提出了质疑：

error: missing lifetime specifier
 |
7 | r: &i32
 | ^ expected lifetime parameter

每当一个引用类型出现在另一个类型的定义中时，必须写出它的生命周期。可以这样写：

struct S {
 r: &'static i32
}

这表示 r 只能引用贯穿程序整个生命周期的 i32 值，这种限制太严格了。还有一种方法是给类型指定一个生命周期参数 'a 并将其用在 r 上：

struct S<'a> {
 r: &'a i32
}

现在 S 类型有了一个生命周期，就像引用类型一样。你创建的每个 S 类型的值都会获得一个全新的生命周期 'a，它会受到该值的使用方式的限制。你存储在 r 中的任何引用的生命周期最好都涵盖 'a，并且 'a 必须比存储在 S 中的任何内容的生命周期都要长。

回到前面的代码，表达式 S { r: &x } 创建了一个新的 S 值，其生命周期为 'a。当你将 &x 存储在 r 字段中时，就将 'a 完全限制在了 x 的生命周期内部。

赋值语句 s = S { ... } 会将此 S 存储在一个变量中，该变量的生命周期会延续到示例的末尾，这种限制决定了 'a 比 s 的生命周期更长。现在 Rust 遇到了与之前一样矛盾的约束： 'a 的生命周期不能超出 x，但必须至少和 s 一样长。因为找不到两全其美的生命周期，所以 Rust 拒绝执行该代码。一场灾难提前化解了。

如果将具有生命周期参数的类型放置在其他类型中会怎样呢？

struct D {
 s: S // 不合格
}

Rust 提出了质疑，就像试图在 S 中放置一个引用而未指定其生命周期一样：

error: missing lifetime specifier
 |
8 | s: S // 不合格
 | ^ expected named lifetime parameter
 |

不能在这里省略 S 的生命周期参数：Rust 需要知道 D 的生命周期和其引用的 S 的生命周期之间是什么关系，以便对 D 进行与“ S 和普通引用”一样的检查。

可以给 s 一个 'static 生命周期。这样没问题：

struct D {
 s: S<'static>
}

使用这种定义， s 字段只能借用存续于整个程序执行过程中的值。这会带来一定的限制，但它确实表明 D 不可能借用局部变量，而 D 本身的生命周期并没有特殊限制。

来自 Rust 的错误消息其实建议了另一种方法，这种方法更通用：

help: consider introducing a named lifetime parameter
 |
7 | struct D<'a> {
8 | s: S<'a>
 |

这一次，为 D 提供生命周期参数并将其传给 S：

struct D<'a> {
 s: S<'a>
}

通过获取生命周期参数 'a 并在 s 的类型中使用它，我们允许 Rust 将 D 值的生命周期和其 S 类型字段持有的引用的生命周期关联起来。

我们之前展示过函数的签名如何明确表达出它对我们传给它的引用做了什么。现在我们在类型方面展示了类似的做法：类型的生命周期参数总会揭示它是否包含某些值得关心其生命周期的引用（也就是非 'static 的）以及这些生命周期可以是什么。

假设我们有一个解析函数，它会接受一个字节切片并返回一个存有解析结果的结构：

fn parse_record<'i>(input: &'i [u8]) -> Record<'i> { ... }

不用看 Record 类型的定义就可以知道，如果从 parse_record 接收到 Record，那么它包含的任何引用就必然指向我们传入的输入缓冲区，而不是其他地方（ 'static 静态值除外）。

事实上，Rust 要求包含引用的类型都要接受显式生命周期参数就是为了明示这种内部行为。其实 Rust 原本可以简单地为结构体中的每个引用创建一个不同的生命周期，从而省去把它们写出来的麻烦。实际上，Rust 的早期版本就是这么做的，但开发人员发现这样会令人困惑：了解“某个值是从另一个值中借用出来的”这一点很有帮助，特别是在处理错误时。

不仅像 S 这样的引用和类型有生命周期，Rust 中的每个类型都有生命周期，包括 i32 和 String。它们大多数是 'static 的，这意味着这些类型的值可以一直存续下去，例如， Vec<i32> 是自包含的，在任何特定变量超出作用域之前都不需要丢弃它。但是像 Vec<&'a i32> 这样的类型，其生命周期就必须被 'a 涵盖，也就是说必须在引用目标仍然存续的情况下丢弃它。

5.3.6 不同的生命周期参数

假设你已经定义了一个包含两个引用的结构体，如下所示：

struct S<'a> {
 x: &'a i32,
 y: &'a i32
}

这两个引用使用相同的生命周期 'a。如果这样写代码，那么可能会有问题：

let x = 10;
let r;
{
 let y = 20;
 {
 let s = S { x: &x, y: &y };
 r = s.x;
 }
}
println!("{}", r);

上述代码不会创建任何悬空指针。对 y 的引用会保留在 s 中，它会在 y 之前超出作用域。对 x 的引用最终会出现在 r 中，它的生命周期不会超出 x。

然而，如果你尝试编译这段代码，那么 Rust 会报错说 y 的存活时间不够长，但其实它看起来是足够长的。为什么 Rust 会担心呢？如果仔细阅读代码，就能明白其推理过程。

• S 的两个字段是具有相同生命周期 'a 的引用，因此 Rust 必须找到一个同时适合 s.x 和 s.y 的生命周期。
• 赋值 r = s.x，这就要求 'a 涵盖 r 的生命周期。
• 用 &y 初始化 s.y，这就要求 'a 不能长于 y 的生命周期。

这些约束是不可能满足的：没有哪个生命周期比 y 短但比 r 长。Rust 被迫止步于此。

出现这个问题是因为 S 中的两个引用具有相同的生命周期 'a。只要更改 S 的定义，让每个引用都有各自的生命周期，就可以解决所有问题：

struct S<'a, 'b> {
 x: &'a i32,
 y: &'b i32
}

根据这个定义， s.x 和 s.y 具有独立的生命周期。对 s.x 所做的操作不会影响 s.y 中存储的内容，因此现在很容易满足约束条件： 'a 可以用 r 的生命周期，而 'b 可以用 s 的生命周期。（虽然 'b 也可以用 y 的生命周期，但 Rust 会尝试选择可行的最小生命周期。）一切都好起来了。

函数签名也有类似的情况。假设有这样一个函数：

fn f<'a>(r: &'a i32, s: &'a i32) -> &'a i32 { r } // 可能过于严格

在这里，两个引用参数使用了相同的生命周期 'a，这可能会给调用者施加不必要的限制，就像前面讲过的那样。如果这确实是问题，可以让各个参数的生命周期独立变化：

fn f<'a, 'b>(r: &'a i32, s: &'b i32) -> &'a i32 { r } // 宽松多了

这样做的缺点是，添加生命周期会让类型和函数签名更难阅读。我们（本书作者）倾向于先尝试尽可能简单的定义，然后放宽限制，直到代码能编译通过为止。由于 Rust 不允许不安全的代码运行，因此简单地等到报告问题时再修改也是一种完全可以接受的策略。

5.3.7 省略生命周期参数

迄今为止，本书已经展示了很多返回引用或以引用为参数的函数，但通常没必要详细说明每个生命周期。生命周期就在那里，如果它们显而易见，那么 Rust 就允许我们省略。

在最简单的情况下，你可能永远不需要为参数写出生命周期。Rust 会为需要生命周期的每个地方分配不同的生命周期。例如：

struct S<'a, 'b> {
 x: &'a i32,
 y: &'b i32
}

fn sum_r_xy(r: &i32, s: S) -> i32 {
 r + s.x + s.y
}

此函数的签名是以下代码的简写形式：

fn sum_r_xy<'a, 'b, 'c>(r: &'a i32, s: S<'b, 'c>) -> i32

如果确实要返回引用或其他带有生命周期参数的类型，那么针对无歧义的情况，Rust 会尽量采用简单的设计。如果函数的参数只有一个生命周期，那么 Rust 就会假设返回值具有同样的生命周期：

fn first_third(point: &[i32; 3]) -> (&i32, &i32) {
 (&point[0], &point[2])
}

明确写出所有生命周期后的代码如下所示：

fn first_third<'a>(point: &'a [i32; 3]) -> (&'a i32, &'a i32)

如果函数的参数有多个生命周期，那么就没有理由选择某一个生命周期作为返回值的生命周期，Rust 会要求你明确指定生命周期。

但是，如果函数是某个类型的方法，并且具有引用类型的 self 参数，那么 Rust 就会假定返回值的生命周期与 self 参数的生命周期相同。（ self 指的是调用方法的对象，类似于 C++、Java 或 JavaScript 中的 this 或者 Python 中的 self。9.6 节会介绍这些方法。）

例如，你可以编写以下内容：

struct StringTable {
 elements: Vec<String>,
}

impl StringTable {
 fn find_by_prefix(&self, prefix: &str) -> Option<&String> {
 for i in 0 .. self.elements.len() {
 if self.elements[i].starts_with(prefix) {
 return Some(&self.elements[i]);
 }
 }
 None
 }
}

find_by_prefix 方法的签名是以下内容的简写形式：

fn find_by_prefix<'a, 'b>(&'a self, prefix: &'b str) -> Option<&'a String>

Rust 假定无论你借用的是什么，本质上都是从 self 借用的。

再次强调，这些都只是简写形式，旨在提供便利且比较直观。如果它们不是你想要的，那么你随时可以明确地写出生命周期。

5.4 共享与可变

迄今为止，本书讨论的都是 Rust 如何确保不会有任何引用指向超出作用域的变量。但是还有其他方法可能引入悬空指针。下面是一个简单的例子：

let v = vec![4, 8, 19, 27, 34, 10];
let r = &v;
let aside = v; // 把向量转移给aside
r[0]; // 错误：这里所用的`v`此刻是未初始化状态

对 aside 的赋值会移动向量、让 v 回到未初始化状态，并将 r 变为悬空指针，如图 5-7 所示。

图 5-7：对已移动出去的向量的引用

尽管 v 在 r 的整个生命周期中都处于作用域内部，但这里的问题是 v 的值已经移动到别处，导致 v 成了未初始化状态，而 r 仍然在引用它。当然，Rust 会捕获错误：

error: cannot move out of `v` because it is borrowed
 |
9 | let r = &v;
 | - borrow of `v` occurs here
10 | let aside = v; // 把向量转移给`aside`
 | ^^^^^ move out of `v` occurs here

在共享引用的整个生命周期中，它引用的目标会保持只读状态，即不能对引用目标赋值或将值移动到别处。在上述代码中， r 的生命周期内发生了移动向量的操作，Rust 当然要拒绝。如果按如下所示更改程序，就没问题了：

let v = vec![4, 8, 19, 27, 34, 10];
{
 let r = &v;
 r[0]; // 正确：向量仍然在那里
}
let aside = v;

在这个版本中， r 作用域范围更小，在把 v 转移给 aside 之前， r 的生命周期就结束了，因此一切正常。

下面是另一种制造混乱的方式。假设我们随手写了一个函数，它使用切片的元素来扩展某个向量：

fn extend(vec: &mut Vec<f64>, slice: &[f64]) {
 for elt in slice {
 vec.push(*elt);
 }
}

这是标准库中向量的 extend_from_slice 方法的一个不太灵活（并且优化程度较低）的版本。可以用它从其他向量或数组的切片中构建一个向量：

let mut wave = Vec::new();
let head = vec![0.0, 1.0];
let tail = [0.0, -1.0];

extend(&mut wave, &head); // 使用另一个向量扩展`wave`
extend(&mut wave, &tail); // 使用数组扩展`wave`

assert_eq!(wave, vec![0.0, 1.0, 0.0, -1.0]);

我们在这里建立了一个正弦波周期。如果想添加另一个周期，那么可以把向量追加到其自身吗？

extend(&mut wave, &wave);
assert_eq!(wave, vec![0.0, 1.0, 0.0, -1.0,
 0.0, 1.0, 0.0, -1.0]);

乍一看你可能觉得这还不错。但别忘了，在往向量中添加元素时，如果它的缓冲区已满，那么就必须分配一个具有更多空间的新缓冲区。假设开始时 wave 有 4 个元素的空间，那么当 extend 尝试添加第五个元素时就必须分配更大的缓冲区。内存最终如图 5-8 所示。

extend 函数的 vec 参数借用了 wave（由调用者拥有），而 wave 为自己分配了一个新的缓冲区，其中有 8 个元素的空间。但是 slice 仍然指向旧的 4 元素缓冲区，该缓冲区已经被丢弃了。

图 5-8：通过向量的重新分配将 slice 变成了悬空指针

这种问题并不是 Rust 独有的：在许多语言中，在指向集合的同时修改集合要加倍小心。在 C++ 中， std::vector 规范会告诫你“重新分配向量缓冲区会令指向序列中各个元素的所有引用、指针和迭代器失效”。Java 对修改 java.util.Hashtable 对象也有类似的说法。

如果在创建迭代器后的任何时间以任何方法（迭代器自身的 remove 方法除外）修改了 Hashtable 的结构，那么迭代器都将抛出 ConcurrentModificationException 异常。

这类错误特别难以调试，因为它只会偶尔发生。在测试中，向量可能总是恰好有足够的空间，缓冲区可能永远都不会重新分配，于是这个问题可能永远都没人发现。

然而，Rust 会在编译期报告调用 extend 有问题：

error: cannot borrow `wave` as immutable because it is also
 borrowed as mutable
 |
9 | extend(&mut wave, &wave);
 | ---- ^^^^- mutable borrow ends here
 | | |
 | | immutable borrow occurs here
 | mutable borrow occurs here

换句话说，我们既可以借用向量的可变引用，也可以借用其元素的共享引用，但这两种引用的生命周期不能重叠。在这个例子中，这两种引用的生命周期都包含着对 extend 的调用，出现了重叠，因此 Rust 会拒绝执行这段代码。

这些错误都源于违反了 Rust 的“可变与共享”规则。

共享访问是只读访问。

共享引用借用的值是只读的。在共享引用的整个生命周期中，无论是它的引用目标，还是可从该引用目标间接访问的任何值，都不能被 任何代码 改变。这种结构中不能存在对任何内容的有效可变引用，其拥有者应保持只读状态，等等。值完全冻结了。

可变访问是独占访问。

可变引用借用的值只能通过该引用访问。在可变引用的整个生命周期中，无论是它的引用目标，还是该引用目标间接访问的任何目标，都没有任何其他路径可访问。对可变引用来说，唯一能和自己的生命周期重叠的引用就是从可变引用本身借出的引用。

Rust 报告说 extend 示例违反了第二条规则：因为我们借用了对 wave 的可变引用，所以该可变引用必须是抵达向量或其元素的唯一方式。而对切片的共享引用本身是抵达这些元素的另一种方式，这违反了第二条规则。

但是 Rust 也可以将我们的错误视为违反了第一条规则：因为我们借用了对 wave 元素的共享引用，所以这些元素和 Vec 本身都是只读的。不能对只读值借用出可变引用。

每种引用都会影响到我们可以对“到引用目标从属路径上的值”以及“从引用目标可间接访问的值”所能执行的操作，如图 5-9 所示。

图 5-9：借用引用会影响你对同一所有权树中的其他值执行的操作

请注意，在这两种情况下，指向引用目标的所有权路径在此引用的生命周期内都无法更改。对于共享借用，这条路径是只读的；对于可变借用，这条路径是完全不可访问的。所以程序无法做出任何会使该引用无效的操作。

可以将这些原则分解为一些最简单的示例：

let mut x = 10;
let r1 = &x;
let r2 = &x; // 正确：允许多个共享借用
x += 10; // 错误：不能赋值给`x`，因为它已被借出
let m = &mut x; // 错误：不能把`x`借入为可变引用，因为
 // 它涵盖在已借出的不可变引用的生命周期内
println!("{}, {}, {}", r1, r2, m); // 这些引用是在这里使用的，所以它们
 // 的生命周期至少要存续这么长
let mut y = 20;
let m1 = &mut y;
let m2 = &mut y; // 错误：不能多次借入为可变引用
let z = y; // 错误：不能使用`y`，因为它涵盖在已借出的可变引用的生命周期内
println!("{}, {}, {}", m1, m2, z); // 在这里使用这些引用

可以从共享引用中重新借入共享引用：

let mut w = (107, 109);
let r = &w;
let r0 = &r.0; // 正确：把共享引用重新借入为共享引用
let m1 = &mut r.1; // 错误：不能把共享引用重新借入为可变
println!("{}", r0); // 在这里使用r0

可以从可变引用中重新借入可变引用：

let mut v = (136, 139);
let m = &mut v;
let m0 = &mut m.0; // 正确: 从可变引用中借入可变引用
*m0 = 137;
let r1 = &m.1; // 正确: 从可变引用中借入共享引用，并且不能和m0重叠
v.1; // 错误：禁止通过其他路径访问
println!("{}", r1); // 可以在这里使用r1

这些限制非常严格。回过头来看看我们尝试调用 extend(&mut wave, &wave) 的地方，没有什么快速而简便的方法来修复代码，以使其按照我们想要的方式工作。Rust 中到处都在应用这些规则：如果要借用对 HashMap 中键的共享引用，那么在共享引用的生命周期结束之前就不能再借入对 HashMap 的可变引用。

但这么做有充分的理由：要为集合设计出“支持不受限制地在迭代期间修改”的能力是非常困难的，而且往往会导致无法简单高效地实现这些集合。Java 的 Hashtable 和 C++ 的 vector 就不支持这种访问方式，Python 的字典和 JavaScript 的对象甚至都不曾定义过这种访问方式。JavaScript 中的其他集合类型固然可以做到，不过需要更繁重的实现。C++ 的 std::map 承诺插入新条目不会让指向此映射表中其他条目的指针失效，但做出这一承诺的代价是该标准无法提供像 Rust 的 BTreeMap 这样更高效的缓存设计方案，因为后者会在树的每个节点中存储多个条目。

下面是通过上述规则捕获各种错误的另一个例子。考虑以下 C++ 代码，它用于管理文件描述符。为了简单起见，这里只展示一个构造函数和复制赋值运算符，并会省略错误处理代码：

struct File {
 int descriptor;

 File(int d) : descriptor(d) { }

 File& operator=(const File &rhs) {
 close(descriptor);
 descriptor = dup(rhs.descriptor);
 return *this;
 }
};

这个赋值运算符很简单，但在下面这种情况下会执行失败：

File f(open("foo.txt", ...));
...
f = f;

如果将一个 File 赋值给它自己，那么 rhs 和 *this 就是同一个对象，所以 operator= 会关闭它要传给 dup 的文件描述符。也就是说，我们销毁了正打算复制的那份资源。

在 Rust 中，类似的代码如下所示：

struct File {
 descriptor: i32
}

fn new_file(d: i32) -> File {
 File { descriptor: d }
}

fn clone_from(this: &mut File, rhs: &File) {
 close(this.descriptor);
 this.descriptor = dup(rhs.descriptor);
}

（这并不是 Rust 的惯用法。有很多很好的方式可以让 Rust 类型拥有自己的构造函数和方法，第 9 章会对此进行讲解，刚才的定义方式仅仅是为了示范。）

如果编写使用了 File 的 Rust 代码，就会得到如下内容：

let mut f = new_file(open("foo.txt", ...));
...
clone_from(&mut f, &f);

当然，Rust 干脆拒绝编译这段代码：

error: cannot borrow `f` as immutable because it is also
 borrowed as mutable
 |
18 | clone_from(&mut f, &f);
 | - ^- mutable borrow ends here
 | | |
 | | immutable borrow occurs here
 | mutable borrow occurs here

以上错误看起来很熟悉。事实证明，这里的两个经典 C++ 错误（无法处理自赋值和使用无效迭代器）本质上是同一种错误。在这两种情况下，代码都以为自己正在修改一个值，同时在引用另一个值，但实际上两者是同一个值。如果你不小心让调用 memcpy 或 strcpy 的源和目标在 C 或 C++ 中重叠，则可能会带来另一种错误。通过要求可变访问必须是独占的，Rust 避免了一大类日常错误。

在编写并发代码时，共享引用和可变引用的互斥性确实证明了其价值。只有当某些值既可变又要在线程之间共享时，才可能出现数据竞争，而这正是 Rust 的引用规则所要消除的。一个用 Rust 编写的并发程序，只要避免使用 unsafe 代码，就可以 在构造之初就避免 产生数据竞争。第 19 章在讨论并发时会更详细地对此进行介绍。总而言之，与大多数其他语言相比，并发在 Rust 中更容易使用。

Rust 的共享引用与 C 的 const 指针

乍一看，Rust 的共享引用似乎与 C 和 C++ 中指向 const 值的指针非常相似。然而，Rust 中共享引用的规则要严格得多。例如，考虑以下 C 代码：

int x = 42; // int变量，不是常量
const int *p = &x; // 指向const int的指针
assert(*p == 42);
x++; // 直接修改变量
assert(*p == 43); //“常量”指向的值发生了变化

p 是 const int * 这一事实意味着不能通过 p 本身修改它的引用目标，也就是说，禁止使用 (*p)++。但是可以直接通过 x 获取引用目标， x 不是 const，能以这种方式更改其值。C 家族的 const 关键字自有其用处，但与“常量”无关。

在 Rust 中，共享引用禁止对其引用目标进行任何修改，直到其生命周期结束：

let mut x = 42; // 非常量型i32变量
let p = &x; // 到i32的共享引用
assert_eq!(*p, 42);
x += 1; // 错误：不能对x赋值，因为它已被借出
assert_eq!(*p, 42); // 如果赋值成功，那么这应该是true

为了保证一个值是常量，需要追踪该值的所有可能路径，并确保它们要么不允许修改，要么根本不能使用。C 和 C++ 的指针不受限制，编译器无法对此进行检查。Rust 的引用总是与特定的生命周期相关联，因此可以在编译期检查它们。

5.5 应对复杂对象关系

自 20 世纪 90 年代自动内存管理兴起以来，所有程序都由大量复杂关联的对象构成，如图 5-10 所示。

图 5-10：复杂对象关系

如果你采用垃圾回收（自动内存管理）并且在开始编写程序之前不做任何设计，就会发生这种情况。我们都构建过这样的系统。

这种架构有很多从图 5-10 中无法看出的优点：初始的进展迅速；很容易添加新功能；几年以后，你将很容易确定你需要完全重写它。（让我们来一首澳大利亚摇滚乐队 AC/DC 的“通往地狱的高速公路”。2）

当然，这种架构也有缺点。当每个部分都像这样依赖于其他部分时，必然很难测试、迭代，甚至很难单独考虑其中的任何组件。

Rust 令人着迷的地方之一就在于，其所有权模型就好像是在通向地狱的高速公路上铺设了一条减速带。在 Rust 中创建循环引用（两个值，每个值都包含指向另一个值的引用）相当困难。你必须使用智能指针类型（如 Rc）和内部可变性（目前为止本书还未涉及这个主题）。Rust 更喜欢让指针、所有权和数据流单向通过系统，如图 5-11 所示。

图 5-11：树形对象关系

之所以现在提出这个问题，是因为在阅读本章后，你可能会很自然地想要立即编写代码并创建出大量的对象，所有对象之间使用 Rc 智能指针关联起来，最终呈现你熟悉的所有面向对象反模式。但此刻这还行不通。Rust 的所有权模型会不断给你制造麻烦。解决之道是进行一些前期设计并构建出更好的程序。

Rust 就是要把你理解程序的痛苦从将来移到现在。它确实做到了：Rust 不仅会迫使你理解为什么自己的程序是线程安全的，甚至可能还需要你做一些高级架构设计。

第 6 章 表达式

LISP 程序员知道一切的价值（value），但不了解其代价。

——Alan Perlis，警句 #55

本章将介绍 Rust 表达式，它是函数体的组成部分，因而也是大部分 Rust 代码的组成部分。Rust 中的大多数内容是表达式。本章将探索表达式的强大功能以及如何克服它的局限性。我们将介绍在 Rust 中完全面向表达式的控制流，以及 Rust 的基础运算符如何独立工作和组合工作。

某些概念（比如闭包和迭代器）严格来说也属于这一类，但略显深奥，我们稍后将用单独的一章来介绍它们。目前，我们的目标是在这“区区几页”中涵盖尽可能多的语法。

6.1 表达式语言

Rust 乍看起来和 C 家族的语言相似，但这只是假象。在 C 语言中， 表达式 和语句之间有明显的区别，表达式看起来是这样的：

5 * (fahr-32) / 9

而 语句 看起来更像这样：

for (; begin != end; ++begin) {
 if (*begin == target)
 break;
}

表达式有值，而语句没有。

Rust 是所谓的 表达式语言。这意味着它遵循更古老的传统，可以追溯到 Lisp，在 Lisp 中，表达式能完成所有工作。

在 C 中， if 和 switch 是语句，它们不生成值，也不能在表达式中间使用。而在 Rust 中， if 和 match 可以 生成值。第 2 章介绍过一个生成数值的 match 表达式：

pixels[r * bounds.0 + c] =
 match escapes(Complex { re: point.0, im: point.1 }, 255) {
 None => 0,
 Some(count) => 255 - count as u8
 };

if 表达式可用于初始化变量：

let status =
 if cpu.temperature <= MAX_TEMP {
 HttpStatus::Ok
 } else {
 HttpStatus::ServerError // 服务程序出错了
 };

match 表达式可以作为参数传给函数或宏：

println!("Inside the vat, you see {}.",
 match vat.contents {
 Some(brain) => brain.desc(),
 None => "nothing of interest"
 });

这解释了为什么 Rust 没有 C 那样的三元运算符（ expr1 ? expr2 : expr3）。在 C 语言中，三元运算符是一个表达式级别的类似 if 语句的东西。这在 Rust 中是多余的： if 表达式足以处理这两种情况。

C 中的大多数控制流工具是语句。而在 Rust 中，它们都是表达式。

6.2 优先级与结合性

表 6-1 总结了 Rust 的表达式语法。本章将讨论所有这些类型的表达式。这里的运算符已按优先级顺序列出，从最高到最低。（与大多数编程语言一样，当一个表达式包含多个相邻的运算符时，Rust 会根据 运算符优先级 来确定运算顺序。例如，在 limit < 2 * broom.size + 1 中， . 运算符具有最高优先级，因此会最先访问字段。）

表 6-1：表达式

表达式类型

示例

相关特型

数组字面量

[1, 2, 3]

数组重复表达式

[0; 50]

元组

(6, "crullers")

分组

(2 + 2)

块

{ f(); g() }

控制流表达式

if ok { f() }

if ok { 1 } else { 0 }

if let Some(x) = f() { x } else { 0 }

match x { None => 0, _ => 1 }

for v in e { f(v); }

while ok { ok = f(); }

while let Some(x) = it.next() { f(x); }

loop { next_event(); }

break

continue

return 0

std::iter::IntoIterator

宏调用

println!("ok")

路径

std::f64::consts::PI

结构体字面量

Point

元组字段访问

pair.0

Deref、 DerefMut

结构体字段访问

point.x

Deref、 DerefMut

方法调用

point.translate(50, 50)

Deref、 DerefMut

函数调用

stdin()

Fn(Arg0, ...) -> T、 FnMut(Arg0, ...) -> T、 FnOnce(Arg0, ...) -> T

索引

arr[0]

Index、 IndexMutDeref、 DerefMut

错误检查

create_dir("tmp")?

逻辑非 / 按位非

!ok

Not

取负

-num

Neg

解引用

*ptr

Deref、 DerefMut

借用

&val

类型转换

x as u32

乘

n * 2

Mul

除

n / 2

Div

取余（取模）

n % 2

Rem

加

n + 1

Add

减

n - 1

Sub

左移

n << 1

Shl

右移

n >> 1

Shr

按位与

n & 1

BitAnd

按位异或

n ^ 1

BitXor

按位或

n | 1

BitOr

小于

n < 1

std::cmp::PartialOrd

小于等于

n <= 1

std::cmp::PartialOrd

大于

n > 1

std::cmp::PartialOrd

大于等于

n >= 1

std::cmp::PartialOrd

等于

n == 1

std::cmp::PartialEq

不等于

n != 1

std::cmp::PartialEq

逻辑与

x.ok && y.ok

逻辑或

x.ok || backup.ok

右开区间范围

start .. stop

右闭区间范围

start ..= stop

赋值

x = val

复合赋值

x *= 1

x /= 1

x %= 1

x += 1

x -= 1

x <<= 1

x >>= 1

x &= 1

x ^= 1

x |= 1

DivAssign

RemAssign

AddAssign

SubAssign

ShlAssign

ShrAssign

BitAndAssign

BitXorAssign

BitOrAssign

MulAssign

闭包

|x, y| x + y

所有可以链式书写的运算符都是左结合的。也就是说，诸如 a - b - c 之类的操作链会分组为 (a - b) - c，而不是 a - (b - c)。所有可以这样链式书写的运算符都遵循左结合规则：

* / % + - << >> & ^ | && || as

比较运算符、赋值运算符和范围运算符（ .. 和 ..=）则根本无法链式书写。

6.3 块与分号

块是一种最通用的表达式。一个块生成一个值，并且可以在任何需要值的地方使用：

let display_name = match post.author() {
 Some(author) => author.name(),
 None => {
 let network_info = post.get_network_metadata()?;
 let ip = network_info.client_address();
 ip.to_string()
 }
};

Some(author) => 之后的代码是简单表达式 author.name()， None => 之后的代码是一个块表达式，它们对 Rust 来说没什么不同。块表达式的值是最后一个表达式 ip.to_string() 的值。

请注意， ip.to_string() 方法调用后面没有分号。大多数 Rust 代码行以分号或花括号结尾，就像 C 或 Java 一样。如果一个块看起来很像 C 代码，在你熟悉的每个地方都有分号，那么它就会像 C 的块一样运行，并且其值为 ()。正如第 2 章提到的，当块的最后一行不带分号时，就以最后这个表达式的值而不是通常的 () 作为块的值。

在某些语言，尤其是 JavaScript 中，可以省略分号，并且该语言会简单地替你填充分号——这是一个小小的便捷特性。但 Rust 不一样。在 Rust 中，分号是有实际意义的：

let msg = {
 // let声明：分号总是必需的
 let dandelion_control = puffball.open();

 // 带分号的表达式：调用方法，丢弃返回值
 dandelion_control.release_all_seeds(launch_codes);

 // 无分号的表达式：调用方法，返回值将存入`msg`
 dandelion_control.get_status()
};

块可以包含多个声明并在末尾生成值，这是一个很好的特性，你很快就会适应它。但它的一个缺点是，如果你不小心遗漏了分号，则会导致奇怪的错误消息：

...
if preferences.changed() {
 page.compute_size() // 糟糕，丢了分号
}
...

如果在 C 或 Java 程序中犯了同样的错误，那么编译器会直接指出你漏了一个分号。但 Rust 会这么说：

error: mismatched types
22 | page.compute_size() // 糟糕，丢了分号
 | ^^^^^^^^^^^^^^^^^^^- help: try adding a semicolon: `;`
 | |
 | expected (), found tuple
 |
 = note: expected unit type `()`
 found tuple `(u32, u32)`

由于缺少分号，块的值将是 page.compute_size() 返回的任何值，但是没有 else 的 if 必定返回 ()。幸好，Rust 已经针对这类错误做出改进，并会建议添加分号。

6.4 声明

除了表达式和分号，块还可以包含任意数量的声明。最常见的是 let 声明，它会声明局部变量：

let name: type = expr;

类型和初始化代码是可选的，分号则是必需的。与 Rust 中的所有标识符一样，变量名必须以字母或下划线开头，并且只能在第一个字符之后包含数字。Rust 中的“字母”是广义的，包括希腊字母、带重音的拉丁字符和更多符号——符合 Unicode 标准中附件 #31 要求的一切字符（也包括中文）。不允许使用表情符号。

let 声明可以在不初始化变量的情况下声明变量，然后再用赋值语句来初始化变量。这在某些情况下很有用，因为有时确实应该在某种控制流结构的中间初始化变量：

let name;
if user.has_nickname() {
 name = user.nickname();
} else {
 name = generate_unique_name();
 user.register(&name);
}

这里有两种初始化局部变量 name 的方式，但无论采用哪种方式，都只会初始化一次，所以 name 不需要声明为 mut。

在初始化之前就使用变量是错误的。（这与“移动后又使用值”的错误紧密相关。Rust 确实非常希望你只使用存在的值。）

你可能偶尔会看到似乎在重新声明现有变量的代码，如下所示：

for line in file.lines() {
 let line = line?;
 ...
}

这个 let 声明会创建一个不同类型的、新的（第二个）变量。第一个 line 变量的类型是 Result<String, io::Error>。第二个 line 变量则是 String。第二个定义会在所处代码块的其余部分代替第一个定义。这叫作 遮蔽（shadowing），在 Rust 程序中很常见。该代码等效于如下内容：

for line_result in file.lines() {
 let line = line_result?;
 ...
}

本书会坚持在这种情况下使用 _result 后缀，以便让不同变量具有不同的名称。

块还可以包含 语法项声明（item declaration）。语法项是指可以在程序或模块中的任意地方出现的声明，比如 fn、 struct 或 use。

后面的章节会详细介绍这些语法项。现阶段，用 fn 这个例子就足够了。任何块都可能包含一个 fn：

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

fn show_files() -> io::Result<()> {
 let mut v = vec![];
 ...
 fn cmp_by_timestamp_then_name(a: &FileInfo, b: &FileInfo) -> Ordering {
 a.timestamp.cmp(&b.timestamp) // 首先，比较时间戳
 .reverse() // 最新的文件优先
 .then(a.path.cmp(&b.path)) // 通过路径做二级比较
 }

 v.sort_by(cmp_by_timestamp_then_name);
 ...
}

当在块内声明一个 fn 时，它的作用域是整个块，也就是说，它可以在整个封闭块内部 使用。但是嵌套的 fn 无法访问恰好在同一作用域内的局部变量或参数。例如，函数 cmp_by_timestamp_then_name 不能直接使用 v。（封闭块与闭包不同。Rust 也有闭包，闭包可以看到封闭块作用域内的变量。请参阅第 14 章。）

块甚至可以包含完整的模块。这可能看起来有点儿过分（真的需要把语言的 每一 部分都嵌进任何其他部分吗？），但是程序员（特别是使用宏的程序员）总是有办法为语言提供的每一种独立语法找到用武之地。

6.5 if 与 match

if 表达式的形式我们很眼熟：

if condition1 {
 block1
} else if condition2 {
 block2
} else {
 block_n
}

每个 condition 都必须是 bool 类型的表达式，依照 Rust 的风格，不会隐式地将数值或指针转换为布尔值。

与 C 不同，条件周围不需要圆括号。事实上，如果出现了不必要的圆括号，那么 rustc 会给出警告。但花括号是必需的。

else if 块以及最后的 else 是可选的。没有 else 块的 if 表达式的行为与具有空的 else 块完全相同。

match 表达式类似于 C 语言中的 switch 语句，但更灵活。下面是一个简单的例子：

match code {
 0 => println!("OK"),
 1 => println!("Wires Tangled"),
 2 => println!("User Asleep"),
 _ => println!("Unrecognized Error {}", code)
}

这类似于 switch 语句的用途。它将执行此 match 表达式的四个分支之一，具体执行哪个分支取决于 code 的值。通配符模式 _ 会匹配所有内容。这类似于 switch 语句中的 default: 语句，不过它必须排在最后。将 _ 模式放在其他模式之前意味着它会优先于其他模式。这样一来，其他模式将永远没机会匹配到（编译器会发出警告）。

编译器可以使用跳转表来优化这种 match，就像 C++ 中的 switch 语句一样。当 match 的每个分支都生成一个常量值时，也会应用与 C++ 类似的优化。在这种情况下，编译器会构建出这些值的数组，并将各个 match 项编译为数组访问。除了边界检查，编译后的代码中根本不存在任何分支。

match 的多功能性源于每个分支 => 左侧支持的多种 模式（pattern）。在上面的例子中，每个模式只是一个常量整数。我们还展示了用以区分两种 Option 值的 match 表达式：

match params.get("name") {
 Some(name) => println!("Hello, {}!", name),
 None => println!("Greetings, stranger.")
}

对模式的强大能力来说，这还只是“冰山一角”。模式可以匹配一系列值，它可以解构元组、可以匹配结构体的各个字段、可以追踪引用、可以借用部分值，等等。甚至可以说，Rust 的模式定义了自己的迷你语言。第 10 章会用一些篇幅来介绍模式。

match 表达式的一般形式如下所示：

match value {
 pattern => expr,
...
}

如果 expr 是一个块，则可以省略此分支之后的逗号。

Rust 会从第一项开始依次根据每个模式检查给定的 value。当模式能够匹配时，对应的 expr 会被求值，而当这个 match 表达式结束时，不会再检查别的模式。至少要有一个模式能够匹配。Rust 禁止执行未覆盖所有可能值的 match 表达式：

let score = match card.rank {
 Jack => 10,
 Queen => 10,
 Ace => 11
}; // 错误：未穷举所有模式

if 表达式的所有块都必须生成相同类型的值：

let suggested_pet =
 if with_wings { Pet::Buzzard } else { Pet::Hyena }; // 正确

let favorite_number =
 if user.is_hobbit() { "eleventy-one" } else { 9 }; // 错误

let best_sports_team =
 if is_hockey_season() { "Predators" }; // 错误

（最后一个示例之所以是错的，是因为在 7 月份结果将是 ()。）1

类似地， match 表达式的所有分支都必须具有相同的类型。

let suggested_pet =
 match favorites.element {
 Fire => Pet::RedPanda,
 Air => Pet::Buffalo,
 Water => Pet::Orca,
 _ => None // 错误：不兼容的类型
 };

6.5.1 if let

还有一种 if 形式，即 if let 表达式：

if let pattern = expr {
 block1
} else {
 block2
}

给定的 expr 要么匹配 pattern，这时会运行 block1；要么无法匹配，这时会运行 block2。有时这是从 Option 或 Result 中获取数据的好办法：

if let Some(cookie) = request.session_cookie {
 return restore_session(cookie);
}

if let Err(err) = show_cheesy_anti_robot_task() {
 log_robot_attempt(err);
 politely_accuse_user_of_being_a_robot();
} else {
 session.mark_as_human();
}

if let 不是 必需 的，因为凡是 if let 可以做到的， match 同样可以做到。 if let 表达式其实是只有一个模式的 match 表达式的简写形式。

match expr {
 pattern => { block1 }
 _ => { block2 }
}

6.5.2 循环

有 4 种循环表达式：

while condition {
 block
}

while let pattern = expr {
 block
}

loop {
 block
}

for pattern in iterable {
 block
}

各种循环都是 Rust 中的表达式，但 while 循环或 for 循环的值总是 ()，因此它们的值通常没什么用。如果指定了一个值，那么 loop 表达式就能生成一个值。

while 循环的行为与 C 中的等效循环完全一样，只不过其 condition 必须是 bool 类型。

while let 循环类似于 if let。在每次循环迭代开始时， expr 的值要么匹配给定的 pattern，这时会运行循环体（ block）；要么不匹配，这时会退出循环。

可以用 loop 来编写无限循环。它会永远重复执行循环体（直到遇上 break 或 return，或者直到线程崩溃）。

for 循环会对可迭代（ iterable）表达式求值，然后为结果迭代器中的每个值运行一次循环体。许多类型可以迭代，包括所有标准库集合，比如 Vec 和 HashMap。标准的 C 语言的 for 循环如下所示：

for (int i = 0; i < 20; i++) {
 printf("%d\n", i);
}

在 Rust 中则是这样的：

for i in 0..20 {
 println!("{}", i);
}

与 C 一样，最后打印出的数值是 19。

.. 运算符会生成一个 范围（range），即具有两个字段（ start 和 end）的简单结构体。 0..20 与 std::ops::Range { start: 0, end: 20 } 相同。各种范围都可以与 for 循环一起使用，因为 Range 是一种可迭代类型，它实现了 std::iter::IntoIterator 特型（参见第 15 章）。标准集合都是可迭代的，数组和切片也是如此。

为了与 Rust 的移动语义保持一致，把值用于 for 循环会消耗该值：

let strings: Vec<String> = error_messages();
for s in strings { // 在这里，每个String都会转移给s……
 println!("{}", s);
} // ……并在此丢弃
println!("{} error(s)", strings.len()); // 错误：使用了已移动出去的值

这可能很不方便。简单的补救措施是在循环中访问此集合的引用。然后，循环变量也会变成对集合中每个条目的引用：

for rs in &strings {
 println!("String {:?} is at address {:p}.", *rs, rs);
}

这里 &strings 的类型是 &Vec<String>， rs 的类型是 &String。

遍历（可迭代对象的）可变引用会为每个元素提供一个可变引用：

for rs in &mut strings { // rs的类型是&mut String
 rs.push('\n'); // 为每个字符串添加一个换行
}

第 15 章会更详细地介绍 for 循环，并展示使用迭代器的许多其他方式。

6.6 循环中的控制流

break 表达式会退出所在循环。（在 Rust 中， break 只能用在循环中，不能用在 match 表达式中，这与 switch 语句不同。）

在 loop 的循环体中，可以在 break 后面跟一个表达式，该表达式的值会成为此 loop 的值：

// 对`next_line`的每一次调用，或者返回一个`Some(line)`（这里的`line`是
// 输入中的一行），或者当输入已结束时返回`None`。最终会返回以"answer: "
// 开头的第1行，如果没找到，就返回"answer: nothing"
let answer = loop {
 if let Some(line) = next_line() {
 if line.starts_with("answer: ") {
 break line;
 }
 } else {
 break "answer: nothing";
 }
};

自然， loop 中的所有 break 表达式也必须生成具有相同类型的值，这样该类型就会成为这个 loop 本身的类型。

continue 表达式会跳转到循环的下一次迭代：

// 读取某些数据，每次一行
for line in input_lines {
 let trimmed = trim_comments_and_whitespace(line);
 if trimmed.is_empty() {
 // 跳转回循环的顶部，并移到输入中的下一行
 continue;
 }
 ...
}

在 for 循环中， continue 会前进到集合中的下一个值，如果没有更多值，则退出循环。同样，在 while 循环中， continue 会重新检查循环条件，如果当前条件为假，就退出循环。

循环可以带有生命周期 标签。在以下示例中， 'search: 是外部 for 循环的标签。因此， break 'search 会退出这层循环，而不是退出内部循环：

'search:
for room in apartment {
 for spot in room.hiding_spots() {
 if spot.contains(keys) {
 println!("Your keys are {} in the {}.", spot, room);
 break 'search;
 }
 }
}

break 可以同时具有标签和值表达式：

// 找到此系列中第一个完全平方数的平方根
let sqrt = 'outer: loop {
 let n = next_number();
 for i in 1.. {
 let square = i * i;
 if square == n {
 // 找到了一个平方根
 break 'outer i;
 }
 if square > n {
 // `n`不是完全平方数，尝试下一个
 break;
 }
 }
};

标签也可以与 continue 一起使用。

6.7 return 表达式

return 表达式会退出当前函数，并向调用者返回一个值。

不带值的 return 是 return () 的简写：

fn f() { // 省略了返回类型：默认为()
 return; // 省略了返回值：默认为()
}

函数不必有明确的 return 表达式。函数体的工作方式类似于块表达式：如果最后一个表达式后没有分号，则它的值就是函数的返回值。事实上，这是在 Rust 中提供函数返回值的首选方式。

但这并不意味着 return 是无用的，或者仅仅是对不熟悉表达式语言的用户做出的让步。与 break 表达式一样， return 可以放弃进行中的工作。例如，第 2 章就使用过 ? 运算符在调用可能失败的函数后检查错误：

let output = File::create(filename)?;

我们曾解释说这是 match 表达式的简写形式：

let output = match File::create(filename) {
 Ok(f) => f,
 Err(err) => return Err(err)
};

上述代码会首先调用 File::create(filename)。如果返回 Ok(f)，则整个 match 表达式的计算结果为 f，因此可以把 f 存储在 output 中，继续执行 match 后的下一行代码。

否则，我们将匹配 Err(err) 并抵达 return 表达式。这时候，对 match 表达式求值的具体结果会决定 output 变量的值。我们会放弃所有这些并退出所在函数，返回从 File::create() 中得到的任何错误。

7.2.4 节会完整讲解 ? 运算符。

6.8 为什么 Rust 中会有 loop

Rust 编译器中有几个部分会分析程序中的控制流。

• Rust 会检查通过函数的每条路径是否返回了预期返回类型的值。为了正确地做到这一点，它需要知道是否有可能抵达函数的末尾。
• Rust 会检查局部变量有没有在未初始化的情况下使用过。这就要检查通过函数的每一条路径，以确保只要不经过初始化此变量的代码，就无法抵达使用它的地方。
• Rust 会对不可达代码发出警告。如果 无法 通过函数抵达某段代码，则这段代码不可达。

以上这些称为 流敏感（flow-sensitive）分析。这不是什么新事物，多年来，Java 一直在采用与 Rust 相似的“显式赋值”分析。

要执行这种规则，语言就必须在简单性和智能性之间取得平衡。简单性使得程序员更容易弄清楚编译器到底在说什么，而智能性有助于消除假警报和编译器拒绝一份完美而安全的程序的情况。Rust 更倾向于简单性，它的流敏感分析根本不会检查循环条件，而会简单地假设程序中的任何条件都可以为真或为假。

这会导致 Rust 可能拒绝某些安全程序：

fn wait_for_process(process: &mut Process) -> i32 {
 while true {
 if process.wait() {
 return process.exit_code();
 }
 }
} // 错误：类型不匹配：期待i32，实际找到了()

这里的错误是假警报。此函数只会通过 return 语句退出，因此 while 循环无法生成 i32 这个事实无关紧要。

loop 表达式就是这个问题的“有话直说”式解决方案。

Rust 的类型系统也会受到控制流的影响。前面说过， if 表达式的所有分支都必须具有相同的类型。但是，在可能以 break 或 return 表达式、无限 loop，或者调用 panic!() 或 std::process::exit() 等多种方式结束的块上强制执行此规则是不现实的。这些表达式的共同点是它们永远都不会以通常的方式结束并生成一个值。 break 或 return 会突然退出当前块、无限 loop 则根本不会结束，等等。

所以，在 Rust 中，这些表达式没有正常类型。不能正常结束的表达式属于一个特殊类型 !，并且它们不受“类型必须匹配”这条规则的约束。可以在 std::process::exit() 的函数签名中看到 !：

fn exit(code: i32) -> !

此处的 ! 表示 exit() 永远不会返回，它是一个 发散函数（divergent function）。

你可以用相同的语法编写自己的发散函数，这在某些情况下是很自然的：

fn serve_forever(socket: ServerSocket, handler: ServerHandler) -> ! {
 socket.listen();
 loop {
 let s = socket.accept();
 handler.handle(s);
 }
}

当然，如果此函数正常返回了，那么 Rust 就会认为它能正常返回反而是一个错误。

有了这些大规模控制流的构建块，就可以继续处理该流中常用的、更细粒度的表达式（比如函数调用和算术运算符）了。

6.9 函数与方法调用

Rust 中调用函数和方法的语法与许多其他语言中的语法相同：

let x = gcd(1302, 462); // 函数调用

let room = player.location(); // 方法调用

在此处的第二个示例中， player 是虚构类型 Player 的变量，它具有虚构的 .location() 方法。（第 9 章在讨论用户定义类型时会展示如何定义我们自己的方法。）

Rust 通常会在引用和它们所引用的值之间做出明确的区分。如果将 &i32 传给需要 i32 的函数，则会出现类型错误。你会注意到 . 运算符稍微放宽了这些规则。在调用 player. location() 的方法中， player 可能是一个 Player、一个 &Player 类型的引用，也可能是一个 Box<Player> 或 Rc<Player> 类型的智能指针。 .location() 方法可以通过值或引用获取 player。同一个 .location() 语法适用于所有情况，因为 Rust 的 . 运算符会根据需要自动对 player 解引用或借入一个对它的引用。

第三种语法用于调用类型关联函数，比如 Vec::new()：

let mut numbers = Vec::new(); // 类型关联函数调用

这些语法类似于面向对象语言中的静态方法：普通方法会在值上调用（如 my_vec.len()），类型关联函数会在类型上调用（如 Vec::new()）。

自然，也支持链式方法调用：

// 来自第2章的基于Actix的Web服务器
server
 .bind("127.0.0.1:3000").expect("error binding server to address")
 .run().expect("error running server");

Rust 语法的怪癖之一就是，在函数调用或方法调用中，泛型类型的常用语法 Vec<T> 是不起作用的：

return Vec<i32>::with_capacity(1000); // 错误：是某种关于“链式比较”的错误消息

let ramp = (0 .. n).collect<Vec<i32>>(); // 同样的错误

这里的问题在于，在表达式中 < 是小于运算符。Rust 编译器建议用 ::<T> 代替 <T>。这样就解决了问题：

return Vec::<i32>::with_capacity(1000); // 正确，改用::<

let ramp = (0 .. n).collect::<Vec<i32>>(); // 正确，改用::<

符号 ::<...> 在 Rust 社区中被亲切地称为 比目鱼（turbofish）。

或者，通常可以删掉类型参数，让 Rust 来推断它们：

return Vec::with_capacity(10); // 正确，只要fn的返回类型是Vec<i32>

let ramp: Vec<i32> = (0 .. n).collect(); // 正确，前面已给定变量的类型

只要类型可以被推断，就省略类型，这是一种很好的代码风格。

6.10 字段与元素

你可以使用早已熟悉的语法访问结构体的字段。元组也一样，不过它们的字段是数值而不是名称：

game.black_pawns // 结构体字段
coords.1 // 元组元素

如果 . 左边的值是引用或智能指针类型，那么它就会像方法调用一样自动解引用。

方括号会访问数组、切片或向量的元素：

pieces[i] // 数组元素

方括号左侧的值也会自动解引用。

像下面这样的 3 个表达式叫作 左值，因为赋值时它们可以出现在左侧：

game.black_pawns = 0x00ff0000_00000000_u64;
coords.1 = 0;
pieces[2] = Some(Piece::new(Black, Knight, coords));

当然，只有当 game、 coords 和 pieces 声明为 mut 变量时才允许这样做。

从数组或向量中提取切片的写法很直观：

let second_half = &game_moves[midpoint .. end];

这里的 game_moves 可以是数组、切片或向量，无论哪种方式，结果都是已被借出的长度为 end - midpoint 的切片。在 second_half 的生命周期内， game_moves 要被视为已借出的引用。

.. 运算符允许省略任何一个操作数，它会根据存在的操作数最多生成 4 种类型的对象：

.. // RangeFull
a .. // RangeFrom { start: a }
.. b // RangeTo { end: b }
a .. b // Range { start: a, end: b }

后两种形式是 排除结束值（或 半开放）的：结束值不包含在所表示的范围内。例如，范围 0 .. 3 包括数值 0、 1 和 2，但不包括 3。

..= 运算符会生成 包含结束值（或 封闭）的范围，其中包括结束值：

..= b // RangeToInclusive { end: b }
a ..= b // RangeInclusive::new(a, b)

例如，范围 0 ..= 3 包括数值 0、 1、 2 和 3。

只有包含起始值的范围才是可迭代的，因为循环必须从某处开始。但是在数组切片中，这 6 种形式都可以使用。如果省略了范围的起点或末尾，则默认为被切片数据的起点或末尾。

因此，经典的分治算法快速排序 quicksort 的实现部分看起来可能像下面这样。

fn quicksort<T: Ord>(slice: &mut [T]) {
 if slice.len() <= 1 {
 return; // 无可排序
 }

 // 把slice分成两部分：前半片和后半片
 let pivot_index = partition(slice);

 // 对slice的前半片递归排序
 quicksort(&mut slice[.. pivot_index]);

 // 对slice的后半片递归排序
 quicksort(&mut slice[pivot_index + 1 ..]);
}

6.11 引用运算符

地址运算符 & 和 &mut 已在第 5 章中介绍过。

一元 * 运算符用于访问引用所指向的值。如你所见，当使用 . 运算符访问字段或方法时，Rust 会自动追踪引用，因此只有想要读取或写入引用所指的整个值时才需要用 * 运算符。

例如，有时迭代器会生成引用，但程序需要访问底层值：

let padovan: Vec<u64> = compute_padovan_sequence(n);
for elem in &padovan {
 draw_triangle(turtle, *elem);
}

在此示例中， elem 的类型为 &u64，因此 *elem 为 u64。

6.12 算术运算符、按位运算符、比较运算符和逻辑运算符

Rust 的二元运算符与许多其他语言中的二元运算符类似。为了节省时间，这里假设你熟悉其中某一种语言，并专注于 Rust 与传统语言不同的几个点。

Rust 有一些常用的算术运算符： +、 -、 *、 / 和 %。如第 3 章所述，在调试构建中会检测到整数溢出并引发 panic。标准库为此提供了一些非检查（ unchecked）的算术方法，比如 a.wrapping_add(b)。

整数除法会向 0 取整，而整数除以 0 会触发 panic，即使在发布构建中也是如此。标准库为整数提供了一个 a.checked_div(b) 方法，它将返回一个 Option（如果 b 为 0 则返回 None），并且不会引发 panic。

一元 - 运算符会对一个数取负。它支持除无符号整数之外的所有数值类型。没有一元 + 运算符。

println!("{}", -100); // -100
println!("{}", -100u32); // 错误：不能在类型`u32`上使用一元`-`运算符
println!("{}", +100); // 错误：期待表达式，但发现了`+`

与在 C 中一样， a % b 会计算向 0 四舍五入的有符号余数或模数。其结果与左操作数的符号相同。注意， % 既能用于整数，也能用于浮点数：

let x = 1234.567 % 10.0; // 约等于4.567

Rust 还继承了 C 的按位整数运算符 &、 |、 ^、 << 和 >>。但是，Rust 会使用 ! 而不是 ~ 表示按位非：

let hi: u8 = 0xe0;
let lo = !hi; // 0x1f

这意味着对于整数 n，不能用 !n 来表示“ n 为 0”，而是应该写成 n == 0。

移位总是对有符号整数类型进行符号扩展，对无符号整数类型进行零扩展。由于 Rust 具有无符号整数，因此它不需要诸如 Java 的 >>> 运算符之类的无符号移位运算符。

与 C 不同，Rust 中按位运算的优先级高于比较运算，因此如果编写 x & BIT != 0，那么就意味着 (x & BIT) != 0，正如预期的那样。这比在 C 中解释成的 x & (BIT != 0) 有用得多，后者会测试错误的位。

Rust 的比较运算符是 ==、 !=、 <、 <=、 > 和 >=，参与比较的两个值必须具有相同的类型。

Rust 还有两个短路逻辑运算符 && 和 ||，它们的操作数都必须具有确切的 bool 类型。

6.13 赋值

= 运算符用于给 mut 变量及其字段或元素赋值。但是赋值在 Rust 中不像在其他语言中那么常见，因为默认情况下变量是不可变的。

如第 4 章所述，如果值是非 Copy 类型的，则赋值会将其 移动 到目标位置。值的所有权会从源转移给目标。目标的先前值（如果有的话）将被丢弃。

Rust 支持复合赋值：

total += item.price;

这等效于 total = total + item.price;。Rust 也支持其他运算符： -=、 *= 等。完整列表参见表 6-1。

与 C 不同，Rust 不支持链式赋值：不能编写 a = b = 3 来将值 3 同时赋给 a 和 b。赋值在 Rust 中非常罕见，你是不会想念这种简写形式的。

Rust 没有 C 的自增运算符 ++ 和自减运算符 --。

6.14 类型转换

在 Rust 中，将值从一种类型转换为另一种类型通常需要进行显式转换。这种转换要使用 as 关键字：

let x = 17; // x是i32类型的
let index = x as usize; // 转换成usize

Rust 允许进行好几种类型的转换。

• 数值可以从任意内置数值类型转换为其他内置数值类型。

  将一种整数类型转换为另一种整数类型始终是明确定义的。转换为更窄的类型会导致截断。转换为更宽类型的有符号整数会进行符号扩展，转换为无符号整数会进行零扩展，等等。简而言之，没有意外。

  从浮点类型转换为整数类型会向 0 舍入，比如 -1.99 as i32 就是 -1。如果值太大而无法容纳整数类型，则转换会生成整数类型可以表示的最接近的值，比如 1e6 as u8 就是 255。

• bool 类型或 char 类型的值或者类似 C 的 enum 类型的值可以转换为任何整数类型。（第 10 章会介绍枚举。）

  不允许向相反方向转换，因为 bool 类型、 char 类型和 enum 类型都对其值有限制，必须通过运行期检查强制执行。例如，禁止将 u16 转换为 char 类型，因为某些 u16 值（如 0xd800）对应于 Unicode 的半代用区码点，因此无法生成有效的 char 值。有一个标准方法 std::char::from_u32()，它会执行运行期检查并返回一个 Option<char>，但更重要的是，这种转变的需求已经越来越少了。我们通常会一次转换整个字符串或流，Unicode 文本的算法通常比较复杂，最好留给库去实现。

  作为例外， u8 可以转换为 char 类型，因为从 0 到 255 的所有整数都是 char 能持有的有效 Unicode 码点。

• 一些涉及不安全指针类型的转换也是允许的。参见 22.8 节。

我们说过 通常 需要进行强制转换。但一些涉及引用类型的转换非常直观，Rust 甚至无须强制转换就能执行它们。一个简单的例子是将可变引用转换为不可变引用。

不过，还可能会发生几个更重要的自动转换。

• &String 类型的值会自动转换为 &str 类型，无须强制转换。
• &Vec<i32> 类型的值会自动转换为 &[i32]。
• &Box<Chessboard> 类型的值会自动转换为 &Chessboard。

这些称为 隐式解引用，因为它们适用于所有实现了内置特型 Deref 的类型。 Deref 隐式转换的目的是使智能指针类型（如 Box）的行为尽可能像其底层值。多亏了 Deref， Box<Chessboard> 的用法基本上和普通 Chessboard 的用法一样。

用户定义类型也可以实现 Deref 特型。当你需要编写自己的智能指针类型时，请参阅 13.5 节。

6.15 闭包

Rust 也有 闭包，即轻量级的类似函数的值。闭包通常由一个参数列表组成，在两条竖线之间列出，后跟一个表达式：

let is_even = |x| x % 2 == 0;

Rust 会推断其参数类型和返回类型。你也可以像写函数一样显式地写出它们。如果确实指定了返回类型，那么为了语法的完整性，闭包的主体必须是一个块：

let is_even = |x: u64| -> bool x % 2 == 0; // 错误

let is_even = |x: u64| -> bool { x % 2 == 0 }; // 正确

调用闭包和调用函数的语法是一样的：

assert_eq!(is_even(14), true);

闭包是 Rust 最令人愉悦的特性之一，关于它们还有很多内容可以讲，第 14 章会详细介绍。

6.16 前路展望

表达式就是我们心目中的“可执行代码”，它们是 Rust 程序中编译成机器指令的那部分。然而，表达式也只是整个语言的一小部分。

大多数编程语言也是如此。程序的首要任务是执行，但这不是它唯一的任务。程序必须进行通信，必须是可测试的，必须保持组织性和灵活性，这样它们才能持续演进。程序还需要与其他团队构建的代码和服务进行互操作。就算只是为了执行，像 Rust 这样的静态类型语言的程序也需要更多的工具来组织数据，而不能仅仅使用元组和数组。

接下来，本书会用几章内容来讨论这些特性：首先是模块与 crate，它们会帮你对程序进行组织；然后是结构体与枚举，它们会帮你对数据进行组织。

不过，在此之前我们先来简单讨论一下“错误处理”这个重要主题。

第 7 章 错误处理

我知道只要活得足够久，这种事就一定会发生。

——萧伯纳论死亡

Rust 的错误处理方法很不寻常，值得用单独的一章来讨论。这里没有什么深奥的编程思想，只是对你来说可能有点儿新而已。本章介绍了 Rust 中的两类错误处理：panic 和 Result。

普通错误使用 Result 类型来处理。 Result 通常用以表示由程序外部的事物引发的错误，比如错误的输入、网络中断或权限问题。这些问题并不是意料之中的，在没有任何 bug 的程序中也可能会不时出现。虽然本章大部分内容是关于 Result 的，但我们会先介绍 panic，因为它相对来说比较简单。

panic 针对的是另一种错误，即那种 永远不应该发生 的错误。1

7.1 panic

当程序遇到下列问题的时候，就可以断定程序自身存在 bug，故而会引发 panic：

• 数组越界访问；
• 整数除以 0；
• 在恰好为 Err 的 Result 上调用 .expect()；
• 断言失败。

（ panic!() 是一种宏，用于处理程序中出现错误的情况。当你的代码检测到出现错误并需要立即触发 panic 时，就可以使用这个宏。 panic!() 可以接受类似于 println!() 的可选参数表，用于构建错误消息。）

以上情况的共同点是它们都由（不客气地说）程序员的错误所导致。而行之有效的一条经验法则是：“不要 panic”。

但每个人都会失误。如果这些不该发生的错误真的发生了，那么该怎么办呢？Rust 为你提供了一种选择。Rust 既可以在发生 panic 时展开调用栈，也可以中止进程。展开调用栈是默认方案。

7.1.1 展开调用栈

当海盗瓜分战利品时，船长会先分得一半，普通船员再对另一半进行平分。（众所周知，海盗讨厌小数，所以如果不能恰好平分，那么其结果将向下舍入，剩下的归船上的鹦鹉所有。）

fn pirate_share(total: u64, crew_size: usize) -> u64 {
 let half = total / 2;
 half / crew_size as u64
}

几个世纪以来，上述算法都能正常工作，直到有一天……船长成了抢劫后唯一的幸存者。如果将 0 作为 crew_size 传给此函数，那么它将除以 0。在 C++ 中，这将是未定义行为。而在 Rust 中，这会触发 panic，通常会按如下方式处理。

• 把一条错误消息打印到终端。

  thread 'main' panicked at 'attempt to divide by zero', pirates.rs:3780
  note: Run with `RUST_BACKTRACE=1` for a backtrace.
  

  如果设置了 RUST_BACKTRACE 环境变量，那么就像这条消息中建议的，Rust 也会在这里转储当前的调用栈。

• 展开调用栈。这很像 C++ 的异常处理。

  当前函数使用的任何临时值、局部变量或参数都将按照与创建它们时相反的顺序被丢弃。丢弃一个值仅仅意味着随后会进行清理：程序正在使用的任何字符串或向量都将被释放，所有打开的文件都将被关闭，等等。还会调用由用户定义的 drop 方法，请参阅 13.1 节。就 pirate_share() 函数而言，没有需要清理的内容。

  清理了当前函数调用后，我们将继续执行到其调用者中，以相同的方式丢弃其变量和参数。然后再“走到” 那个调用者 的调用者中，在调用栈中逐级向上，以此类推。

• 最后，线程退出。如果 panic 线程是主线程，则整个进程退出（使用非零退出码）。

也许把 panic 作为这个有序过程的名称有误导性。panic 不是崩溃，也不是未定义行为。它更像是 Java 中的 RuntimeException 或 C++ 中的 std::logic_error。其行为是明确定义的，只是本就不该发生罢了。

panic 是安全的，没有违反 Rust 的任何安全规则，即使你故意在标准库方法的中间引发 panic，它也永远不会在内存中留下悬空指针或半初始化的值。Rust 的设计理念是要在出现任何意外之前捕获诸如无效数组访问之类的错误。继续往下执行显然是不安全的，所以 Rust 会展开这个调用栈。但是进程的其余部分可以继续运行。

panic 是基于线程的。一个线程 panic 时，其他线程可以继续做自己的事。第 19 章会展示父线程如何发现子线程中的 panic 并优雅地处理错误。

还有一种方法可以 捕获 调用栈展开，让线程“存活”并继续运行。标准库函数 std::panic::catch_unwind() 可以做到这一点。本章不会介绍如何使用它，但这是 Rust 的测试工具用于在测试中断言失败时进行恢复的机制。（在编写可以从 C 或 C++ 调用的 Rust 代码时，这种机制是必需的，因为跨越非 Rust 代码展开调用栈是未定义行为，详情请参阅第 22 章。）

人无完人，没有 bug 且不会出现 panic 的代码只存在于理想之中。为了使程序更加健壮，可以使用线程和 catch_unwind() 来处理 panic。但有一个重要的限制，即这些工具只能捕获那些会展开调用栈的 panic。不过，并非所有 panic 都会展开调用栈。

7.1.2 中止

调用栈展开是默认的 panic 处理行为，但在两种情况下 Rust 不会试图展开调用栈。

如果 Rust 在试图清理第一个 panic 时， .drop() 方法触发了第二个 panic，那么这个 panic 就是致命的。Rust 会停止展开调用栈并中止整个进程。

此外，Rust 处理 panic 的行为是可定制的。如果使用 -C panic=abort 参数进行编译，那么程序中的 第一个 panic 会立即中止进程。（如果使用这个选项，那么 Rust 就不需要知道如何展开调用栈，故此可以减小编译后的代码的大小。）

对 Rust 中 panic 机制的讨论到此结束。需要说的就这些，因为普通的 Rust 代码没有处理 panic 的义务。即使你确实使用了线程或 catch_unwind()，所有的 panic 处理代码也会集中在几个地方。期望程序中的每个函数都能预测并处理其自身代码中的 bug 是不合理的。但由其他因素引起的错误就是另一回事了。

7.2 Result

Rust 中没有异常。相反，函数执行失败时会有像下面这样的返回类型：

fn get_weather(location: LatLng) -> Result<WeatherReport, io::Error>

Result 类型会指示出可能的失败。当我们调用 get_weather() 函数时，它要么返回一个 成功结果 Ok(weather)，其中的 weather 是一个新的 WeatherReport 值；要么返回一个 错误结果 Err(error_value)，其中的 error_value 是一个 io::Error，用来解释出了什么问题。

每当调用此函数时，Rust 都会要求我们编写某种错误处理代码。如果不对 Result 执行 某些 操作，就无法获取 WeatherReport；如果未使用 Result 值，就会收到编译器警告。

第 10 章将介绍标准库如何定义 Result 以及我们如何自定义出类似的类型。本章将采用类似“食谱”的方式并专注于使用 Result 来实现你期望的错误处理行为。你将了解如何捕获错误、传播错误和报告错误，以及关于组织和使用 Result 类型的常见模式。

7.2.1 捕获错误

第 2 章中已经展示过 Result 最彻底的处理方式：使用 match 表达式。

match get_weather(hometown) {
 Ok(report) => {
 display_weather(hometown, &report);
 }
 Err(err) => {
 println!("error querying the weather: {}", err);
 schedule_weather_retry();
 }
}

这相当于其他语言中的 try/catch。如果想直接处理错误而不是将错误传给调用者，就可以使用这种方式。

match 有点儿冗长，因此 Result<T, E> 针对一些常见的特定场景提供了多个有用的方法，每个方法在其实现中都有一个 match 表达式。（有关 Result 方法的完整列表，请查阅在线文档。此处列出的是最常用的方法。）

result.is_ok()（已成功）和 result.is_err()（已出错）

返回一个 bool，告知此结果是成功了还是出错了。

result.ok()（成功值）

以 Option<T> 类型返回成功值（如果有的话）。如果 result 是成功的结果，就返回 Some(success_value)；否则，返回 None，并丢弃错误值。

result.err()（错误值）

以 Option<E> 类型返回错误值（如果有的话）。

result.unwrap_or(fallback)（解包或回退值）

如果 result 为成功结果，就返回成功值；否则，返回 fallback，丢弃错误值。

// 对南加州而言，这是一则十拿九稳的天气预报
const THE_USUAL: WeatherReport = WeatherReport::Sunny(72);

// 如果可能，就获取真实的天气预报；如果不行，就回退到常见状态
let report = get_weather(los_angeles).unwrap_or(THE_USUAL);
display_weather(los_angeles, &report);

这是 .ok() 的一个很好的替代方法，因为返回类型是 T，而不是 Option<T>。当然，只有存在合适的回退值时，才能用这个方法。

result.unwrap_or_else(fallback_fn)（解包，否则调用）

这个方法也一样，但不会直接传入回退值，而是传入一个函数或闭包。它针对的是大概率不会用到回退值且计算回退值会造成浪费的情况。只有在得到错误结果时才会调用 fallback_fn。

let report =
 get_weather(hometown)
 .unwrap_or_else(|_err| vague_prediction(hometown));

（第 14 章会详细介绍闭包。）

result.unwrap()（解包）

如果 result 是成功结果，那么此方法同样会返回成功值。但如果 result 是错误结果，则会引发 panic。此方法有其应用场景，后面会详细讨论。

result.expect(message)（期待）

与 .unwrap() 相同，但此方法允许你提供一条消息，在发生 panic 时会打印该消息。

最后是处理 Result 引用的两个方法。

result.as_ref()（转引用）

将 Result<T, E> 转换为 Result<&T, &E>。

result.as_mut()（转可变引用）

与上一个方法一样，但它借入了一个可变引用，其返回类型是 Result<&mut T, &mut E>。

最后这两个方法之所以有用，是因为前面列出的所有其他方法，除了 .is_ok() 和 .is_err()，都在 消耗 result。也就是说，它们会按值接受 self 参数。有时在不破坏 result 的情况下访问 result 中的数据是非常方便的，这就是 .as_ref() 和 .as_mut() 的用武之地。假设你想调用 result.ok()，但要让 result 保持不可变状态，那么就可以写成 result.as_ref().ok()，它只会借用 result，返回 Option<&T> 而非 Option<T>。

7.2.2 Result 类型别名

有时你会看到 Rust 文档中似乎忽略了 Result 中的错误类型：

fn remove_file(path: &Path) -> Result<()>

这意味着正在使用 Result 的类型别名。

类型别名是类型名称的一种简写形式。模块通常会定义一个 Result 类型的别名，以免重复编写模块中几乎每个函数都要用到的 Error 类型。例如，标准库的 std::io 模块包括下面这行代码：

pub type Result<T> = result::Result<T, Error>;

这定义了一个公共类型 std::io::Result<T>，它是 Result<T, E> 的别名，但将错误类型硬编码为 std::io::Error。实际上，这意味着如果你写下 use std::io;，那么 Rust 就会将 io::Result<String> 当作 Result<String, io::Error> 的简写形式。

当在线文档中出现类似 Result<()> 的内容时，可以单击标识符 Result 以查看正在使用的类型别名并了解其错误类型。实践中，错误类型在上下文中通常是显而易见的。

7.2.3 打印错误

有时处理错误的唯一方法是将其转储到终端并继续执行。前面已经展示过这样处理的一种方法：

println!("error querying the weather: {}", err);

标准库定义了几种名称平平无奇的错误类型： std::io::Error、 std::fmt::Error、 std::str::Utf8Error 等。它们都实现了一个公共接口，即 std::error::Error 特型，这意味着它们都有以下特性和方法。

println!()（打印）

所有错误类型都可以通过 println!() 打印出来。使用格式说明符 {} 打印错误通常只会显示一条简短的错误消息。或者，也可以使用格式说明符 {:?}，以获得该错误的 Debug 视图。虽然这对用户不太友好，但包含额外的技术信息。

// `println!("error: {}", err);`的结果
error: failed to look up address information: No address associated with
hostname

// `println!("error: {:?}", err);`的结果
error: Error { repr: Custom(Custom { kind: Other, error: StringError(
"failed to look up address information: No address associated with
hostname") }) }

err.to_string()（转字符串）

以 String 形式返回错误消息。

err.source()（错误来源）

返回导致 err 的底层错误的 Option（如果有的话）。例如，网络错误可能导致银行交易失败，进而导致你的游艇被收回。如果 err.to_string() 是 "boat was repossessed"，那么 err.source() 可能会返回关于本次交易失败的错误。该错误的 .to_string() 可能是 "failed to transfer $300 to United Yacht Supply"，而该错误的 .source() 可能是一个 io::Error（第二个错误），其中包含导致这一切乱象的特定网络中断的详细信息。第三个错误是根本原因，因此它的 .source() 方法应该返回 None。由于标准库仅包含相当底层的特性，因此从标准库返回的错误来源（ .source()）通常都是 None。

打印一个错误值并不会打印出其来源。如果想确保打印所有可用信息，请使用下面这个函数：

use std::error::Error;
use std::io::;

/// 把错误消息转储到`stderr`
///
/// 如果在构建此错误消息或将其写入`stderr`期间发生了另一个错误，就忽略新的错误
fn print_error(mut err: &dyn Error) {
 let _ = writeln!(stderr(), "error: {}", err);
 while let Some(source) = err.source() {
 let _ = writeln!(stderr(), "caused by: {}", source);
 err = source;
 }
}

writeln! 宏类似于 println!，但它会将数据写入所选的流。在这里，我们将错误消息写入了标准错误流 std::io::stderr。可以使用 eprintln! 宏做同样的事情，但是如果 eprintln! 中发生了错误，就会 panic。在 print_error 中，要忽略在写入消息时出现的错误，稍后 7.2.7 节会解释原因。

标准库的这些错误类型不包括调用栈跟踪，但是，当与不稳定版本的 Rust 编译器一起使用时，可以使用广受欢迎的 anyhow crate 提供的一个现成的错误类型。（直到 Rust 1.50 为止，标准库中用于捕获回溯跟踪的函数尚未稳定。）

7.2.4 传播错误

大多数时候，当我们试图做某些可能失败的事情时，可能不想立即捕获并处理错误。如果在每个可能出错的地方都要使用十来行 match 语句，那代码就太多了。

因此，当发生某种错误时，我们通常希望让调用者去处理。也就是说，我们希望错误沿着调用栈向上 传播。

Rust 的 ? 运算符可以执行此操作。可以为任何生成 Result 的表达式加上一个 ?，比如将其加在函数调用的结果后面：

let weather = get_weather(hometown)?;

? 的行为取决于此函数是返回了成功结果还是错误结果。

• 如果是成功结果，那么它会解包 Result 以获取其中的成功值。这里的 weather 类型不是 Result<WeatherReport, io::Error>，而是简单的 WeatherReport。
• 如果是错误结果，那么它会立即从所在函数返回，将错误结果沿着调用链向上传播。为了确保此操作有效， ? 只能在返回类型为 Result 的函数中的 Result 值上使用。

? 运算符并无任何神奇之处。可以使用 match 表达式来表达同样的意图，只是更冗长：

let weather = match get_weather(hometown) {
 Ok(success_value) => success_value,
 Err(err) => return Err(err)
};

? 运算符与 match 表达式唯一的区别在于，它有一些涉及类型和转换的知识点。7.2.5 节会介绍这些细节。

在旧式代码中，你可能还会看到 try!() 宏，在 Rust 1.13 引入 ? 运算符之前，这是传播错误的常用方法：

let weather = try!(get_weather(hometown));

此宏会扩展为一个 match 表达式，就像之前那段代码一样。

人们很难意识到在程序中出现错误的情况有多普遍，尤其是在与操作系统交互的代码中。 ? 运算符有时几乎会出现在函数的每一行中：

use std::fs;
use std::io;
use std::path::Path;

fn move_all(src: &Path, dst: &Path) -> io::Result<()> {
 for entry_result in src.read_dir()? { // 打开目录可能失败
 let entry = entry_result?; // 读取目录可能失败
 let dst_file = dst.join(entry.file_name());
 fs::rename(entry.path(), dst_file)?; // 重命名可能失败
 }
 Ok(()) // 哦……总算结束了！
}

? 的作用也与 Option 类型相似。在返回 Option 类型的函数中，也可以使用 ? 解包某个值，这样当遇到 None 时就会提前返回。

let weather = get_weather(hometown).ok()?;

7.2.5 处理多种 Error 类型

通常，不止一个操作会出错。假设我们只想从文本文件中读取数值：

use std::io::;

/// 从文本文件中读取整数
/// 该文件中应该每行各有一个数值
fn read_numbers(file: &mut dyn BufRead) -> Result<Vec<i64>, io::Error> {
 let mut numbers = vec![];
 for line_result in file.lines() {
 let line = line_result?; // 读取各行可能失败
 numbers.push(line.parse()?); // 解析整数可能失败
 }
 Ok(numbers)
}

Rust 会报告一个编译器错误：

error: `?` couldn't convert the error to `std::io::Error`

 numbers.push(line.parse()?); // 解析整数可能失败
 ^
 the trait `std::convert::From<std::num::ParseIntError>`
 is not implemented for `std::io::Error`

note: the question mark operation (`?`) implicitly performs a conversion
on the error value using the `From` trait

当我们读到第 11 章（介绍了相关特型）时，本错误消息中的这些术语会更有意义。现在，只需要注意 Rust 正在报错说 ? 运算符不能将 std::num::ParseIntError 值转换为 std::io::Error 类型就可以了。

这里的问题在于从文件中读取一行并解析一个整数时会生成两种潜在错误类型。 line_result 的类型是 Result<String, std::io::Error>。 line.parse() 的类型是 Result<i64, std::num::ParseIntError>。而我们的 read_numbers() 函数的返回类型只能容纳 io::Error。Rust 试图将 ParseIntError 转换为 io::Error，但是无法进行这样的转换，所以我们得到了一个类型错误。

有几种方法可以解决这个问题。例如，第 2 章中用于创建曼德博集图像文件的 image crate 定义了自己的错误类型 ImageError，并实现了从 io::Error 和其他几种错误类型到 ImageError 的转换。如果你想采用这种方法，那么可以试试 thiserror crate，它旨在帮助你用几行代码就定义出良好的错误类型。

还有一种更简单的方法是使用 Rust 中内置的特性。所有标准库中的错误类型都可以转换为类型 Box<dyn std::error::Error + Send + Sync + 'static>。这虽然有点儿啰唆，不过也不算难： dyn std::error::Error 表示“任何错误”， Send + Sync + 'static 表示可以安全地在线程之间传递，而这往往是我们的要求。2为便于使用，还可以定义类型别名：

type GenericError = Box<dyn std::error::Error + Send + Sync + 'static>;
type GenericResult<T> = Result<T, GenericError>;

然后，将 read_numbers() 的返回类型改为 GenericResult<Vec<i64>>。这样一来，函数就可以编译了。 ? 运算符会根据需要自动将任意类型的错误转换为 GenericError。

顺便说一句， ? 运算符使用了一种标准方法进行这种自动转换。你也可以使用这种方法将任何错误转换为 GenericError 类型，为此，可以调用 GenericError::from()：

let io_error = io::Error::new( // 制作自己的io::Error
 io::ErrorKind::Other, "timed out");
return Err(GenericError::from(io_error)); // 手动转换成GenericError

第 13 章会全面介绍 From 特型及其 from() 方法。

GenericError 方法的缺点是返回类型不再准确地传达调用者可预期的错误类型。调用者必须做好应对任何情况的准备。

如果你正在调用一个返回 GenericResult 的函数，并且想要处理一种特定类型的错误，而让所有其他错误传播出去，那么可以使用泛型方法 error.downcast_ref::<ErrorType>()。 如果 这个错误恰好是你要找的那种类型的错误，那么该方法就会借用对它的引用：

loop {
 match compile_project() {
 Ok(()) => return Ok(()),
 Err(err) => {
 if let Some(mse) = err.downcast_ref::<MissingSemicolonError>() {
 insert_semicolon_in_source_code(mse.file(), mse.line())?;
 continue; // 再试一次！
 }
 return Err(err);
 }
 }
}

许多语言提供了内置语法来执行此操作，但事实证明没什么必要。Rust 可以用 downcast_ref 方法代替它。

7.2.6 处理“不可能发生”的错误

有时我们明确 知道 某个错误不可能发生。假设我们正在编写代码来解析配置文件，并且确信文件中接下来的内容肯定是一串数字：

if next_char.is_digit(10) {
 let start = current_index;
 current_index = skip_digits(&line, current_index);
 let digits = &line[start..current_index];
 ...

我们想将这个数字串转换为实际的数值。有一个标准方法可以做到这一点：

let num = digits.parse::<u64>();

现在的问题是： str.parse::<u64>() 方法不返回 u64，而是返回了一个 Result。转换可能会失败，因为某些字符串不是数值：

"bleen".parse::<u64>() // ParseIntError: 无效的数字

但我们碰巧知道，在这种情况下， digits 一定完全由数字组成。那么应该怎么办呢？

如果我们正在编写的代码已经返回了 GenericResult，那么就可以添加一个 ?，并且忽略这个错误。否则，我们将不得不为处理不可能发生的错误而烦恼。最好的选择是使用 Result 的 .unwrap() 方法。如果结果是 Err，就会 panic；但如果成功了，则会直接返回 Ok 中的成功值：

let num = digits.parse::<u64>().unwrap();

这和 ? 的用法很相似，但如果我们对这个错误有没有可能发生的理解是错误的，也就是说如果它其实 有可能 发生，那么这种情况就会报 panic。

事实上，对于刚才这个例子，我们确实理解错了。如果输入中包含足够长的数字串，则这个数值会因为太大而无法放入 u64 中：

"99999999999999999999".parse::<u64>() // 溢出错误

因此，在这种特殊情况下使用 .unwrap() 存在 bug。这种有 bug 的输入本不应该引发 panic。

话又说回来，确实会出现 Result 值不可能是错误的情况。例如，在第 18 章中，你会看到 Write 特型为文本和二进制输出定义了一组泛型方法（ .write() 等）。所有这些方法都会返回 io::Result，但如果你碰巧正在写入 Vec<u8>，那么它们就不可能失败。在这种情况下，可以使用 .unwrap() 或 .expect(message) 来简化 Result 的处理。

当错误表明情况相当严重或异乎寻常，理当用 panic 对它进行处理时，这些方法也很有用：

fn print_file_age(filename: &Path, last_modified: SystemTime) {
 let age = last_modified.elapsed().expect("system clock drift");
 ...
}

在这里，仅当系统时间 早于 文件创建时间时， .elapsed() 方法才会失败。如果文件是最近创建的，并且在程序运行期间系统时钟往回调整过，就会发生这种情况。根据这段代码的使用方式，在这种情况下，调用 panic 是一个合理的选择，而不必处理该错误或将该错误传播给调用者。

7.2.7 忽略错误

有时我们只想完全忽略一个错误。例如，在 print_error() 函数中，我们必须处理打印一个错误时会触发另一个错误等罕见情况。如果将 stderr 通过管道传给另一个进程，而那个进程已终止，就可能发生这种情况。因为要报告的原始错误可能更值得传播，所以我们只想忽略 stderr 带来的这些小麻烦，但 Rust 编译器会警告你有未使用的 Result 值：

writeln!(stderr(), "error: {}", err); // 警告：未使用的结果

惯用法 let _ = ... 可用来消除这种警告。

let _ = writeln!(stderr(), "error: {}", err); // 正确，忽略结果

7.2.8 处理 main() 中的错误

在大多数生成 Result 的地方，让错误冒泡到调用者通常是正确的行为。这就是为什么 ? 在 Rust 中会设计成单字符语法。正如我们所见，在某些程序中，它曾连续用于多行代码。

但是，如果你传播错误的距离足够远，那么最终它就会抵达 main()，后者必须对其进行处理。通常来说， main() 不能使用 ?，因为它的返回类型不是 Result：

fn main() {
 calculate_tides()?; // 错误：main()无法再推卸责任了
}

处理 main() 中错误的最简单方式是使用 .expect()：

fn main() {
 calculate_tides().expect("error"); // 责任止于此
}

如果 calculate_tides() 返回错误结果，那么 .expect() 方法就会 panic。主线程中的 panic 会打印出一条错误消息，然后以非零的退出码退出，大体上，这就是我们期望的行为。在一般的小型程序中我们都是这样做的。这是一个开始。

不过，错误消息有点儿吓人：

$ tidecalc --planet mercury
thread 'main' panicked at 'error: "moon not found"', src/main.rs:2:23
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

错误消息淹没在噪声中。此外，在这种特殊情况下， RUST_BACKTRACE=1 是一个糟糕的建议。

但是，也可以更改 main() 的类型签名以返回 Result 类型，这样就可以使用 ? 了 :

fn main() -> Result<(), TideCalcError> {
 let tides = calculate_tides()?;
 print_tides(tides);
 Ok(())
}

这适用于任何能用 {:?} 格式说明符打印的错误类型，也就是说，所有标准错误类型（如 std::io::Error）都适用。这种技巧易于使用，并能提供更好的错误消息，但它并不理想：

$ tidecalc --planet mercury
Error: TideCalcError { error_type: NoMoon, message: "moon not found" }

如果你有更复杂的错误类型或想要在消息中包含更多信息，那么可以自己打印错误消息：

fn main() {
 if let Err(err) = calculate_tides() {
 print_error(&err);
 std::process::exit(1);
 }
}

上述代码使用了 if let 表达式，以便仅在对 calculate_tides() 的调用返回错误结果时才打印错误消息。有关 if let 表达式的详细信息，请参阅第 10 章。 print_error 函数在 7.2.3 节中介绍过。

现在的输出就相当整洁了。

$ tidecalc --planet mercury
error: moon not found

7.2.9 声明自定义错误类型

假设你正在编写一个新的 JSON 解析器，并且希望它有自己的错误类型。（到目前为止，本书尚未介绍用户定义类型，后面我们将用几章的篇幅进行介绍。声明错误类型很简单，我们先在此处大概预览一下。）

要编写的代码大概也就下面几行：

// json/src/error.rs

#[derive(Debug, Clone)]
pub struct JsonError {
 pub message: String,
 pub line: usize,
 pub column: usize,
}

这个结构体叫作 json::error::JsonError。当你想引发这种类型的错误时，可以像下面这样写：

return Err(JsonError {
 message: "expected ']' at end of array".to_string(),
 line: current_line,
 column: current_column
});

这没什么问题。但是，如果你希望达到你的库用户的预期，确保这个错误类型像标准错误类型一样工作，那么还有一点儿额外的工作要做：

use std::fmt;

// 错误应该是可打印的
impl fmt::Display for JsonError {
 fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
 write!(f, "{} ({}:{})", self.message, self.line, self.column)
 }
}

// 错误应该实现std::error::Error特型，但使用Error各个方法的默认定义就够了
impl std::error::Error for JsonError { }

impl 关键字、 self 和其他所有关键字的含义在后面的几章中会进行解释。

与 Rust 语言的许多方面一样，各种 crate 的存在是为了让错误处理更容易、更简洁。crate 种类繁多，但最常用的一个是 thiserror，它会帮你完成之前的所有工作，让你像下面这样编写错误定义：

use thiserror::Error;

#[derive(Error, Debug)]
#[error(" (, )")]
pub struct JsonError {
 message: String,
 line: usize,
 column: usize,
}

#[derive(Error)] 指令会让 thiserror 生成前面展示过的代码，这可以节省大量的时间和精力。

7.2.10 为什么是 Result

现在我们已经足够了解为何 Rust 会优先选择 Result 而非异常了。以下是此设计的几个要点。

• Rust 要求程序员在每个可能发生错误的地方做出某种决策，并将其记录在代码中。这样做很好，否则容易因为疏忽而无法正确处理错误。
• 最常见的决策是让错误继续传播，而这用单个字符 ? 就可以实现。因此，错误处理管道不会像在 C 和 Go 中那样让你的代码混乱不堪，而且它还具有可见性：在浏览一段代码时，你一眼就能看出错误是从哪里传出来的。
• 是否可能出错是每个函数的返回类型的一部分，因此哪些函数会失败、哪些不会失败非常清晰。如果你将一个函数改为可能出错的，那么就要同时更改它的返回类型，而编译器会让你随之修改该函数的各个下游使用者。
• Rust 会检查 Result 值是否被用过了，这样你就不会意外地让错误悄悄溜过去（C 中的常见失误）。
• 由于 Result 是一种与任何其他数据类型没有本质区别的数据类型，因此很容易将成功结果和错误结果存储在同一个集合中，也很容易对“部分成功”的情况进行模拟。如果你正在编写一个从文本文件加载数百万条记录的程序，并且需要一种方法来处理大多数时候会成功但偶尔也会失败的可能结果，就可以用向量 Result 在内存中表达出现这种结果时的情形。

这样设计的代价是，你会发现自己在 Rust 中要比在其他语言中做更多的思考和工程化的错误处理。与许多其他领域一样，Rust 在错误处理方面比你所习惯的要严格一些。但对系统编程来说，这绝对是值得的。

第 8 章 crate 与模块(1)

第 8 章 crate 与模块

这是 Rust 主题下的小小理念之一：系统程序员也能享受美好。

——Robert O'Callahan，“Random Thoughts on Rust: crates.io and IDEs”

假设你正在编写一个程序，用来模拟蕨类植物从单个细胞开始的生长过程。你的程序，也像蕨类植物一样，一开始会非常简单，所有的代码也许都在一个文件中——这只是想法的萌芽。随着成长，它将开始分化出内部结构，不同的部分会有不同的用途。然后它将分化成多个文件，可能遍布在各个目录中。随着时间的推移，它可能会成为整个软件生态系统的重要组成部分。对于任何超出几个数据结构或几百行代码的程序，进行适当的组织都是很有必要的。

本章介绍了 Rust 的一些特性（crate 与模块），这些特性有助于你的程序保持井井有条。我们还将涵盖其他与 Rust crate 的结构和分发有关的主题，包括如何记录与测试 Rust 代码、如何消除不必要的编译器警告、如何使用 Cargo 管理项目依赖项和版本控制、如何在 Rust 的公共 crate 存储库 crates.io 上发布开源库、Rust 如何通过语言版本进行演进等。本章将使用蕨类模拟器作为运行示例。

8.1 crate

Rust 程序由 crate（板条箱）组成。每个 crate 都是既完整又内聚的单元，包括单个库或可执行程序的所有源代码，以及任何相关的测试、示例、工具、配置和其他杂项。对于蕨类植物模拟器，我们可以使用第三方库完成 3D 图形、生物信息学、并行计算等工作。这些库以 crate 的形式分发，如图 8-1 所示。

图 8-1：一个 crate 及其依赖

弄清楚 crate 是什么以及它们如何协同工作的最简单途径是，使用带有 --verbose 标志的 cargo build 来构建具有某些依赖项的现有项目。我们以 2.6.6 节的“并发曼德博程序”为例来执行此操作。结果如下所示：

$ cd mandelbrot
$ cargo clean # 删除之前编译的代码
$ cargo build --verbose
 Updating registry `https://github.com/rust-lang/crates.io-index`
 Downloading autocfg v1.0.0
 Downloading semver-parser v0.7.0
 Downloading gif v0.9.0
 Downloading png v0.7.0

... (downloading and compiling many more crates)

Compiling jpeg-decoder v0.1.18
 Running `rustc
 --crate-name jpeg_decoder
 --crate-type lib
 ...
 --extern byteorder=.../libbyteorder-29efdd0b59c6f920.rmeta
 ...
 Compiling image v0.13.0
 Running `rustc
 --crate-name image
 --crate-type lib
 ...
 --extern byteorder=.../libbyteorder-29efdd0b59c6f920.rmeta
 --extern gif=.../libgif-a7006d35f1b58927.rmeta
 --extern jpeg_decoder=.../libjpeg_decoder-5c10558d0d57d300.rmeta
 Compiling mandelbrot v0.1.0 (/tmp/rustbook-test-files/mandelbrot)
 Running `rustc
 --edition=2021
 --crate-name mandelbrot
 --crate-type bin
 ...
 --extern crossbeam=.../libcrossbeam-f87b4b3d3284acc2.rlib
 --extern image=.../libimage-b5737c12bd641c43.rlib
 --extern num=.../libnum-1974e9a1dc582ba7.rlib -C link-arg=-fuse-ld=lld`
 Finished dev [unoptimized + debuginfo] target(s) in 16.94s
$

这里重新格式化了 rustc 命令行以提高可读性，我们删除了很多与本次讨论无关的编译器选项，然后将它们替换成了省略号（ ...）。

你可能还记得，当“并发曼德博程序”的例子完成时，曼德博程序的 main.rs 包含几个来自其他 crate 的语法项的 use 声明：

use num::Complex;
// ...
use image::ColorType;
use image::png::PNGEncoder;

并且 Cargo.toml 文件中指定了我们想要的每个 crate 的版本：

[dependencies]
num = "0.4"
image = "0.13"
crossbeam = "0.8"

单词 dependencies 在这里是指这个项目使用的其他 crate，也就是我们所依赖的代码。我们在 crates.io（Rust 社区的开源 crate 站点）上找到了这些 crate。例如，通过访问 crates.io 我们搜索并找到了 image 库。crates.io 上的每个 crate 页面都显示了其 README.md 文件及文档和源代码的链接，以及像 image = "0.13" 这样的可以复制并添加到 Cargo.toml 中的配置行。这里展示的版本号只是我们编写本程序时这 3 个包的最新版本。

Cargo 清单讲述了如何使用这些信息。运行 cargo build 时，Cargo 首先会从 crates.io 下载这些 crate 的指定版本的源代码。然后，它会读取这些 crate 的 Cargo.toml 文件、下载 它们 的依赖项，并递归地进行。例如， 0.13.0 版的 image crate 的源代码包含一个 Cargo.toml 文件，其中列出了如下内容：

[dependencies]
byteorder = "1.0.0"
num-iter = "0.1.32"
num-rational = "0.1.32"
num-traits = "0.1.32"
enum_primitive = "0.1.0"

看到这个文件，Cargo 就知道在它使用 image 之前，必须先获取这些 crate。稍后你将看到如何要求 Cargo 从 Git 存储库或本地文件系统而非 crates.io 获取源代码。

由于 mandelbrot 通过使用 image crate 间接依赖于这些 crate，因此我们称它们为 mandelbrot 的 传递 依赖。所有这些依赖关系的集合，会告诉 Cargo 关于要构建什么 crate 以及应该按什么顺序构建的全部知识，这叫作该 crate 的 依赖图。Cargo 对依赖图和传递依赖的自动处理可以显著节省程序员的时间和精力。

一旦有了源代码，Cargo 就会编译所有的 crate。它会为项目依赖图中的每个 crate 都运行一次 rustc（Rust 编译器）。编译库时，Cargo 会使用 --crate-type lib 选项。这会告诉 rustc 不要寻找 main() 函数，而是生成一个 .rlib 文件，其中包含一些已编译代码，可用于创建二进制文件和其他 .rlib 文件。

编译程序时，Cargo 会使用 --crate-type bin，结果是目标平台的二进制可执行文件，比如 Windows 上的 mandelbrot.exe。

对于每个 rustc 命令，Cargo 都会传入 --extern 选项，给出 crate 将使用的每个库的文件名。这样，当 rustc 看到一行代码（如 use image::png::PNGEncoder）时，就可以确定 image 是另一个 crate 的名称。感谢 Cargo，它知道在哪里可以找到磁盘上已编译的 crate。Rust 编译器需要访问这些 .rlib 文件，因为它们包含库的已编译代码。Rust 会将代码静态链接到最终的可执行文件中。.rlib 也包含一些类型信息，这样 Rust 就可以检查我们在代码中使用的库特性是否确实存在于 crate 中，以及我们是否正确使用了它们。.rlib 文件中还包含此 crate 的公共内联函数、泛型和宏这三者的副本，在 Rust 知道我们将如何使用它们之前，这些特性无法完全编译为机器码。

cargo build 支持各种选项，其中大部分超出了本书的范畴，我们在这里只提一个： cargo build --release 会生成优化过的程序。这种程序运行得更快，但它们的编译时间更长、运行期不会检查整数溢出、会跳过 debug_assert!() 断言，并且在 panic 时生成的调用栈跟踪通常不太可靠。

8.1.1 版本

Rust 具有极强的兼容性保证。任何能在 Rust 1.0 上编译的代码在 Rust 1.50 或 Rust 1.900（如果已经发布的话）上都必然编译得一样好。

但有时会有一些必要的扩展提议加入语言中，这有可能导致旧代码无法再编译。例如，经过多次讨论，Rust 确定了一种支持异步编程的语法，该语法将标识符 async 和 await 重新用作关键字（参见第 20 章）。但是这种语言更改会破坏任何使用 async 或 await 作为变量名的现有代码。

为了在不破坏现有代码的情况下继续演进，Rust 会使用 版本。2015 版 Rust 会与 Rust 1.0 兼容。2018 版 Rust 将 async 和 await 改为关键字并精简了模块系统，而 2021 版 Rust 则提升了数组对人类的友好性，并默认让一些广泛使用的库定义随处可用。虽然这些都是对该语言的重要改进，但会破坏现有代码。为避免这种情况，每个 crate 都在其 Cargo.toml 文件顶部的 [package] 部分使用下面这样的行来表明自己是用哪个版本的 Rust 编写的：

edition = "2021"

如果该关键字不存在，则假定为 2015 版，因此旧 crate 根本不必更改。但是如果你想使用异步函数或新的模块系统，就要在 Cargo.toml 文件中添加一句“ edition = "2018" 或更高版本”。

Rust 承诺编译器将始终接受该语言的所有现存版本，并且程序可以自由混用以不同版本编写的 crate。2015 版的 crate 甚至可以依赖 2021 版的 crate。换句话说，crate 的版本只影响其源代码的解释方式，编译代码时，版本的差异已然消失。这意味着你无须为了继续参与到现代 Rust 生态系统中而更新旧的 crate。同样，你也不必为了避免给用户带来不便而被迫使用旧的 crate。当你想在自己的代码中使用新的语言特性时，只要更改版本就可以了。

Rust 项目组不会每年都发布新版本，只有认为确有必要时才会发布。例如，没有 2020 版 Rust。将 edition 设置为 "2020" 会导致错误。Rust 版本指南涵盖了每个版本中引入的更改，并提供了有关版本体系的完善的背景知识。

使用最新版本几乎总是更好的做法，尤其是对于新代码。 cargo new 默认会在最新版本上创建新项目。本书全程使用 2021 版。

如果你有一个用旧版本的 Rust 编写的 crate，则 cargo fix 命令能帮助你自动将代码升级到新版本。Rust 版本指南详细解释了 cargo fix 命令。

8.1.2 创建配置文件

你可以在 Cargo.toml 文件中放置几个配置设定区段，这些设定会影响 cargo 生成的 rustc 命令行，如表 8-1 所示。

表 8-1：Cargo.toml 的配置设定区段

命令行

使用的 Cargo.toml 区段

cargo build

[profile.dev]

cargo build --release

[profile.release]

cargo test

[profile.test]

通常情况下，默认设置是可以使用的，但当你想要使用剖析器（一种用来测量程序在哪些地方消耗了 CPU 时间的工具）时会出现例外情况。要从剖析器中获得最佳数据，需要同时启用优化（通常仅在发布构建中启用）和调试符号（通常仅在调试构建中启用）这两个选项。要同时启用它们，请将如下代码添加到你的 Cargo.toml 中：

[profile.release]
debug = true # 在release构建中启用debug符号

debug 设定会控制 rustc 的 -g 选项。通过这个配置，当你键入 cargo build --release 时，将获得带有调试符号的二进制文件。而优化设置未受影响。

Cargo 文档中列出了可以在 Cargo.toml 中调整的许多其他设定。

8.2 模块

crate 是关于项目间代码共享的，而 模块 是关于项目内代码组织的。它们扮演着 Rust 命名空间的角色，是构成 Rust 程序或库的函数、类型、常量等的容器。一个模块看起来是这样的：

mod spores {
 use cells::;

 /// 由成年蕨类植物产生的细胞。作为蕨类植物生命周期的一部分，细胞会随风
 /// 传播。一个孢子会长成原叶体（一个完整的独立有机体，最大直径达5毫米），
 /// 原叶体产生的受精卵会长成新的蕨类植物（植物的性别很复杂）
 pub struct Spore {
 ...
 }

 /// 模拟减数分裂产生孢子
 pub fn produce_spore(factory: &mut Sporangium) -> Spore {
 ...
 }

 /// 提取特定孢子中的基因
 pub(crate) fn genes(spore: &Spore) -> Vec<Gene> {
 ...
 }

 /// 混合基因以准备减数分裂（细胞分裂间期的一部分）
 fn recombine(parent: &mut Cell) {
 ...
 }

 ...
}

模块是一组 语法项 的集合，这些语法项具有命名的特性，比如此示例中的 Spore 结构体和 3 个函数。 pub 关键字会使某个语法项声明为公共项，这样它就可以从模块外部访问了。

如果把一个函数标记为 pub(crate)，那么就意味着它可以在这个 crate 中的任何地方使用，但不会作为外部接口的一部分公开。它不能被其他 crate 使用，也不会出现在这个 crate 的文档中。

任何未标记为 pub 的内容都是私有的，只能在定义它的模块及其任意子模块中使用：

let s = spores::produce_spore(&mut factory); // 正确

spores::recombine(&mut cell); // 错误：`recombine`是私有的

将某个语法项标记为 pub 通常称为“导出”该语法项。

本节的其余部分涵盖了要想充分利用模块所需了解的详细信息。

• 我们会展示如何嵌套模块并在需要时将它们分散到不同的文件和目录中。
• 我们会解释 Rust 使用的路径语法，以引用来自其他模块的语法项，并展示如何导入这些语法项，以便你使用它们而不必写出其完整路径。
• 我们会触及 Rust 对结构体字段的细粒度控制。
• 我们会介绍 预导入（prelude，原意为“序曲”）模块，它们通过收集几乎所有用户都需要的常用导入，减少了样板代码的编写。
• 为了提高代码的清晰性和一致性，我们还会介绍 常量 和 静态变量 这两种定义命名值的方法。

8.2.1 嵌套模块

模块可以嵌套，通常可以看到某个模块仅仅是一组子模块集合：

mod plant_structures {
 pub mod roots {
 ...
 }
 pub mod stems {
 ...
 }
 pub mod leaves {
 ...
 }
}

如果你希望嵌套模块中的语法项对其他 crate 可见，请务必将 它和它所在的模块 标记为公开的。否则可能会看到这样的警告：

warning: function is never used: `is_square`
 |
23 | / pub fn is_square(root: &Root) -> bool {
24 | | root.cross_section_shape().is_square()
25 | | }
 | |_________^
 |

也许这个函数目前确实是无用的代码。但是，如果你打算在其他 crate 中使用它，那么 Rust 就会提示你这个函数对它们实际上是不可见的。你应该确保它所在的模块也是 pub 形式。

也可以指定 pub(super)，让语法项只对其父模块可见。还可以指定 pub(in <path>)，让语法项在特定的父模块及其后代中可见。这对于深度嵌套的模块特别有用：

mod plant_structures {
 pub mod roots {
 pub mod products {
 pub(in crate::plant_structures::roots) struct Cytokinin {
 ...
 }
 }

 use products::Cytokinin; // 正确：在`roots`模块中可见
 }

 use roots::products::Cytokinin; // 错误：`Cytokinin`是私有的
}

// 错误：`Cytokinin`是私有的
use plant_structures::roots::products::Cytokinin;

通过这种方式，我们可以写出一个完整的程序，把大量代码和完整的模块层次结构以我们想要的任何方式关联起来，并放在同一个源文件中。

但实际上，以这种方式写代码相当痛苦，因此还有另一种选择。

8.2.2 单独文件中的模块

模块还可以这样写：

mod spores;

前面我们一直把 spores 模块的主体代码包裹在花括号中。在这里，我们告诉 Rust 编译器， spores 模块保存在一个单独的名为 spores.rs 的文件中：

// spores.rs

/// 由成年蕨类植物产生的细胞……
pub struct Spore {
 ...
}

/// 模拟减数分裂产生孢子
pub fn produce_spore(factory: &mut Sporangium) -> Spore {
 ...
}

/// 提取特定孢子中的基因
pub(crate) fn genes(spore: &Spore) -> Vec<Gene> {
 ...
}

/// 混合基因以准备减数分裂（细胞分裂间期的一部分）
fn recombine(parent: &mut Cell) {
 ...
}

spores.rs 仅包含构成该模块的那些语法项，它不需要任何样板代码来声明自己是一个模块。

代码的位置是这个 spores 模块与 8.2.1 节中展示的版本之间的 唯一 区别。Rust 遵循同样的规则，以决定什么是公共的以及什么是私有的。而且即便模块在单独的文件中，Rust 也永远不会分别编译它们，因为只要你构建 Rust crate，就会重新编译它的所有模块。

模块可以有自己的目录。当 Rust 看到 mod spore; 时，会同时检查 spores.rs 和 spores/mod.rs，如果两个文件都不存在，或者都存在，就会报错。对于这个例子，我们使用了 spores.rs，因为 spores 模块没有任何子模块。但是考虑一下我们之前编写的 plant_structures 模块。如果将该模块及其 3 个子模块拆分到它们自己的文件中，则会生成如下项目：

fern_sim/
├── Cargo.toml
└── src/
 ├── main.rs
 ├── spores.rs
 └── plant_structures/
 ├── mod.rs
 ├── leaves.rs
 ├── roots.rs
 └── stems.rs

在 main.rs 中，我们声明了 plant_structures 模块：

pub mod plant_structures;

这会导致 Rust 加载 plant_structures/mod.rs，该文件声明了 3 个子模块：

// 在plant_structures/mod.rs中
pub mod roots;
pub mod stems;
pub mod leaves;

这 3 个模块的内容存储在 leaves.rs、roots.rs 和 stems.rs 这 3 个单独的文件中，与 mod.rs 一样位于 plant_structures 目录下。

也可以使用同名的文件和目录来组成模块。如果 stems（茎）需要包含称为 xylem（木质部）和 phloem（韧皮部）的模块，那么可以选择将 stems 保留在 plant_structures/stems.rs 中并添加一个 stems 目录：

fern_sim/
├── Cargo.toml
└── src/
 ├── main.rs
 ├── spores.rs
 └── plant_structures/
 ├── mod.rs
 ├── leaves.rs
 ├── roots.rs
 ├── stems/
 │ ├── phloem.rs
 │ └── xylem.rs
 └── stems.rs

然后，在 stems.rs 中，我们声明了两个新的子模块：

// 在plant_structures/stems.rs中
pub mod xylem;
pub mod phloem;

这 3 种选项（模块位于自己的文件中、模块位于自己的带有 mod.rs 的目录中，以及模块在自己的文件中，并带有包含子模块的补充目录）为模块系统提供了足够的灵活性，以支持你可能用到的几乎任何项目结构。

8.2.3 路径与导入

:: 运算符用于访问模块中的各项特性。项目中任何位置的代码都可以通过写出其路径来引用标准库特性：

if s1 > s2 {
 std::mem::swap(&mut s1, &mut s2);
}

std 是标准库的名称。路径 std 指的是标准库的顶层模块。 std::mem 是标准库中的子模块，而 std::mem::swap 是该模块中的公共函数。

可以用这种方式编写所有代码：如果你想要一个圆或字典，就明确写出 std::f64::consts::PI 或 std::collections::HashMap::new。但这样做会很烦琐并且难以阅读。另一种方法是将这些特性 导入 使用它们的模块中：

use std::mem;

if s1 > s2 {
 mem::swap(&mut s1, &mut s2);
}

这条 use 声明导致名称 mem 在整个封闭块或模块中成了 std::mem 的本地别名。

可以通过写 use std::mem::swap; 来导入 swap 函数本身，而不是 mem 模块。然而，我们之前的编写风格通常被认为是最好的：导入类型、特型和模块（如 std::mem），然后使用相对路径访问其中的函数、常量和其他成员。

可以一次导入多个名称：

use std::collections::; // 同时导入两个模块

use std::fs::; // 同时导入`std::fs`和`std::fs::File`

use std::io::prelude::*; // 导入所有语法项

上述代码只是对“明确写出所有单独导入”的简写：

use std::collections::HashMap;
use std::collections::HashSet;

use std::fs;
use std::fs::File;

// std::io::prelude中的全部公开语法项:
use std::io::prelude::Read;
use std::io::prelude::Write;
use std::io::prelude::BufRead;
use std::io::prelude::Seek;

可以使用 as 导入一个语法项，但在本地赋予它一个不同的名称：

use std::io::Result as IOResult;

// 这个返回类型只是`std::io::Result<()>`的另一种写法：
fn save_spore(spore: &Spore) -> IOResult<()>
...

模块 不会 自动从其父模块继承名称。假设 proteins/mod.rs 中有如下代码：

// proteins/mod.rs
pub enum AminoAcid { ... }
pub mod synthesis;

那么 synthesis.rs 中的代码不会自动“看到”类型 `AminoAcid`：

// proteins/synthesis.rs
pub fn synthesize(seq: &[AminoAcid]) // 错误：找不到类型AminoAcid
 ...

其实，每个模块都会以“白板”开头，并且必须导入它使用的名称：

// proteins/synthesis.rs
use super::AminoAcid; // 从父模块显式导入

pub fn synthesize(seq: &[AminoAcid]) // 正确
 ...

默认情况下，路径是相对于当前模块的：

// in proteins/mod.rs

// 从某个子模块导入
use synthesis::synthesize;

self 也是当前模块的同义词，所以可以这样写：

// in proteins/mod.rs

// 从枚举中导入名称，因此可以把赖氨酸写成`Lys`，而不是`AminoAcid::Lys`
use self::AminoAcid::*;

或者简单地写成如下形式。

// 在proteins/mod.rs中

use AminoAcid::*;

（当然，这里的 AminoAcid 示例偏离了之前提到过的仅导入类型、特型和模块的样式规则。如果我们的程序中包含长氨基酸序列，那么这种调整就符合奥威尔第六规则：“为了表达准确，宁可打破上述规则”。）

关键字 super 和 crate 在路径中有着特殊的含义： super 指的是父模块， crate 指的是当前模块所在的 crate。

使用相对于 crate 根而不是当前模块的路径可以更容易地在项目中移动代码，因为如果当前模块的路径发生了变化，则不会破坏任何导入。例如，我们可以使用 crate 编写 synthesis.rs：

// proteins/synthesis.rs
use crate::proteins::AminoAcid; // 显式导入相对于crate根路径的语法项

pub fn synthesize(seq: &[AminoAcid]) // 正确
 ...

子模块可以使用 use super::* 访问其父模块中的私有语法项。

如果有一个与你正使用的 crate 同名的模块，那么引用它们的内容时有一些注意事项。如果你的程序在其 Cargo.toml 文件中将 image crate 列为依赖项，但还有另一个名为 image 的模块，那么以 image 开头的路径就是有歧义的：

mod image {
 pub struct Sampler {
 ...
 }
}

// 错误：它引用的是我们的`image`模块还是`image crate`？
use image::Pixels;

即使 image 模块中没有 Pixels 类型，这种歧义仍然是有问题的：如果模块中稍后添加了这样的定义，则可能会默默地改变程序中其他地方引用到的路径，而这将给人带来困扰。

为了解决歧义，Rust 有一种特殊的路径，称为 绝对路径，该路径以 :: 开头，总会引用外部 crate。要引用 image crate 中的 Pixels 类型，可以这样写：

use ::image::Pixels; // `image crate`中的`Pixels`

要引用你自己模块中的 Sampler 类型，可以这样写：

use self::image::Sampler; // `image`模块中的`Sampler`

模块与文件不是一回事，但模块与 Unix 文件系统中的目录和文件有些相似之处。 use 关键字会创建别名，就像用 ln 命令创建链接一样。路径和文件名一样，有绝对和相对两种形式。 self 和 super 类似于 . 和 .. 这样的特殊目录。

8.2.4 标准库预导入

我们刚才说过，就导入的名称而言，每个模块都以“白板”开头。但这个“白板”并不是 完全 空白的。

一方面，标准库 std 会自动链接到每个项目。这意味着你始终可以使用 use std::whatever，或者就按名称引用 std 中的语法项，比如代码中内联的 std::mem::swap()。另一方面，还有一些特别的便捷名称（如 Vec 和 Result）会包含在 标准库预导入 中并自动导入。Rust 的行为就好像每个模块（包括根模块）都用以下导入语句开头一样：

use std::prelude::v1::*;

标准库预导入包含几十个常用的特型和类型。

我们在第 2 章中提到的那些库有时会提供一些名为 prelude（预导入）的模块。但 std::prelude::v1 是唯一会自动导入的预导入。把一个模块命名为 prelude 只是一种约定，旨在告诉用户应该使用 * 导入它。

8.2.5 公开 use 声明

虽然 use 声明只是个别名，但也可以公开它们：

// 在plant_structures/mod.rs中
...
pub use self::leaves::Leaf;
pub use self::roots::Root;

这意味着 Leaf 和 Root 是 plant_structures 模块的公共语法项。它们还是 plant_structures::leaves::Leaf 和 plant_structures::roots::Root 的简单别名。

标准库预导入就是像这样编写的一系列 pub 导入。

8.2.6 公开结构体字段

模块可以包含用户定义的一些结构体类型（使用 struct 关键字引入）。第 9 章会详细介绍这些内容，但现在可以简单讲讲模块与结构体字段的可见性之间是如何相互作用的。

一个简单的结构体如下所示：

pub struct Fern {
 pub roots: RootSet,
 pub stems: StemSet
}

结构体的字段，甚至是私有字段，都可以在声明该结构体的整个模块及其子模块中访问。在模块之外，只能访问公共字段。

事实证明，通过模块而不是像 Java 或 C++ 那样通过类来强制执行访问控制对软件设计非常有帮助。它减少了样板“getter”方法和“setter”方法，并且在很大程度上消除了对诸如 C++ friend（友元）声明等语法的需求。单个模块可以定义多个紧密协作的类型，例如 frond::LeafMap 和 frond::LeafMapIter，它们可以根据需要访问彼此的私有字段，同时仍然对程序的其余部分隐藏这些实现细节。

8.2.7 静态变量与常量

除了函数、类型和嵌套模块，模块还可以定义 常量 和 静态变量。

关键字 const 用于引入常量，其语法和 let 一样，只是它可以标记为 pub，并且必须写明类型。此外，常量的命名规约是 UPPERCASE_NAMES：

pub const ROOM_TEMPERATURE: f64 = 20.0; // 摄氏度

static 关键字引入了一个静态语法项，跟常量几乎是一回事：

pub static ROOM_TEMPERATURE: f64 = 68.0; // 华氏度

常量有点儿像 C++ 的 #define：该值在每个使用了它的地方都会编译到你的代码中。静态变量是在程序开始运行之前设置并持续到程序退出的变量。在代码中对魔数和字符串要使用常量，而在处理大量的数据或需要借用常量值的引用时则要使用静态变量。

没有 mut 常量。静态变量可以标记为 mut，但正如第 5 章所述，Rust 没有办法强制执行其关于 mut 静态变量的独占访问规则。因此， mut 静态变量本质上是非线程安全的，安全代码根本不能使用它们：

static mut PACKETS_SERVED: usize = 0;

println!("{} served", PACKETS_SERVED); // 错误：使用了mut静态变量

Rust 不鼓励使用全局可变状态。有关备选方案的讨论，请参阅 19.3.11 节。

8.3 将程序变成库

随着蕨类植物模拟器成功运行，你会发现你所需要的不仅仅是单个程序。假设你有一个运行此模拟并将结果保存在文件中的命令行程序。现在，你想编写其他程序对这些保存下来的结果进行科学分析、实时显示正在生长的植物的 3D 渲染图、渲染足以乱真的图片，等等。所有这些程序都需要共享基本的蕨类植物模拟代码。这时候你应该建立一个库。

第一步是将现有的项目分为两部分：一个库 crate，其中包含所有共享代码；一个可执行文件，其中只包含你现在的命令行程序才需要的代码。

为了展示如何做到这一点，要使用一个极度简化的示例程序：

struct Fern {
 size: f64,
 growth_rate: f64
}

impl Fern {
 /// 模拟一株蕨类植物在一天内的生长
 fn grow(&mut self) {
 self.size *= 1.0 + self.growth_rate;
 }
}

/// 执行days天内某株蕨类植物的模拟
fn run_simulation(fern: &mut Fern, days: usize) {
 for _ in 0 .. days {
 fern.grow();
 }
}

fn main() {
 let mut fern = Fern {
 size: 1.0,
 growth_rate: 0.001
 };
 run_simulation(&mut fern, 1000);
 println!("final fern size: {}", fern.size);
}

假设这个程序有一个简单的 Cargo.toml 文件。

[package]
name = "fern_sim"
version = "0.1.0"
authors = ["You <you@example.com>"]
edition = "2021"

很容易将这个程序变成库，步骤如下。

1. 将文件 src/main.rs 重命名为 src/lib.rs。
2. 将 pub 关键字添加到 src/lib.rs 中的语法项上，这些语法项将成为这个库的公共特性。
3. 将 main 函数移动到某个临时文件中。（我们暂时不同管它。）

生成的 src/lib.rs 文件如下所示：

pub struct Fern {
 pub size: f64,
 pub growth_rate: f64
}

impl Fern {
 /// 模拟一株蕨类植物在一天内的生长
 pub fn grow(&mut self) {
 self.size *= 1.0 + self.growth_rate;
 }
}

/// 执行days天内某株蕨类植物的模拟
pub fn run_simulation(fern: &mut Fern, days: usize) {
 for _ in 0 .. days {
 fern.grow();
 }
}

请注意，不需要更改 Cargo.toml 中的任何内容。这是因为这个最小化的 Cargo.toml 文件只是为了让 Cargo 保持默认行为而已。默认设定下， cargo build 会查看源目录中的文件并根据文件名确定要构建的内容。当它发现存在文件 src/lib.rs 时，就知道要构建一个库。

src/lib.rs 中的代码构成了库的 根模块。其他使用这个库的 crate 只能访问这个根模块的公共语法项。

8.4 src/bin 目录

要让原来的命令行程序 fern_sim 再次运行起来也很简单，因为 Cargo 对和库位于同一个 crate 中的小型程序有一些内置支持。

其实 Cargo 本身就是用这样的方式编写的。它的大部分代码在一个 Rust 库中。本书中一直使用的 cargo 命令行程序只是一个很薄的包装程序，它会调用库来完成所有繁重的工作。库和命令行程序都位于同一个源代码存储库中。

你也可以将自己的程序和库放在同一个 crate 中。请将下面这段代码放入名为 src/bin/efern.rs 的文件中：

use fern_sim::;

fn main() {
 let mut fern = Fern {
 size: 1.0,
 growth_rate: 0.001
 };
 run_simulation(&mut fern, 1000);
 println!("final fern size: {}", fern.size);
}

main 函数就是之前搁置的那个。我们为 fern_sim crate 中的一些语法项（ Fern 和 run_simulation）添加了 use 声明。换句话说，我们在把这个 crate 当库来用。

因为我们已将这个文件放入了 src/bin 中，所以 Cargo 将在我们下次运行 cargo build 时同时编译 fern_sim 库和这个程序。可以使用 cargo run --bin efern 来运行 efern 程序。下面是它的输出，使用 --verbose 可以展示 Cargo 正在运行的命令：

$ cargo build --verbose
 Compiling fern_sim v0.1.0 (file:///.../fern_sim)
 Running `rustc src/lib.rs --crate-name fern_sim --crate-type lib ...`
 Running `rustc src/bin/efern.rs --crate-name efern --crate-type bin ...`
$ cargo run --bin efern --verbose
 Fresh fern_sim v0.1.0 (file:///.../fern_sim)
 Running `target/debug/efern`
final fern size: 2.7169239322355985

我们仍然不必对 Cargo.toml 进行任何修改，因为 Cargo 的默认设定就是查看你的源文件并自行决定做什么。Cargo 会自动将 src/bin 中的 .rs 文件视为应该构建的额外程序。

还可以利用子目录在 src/bin 目录中构建更大的程序。假设我们要提供第二个在屏幕上绘制蕨类植物的程序，但绘制代码规模很大而且是模块化的，因此它拥有自己的文件。我们可以给第二个程序建立它自己的子目录：

fern_sim/
├── Cargo.toml
└── src/
 └── bin/
 ├── efern.rs
 └── draw_fern/
 ├── main.rs
 └── draw.rs

这样做的好处是能让更大的二进制文件拥有自己的子模块，而不会弄乱库代码或 src/bin 目录。

不过，既然 fern_sim 现在是一个库，那么我们也就多了一种选择：把这个程序放在它自己的独立项目中，再保存到一个完全独立的目录中，然后在它自己的 Cargo.toml 中将 fern_sim 列为依赖项：

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

也许这就是你以后要为其他蕨类植物模拟程序专门做的事。src/bin 目录只适合像 efern 和 draw_fern 这样的简单程序。

8.5 属性

Rust 程序中的任何语法项都可以用 属性 进行装饰。属性是 Rust 的通用语法，用于向编译器提供各种指令和建议。假设你收到了如下警告：

libgit2.rs: warning: type `git_revspec` should have a camel case name
 such as `GitRevspec`, #[warn(non_camel_case_types)] on by default

但是你选择这个名字是有特别原因的，只希望 Rust 对此“闭嘴”。那么通过在此类型上添加 #[allow] 属性就可以禁用这条警告：

#[allow(non_camel_case_types)]
pub struct git_revspec {
 ...
}

条件编译是使用名为 #[cfg] 的属性编写的另一项特性：

// 只有当我们为Android构建时才在项目中包含此模块
#[cfg(target_os = "android")]
mod mobile;

#[cfg] 的完整语法可以到 Rust 参考手册中查看，表 8-2 列出了最常用的选项。

表 8-2：最常用的 #[cfg] 选项

#[cfg(...)] 选项

当启用时·····

test

启用测试（使用 cargo test 或 rustc --test 编译）

debug_assertions

启用调试断言（通常在非优化构建中）

unix

为 Unix（包括 macOS）编译

windows

为 Windows 编译

target_pointer_width = "64"

针对 64 位平台。另一个可能的值是 "32"

target_arch = "x86_64"

特别针对 x86-64。其他值有： "x86"、 "arm"、 "aarch64"、 "powerpc"、 "powerpc64" 和 "mips"

target_os = "macos"

为 macOS 编译。其他值有： "windows"、 "ios"、 "android"、 "linux"、 "freebsd"、 "openbsd"、 "netbsd" 和 "dragonfly"

feature = "robots"

启用名为 "robots" 的用户自定义特性（用 cargo build --feature robots 或 rustc --cfg feature='"robots"' 编译）。这些特性是在 Cargo.toml 的 [features] 区段中声明的

not( A )

不满足条件 A 时。如果要提供某函数的两种实现，请将其中一个标记为 #[cfg(X)]，另一个标记为 #[cfg(not(X))]

all( A , B )

同时满足 A 和 B（相当于 &&）

any( A , B )

只要满足 A 或 B 之一（相当于 ||）

有时，可能需要对函数的内联展开进行微观管理，但我们通常会把这种优化留给编译器。可以使用 #[inline] 属性进行微观管理：

/// 由于相邻细胞之间存在渗透作用，因此需要调整它们的离子水平等
#[inline]
fn do_osmosis(c1: &mut Cell, c2: &mut Cell) {
 ...
}

在一种特定的情况下，如果没有 #[inline]， 就不会 发生内联。当在一个 crate 中定义的函数或方法在另一个 crate 中被调用时，Rust 不会将其内联，除非它是泛型的（具有类型参数）或明确标记为 #[inline]。

在其他情况下，编译器只会将 #[inline] 视为建议。Rust 还支持更坚定的 #[inline(always)]（要求函数在每个调用点内联展开）和 #[inline(never)]（要求函数永不内联）。

一些属性（如 #[cfg] 和 #[allow]）可以附着到整个模块上并对其中的所有内容生效。另一些属性（如 #[test] 和 #[inline]）则必须附着到单个语法项上。正如你对这种包罗万象的语法特性的预期一样，每个属性都是定制的，并且有自己所支持的一组参数。Rust 参考文档详细记录了它支持的全套属性。

要将属性附着到整个 crate 上，请将其添加到 main.rs 文件或 lib.rs 文件的顶部，放在任何语法项之前，并写成 #!，而不是 #，就像这样：

// libgit2_sys/lib.rs
#![allow(non_camel_case_types)]

pub struct git_revspec {
 ...
}

pub struct git_error {
 ...
}

#! 要求 Rust 将一个属性附着到整个封闭区中的语法项而不只是紧邻其后的内容上：在这种情况下， #![allow] 属性会附着到整个 libgit2_sys 包而不仅仅是 struct git_revspec 上

#! 也可以在函数、结构体等内部使用（但 #! 通常只用在文件的开头，以将属性附着到整个模块或 crate 上）。某些属性始终使用 #! 语法，因为它们只能应用于整个 crate。

例如， #![feature] 属性用于启用 Rust 语言和库的 不稳定 特性，这些特性是实验性的，因此可能有 bug 或者未来可能会被更改或移除。例如，在我们撰写本章时，Rust 实验性地支持跟踪像 assert! 这样的宏的展开。但由于此支持是实验性的，因此你只能通过两种方式来使用：安装 Rust 的夜间构建版或明确声明你的 crate 使用宏跟踪。

#![feature(trace_macros)]

fn main() {
 // 我想知道这个使用assert_eq!的代码替换（展开）后会是什么样子！
 trace_macros!(true);
 assert_eq!(10*10*10 + 9*9*9, 12*12*12 + 1*1*1);
 trace_macros!(false);
}

随着时间的推移，Rust 团队有时会将实验性特性 稳定 下来，使其成为语言标准的一部分。那时这个 #![feature] 属性就会变得多余，因此 Rust 会生成一个警告，建议你将其移除。

第 8 章 crate 与模块(2)

8.6 测试与文档

正如 2.3 节所述，Rust 中内置了一个简单的单元测试框架。测试是标有 #[test] 属性的普通函数：

#[test]
fn math_works() {
 let x: i32 = 1;
 assert!(x.is_positive());
 assert_eq!(x + 1, 2);
}

cargo test 会运行项目中的所有测试：

$ cargo test
 Compiling math_test v0.1.0 (file:///.../math_test)
 Running target/release/math_test-e31ed91ae51ebf22

running 1 test
test math_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

（你还会看到一些关于“文档测试”的输出，我们稍后会讲到。）

无论你的 crate 是可执行文件还是库，你都可以通过将参数传给 Cargo 来运行特定测试： cargo test math 会运行名称中包含 math 的所有测试。

测试通常会使用 assert! 和 assert_eq! 这两个来自 Rust 标准库的宏。如果 expr 为真，那么 assert!(expr) 就会成功；否则，它会 panic，导致测试失败。 assert_eq!(v1, v2) 和 assert!(v1 == v2) 基本等效，但当断言失败时，其错误消息会展示两个值。

你可以在普通代码中使用这些宏来检查不变条件，但请注意 assert! 和 assert_eq! 会包含在发布构建中。因此，可以改用 debug_assert! 和 debug_assert_eq! 来编写仅在调试构建中检查的断言。

要测试各种出错情况，请将 #[should_panic] 属性添加到你的测试中：

/// 正如我们在第7章中所讲的那样，只有当除以零导致panic时，这个测试才能通过
#[test]
#[allow(unconditional_panic, unused_must_use)]
#[should_panic(expected="divide by zero")]
fn test_divide_by_zero_error() {
 1 / 0; // 应该panic！
}

在这个例子中，还需要添加一个 allow 属性，以让编译器允许我们做一些它本可以静态证明而无法触发 panic 的事情，然后才能执行除法并丢弃答案，因为在正常情况下，它会试图阻止这种愚蠢行为。

还可以从测试中返回 Result<(), E>。只要错误变体实现了 Debug 特型（通常都实现了），你就可以简单地使用 ? 抛弃 Ok 变体以返回 Result：

use std::num::ParseIntError;

/// 如果"1024"是一个有效的数值（这里正是如此），那么本测试就会通过
#[test]
fn explicit_radix() -> Result<(), ParseIntError> {
 i32::from_str_radix("1024", 10)?;
 Ok(())
}

标有 #[test] 的函数是有条件编译的。普通的 cargo build 或 cargo build --release 会跳过测试代码。但是当你运行 cargo test 时，Cargo 会分两次来构建你的程序：一次以普通方式，一次带着你的测试和已启用的测试工具。这意味着你的单元测试可以与它们所测试的代码一起使用，按需访问内部实现细节，而且没有运行期成本。但是，这可能会导致一些警告。

fn roughly_equal(a: f64, b: f64) -> bool {
 (a - b).abs() < 1e-6
}

#[test]
fn trig_works() {
 use std::f64::consts::PI;
 assert!(roughly_equal(PI.sin(), 0.0));
}

在省略了测试代码的构建中， roughly_equal 似乎从未使用过，于是 Rust 会报错：

$ cargo build
 Compiling math_test v0.1.0 (file:///.../math_test)
warning: function is never used: `roughly_equal`
 |
7 | / fn roughly_equal(a: f64, b: f64) -> bool {
8 | | (a - b).abs() < 1e-6
9 | | }
 | |_^
 |
 = note: #[warn(dead_code)] on by default

因此，当你的测试变得很庞大以至于需要支撑性代码时，应该按照惯例将它们放在 tests 模块中，并使用 #[cfg] 属性声明整个模块仅用于测试：

#[cfg(test)] // 只有在测试时才包含此模块
mod tests {
 fn roughly_equal(a: f64, b: f64) -> bool {
 (a - b).abs() < 1e-6
 }

 #[test]
 fn trig_works() {
 use std::f64::consts::PI;
 assert!(roughly_equal(PI.sin(), 0.0));
 }
}

Rust 的测试工具会使用多个线程同时运行好几个测试，这是 Rust 代码默认线程安全的附带好处之一。要禁用此功能，请运行单个测试 cargo test testname 或运行 cargo test -- --test-threads 1。（第一个 -- 确保 cargo test 将 --test-threads 选项透传给实际执行测试的可执行文件。）这意味着，从严格意义上说，我们在第 2 章中展示的曼德博程序不是该章中第二个而是第三个多线程程序。2.3 节的 cargo test 运行的才是第一个多线程程序。

通常，测试工具只会显示失败测试的输出。如果也想展示成功测试的输出，请运行 cargo test -- --nocapture。

8.6.1 集成测试

你的蕨类植物模拟器继续“成长”。你已决定将所有主要功能放入可供多个可执行文件使用的库中。如果能从最终使用者的视角编写一些测试，把 fern_sim.rlib 像外部 crate 那样链接进来，那仿真度就更高了。此外，你有一些测试是通过从二进制文件加载已保存的模拟记录开始的，同时把这些大型测试文件放在 src 目录中会很棘手。集成测试有助于解决这两个问题。

集成测试是 .rs 文件，位于项目的 src 目录旁边的 tests 目录中。当你运行 cargo test 时，Cargo 会将每个集成测试编译为一个独立的 crate，与你的库和 Rust 测试工具链接在一起。下面是一个例子：

// tests/unfurl.rs——蕨菜在阳光下舒展开

use fern_sim::Terrarium;
use std::time::Duration;

#[test]
fn test_fiddlehead_unfurling() {
 let mut world = Terrarium::load("tests/unfurl_files/fiddlehead.tm");
 assert!(world.fern(0).is_furled());
 let one_hour = Duration::from_secs(60 * 60);
 world.apply_sunlight(one_hour);
 assert!(world.fern(0).is_fully_unfurled());
}

集成测试之所以有价值，部分原因在于它们会从外部视角看待你的 crate，就像用户的做法一样。集成测试会测试你的 crate 的公共 API。

cargo test 会运行单元测试和集成测试。如果仅运行某个特定文件（如 tests/unfurl.rs）中的集成测试，请使用命令 cargo test --test unfurl。

8.6.2 文档

命令 cargo doc 会为你的库创建 HTML 文档：

$ cargo doc --no-deps --open
 Documenting fern_sim v0.1.0 (file:///.../fern_sim)

--no-deps 选项会要求 Cargo 只为 fern_sim 本身生成文档，而不会为它依赖的所有 crate 生成文档。

--open 选项会要求 Cargo 随后在浏览器中打开此文档。

你可以在图 8-2 中看到结果。Cargo 会将这个新文档文件保存在 target/doc 中。起始页是 target/doc/fern_sim/index.html。

图 8-2： rustdoc 生成的文档示例

该文档是根据你库中的 pub 特性以及附加的所有 文档型注释 生成的。我们已经在本章中看到了一些文档型注释。它们看起来很像注释：

/// 模拟减数分裂产生孢子
pub fn produce_spore(factory: &mut Sporangium) -> Spore {
 ...
}

但是当 Rust 看到以 3 个斜杠开头的注释时，会将它们视为 #[doc] 属性。如下代码的效果和 Rust 处理前面那个例子的效果完全一样：

#[doc = "模拟减数分裂产生孢子。"]
pub fn produce_spore(factory: &mut Sporangium) -> Spore {
 ...
}

当你编译一个库或二进制文件时，这些属性不会改变任何东西，但是当你生成文档时，关于公共特性的文档型注释会包含在其输出中。

同样，以 //! 开头的注释会被视为 #![doc] 属性并附着到封闭块一级的特性（通常是模块或 crate）上。例如，你的 fern_sim/src/lib.rs 文件可能从这句话开始：

//! 模拟蕨类植物从单个细胞开始的生长过程

文档型注释的内容是 Markdown 格式的，这是一种等效于简单 HTML 格式的简写法。星号用于表示 * 斜体 * 和 ** 粗体 **，空行用于表示分段符，等等。你还可以使用 HTML 标记，这些标记会原样复制到格式化后的文档中。

Rust 中文档型注释的一大特色是，Markdown 链接中可以使用 Rust 语法项路径（如 leaves::Leaf），而不是相对 URL，来指示它们所指的内容。Cargo 会查找路径所指的内容，并在相应的文档页面中将其替换为正确的链接。例如，从如下代码生成的文档会链接到 VascularPath、 Leaf 和 Root 的文档页面：

/// 创建并返回一个[`VascularPath`]，它表示从给定的[`Root`][r]到
/// 给定的[`Leaf`](leaves::Leaf)之间的营养路径
///
/// [r]: roots::Root
pub fn trace_path(leaf: &leaves::Leaf, root: &roots::Root) -> VascularPath {
 ...
}

你还可以添加搜索别名，以便使用内置搜索功能更轻松地查找内容。在此 crate 的文档中搜索“ path”或“ route”都能找到 VascularPath：

#[doc(alias = "route")]
pub struct VascularPath {
 ...
}

为了处理较长的文档块或者简化工作流，还可以在文档中包含外部文件。如果存储库的 README.md 文件中包含与准备用作 crate 的顶层文档相同的文本，那么可以将下面这句话放在 lib.rs 或 main.rs 的顶部：

#![doc = include_str!("../README.md")]

你可以使用反引号（ `）来标出文本中的少量代码。在输出中，这些片段会格式化为等宽字体。还可以通过“4 空格缩进”来添加更大的代码示例：

/// 文档型注释里的代码块：
///
/// if samples::everything().works() {
/// println!("ok");
/// }

也可以使用 Markdown 的三重反引号（ ```）来标记代码块。效果完全一样：

/// 另一种代码片段，代码一样，但写法不同：
///
/// ```
/// if samples::everything().works() {
/// println!("ok");
/// }
/// ```

无论使用哪种格式，当你在文档型注释里包含一段代码时，都会发生一些有意思的事。Rust 会自动将它转成一个测试。

8.6.3 文档测试

当你在 Rust 库 crate 中运行测试时，Rust 会检查文档中出现的所有代码是否真能如预期般工作。为此，Rust 会获取文档型注释中出现的每个代码块，然后将其编译为单独的可执行包，再与你的库链接在一起，最后运行。

这是一个独立的文档测试示例。通过运行 cargo new --lib ranges 创建一个新项目（ --lib 标志告诉 Cargo 我们正在创建一个库 crate，而不是一个可执行 crate）并将以下代码放入 ranges/src/lib.rs 中：

use std::ops::Range;

/// 如果两个范围重叠，就返回true
///
/// assert_eq!(ranges::overlap(0..7, 3..10), true);
/// assert_eq!(ranges::overlap(1..5, 101..105), false);
///
/// 如果任何一个范围为空，则它们不会被看作是重叠的
///
/// assert_eq!(ranges::overlap(0..0, 0..10), false);
///
pub fn overlap(r1: Range<usize>, r2: Range<usize>) -> bool {
 r1.start < r1.end && r2.start < r2.end &&
 r1.start < r2.end && r2.start < r1.end
}

文档型注释中的这两小段代码会出现在 cargo doc 生成的文档中，如图 8-3 所示。

图 8-3：展示一些文档测试的文档

它们也会成为两个独立的测试：

$ cargo test
 Compiling ranges v0.1.0 (file:///.../ranges)
...
 Doc-tests ranges

running 2 tests
test overlap_0 ... ok
test overlap_1 ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

如果将 --verbose 标志传给 Cargo，你会看到它正在使用 rustdoc --test 运行这两个测试。 rustdoc 会将每个代码示例存储在一个单独的文件中，并给它们添加几行样板代码，以生成两个程序。这是第一个：

use ranges;
fn main() {
 assert_eq!(ranges::overlap(0..7, 3..10), true);
 assert_eq!(ranges::overlap(1..5, 101..105), false);
}

这是第二个：

use ranges;
fn main() {
 assert_eq!(ranges::overlap(0..0, 0..10), false);
}

如果这些程序能成功编译并运行，则测试通过。

这两个代码示例都包含一些断言，但这只是因为在这种情况下，断言构成了不错的文档。文档测试背后的理念并不是将所有测试都放入注释中。相反，你应该编写尽可能好的文档，Rust 只会帮你确保文档中的代码示例能实际编译和运行。

通常，哪怕一个最小的工作示例都会包含一些细节，像导入或设置代码这样的细节是编译代码所必需的，只是还没重要到值得在文档中展示。要隐藏代码示例中的一行，请在该行的开头放置一个 #，后跟一个空格：

/// 让阳光照进来，并运行模拟器一段时间
///
/// # use fern_sim::Terrarium;
/// # use std::time::Duration;
/// # let mut tm = Terrarium::new();
/// tm.apply_sunlight(Duration::from_secs(60));
///
pub fn apply_sunlight(&mut self, time: Duration) {
 ...
}

有时在文档中展示完整的示例程序（包含 main 函数）会很有帮助。显然，如果这些代码片段出现在代码示例中，你也不希望 rustdoc 自动添加包装代码，因为那样会导致编译无法通过。因此， rustdoc 会将所有精确包含字符串 fn main 的代码块视为一个完整的程序，不向其中添加任何代码。

可以针对特定的代码块禁用测试。要告诉 Rust 编译你的示例，但不实际运行它，请使用带有 no_run 注释的多行代码块：

/// 将本地玻璃栽培箱的所有照片上传到在线画廊
///
/// ```no_run
/// let mut session = fern_sim::connect();
/// session.upload_all();
/// ```
pub fn upload_all(&mut self) {
 ...
}

如果代码甚至都不希望编译，请改用 ignore 而不是 no_run。标记为 ignore 的块不会出现在 cargo run 的输出中，但 no_run 测试如果编译了就会显示为已通过。如果代码块根本不是 Rust 代码，请使用语言的名称，比如 c++ 或 sh，或用 text 表示纯文本。 rustdoc 并不了解数百种编程语言的名称，相反，它将任何自己无法识别的注解都理解为该代码块不是 Rust。这会禁用代码的高亮显示和文档测试功能。

8.7 指定依赖项

前面我们看到过告诉 Cargo 从哪里获取项目所依赖的 crate 源代码的一种方法：通过版本号。

image = "0.6.1"

还有几种指定依赖项的方法，以及一些关于要使用哪个版本的微妙细节，因此值得在这上面花一些时间来讲一下。

首先，你可能想要使用根本没发布在 crates.io 上的依赖项。一种方法是指定 Git 存储库 URL 和修订号：

image = { git = "https://github.com/Piston/image.git", rev = "528f19c" }

这个特定的 crate 是开源的，托管在 GitHub 上，但你也可以轻松地指向托管在公司内网上的私有 Git 存储库。如上述代码所示，你可以指定要使用的特定版本（ rev）、标签（ tag）或分支名（ branch）。（这些都是告诉 Git 要检出哪个源代码版本的方法。）

另一种方法是指定一个包含 crate 源代码的目录：

image = { path = "vendor/image" }

如果你的团队有个做版本控制的单一存储库，而且其中包含多个 crate 的源代码，或者可能包含整个依赖图，那么这种方法就很方便。每个 crate 都可以使用相对路径指定其依赖项。

对依赖项进行这种层级的控制是一项非常强大的特性。如果你要使用的任何开源 crate 都不完全符合你的喜好，那么可以简单地对其进行分叉：只需点击 GitHub 上的 Fork 按钮并更改 Cargo.toml 文件中的一行即可。你的下一次 cargo build 将自然使用此 crate 的分叉版本而非官方版本。

8.7.1 版本

当你在 Cargo.toml 文件中写入类似 image = "0.13.0" 这样的内容时，Cargo 会相当宽松地理解它。它会使用自认为与版本 0.13.0 兼容的最新版本的 image。

这些兼容性规则改编自语义化版本规范。

• 以 0.0 开头的版本号还非常原始，所以 Cargo 永远不会假定它能与任何其他版本兼容。
• 以 0. x（ x 不为 0）开头的版本号，可认为与 0. x 系列的版本兼容。前面我们指定了 image 版本为 0.6.1，但如果可用，则 Cargo 会使用 0.6.3。（这跟语义化版本规范所说的 0. x 版本号规则不太一样，但事实证明这条规则太有用了，不能遗漏。）
• 一旦项目达到 1.0，只有出现新的主版本号时才会破坏兼容性。因此，如果你要求版本为 2.0.1，那么 Cargo 可能会使用 2.17.99，但不会使用 3.0。

默认情况下版本号是灵活的，否则使用哪个版本的问题很快就会变成过度的束缚。假设一个库 libA 使用 num = "0.1.31"，而另一个库 libB 使用 num = "0.1.29"。如果版本号需要完全匹配，则没有项目能够同时使用这两个库。允许 Cargo 使用任何兼容版本是一个更实用的默认设定。

不过，不同的项目在依赖性和版本控制方面有不同的需求。你可以使用一些运算符来指定确切的版本或版本范围，如表 8-3 所示。

表 8-3：在 Cargo.toml 文件中指定版本

Cargo.toml 行

含义

image = "=0.10.0"

仅使用确切的版本 0.10.0

image = ">=1.0.5"

使用 1.0.5 或更高版本（甚至 2.9，如果其可用的话）

image = ">1.0.5 <1.1.9"

使用高于 1.0.5 但低于 1.1.9 的版本

image = "<=2.7.10"

使用 2.7.10 或更早的任何版本

你偶尔会看到的另一种版本规范是使用通配符 *。它会告诉 Cargo 任何版本都可以。除非其他 Cargo.toml 文件包含更具体的约束，否则 Cargo 将使用最新的可用版本。doc.crates.io 上的 Cargo 文档更详细地介绍了这些版本规范。

请注意，兼容性规则意味着不能纯粹出于营销目的而选择版本号。这实际上意味着它们是 crate 的维护者与其用户之间的契约。如果你维护一个版本为 1.7 的 crate，并且决定移除一个函数或进行任何其他不完全向后兼容的更改，则必须将版本号提高到 2.0。如果你将其称为 1.8，就相当于声称这个新版本与 1.7 兼容，而用户可能会发现构建失败了。

8.7.2 Cargo.lock

Cargo.toml 中的版本号是刻意保持灵活的，但我们不希望每次构建 Cargo 时都将其升级到最新的库版本。想象一下，当你正处于紧张的调试过程中时， cargo build 突然升级到了新版本的库。这可能带来难以估量的破坏性。调试过程中引入的任何变数都是坏事。事实上，对库而言，从来就没有什么好的时机进行意料之外的改变。

因此，Cargo 有一种内置机制来防止发生这种情况。当第一次构建项目时，Cargo 会输出一个 Cargo.lock 文件，以记录它使用的每个 crate 的确切版本。以后的构建都将参考此文件并继续使用相同的版本。仅当你要求 Cargo 升级时它才会升级到更新版本，方法是手动增加 Cargo.toml 文件中的版本号或运行 cargo update：

$ cargo update
 Updating registry `https://github.com/rust-lang/crates.io-index`
 Updating libc v0.2.7 -> v0.2.11
 Updating png v0.4.2 -> v0.4.3

cargo update 只会升级到与你在 Cargo.toml 中指定的内容兼容的最新版本。如果你指定了 image = "0.6.1"，并且想要升级到版本 0.10.0，则必须自己在 Cargo.toml 中进行更改。下次构建时，Cargo 会将 image 库更新到这个新版本并将新版本号存储在 Cargo.lock 中。

前面的示例展示 Cargo 更新了托管在 crates.io 上的两个 crate。存储在 Git 中的依赖项会发生非常相似的情况。假设 Cargo.toml 文件包含以下内容：

image = { git = "https://github.com/Piston/image.git", branch = "master" }

如果 cargo build 发现我们有一个 Cargo.lock 文件，那么它将不会从 Git 存储库中拉取新的更改。相反，它会读取 Cargo.lock 并使用与上次相同的修订版。但是 cargo update 会重新从 master 中拉取，以便我们的下一个构建使用最新版本。

Cargo.lock 是自动生成的，通常不用手动编辑。不过，如果此项目是可执行文件，那你就应该将 Cargo.lock 提交到版本控制。这样，构建项目的每个人总是会获得相同的版本。Cargo.lock 文件的版本历史中会记录这些依赖项更新。

如果你的项目是一个普通的 Rust 库，请不要费心提交 Cargo.lock。你的库的下游用户拥有包含其整个依赖图版本信息的 Cargo.lock 文件，他们将忽略这个库的 Cargo.lock 文件。在极少数情况下，你的项目是一个共享库（比如输出是 .dll 文件、.dylib 文件或 .so 文件），它没有这样的下游 cargo 用户，这时候就应该提交 Cargo.lock。

Cargo.toml 灵活的版本说明符使你可以轻松地在项目中使用 Rust 库，并最大限度地提高库之间的兼容性。Cargo.lock 中的这些详尽记录可以支持跨机器的一致且可重现的构建。它们会共同帮你避开“依赖地狱”的问题。

8.8 将 crate 发布到 crates.io

如果你已决定将这个蕨类植物模拟库作为开源软件发布，那么，恭喜！这部分很简单。

首先，确保 Cargo 可以为你打包 crate。

$ cargo package
warning: manifest has no description, license, license-file, documentation,
homepage or repository. See http://doc.crates.io/manifest.html#package-metadata
for more info.
 Packaging fern_sim v0.1.0 (file:///.../fern_sim)
 Verifying fern_sim v0.1.0 (file:///.../fern_sim)
 Compiling fern_sim v0.1.0 (file:///.../fern_sim/target/package/fern_sim-0.1.0)

cargo package 命令会创建一个文件（在本例中为 target/package/fern_sim-0.1.0.crate），其中包含所有库的源文件（包括 Cargo.toml）。这是你要上传到 crates.io 以便与全世界分享的文件。（可以使用 cargo package --list 来查看包含哪些文件。）然后 Cargo 会像最终用户一样，从 .crate 文件构建这个库，以仔细检查其工作。

Cargo 会警告 Cargo.toml 的 [package] 部分缺少一些对下游用户很重要的信息，比如你分发代码所依据的许可证。警告中给出的 URL 是一个很好的资源，因此我们不会在这里详细解释所有字段。简而言之，你可以通过向 Cargo.toml 添加几行代码来修复此警告。

[package]
name = "fern_sim"
version = "0.1.0"
edition = "2021"
authors = ["You <you@example.com>"]
license = "MIT"
homepage = "https://fernsim.example.com/"
repository = "https://gitlair.com/sporeador/fern_sim"
documentation = "http://fernsim.example.com/docs"
description = """
Fern simulation, from the cellular level up.
"""

一旦在 crates.io 上发布了这个 crate，任何下载你的 crate 的人都能看到此 Cargo.toml 文件。因此，如果 authors 字段包含你希望保密的电子邮件地址，那么现在是更改它的时候了。

这个阶段有时会出现的另一个问题是你的 Cargo.toml 文件可能通过 path 指定其他 crate 的位置，如 8.7 节所示：

image = { path = "vendor/image" }

对你和你的团队来说，这可能没什么问题。但当其他人下载 fern_sim 库时，他们的计算机上可能不会有与你一样的文件和目录。因此，Cargo 会 忽略 自动下载的库中的 path 键，而这可能会导致构建错误。解决方案一目了然：如果你的库要发布在 crates.io 上，那么它的依赖项也应该在 crates.io 上。应该指定版本号而不是 path：

image = "0.13.0"

如果你愿意，可以同时指定一个 path（供你自己在本地构建时优先使用）和一个 version（供所有其他用户使用）：

image = { path = "vendor/image", version = "0.13.0" }

当然，在这种情况下，你有责任确保两者保持同步。

最后，在发布 crate 之前，你需要登录 crates.io 并获取 API 密钥。这一步很简单：一旦你在 crates.io 上有了账户，其“账户设置”页面就会展示一条 cargo login 命令，就像这样：

$ cargo login 5j0dV54BjlXBpUUbfIj7G9DvNl1vsWW1

Cargo 会把密钥保存在配置文件中，API 密钥应该像密码一样保密。因此，你应该只在自己控制的计算机上运行此命令。

这些都完成后，最后一步是运行 cargo publish：

$ cargo publish
 Updating registry `https://github.com/rust-lang/crates.io-index`
 Uploading fern_sim v0.1.0 (file:///.../fern_sim)

做完这一步，你的库就成为 crates.io 中成千上万个库中的一员了。

8.9 工作空间

随着项目不断“成长”，你最终会写出很多 crate。它们并存于同一个源代码存储库中：

fernsoft/
├── .git/...
├── fern_sim/
│ ├── Cargo.toml
│ ├── Cargo.lock
│ ├── src/...
│ └── target/...
├── fern_img/
│ ├── Cargo.toml
│ ├── Cargo.lock
│ ├── src/...
│ └── target/...
└── fern_video/
 ├── Cargo.toml
 ├── Cargo.lock
 ├── src/...
 └── target/...

Cargo 的工作方式是，每个 crate 都有自己的构建目录 target，其中包含该 crate 的所有依赖项的单独构建。这些构建目录是完全独立的。即使两个 crate 具有共同的依赖项，它们也不能共享任何已编译的代码。这好像有点儿浪费。

你可以使用 Cargo 工作空间来节省编译时间和磁盘空间。Cargo 工作空间 是一组 crate，它们共享着公共构建目录和 Cargo.lock 文件。

你需要做的就是在存储库的根目录中创建一个 Cargo.toml 文件，并将下面这两行代码放入其中：

[workspace]
members = ["fern_sim", "fern_img", "fern_video"]

这里的 fern_sim 等是那些包含你的 crate 的子目录名。这些子目录中所有残存的 Cargo.lock 文件和 target 目录都需要删除。

完成此操作后，任何 crate 中的 cargo build 都会自动在根目录（在本例中为 fernsoft/target）下创建和使用共享构建目录。命令 cargo build --workspace 会构建当前工作空间中的所有 crate。 cargo test 和 cargo doc 也能接受 --workspace 选项。

8.10 更多好资源

如果你仍然意犹未尽，Rust 社区还准备了一些你可能感兴趣的资源。

• 当你在 crates.io 上发布一个开源 crate 时，你的文档会自动渲染并托管在 docs.rs 上，这要归功于 Onur Aslan。

• 如果你的项目在 GitHub 上，那么 Travis CI 可以在每次推送时构建和测试你的代码。设置起来非常容易，有关详细信息，请参阅 travis-ci.org。如果你已经熟悉 Travis，则可以从下面这个 .travis.yml 文件开始。

  language: rust
  rust:
  

• stable

- 你可以从 crate 的顶层文档型注释生成 README.md 文件。此特性是由 Livio Ribeiro 作为第三方 Cargo 插件提供的。运行 `cargo install cargo-readme` 来安装此插件，然后运行 `cargo readme --help` 来学习如何使用它。


我们将继续前行。

虽然 Rust 是一门新语言，但它旨在支持大型、雄心勃勃的项目。它有很棒的工具和活跃的社区。系统程序员 **也能** 享受美好。

第 9 章 结构体

很久以前，当牧羊人想要了解两个羊群是否相似时，会挨个对它们进行比对。

——John C. Baez，James Dolan，“Categorification”

Rust 中的结构体（struct/structure）类似于 C 和 C++ 中的 struct 类型、Python 中的类和 JavaScript 中的对象。结构体会将多个不同类型的值组合成一个单一的值，以便你能把它们作为一个单元来处理。给定一个结构体，你可以读取和修改它的各个组件。结构体也可以具有关联的方法，以对其组件进行操作。

Rust 有 3 种结构体类型： 具名字段型结构体、 元组型结构体 和 单元型结构体。这 3 种结构体在引用组件的方式上有所不同：具名字段型结构体会为每个组件命名；元组型结构体会按组件出现的顺序标识它们；单元型结构体则根本没有组件。单元型结构体虽然不常见，但它们比你想象的更有用。

本章将详细解释每种类型并展示它们在内存中的样子；介绍如何向它们添加方法、如何定义适用于不同组件类型的泛型结构体类型，以及如何让 Rust 为你的结构体生成常见的便捷特型的实现。

9.1 具名字段型结构体

具名字段型结构体的定义如下所示：

/// 由8位灰度像素组成的矩形
struct GrayscaleMap {
 pixels: Vec<u8>,
 size: (usize, usize)
}

它声明了一个 GrayscaleMap 类型，其中包含两个给定类型的字段，分别名为 pixels 和 size。Rust 中的约定是，所有类型（包括结构体）的名称都将每个单词的第一个字母大写（如 GrayscaleMap），这称为 大驼峰格式（CamelCase 或 PascalCase）。字段和方法是小写的，单词之间用下划线分隔，这称为 蛇形格式（snake_case）。

你可以使用 结构体表达式 构造出此类型的值，如下所示：

let width = 1024;
let height = 576;
let image = GrayscaleMap {
 pixels: vec![0; width * height],
 size: (width, height)
};

结构体表达式以类型名称（ GrayscaleMap）开头，后跟一对花括号，其中列出了每个字段的名称和值。还有用来从与字段同名的局部变量或参数填充字段的简写形式：

fn new_map(size: (usize, usize), pixels: Vec<u8>) -> GrayscaleMap {
 assert_eq!(pixels.len(), size.0 * size.1);
 GrayscaleMap { pixels, size }
}

结构体表达式 GrayscaleMap { pixels, size } 是 GrayscaleMap { pixels: pixels, size: size } 的简写形式。你可以对某些字段使用 key: value 语法，而对同一结构体表达式中的其他字段使用简写语法。

要访问结构体的字段，请使用我们熟悉的 . 运算符：

assert_eq!(image.size, (1024, 576));
assert_eq!(image.pixels.len(), 1024 * 576);

与所有其他语法项一样，结构体默认情况下是私有的，仅在声明它们的模块及其子模块中可见。你可以通过在结构体的定义前加上 pub 来使结构体在其模块外部可见。结构体中的每个字段默认情况下也是私有的：

/// 由8位灰度像素组成的矩形
pub struct GrayscaleMap {
 pub pixels: Vec<u8>,
 pub size: (usize, usize)
}

即使一个结构体声明为 pub，它的字段也可以是私有的：

/// 由8位灰度像素组成的矩形
pub struct GrayscaleMap {
 pixels: Vec<u8>,
 size: (usize, usize)
}

其他模块可以使用此结构体及其任何公共的关联函数，但不能按名称访问私有字段或使用结构体表达式来创建新的 GrayscaleMap 值。也就是说，要创建结构体型的值，就需要结构体的所有字段都可见。这就是为什么你不能编写结构体表达式来创建新的 String 或 Vec。这些标准类型都是结构体，但它们的所有字段都是私有的。如果想创建一个值，就必须使用公共的类型关联函数，比如 Vec::new()。

创建具名字段结构体的值时，可以使用另一个相同类型的结构体为省略的那些字段提供值。在结构体表达式中，如果具名字段后面跟着 .. EXPR，则任何未提及的字段都会从 EXPR（必须是相同结构体类型的另一个值）中获取它们的值。假设我们有一个代表游戏中怪物的结构体：

// 在这个游戏中，怪物是一些扫帚。你会看到：
struct Broom {
 name: String,
 height: u32,
 health: u32,
 position: (f32, f32, f32),
 intent: BroomIntent
}

/// `Broom`可以支持的两种用途
#[derive(Copy, Clone)]
enum BroomIntent { FetchWater, DumpWater }

对程序员来说，最好的童话故事是 The Sorcerer' s Apprentice（《 魔法师的学徒》）：一个新手魔法师对一把扫帚施了魔法，让它为自己工作，但工作完成后不知道如何让它停下来。于是，他用斧头将扫帚砍成了两半，结果一把扫帚变成了两把，虽然每把扫帚的大小只有原始扫帚的一半，但仍然具有和原始扫帚一样的“工作热情”。

// 按值接收输入的Broom（扫帚），并获得所有权
fn chop(b: Broom) -> (Broom, Broom) {
 // 主要从`b`初始化`broom1`，只修改`height`。由于`String`
 // 不是`Copy`类型，因此`broom1`获得了`b`中`name`的所有权
 let mut broom1 = Broom { height: b.height / 2, .. b };

 // 主要从`broom1`初始化`broom2`。由于`String`不是`Copy`类型，
 // 因此我们显式克隆了`name`
 let mut broom2 = Broom { name: broom1.name.clone(), .. broom1 };

 // 为每一半扫帚分别起一个名字
 broom1.name.push_str(" I");
 broom2.name.push_str(" II");

 (broom1, broom2)
}

有了这个定义，我们就可以制作一把扫帚，把它一分为二，然后看看会得到什么：

let hokey = Broom {
 name: "Hokey".to_string(),
 height: 60,
 health: 100,
 position: (100.0, 200.0, 0.0),
 intent: BroomIntent::FetchWater
};

let (hokey1, hokey2) = chop(hokey);
assert_eq!(hokey1.name, "Hokey I");
assert_eq!(hokey1.height, 30);
assert_eq!(hokey1.health, 100);

assert_eq!(hokey2.name, "Hokey II");
assert_eq!(hokey2.height, 30);
assert_eq!(hokey2.health, 100);

新的扫帚 hokey1 和 hokey2 获得了修改后的名字，长度只有原来的一半，但生命值都跟原始扫帚一样。

9.2 元组型结构体

第二种结构体类型称为 元组型结构体，因为它类似于元组：

struct Bounds(usize, usize);

构造此类型的值与构造元组非常相似，只是必须包含结构体名称：

let image_bounds = Bounds(1024, 768);

元组型结构体保存的值称为 元素，就像元组的值一样。你可以像访问元组一样访问它们：

assert_eq!(image_bounds.0 * image_bounds.1, 786432);

元组型结构体的单个元素可以是公共的，也可以不是：

pub struct Bounds(pub usize, pub usize);

表达式 Bounds(1024, 768) 看起来像一个函数调用，实际上它确实是，即定义这种类型时也隐式定义了一个函数：

fn Bounds(elem0: usize, elem1: usize) -> Bounds { ... }

在最基本的层面上，具名字段型结构体和元组型结构体非常相似。选择使用哪一个需要考虑易读性、无歧义性和简洁性。如果你喜欢用 . 运算符来获取值的各个组件，那么用名称来标识字段就能为读者提供更多信息，并且更容易防范拼写错误。如果你通常使用模式匹配来查找这些元素，那么元组型结构体会更好用。

元组型结构体适用于创造 新类型（newtype），即建立一个只包含单组件的结构体，以获得更严格的类型检查。如果你正在使用纯 ASCII 文本，那么可以像下面这样定义一个新类型：

struct Ascii(Vec<u8>);

将此类型用于 ASCII 字符串比简单地传递 Vec<u8> 缓冲区并在注释中解释它们的内容要好得多。在将其他类型的字节缓冲区传给需要 ASCII 文本的函数时，这种新类型能帮 Rust 捕获错误。我们会在第 22 章中给出一个使用新类型进行高效类型转换的例子。

9.3 单元型结构体

第三种结构体有点儿晦涩难懂，因为它声明了一个根本没有元素的结构体类型：

struct Onesuch;

这种类型的值不占用内存，很像单元类型 ()。Rust 既不会在内存中实际存储单元型结构体的值，也不会生成代码来对它们进行操作，因为仅通过值的类型它就能知道关于值的所有信息。但从逻辑上讲，空结构体是一种可以像其他任何类型一样有值的类型。或者更准确地说，空结构体是一种只有一个值的类型：

let o = Onesuch;

在阅读 6.10 节中有关 .. 范围运算符的内容时，你已经遇到过单元型结构体。像 3..5 这样的表达式是结构体值 Range { start: 3, end: 5 } 的简写形式，而表达式 ..（一个省略两个端点的范围）是单元型结构体值 RangeFull 的简写形式。

单元型结构体在处理特型时也很有用，第 11 章会对此进行描述。

9.4 结构体布局

在内存中，具名字段型结构体和元组型结构体是一样的：值（可能是混合类型）的集合以特定方式在内存中布局。例如，在本章前面我们定义了下面这个结构体：

struct GrayscaleMap {
 pixels: Vec<u8>,
 size: (usize, usize)
}

GrayscaleMap 值在内存中的布局如图 9-1 所示。

图 9-1：内存中的 GrayscaleMap 结构体

与 C 和 C++ 不同，Rust 没有具体承诺它将如何在内存中对结构体的字段或元素进行排序，图 9-1 仅展示了一种可能的安排。然而，Rust 确实承诺会将字段的值直接存储在结构体本身的内存块中。JavaScript、Python 和 Java 会将 pixels 值和 size 值分别放在它们自己的分配在堆上的块中，并让 GrayscaleMap 的字段指向它们，而 Rust 会将 pixels 值和 size 值直接嵌入 GrayscaleMap 值中。只有由 pixels 向量拥有的在堆上分配的缓冲区才会留在它自己的块中。

你可以使用 #[repr(C)] 属性要求 Rust 以兼容 C 和 C++ 的方式对结构体进行布局，第 23 章会对此进行详细介绍。

9.5 用 impl 定义方法

在本书中，我们一直在对各种值调用方法，比如使用 v.push(e) 将元素推送到向量上、使用 v.len() 获取向量的长度、使用 r.expect("msg") 检查 Result 值是否有错误，等等。你也可以在自己的结构体类型上定义方法。Rust 方法不会像 C++ 或 Java 中的方法那样出现在结构体定义中，而是会出现在单独的 impl 块中。

impl 块只是 fn 定义的集合，每个定义都会成为块顶部命名的结构体类型上的一个方法。例如，这里我们定义了一个公共的 Queue 结构体，然后为它定义了 push 和 pop 这两个公共方法：

/// 字符的先入先出队列
pub struct Queue {
 older: Vec<char>, // 较旧的元素，最早进来的在后面
 younger: Vec<char> // 较新的元素，最后进来的在后面
}

impl Queue {
 /// 把字符推入队列的最后
 pub fn push(&mut self, c: char) {
 self.younger.push(c);
 }

 /// 从队列的前面弹出一个字符。如果确实有要弹出的字符，
 /// 就返回`Some(c)`；如果队列为空，则返回`None`
 pub fn pop(&mut self) -> Option<char> {
 if self.older.is_empty() {
 if self.younger.is_empty() {
 return None;
 }

 // 将younger中的元素移到older中，并按照所承诺的顺序排列它们
 use std::mem::swap;
 swap(&mut self.older, &mut self.younger);
 self.older.reverse();
 }

 // 现在older能保证有值了。Vec的pop方法已经
 // 返回一个Option，所以可以放心使用了
 self.older.pop()
 }
}

在 impl 块中定义的函数称为 关联函数，因为它们是与特定类型相关联的。与关联函数相对的是 自由函数，它是未定义在 impl 块中的语法项。

Rust 会将调用关联函数的结构体值作为第一个参数传给方法，该参数必须具有特殊名称 self。由于 self 的类型显然就是在 impl 块顶部命名的类型或对该类型的引用，因此 Rust 允许你省略类型，并以 self、 &self 或 &mut self 作为 self: Queue、 self: &Queue 或 self: &mut Queue 的简写形式。如果你愿意，也可以使用完整形式，但如前所述，几乎所有 Rust 代码都会使用简写形式。

在我们的示例中， push 方法和 pop 方法会通过 self.older 和 self.younger 来引用 Queue 的字段。在 C++ 和 Java 中， "this" 对象的成员可以在方法主体中直接可见，不用加 this. 限定符，而 Rust 方法中则必须显式使用 self 来引用调用此方法的结构体值，这类似于 Python 方法中使用 self 以及 JavaScript 方法中使用 this 的方式。

由于 push 和 pop 需要修改 Queue，因此它们都接受 &mut self 参数。然而，当调用一个方法时，你不需要自己借用可变引用，常规的方法调用语法就已经隐式处理了这一点。因此，有了这些定义，你就可以像下面这样使用 Queue 了：

let mut q = Queue { older: Vec::new(), younger: Vec::new() };

q.push('0');
q.push('1');
assert_eq!(q.pop(), Some('0'));

q.push('∞');
assert_eq!(q.pop(), Some('1'));
assert_eq!(q.pop(), Some('∞'));
assert_eq!(q.pop(), None);

只需编写 q.push(...) 就可以借入对 q 的可变引用，就好像你写的是 (&mut q).push(...) 一样，因为这是 push 方法的 self 参数所要求的。

如果一个方法不需要修改 self，那么可以将其定义为接受共享引用：

impl Queue {
 pub fn is_empty(&self) -> bool {
 self.older.is_empty() && self.younger.is_empty()
 }
}

同样，方法调用表达式知道要借用哪种引用：

assert!(q.is_empty());
q.push('⊙');
assert!(!q.is_empty());

或者，如果一个方法想要获取 self 的所有权，就可以通过值来获取 self：

impl Queue {
 pub fn split(self) -> (Vec<char>, Vec<char>) {
 (self.older, self.younger)
 }
}

调用这个 split 方法看上去和调用其他方法是一样的：

let mut q = Queue { older: Vec::new(), younger: Vec::new() };

q.push('P');
q.push('D');
assert_eq!(q.pop(), Some('P'));
q.push('X');

let (older, younger) = q.split();

// q现在是未初始化状态
assert_eq!(older, vec!['D']);
assert_eq!(younger, vec!['X']);

但请注意，由于 split 通过值获取 self，因此这会将 Queue 从 q 中 移动 出去，使 q 变成未初始化状态。由于 split 的 self 现在拥有此队列，因此它能够将这些单独的向量移出队列并返回给调用者。

有时，像这样通过值或引用获取 self 还是不够的，因此 Rust 还允许通过智能指针类型传递 self。

9.5.1 以 Box、 Rc 或 Arc 形式传入 self

方法的 self 参数也可以是 Box<Self> 类型、 Rc<Self> 类型或 Arc<Self> 类型。这种方法只能在给定的指针类型值上调用。调用该方法会将指针的所有权传给它。

你通常不需要这么做。如果一个方法期望通过引用接受 self，那它在任何指针类型上调用时都可以正常工作：

let mut bq = Box::new(Queue::new());

// `Queue::push`需要一个`&mut Queue`，但`bq`是一个`Box<Queue>`
// 这没问题：Rust在调用期间从`Box`借入了`&mut Queue`
bq.push('■');

对于方法调用和字段访问，Rust 会自动从 Box、 Rc、 Arc 等指针类型中借入引用，因此 &self 和 &mut self 几乎总是（偶尔也会用一下 self）方法签名里的正确选择。

但是如果某些方法确实需要获取指向 Self 的指针的所有权，并且其调用者手头恰好有这样一个指针，那么 Rust 也允许你将它作为方法的 self 参数传入。为此，你必须明确写出 self 的类型，就好像它是普通参数一样。

impl Node {
 fn append_to(self: Rc<Self>, parent: &mut Node) {
 parent.children.push(self);
 }
}

9.5.2 类型关联函数

给定类型的 impl 块还可以定义根本不以 self 为参数的函数。这些函数仍然是关联函数，因为它们在 impl 块中，但它们不是方法，因为它们不接受 self 参数。为了将它们与方法区分开来，我们称其为 类型关联函数。

它们通常用于提供构造函数，如下所示：

impl Queue {
 pub fn new() -> Queue {
 Queue { older: Vec::new(), younger: Vec::new() }
 }
}

要使用此函数，需要写成 Queue::new，即类型名称 + 双冒号 + 函数名称。现在我们的示例代码简洁一点儿了：

let mut q = Queue::new();

q.push('*');
...

在 Rust 中，构造函数通常按惯例命名为 new，我们已经见过 Vec::new、 Box::new、 HashMap::new 等。但是 new 这个名字并没有什么特别之处，它不是关键字。类型通常还有其他关联函数作为构造函数，比如 Vec::with_capacity。

虽然对于一个类型可以有许多独立的 impl 块，但它们必须都在定义该类型的同一个 crate 中。不过，Rust 确实允许你将自己的方法附加到其他类型中，第 11 章会解释具体做法。

如果你习惯了用 C++ 或 Java，那么将类型的方法与其定义分开可能看起来很不寻常，但这样做有几个优点。

• 找出一个类型的数据成员总是很容易。在大型 C++ 类定义中，你可能需要浏览数百行成员函数的定义才能确保没有遗漏该类的任何数据成员，而在 Rust 中，它们都在同一个地方。
• 尽管可以把方法放到具名字段型结构体中，但对元组型结构体和单元型结构体来说这看上去不那么简洁。将方法提取到一个 impl 块中可以让所有这 3 种结构体使用同一套语法。事实上，Rust 还使用相同的语法在根本不是结构体的类型（比如 enum 类型和像 i32 这样的原始类型）上定义方法。（任何类型都可以有方法，这是 Rust 很少使用 对象 这个术语的原因之一，它更喜欢将所有东西都称为 值。）
• 同样的 impl 语法也可以巧妙地用于实现特型，第 11 章会对此进行介绍。

9.6 关联常量

Rust 在其类型系统中的另一个特性也采用了类似于 C# 和 Java 的思想，有些值是与类型而不是该类型的特定实例关联起来的。在 Rust 中，这些叫作 关联常量。

顾名思义，关联常量是常量值。它们通常用于表示指定类型下的常用值。例如，你可以定义一个用于线性代数的二维向量和一个关联的单位向量：

pub struct Vector2 {
 x: f32,
 y: f32,
}

impl Vector2 {
 const ZERO: Vector2 = Vector2 { x: 0.0, y: 0.0 };
 const UNIT: Vector2 = Vector2 { x: 1.0, y: 0.0 };
}

这些值是和类型本身相关联的，你可以在不必引用 Vector2 的任一实例的情况下使用它们。这与关联函数非常相似，使用的名字是与其关联的类型名，后面跟着它们自己的名字：

let scaled = Vector2::UNIT.scaled_by(2.0);

关联常量的类型不必是其所关联的类型，我们可以使用此特性为类型添加 ID 或名称。如果有多种类似于 Vector2 的类型需要写入文件然后加载到内存中，则可以使用关联常量来添加名称或数值 ID，这些名称或数值 ID 可以写在数据旁边以标识其类型。

impl Vector2 {
 const NAME: &'static str = "Vector2";
 const ID: u32 = 18;
}

9.7 泛型结构体

前面对 Queue 的定义并不令人满意：它是为存储字符而写的，但是它的结构体或方法根本没有任何专门针对字符的内容。如果我们要定义另一个包含 String 值的结构体，那么除了将 char 替换为 String 外，其余代码可以完全相同。这纯属浪费时间。

幸运的是，Rust 结构体可以是 泛型 的，这意味着它们的定义是一个模板，你可以在其中插入任何自己喜欢的类型。例如，下面是 Queue 的定义，它可以保存任意类型的值：

pub struct Queue<T> {
 older: Vec<T>,
 younger: Vec<T>
}

你可以把 Queue<T> 中的 <T> 读作“对于任意元素类型 T……”。所以上面的定义可以这样解读：“对于任意元素类型 T， Queue<T> 有两个 Vec<T> 类型的字段。”例如，在 Queue<String> 中， T 是 String，所以 older 和 younger 的类型都是 Vec<String>。而在 Queue<char> 中， T 是 char，我们最终得到的结构体与最初那个针对 char 定义的结构体是一样的。事实上， Vec 本身也是一个泛型结构体，它就是这样定义的。

在泛型结构体定义中，尖括号（ <>）中的类型名称叫作 类型参数。泛型结构体的 impl 块如下所示：

impl<T> Queue<T> {
 pub fn new() -> Queue<T> {
 Queue { older: Vec::new(), younger: Vec::new() }
 }

 pub fn push(&mut self, t: T) {
 self.younger.push(t);
 }

 pub fn is_empty(&self) -> bool {
 self.older.is_empty() && self.younger.is_empty()
 }

 ...
}

你可以将 impl<T> Queue<T> 这一行解读为“对于任意元素类型 T，这里有一些在 Queue<T> 上可用的关联函数。”然后，你可以使用类型参数 T 作为关联函数定义中的类型。

语法可能看起来有点儿累赘，但 impl<T> 可以清楚地表明 impl 块能涵盖任意类型 T，这便能将它与为某种特定类型的 Queue 编写的 impl 块区分开来，如下所示：

impl Queue<f64> {
 fn sum(&self) -> f64 {
 ...
 }
}

这个 impl 块标头表明“这里有一些专门用于 Queue<f64> 的关联函数”。这为 Queue<f64> 提供了一个 sum 方法，不过该方法在其他类型的 Queue 上不可用。

我们在前面的代码中使用了 Rust 的 self 参数简写形式，如果到处都写成 Queue<T>，则让人觉得拗口且容易分心。作为另一种简写形式，每个 impl 块，无论是不是泛型，都会将特殊类型的参数 Self（注意这里是大驼峰 CamelCase）定义为我们要为其添加方法的任意类型。对前面的代码来说， Self 就应该是 Queue<T>，因此我们可以进一步缩写 Queue::new 的定义：

pub fn new() -> Self {
 Queue { older: Vec::new(), younger: Vec::new() }
}

你可能注意到了，在 new 的函数体中，不需要在构造表达式中写入类型参数，简单地写 Queue { ... } 就足够了。这是 Rust 的类型推断在起作用：由于只有一种类型适用于该函数的返回值（ Queue<T>），因此 Rust 为我们补齐了该类型参数。但是，你始终都要在函数签名和类型定义中提供类型参数。Rust 不会推断这些，相反，它会以这些显式类型为基础，推断函数体内的类型。

Self 也可以这样使用，我们可以改写成 Self { ... }。你觉得哪种写法最容易理解就写成哪种。

在调用关联函数时，可以使用 ::<>（比目鱼）表示法显式地提供类型参数：

let mut q = Queue::<char>::new();

但实际上，通常可以让 Rust 帮你推断出来：

let mut q = Queue::new();
let mut r = Queue::new();

q.push("CAD"); // 显然是Queue<&'static str>
r.push(0.74); // 显然是Queue<f64>

q.push("BTC"); // 2019年6月一比特币值多少美元
r.push(13764.0); // Rust可没能力检测出非理性繁荣

事实上，我们在本书中经常这样使用另一种泛型结构体类型 Vec。

不仅结构体可以是泛型的，枚举同样可以接受类型参数，而且语法也非常相似。10.1 节会详细介绍“枚举”。

9.8 带生命周期参数的泛型结构体

正如我们在 5.3.5 节中讨论的那样，如果结构体类型包含引用，则必须为这些引用的生命周期命名。例如，下面这个结构体可能包含对某个切片的最大元素和最小元素的引用：

struct Extrema<'elt> {
 greatest: &'elt i32,
 least: &'elt i32
}

早些时候，我们建议你把像 struct Queue<T> 这样的声明理解为：给定任意类型 T，都可以创建一个持有该类型的 Queue<T>。同样，可以将 struct Extrema<'elt> 理解为：给定任意生命周期 'elt，都可以创建一个 Extrema<'elt> 来持有对该生命周期的引用。

下面这个函数会扫描切片并返回一个 Extrema 值，这个值的各个字段会引用其中的元素：

fn find_extrema<'s>(slice: &'s [i32]) -> Extrema<'s> {
 let mut greatest = &slice[0];
 let mut least = &slice[0];

 for i in 1..slice.len() {
 if slice[i] < *least { least = &slice[i]; }
 if slice[i] > *greatest { greatest = &slice[i]; }
 }
 Extrema { greatest, least }
}

在这里，由于 find_extrema 借用了 slice 的元素，而 slice 有生命周期 's，因此我们返回的 Extrema 结构体也使用了 's 作为其引用的生命周期。Rust 总会为各种调用推断其生命周期参数，所以调用 find_extrema 时不需要提及它们：

let a = [0, -3, 0, 15, 48];
let e = find_extrema(&a);
assert_eq!(*e.least, -3);
assert_eq!(*e.greatest, 48);

因为返回类型的生命周期与参数的生命周期相同是很常见的情况，所以如果有一个显而易见的候选者，那么 Rust 就允许我们省略生命周期。因此也可以把 find_extrema 的签名写成如下形式，意思不变：

fn find_extrema(slice: &[i32]) -> Extrema {
 ...
}

当然，我们的意思 也可能 是 Extrema<'static>，但这很不寻常。Rust 只为最常见的情况提供了简写形式。

9.9 带常量参数的泛型结构体

泛型结构体也可以接受常量值作为参数。例如，你可以定义一个表示任意次数多项式的类型，如下所示：

/// N - 1次多项式
struct Polynomial<const N: usize> {
 /// 多项式的系数
 ///
 /// 对于多项式a + bx + cx2 + ... + zxn-1，其第`i`个元素是xi的系数
 coefficients: [f64; N]
}

例如，根据这个定义， Polynomial<3> 是一个二次多项式。这里的 <const N: usize> 子句表示 Polynomial 类型需要一个 usize 值作为它的泛型参数，以此来决定要存储多少个系数。

与通过字段保存长度和容量而将元素存储在堆中的 Vec 不同， Polynomial 会将其系数（ coefficients）直接存储在值中，再无其他字段。长度直接由类型给出。（这里不需要容量的概念，因为 Polynomial 不能动态增长。）

也可以在类型的关联函数中使用参数 N：

impl<const N: usize> Polynomial<N> {
 fn new(coefficients: [f64; N]) -> Polynomial<N> {
 Polynomial { coefficients }
 }

 /// 计算`x`处的多项式的值
 fn eval(&self, x: f64) -> f64 {
 // 秦九韶算法在数值计算上稳定、高效且简单：
 // c0 + x(c1 + x(c2 + x(c3 + ... x(c[n-1] + x c[n]))))
 let mut sum = 0.0;
 for i in (0..N).rev() {
 sum = self.coefficients[i] + x * sum;
 }

 sum
 }
}

这里， new 函数会接受一个长度为 N 的数组，并将其元素作为新 Polynomial 值的系数。 eval 方法将在 0..N 范围内迭代以找到给定点 x 处的多项式值。

与类型参数和生命周期参数一样，Rust 通常也能为常量参数推断出正确的值：

use std::f64::consts::FRAC_PI_2; // π/2

// 用近似法对`sin`函数求值：sin x ≅ x - 1/6 x³ + 1/120 x5
// 误差几乎为0，相当精确！
let sine_poly = Polynomial::new([0.0, 1.0, 0.0, -1.0/6.0, 0.0,
 1.0/120.0]);
assert_eq!(sine_poly.eval(0.0), 0.0);
assert!((sine_poly.eval(FRAC_PI_2) - 1.).abs() < 0.005);

由于我们向 Polynomial::new 传递了一个包含 6 个元素的数组，因此 Rust 知道必须构造出一个 Polynomial<6>。 eval 方法仅通过查询其 Self 类型就知道 for 循环应该运行多少次迭代。由于长度在编译期是已知的，因此编译器可能会用一些顺序执行的代码完全替换循环。

常量泛型参数可以是任意整数类型、 char 或 bool。不允许使用浮点数、枚举和其他类型。

如果结构体还接受其他种类的泛型参数，则生命周期参数必须排在第一位，然后是类型，接下来是任何 const 值。例如，一个包含引用数组的类型可以这样声明：

struct LumpOfReferences<'a, T, const N: usize> {
 the_lump: [&'a T; N]
}

常量泛型参数是 Rust 的一个相对较新的功能，目前它们的使用受到了一定的限制。例如，像下面这样定义 Polynomial 显然更好：

/// 一个N次多项式
struct Polynomial<const N: usize> {
 coefficients: [f64; N + 1]
}

然而，Rust 会拒绝这个定义：

error: generic parameters may not be used in const operations
 |
6 | coefficients: [f64; N + 1]
 | ^ cannot perform const operation using `N`
 |
 = help: const parameters may only be used as standalone arguments, i.e. `N`

虽然 [f64; N] 没问题，但像 [f64; N + 1] 这样的类型显然对 Rust 来说太过激进了。所以 Rust 暂时施加了这个限制，以避免遇到像下面这样的问题：

struct Ketchup<const N: usize> {
 tomayto: [i32; N & !31],
 tomahto: [i32; N - (N % 32)],
}

通过计算可知，不管 N 取何值， N & !31 和 N - (N % 32) 总是相等的，因此 tomayto 和 tomahto 始终具有相同的类型。例如，应该允许将任何一个赋值给另一个。但是，如果想让 Rust 的类型检查器识别这种位运算，就需要把一些令人困惑的极端情况引入这种本已相当复杂的语言中，而这会带来复杂度失控的风险。当然，支持像 N + 1 这样的简单表达式是没问题的，并且也确实已经有人在努力教 Rust 顺利处理这些问题。

由于此处关注的是类型检查器的行为，因此这种限制仅适用于出现在类型中的常量参数，比如数组的长度。在普通表达式中，可以随意使用 N：像 N + 1 和 N & !31 这样的写法是完全可以的。

如果要为 const 泛型参数提供的值不仅仅是字面量或单个标识符，那么就必须将其括在花括号中，就像 Polynomial<> 这样。此规则能让 Rust 更准确地报告语法错误。

9.10 让结构体类型派生自某些公共特型

结构体很容易编写：

struct Point {
 x: f64,
 y: f64
}

但是，如果你要开始使用这种 Point 类型，很快就会发现它有点儿难用。像这样写的话， Point 不可复制或克隆，不能用 println!("{:?}", point); 打印，而且不支持 == 运算符和 != 运算符。

这些特性中的每一个在 Rust 中都有名称—— Copy、 Clone、 Debug 和 PartialEq，它们被称为 特型。第 11 章会展示如何为自己的结构体手动实现特型。但是对于这些标准特型和其他一些特型，无须手动实现，除非你想要某种自定义行为。Rust 可以自动为你实现它们，而且结果准确无误。只需将 #[derive] 属性添加到结构体上即可：

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

这些特型中的每一个都可以为结构体自动实现特型，但前提是结构体的每个字段都实现了该特型。我们可以要求 Rust 为 Point 派生 PartialEq，因为它的两个字段都是 f64 类型，而 f64 类型已经实现了 PartialEq。

Rust 还可以派生 PartialOrd，这将增加对比较运算符 <、 >、 <= 和 >= 的支持。我们在这里并没有这样做，因为比较两个点以了解一个点是否“小于”另一个点是一件很奇怪的事情。毕竟点和点之间并没有任何常规意义上的顺序可言。所以我们选择不让 Point 值支持这些运算符。这种特例就是 Rust 让我们自己编写 #[derive] 属性而不会自动为它派生每一个可能特型的原因之一。而另一个原因是，只要实现某个特型就会自动让它成为公共特性，因此可复制性、可克隆性等都会成为该结构体的公共 API 的一部分，应该慎重选择。

第 13 章会详细描述 Rust 的标准特型并解释哪些可用于 #[derive]。

9.11 内部可变性

可变性与其他任何事物一样：过犹不及，而你通常只需要一点点就够了。假设你的蜘蛛机器人控制系统有一个中心结构体 SpiderRobot，其中包含一些设置和 I/O 句柄。该结构体会在机器人启动时设置好，并且值永不改变：

pub struct SpiderRobot {
 species: String,
 web_enabled: bool,
 leg_devices: [fd::FileDesc; 8],
 ...
}

机器人的每个主要系统由不同的结构体处理，它们都有一个指向 SpiderRobot 的指针：

use std::rc::Rc;

pub struct SpiderSenses {
 robot: Rc<SpiderRobot>, // <--指向设置和I/O的指针
 eyes: [Camera; 32],
 motion: Accelerometer,
 ...
}

织网、捕食、毒液流量控制等结构体也都有一个 Rc<SpiderRobot> 智能指针。回想一下， Rc 代表引用计数（reference counting），并且 Rc 指向的值始终是共享的，因此将始终不可变。

现在假设你要使用标准 File 类型向 SpiderRobot 结构体添加一点儿日志记录。但有一个问题： File 必须是可变的。所有用于写入的方法都需要一个可变引用。

这种情况经常发生。我们需要一个不可变值（ SpiderRobot 结构体）中的一丁点儿可变数据（一个 File）。这称为 内部可变性。Rust 提供了多种可选方案，本节将讨论两种最直观的类型，即 Cell<T> 和 RefCell<T>，它们都在 std::cell 模块中。1

Cell<T> 是一个包含类型 T 的单个私有值的结构体。 Cell 唯一的特殊之处在于，即使你对 Cell 本身没有 mut 访问权限，也可以获取和设置这个私有值字段。

Cell::new(value)（新建）

创建一个新的 Cell，将给定的 value 移动进去。

cell.get()（获取）

返回 cell 中值的副本。

cell.set(value)（设置）

将给定的 value 存储在 cell 中，丢弃先前存储的值。

此方法接受一个不可变引用型的 self。

fn set(&self, value: T) // 注意：不是`&mut self`

当然，这对名为 set 的方法来说是相当不寻常的。迄今为止，Rust 一直在告诉我们如果想更改数据，就需要 mut 型访问。但出于同样的原因，这个不寻常的细节正是 Cell 的全部意义所在。 Cell 只是改变不变性规则的一种安全方式——一丝不多，一毫不少。

cell 还有其他一些方法，你可以查阅其文档进行了解。

如果你想在 SpiderRobot 中添加一个简单的计数器，那么 Cell 是一个不错的工具。可以写成如下形式：

use std::cell::Cell;

pub struct SpiderRobot {
 ...
 hardware_error_count: Cell<u32>,
 ...
}

然后，即使 SpiderRobot 中的非 mut 方法也可以使用 .get() 方法和 .set() 方法访问 u32：

impl SpiderRobot {
 /// 把错误计数递增1
 pub fn add_hardware_error(&self) {
 let n = self.hardware_error_count.get();
 self.hardware_error_count.set(n + 1);
 }

 /// 如果报告过任何硬件错误，则为true
 pub fn has_hardware_errors(&self) -> bool {
 self.hardware_error_count.get() > 0
 }
}

这很容易，但它无法解决我们的日志记录问题。 Cell 不允许 在共享值上调用 mut 方法。 .get() 方法会返回 Cell 中值的副本，因此它仅在 T 实现了 Copy 特型时才有效。对于日志记录，我们需要一个可变的 File，但 File 不是 Copy 类型。

在这种情况下，正确的工具是 RefCell。与 Cell<T> 一样， RefCell<T> 也是一种泛型类型，它包含类型 T 的单个值。但与 Cell 不同， RefCell 支持借用对其 T 值的引用。

RefCell::new(value)（新建）

创建一个新的 RefCell，将 value 移动进去。

ref_cell.borrow()（借用）

返回一个 Ref<T>，它本质上只是对存储在 ref_cell 中值的共享引用。

如果该值已被以可变的方式借出，则此方法会 panic，详细信息稍后会解释。

ref_cell.borrow_mut()（可变借用）

返回一个 RefMut<T>，它本质上是对 ref_cell 中值的可变引用。

如果该值已被借出，则此方法会 panic，详细信息稍后会解释。

ref_cell.try_borrow()（尝试借用）和 ref_cell.try_borrow_mut()（尝试可变借用）

行为与 borrow() 和 borrow_mut() 一样，但会返回一个 Result。如果该值已被以可变的方式借出，那么这两个方法不会 panic，而是返回一个 Err 值。

同样， RefCell 也有一些其他的方法，你可以在其文档中进行查找。

仅当你试图打破“可变引用必须独占”的 Rust 规则时，这两个 borrow 方法才会 panic。例如，以下代码会引起 panic：

use std::cell::RefCell;

let ref_cell: RefCell<String> = RefCell::new("hello".to_string());

let r = ref_cell.borrow(); // 正确，返回Ref<String>
let count = r.len(); // 正确，返回"hello".len()
assert_eq!(count, 5);

let mut w = ref_cell.borrow_mut(); // panic：已被借出
w.push_str(" world");

为避免 panic，可以将这两个借用放入不同的块中。这样，在你尝试借用 w 之前， r 已经被丢弃了。

这很像普通引用的工作方式。唯一的区别是，通常情况下，当你借用一个变量的引用时，Rust 会 在编译期 进行检查，以确保你在安全地使用该引用。如果检查失败，则会出现编译错误。 RefCell 会使用运行期检查强制执行相同的规则。因此，如果你违反了规则，就会收到 panic（对于 try_borrow 和 try_borrow_mut 则会显示 Err）。

现在我们已经准备好把 RefCell 用在 SpiderRobot 类型中了：

pub struct SpiderRobot {
 ...
 log_file: RefCell<File>,
 ...
}

impl SpiderRobot {
 /// 往日志文件中写一行消息
 pub fn log(&self, message: &str) {
 let mut file = self.log_file.borrow_mut();
 // `writeln!`很像`println!`，但会把输出发送到给定的文件中
 writeln!(file, "{}", message).unwrap();
 }
}

变量 file 的类型为 RefMut<File>，我们可以像使用 File 的可变引用一样使用它。有关写入文件的详细信息，请参阅第 18 章。

Cell 很容易使用。虽然不得不调用 .get() 和 .set() 或 .borrow() 和 .borrow_mut() 略显尴尬，但这就是我们为违反规则而付出的代价。还有一个缺点虽不太明显但更严重： Cell 以及包含它的任意类型都不是线程安全的。因此 Rust 不允许多个线程同时访问它们。第 19 章会讲解内部可变性的线程安全风格，届时我们会讨论“ Mutex<T>”（参见 19.3.2 节）、“原子化类型”（参见 19.3.10 节）和“全局变量”（参见 19.3.11 节）这几项技术。

无论一个结构体是具名字段型的还是元组型的，它都是其他值的聚合：如果我有一个 SpiderSenses 结构体，那么就有了指向共享 SpiderRobot 结构体的 Rc 指针、有了眼睛、有了陀螺仪，等等。所以结构体的本质是“和”这个字：我有 X 和 Y。但是如果围绕“或”这个字构建另一种类型呢？也就是说，当你拥有这种类型的值时，你就拥有了 X 或 Y。这种类型也非常有用，在 Rust 中无处不在，它们是第 10 章的主题。

第 10 章 枚举与模式

在计算机领域，总和类型（sum type）长期悲剧性缺位，很多事情却依然行得通，这简直不可思议（参见 Lambda 的缺位）。1

——Graydon Hoare

本章的第一个主题强劲有力且非常“古老”，它能帮助你在短期内完成很多事（但要付出一定代价），并且许多文化中有关于它的传说。我要说的不是“恶魔”，而是一种用户定义数据类型，长期以来被 ML 社区和 Haskell 社区的黑客们称为总和类型、可区分的联合体（union）或代数数据类型。在 Rust 中，它们被称为 枚举。与“恶魔”不同，它们相当安全，而且也不用付出多少代价。

C++ 和 C# 都有枚举，你可以使用它们来定义自己的类型，其值是一组命名常量。例如，你可以定义一个名为 Color 的类型，其值为 Red、 Orange、 Yellow 等。这种枚举也适用于 Rust，但是 Rust 的枚举远不止于此。Rust 枚举还可以包含数据，甚至是不同类型的数据。例如，Rust 的 Result<String, io::Error> 类型就是一个枚举，这样的值要么是包含 String 型的 Ok 值，要么是包含 io::Error 的 Err 值。C++ 枚举和 C# 枚举则不具备这样的能力。Rust 枚举更像是 C 的联合体，但不同之处在于它是类型安全的。

只要值可能代表多种事物，枚举就很有用。使用枚举的“代价”是你必须通过模式匹配安全地访问数据，这是本章后半部分的主题。

如果你用过 Python 中的解包或 JavaScript 中的解构，那么应该很熟悉“模式”这个词，但 Rust 的模式不止于此。Rust 模式有点儿像针对所有数据的正则表达式。它们用于测试一个值是否具有特定的目标形态，可以一次从结构体或元组中把多个字段提取到局部变量中。

和正则表达式一样，模式很简洁，通常能在一行代码中完成全部工作。

本章从枚举的基础知识讲起，首先展示数据如何关联到枚举的各个变体，以及枚举如何存储在内存中；然后展示 Rust 的模式和 match（匹配）语句如何基于枚举、结构体、数组和切片简洁地表达逻辑。模式中还可以包含引用、移动和 if 条件，来让自己更加强大。

10.1 枚举

Rust 中简单的 C 风格枚举很直观：

enum Ordering {
 Less,
 Equal,
 Greater,
}

这声明了一个具有 3 个可能值的 Ordering 类型，称为 变体 或 构造器： Ordering::Less、 Ordering::Equal 和 Ordering::Greater。这个特殊的枚举是标准库的一部分，因此 Rust 代码能够直接导入它：

use std::cmp::Ordering;

fn compare(n: i32, m: i32) -> Ordering {
 if n < m {
 Ordering::Less
 } else if n > m {
 Ordering::Greater
 } else {
 Ordering::Equal
 }
}

或连同其所有构造器一同导入：

use std::cmp::Ordering::; // `*`导入所有子项

fn compare(n: i32, m: i32) -> Ordering {
 if n < m {
 Less
 } else if n > m {
 Greater
 } else {
 Equal
 }
}

导入构造器后，我们就可以写成 Less 而非 Ordering::Less，等等，但是因为这样写意思不太明确，所以通常认为 不导入 构造器的那种风格更好，除非导入它们能让你的代码更具可读性。

要导入当前模块中声明的枚举的构造器，请使用 self：

enum Pet {
 Orca,
 Giraffe,
 ...
}

use self::Pet::*;

在内存中，C 风格枚举的各个值会存储为整数。有时告诉 Rust 要使用哪几个整数是很有用的：

enum HttpStatus {
 Ok = 200,
 NotModified = 304,
 NotFound = 404,
 ...
}

否则 Rust 会从 0 开始帮你分配数值。

默认情况下，Rust 会使用可以容纳它们的最小内置整数类型来存储 C 风格枚举。最适合的是单字节：

use std::mem::size_of;
assert_eq!(size_of::<Ordering>(), 1);
assert_eq!(size_of::<HttpStatus>(), 2); // 404不适合存入u8

你可以通过向枚举添加 #[repr] 属性来覆盖 Rust 对内存中表示法的默认选择。有关详细信息，请参阅 23.1 节。

可以将 C 风格枚举转换为整数：

assert_eq!(HttpStatus::Ok as i32, 200);

从整数到枚举的反向转换则行不通。与 C 和 C++ 不同，Rust 会保证枚举值必然是 enum 声明中阐明的值之一。从整数类型到枚举类型的非检查转换可能会破坏此保证，因此不允许这样做。你可以编写自己的“检查完再转换”逻辑：

fn http_status_from_u32(n: u32) -> Option<HttpStatus> {
 match n {
 200 => Some(HttpStatus::Ok),
 304 => Some(HttpStatus::NotModified),
 404 => Some(HttpStatus::NotFound),
 ...
 _ => None,
 }
}

或者借助 enum_primitive crate。它包含一个宏，可以帮你自动生成这类转换代码。

与结构体一样，编译器能为你实现 == 运算符等特性，但你必须明确提出要求：

#[derive(Copy, Clone, Debug, PartialEq, Eq)]
enum TimeUnit {
 Seconds, Minutes, Hours, Days, Months, Years,
}

枚举可以有方法，就像结构体一样：

impl TimeUnit {
 /// 返回此时间单位的复数名词
 fn plural(self) -> &'static str {
 match self {
 TimeUnit::Seconds => "seconds",
 TimeUnit::Minutes => "minutes",
 TimeUnit::Hours => "hours",
 TimeUnit::Days => "days",
 TimeUnit::Months => "months",
 TimeUnit::Years => "years",
 }
 }

 /// 返回此时间单位的单数名词
 fn singular(self) -> &'static str {
 self.plural().trim_end_matches('s')
 }
}

至此，C 风格枚举就介绍完了。更有趣的 Rust 枚举类型是其变体中能持有数据的类型。我们将展示如何将它们存储在内存中、如何通过添加类型参数来泛化它们，以及如何运用枚举构建复杂的数据结构。

10.1.1 带数据的枚举

有些程序总是要显示精确到毫秒的完整日期和时间，但对大多数应用程序来说，使用粗略的近似值（比如“两个月前”）对用户更友好。我们可以使用之前定义的枚举来编写一个新的 enum，以帮忙解决此问题：

/// 刻意四舍五入后的时间戳，所以程序会显示“6个月前”
/// 而非“2016年2月9日上午9点49分”
#[derive(Copy, Clone, Debug, PartialEq)]
enum RoughTime {
 InThePast(TimeUnit, u32),
 JustNow,
 InTheFuture(TimeUnit, u32),
}

此枚举中的两个变体 InThePast 和 InTheFuture 能接受参数。这种变体叫作 元组型变体。与元组型结构体一样，这些构造器也是可创建新 RoughTime 值的函数：

let four_score_and_seven_years_ago =
 RoughTime::InThePast(TimeUnit::Years, 4 * 20 + 7);

let three_hours_from_now =
 RoughTime::InTheFuture(TimeUnit::Hours, 3);

枚举还可以有 结构体型变体，就像普通结构体一样包含一些具名字段：

enum Shape {
 Sphere { center: Point3d, radius: f32 },
 Cuboid { corner1: Point3d, corner2: Point3d },
}

let unit_sphere = Shape::Sphere {
 center: ORIGIN,
 radius: 1.0,
};

总而言之，Rust 有 3 种枚举变体，这与我们在第 9 章中展示的 3 种结构体相呼应。没有数据的变体对应于单元型结构体。元组型变体的外观和功能很像元组型结构体。结构体型变体具有花括号和具名字段。单个枚举中可以同时有 3 种类型的变体：

enum RelationshipStatus {
 Single,
 InARelationship,
 ItsComplicated(Option<String>),
 ItsExtremelyComplicated {
 car: DifferentialEquation,
 cdr: EarlyModernistPoem,
 },
}

枚举的所有构造器和字段都与枚举本身具有相同的可见性。

10.1.2 内存中的枚举

在内存中，带有数据的枚举会以一个小型整数 标签 加上足以容纳最大变体中所有字段的内存块的格式进行存储。标签字段供 Rust 内部使用。它会区分由哪个构造器创建了值，进而决定这个值应该有哪些字段。

从 Rust 1.50 开始， RoughTime 会占用 8 字节，如图 10-1 所示。

图 10-1：内存中的 RoughTime 值

不过，为了给将来的优化留下余地，Rust 并没有对枚举的内存布局做出任何承诺。在某些情况下，Rust 可以比图 10-1 中展示的布局更有效地打包枚举。例如，有些泛型结构体可以在不需要标签的情况下存储，稍后我们会介绍。

10.1.3 用枚举表示富数据结构

枚举对于快速实现树形数据结构也很有用。假设一个 Rust 程序需要处理任意 JSON 数据。在内存中，任何 JSON 文档都可以表示为这种 Rust 类型的值：

use std::collections::HashMap;

enum Json {
 Null,
 Boolean(bool),
 Number(f64),
 String(String),
 Array(Vec<Json>),
 Object(Box<HashMap<String, Json>>),
}

用自然语言解释这种数据结构还不如直接看 Rust 代码。JSON 标准指定了可以出现在 JSON 文档中的不同数据类型： null、布尔值、数值、字符串、各种 JSON 值的数组以及具有字符串键名和 JSON 值的对象。这里的 Json 枚举只是简单地列出了这些类型而已。

这不是一个假想的例子。可以在 serde_json 中找到一个非常相似的枚举， serde_json 是 Rust 的结构体序列化库，是 crates.io 上最常下载的 crate 之一。

这里在表示 Object 的 HashMap 周围加 Box 只是为了让所有 Json 值更紧凑。在内存中， Json 类型的值占用 4 个机器字。而 String 值和 Vec 值占用 3 个机器字，Rust 又添加了一个标签字节。 Null 值和 Boolean 值中没有足够的数据来用完所有空间，但所有 Json 值的大小必须相同。因此，额外的空间就用不上了。图 10-2 展示了 Json 值在内存中的实际布局的一些示例。

图 10-2：内存中的 Json 值

HashMap 则更大。如果必须在每个 Json 值中为它留出空间，那么将会非常大，在 8 个机器字左右。但是 Box<HashMap> 是 1 个机器字：它只是指向堆中分配的数据的指针。我们甚至可以通过装箱更多字段来让 Json 更加紧凑。

这里值得注意的是用 Rust 建立这个结构有多么容易。在 C++ 中，可能要为此编写一个类：

class JSON {
private:
 enum Tag {
 Null, Boolean, Number, String, Array, Object
 };
 union Data {
 bool boolean;
 double number;
 shared_ptr<string> str;
 shared_ptr<vector<JSON>> array;
 shared_ptr<unordered_map<string, JSON>> object;

 Data() {}
 ~Data() {}
 ...
 };

 Tag tag;
 Data data;

public:
 bool is_null() const { return tag == Null; }
 bool is_boolean() const { return tag == Boolean; }
 bool get_boolean() const {
 assert(is_boolean());
 return data.boolean;
 }
 void set_boolean(bool value) {
 this->~JSON(); // 清理string/array/object值
 tag = Boolean;
 data.boolean = value;
 }
 ...
};

写了 30 行代码，我们才刚开了个头。这个类将需要构造函数、析构函数和赋值运算符。还有一种方法是创建一个具有基类 JSON 和子类 JSONBoolean、 JSONString 等的类层次结构。无论采用哪种方法，操作完成时，我们的 C++ 版 JSON 库都将有十几个方法。其他程序员需要阅读一定的内容才能掌握并使用它。而整个 Rust 枚举才 8 行代码。

10.1.4 泛型枚举

枚举可以是泛型的。Rust 标准库中的两个例子是该语言中最常用的数据类型：

enum Option<T> {
 None,
 Some(T),
}

enum Result<T, E> {
 Ok(T),
 Err(E),
}

现在你已经很熟悉这些类型了，泛型枚举的语法与泛型结构体是一样的。

一个不太明显的细节是，当类型 T 是引用、 Box 或其他智能指针类型时，Rust 可以省掉 Option<T> 的标签字段。由于这些指针类型都不允许为 0，因此 Rust 可以将 Option<Box<i32>> 表示为单个机器字：0 表示 None，非零表示 Some 指针。这能让 Option 类型的值尽量接近于可能为空的 C 或 C++ 指针。不同之处在于 Rust 的类型系统要求你在使用其内容之前检查 Option 是否为 Some。这有效地避免了对空指针解引用。

只需几行代码就可以构建出泛型数据结构：

// `T`组成的有序集合
enum BinaryTree<T> {
 Empty,
 NonEmpty(Box<TreeNode<T>>),
}

// BinaryTree的部件
struct TreeNode<T> {
 element: T,
 left: BinaryTree<T>,
 right: BinaryTree<T>,
}

这几行代码定义了一个 BinaryTree 类型，它可以存储任意数量的 T 类型的值。

这两个定义中包含了大量信息，因此我们需要花点儿时间逐字解释这些代码。每个 BinaryTree 值要么是 Empty，要么是 NonEmpty。如果是 Empty，那它根本不含任何数据。如果是 NonEmpty，那它就会有一个 Box，即一个指向堆上分配的 TreeNode 的指针。

每个 TreeNode 值包含一个实际元素以及另外两个 BinaryTree 值。这意味着树可以包含子树，因此 NonEmpty 树可以有任意数量的后代。

BinaryTree<&str> 类型值的示意图如图 10-3 所示。与 Option<Box<T>> 一样，Rust 在这里也省略了标签字段，因此 BinaryTree 值占用一个机器字。

图 10-3：包含 6 个字符串的 BinaryTree

在此树中构建任何特定节点都很简明直观：

use self::BinaryTree::*;
let jupiter_tree = NonEmpty(Box::new(TreeNode {
 element: "Jupiter",
 left: Empty,
 right: Empty,
}));

较大的树可以基于较小的树来构建：

let mars_tree = NonEmpty(Box::new(TreeNode {
 element: "Mars",
 left: jupiter_tree,
 right: mercury_tree,
}));

自然，此赋值会将 jupiter_node 和 mercury_node 的所有权转移给它们的新父节点。

树的其余部分都遵循同样的模式。根节点与其他节点没有什么区别：

let tree = NonEmpty(Box::new(TreeNode {
 element: "Saturn",
 left: mars_tree,
 right: uranus_tree,
}));

稍后本章将展示如何在 BinaryTree 类型上实现一个 add 方法，以便像下面这样写：

let mut tree = BinaryTree::Empty;
for planet in planets {
 tree.add(planet);
}

无论你的语言背景如何，在 Rust 中创建像 BinaryTree 这样的数据结构都可能需要做一些练习。起初并不容易看出应该把这些 Box 放在哪里。找到可行设计方案的方法之一是画出图 10-3 那样的图，展示你希望这些数据在内存中如何布局。然后从图片倒推出代码。每组方块都表示一个结构体或元组，每个箭头都是一个 Box 或其他智能指针。弄清楚每个字段的类型虽然有点儿难，但仍然是可以解决的。解决此难题的回报是对程序内存进行了更好的控制。

现在再来说一下本章开头提过的“代价”。枚举的标签字段会占用一点儿内存，最坏情况下可达 8 字节，但这通常可以忽略不计。枚举的真正缺点（如果一定要算的话）是，虽然这些字段真的存在于值中，但 Rust 代码不允许你直接访问它们：

let r = shape.radius; // 错误：在`Shape`类型上没有`radius`字段

只能用一种安全的方式来访问枚举中的数据，即使用模式。

10.2 模式

回忆一下本章前面定义过的 RoughTime 类型：

enum RoughTime {
 InThePast(TimeUnit, u32),
 JustNow,
 InTheFuture(TimeUnit, u32),
}

假设你有一个 RoughTime 值并希望把它显示在网页上。你需要访问值内的 TimeUnit 字段和 u32 字段。Rust 不允许你通过编写 rough_time.0 和 rough_time.1 来直接访问它们，因为毕竟 rough_time 也可能是没有字段的，比如 RoughTime::JustNow。那么，怎样才能获得数据呢？

你需要一个 match 表达式：

 1 fn rough_time_to_english(rt: RoughTime) -> String {
 2 match rt {
 3 RoughTime::InThePast(units, count) =>
 4 format!("{} {} ago", count, units.plural()),
 5 RoughTime::JustNow =>
 6 format!("just now"),
 7 RoughTime::InTheFuture(units, count) =>
 8 format!("{} {} from now", count, units.plural()),
 9 }
10 }

match 会执行模式匹配，在此示例中， 模式 就是第 3 行、第 5 行和第 7 行中出现在 => 符号前面的部分。匹配 RoughTime 值的模式很像用于创建 RoughTime 值的表达式。这是刻意的设计。表达式会 生成 值，模式会 消耗 值。两者刻意使用了很多相同的语法。

我们分步了解一下此 match 表达式在运行期会发生什么。假设 rt 是 RoughTime::InTheFuture(TimeUnit::Months, 1) 的值。Rust 会首先尝试将这个值与第 3 行的模式相匹配。如图 10-4 所示，二者不匹配。

图 10-4：不匹配的 RoughTime 值和模式

对于枚举、结构体或元组类型的匹配，Rust 的工作方式就像简单地从左到右进行扫描一样，会检查模式的每个组件以查看该值是否与之匹配。如果不匹配，Rust 就会接着尝试下一个模式。

第 3 行和第 5 行的模式都不匹配，但是第 7 行的模式匹配成功了，如图 10-5 所示。

图 10-5：一次成功的匹配

模式中包含的简单标识符（如 units 和 count）会成为模式后面代码中的局部变量。值中存在的任何内容都会复制或移动到新变量中。Rust 会在 units 中存储 TimeUnit::Months，在 count 中存储 1，然后运行第 8 行代码，并返回字符串 "1 months from now"。

该输出有一个小小的英语语法问题（未处理复数），可以通过在 match 中添加另一个分支来解决：

RoughTime::InTheFuture(unit, 1) =>
 format!("a {} from now", unit.singular()),

仅当 count 字段恰好为 1 时，才会匹配此分支。请注意，这行新代码必须添加到第 7 行之前。如果将其添加到末尾，那么 Rust 将永远无法访问它，因为第 7 行的模式会匹配所有 InTheFuture 值。如果你犯了这种错误，那么 Rust 编译器将警告发现了 "unreachable pattern"（无法抵达的模式）。

即使用了新代码， RoughTime::InTheFuture(TimeUnit::Hours, 1) 仍然存在问题： "a hour from now" 这个结果不太正确。唉，这就是英语啊。这也可以通过在 match 中添加另一个分支来解决。

如本示例所示，模式匹配可以和枚举协同工作，甚至可以测试它们包含的数据，这让 match 成了 C 的 switch 语句的强大而灵活的替代品。迄今为止，我们只看到了匹配枚举值的模式。但模式的类型不止于此，Rust 模式还有它们自己的小型语言，如表 10-1 所示。我们将用本章剩余的大部分内容来介绍此表中展示的特性。

表 10-1：模式

模式类型

例子

注意事项

字面量

100

"name"

匹配一个确切的值；也允许匹配常量名称

范围

0 ..= 100

'a' ..= 'k'

256..

匹配范围内的任何值，包括可能给定的结束值

通配符

_

匹配任何值并忽略它

变量

name

mut count

类似于 _，但会把值移动或复制到新的局部变量中

引用变量

ref field

ref mut field

借用对匹配值的引用，而不是移动或复制它

与子模式绑定

val @ 0 ..= 99

ref circle @ Shape::Circle { .. }

使用 @ 左边的变量名，匹配其右边的模式

枚举型模式

Some(value)

None

Pet::Orca

元组型模式

(key, value)

(r, g, b)

数组型模式

[a, b, c, d, e, f, g]

[heading, carom, correction]

切片型模式

[first, second]

[first, _, third]

[first, .., nth]

[ ]

结构体型模式

Color(r, g, b)

Point { x, y }

Card { suit: Clubs, rank: n }

Account { id, name, .. }

引用

&value

&(k, v)

仅匹配引用值

或多个模式

'a' | 'A'

Some("left" | "right")

守卫表达式

x if x * x <= r2

只用在 match 表达式中（不能用在 let 语句等处）

10.2.1 模式中的字面量、变量和通配符

迄今为止，我们已经展示了如何借助 match 表达式来使用枚举。 match 也可用来匹配其他类型。当你需要类似 C 语言的 switch 语句的内容时，可以使用针对整数值的 match。像 0 和 1 这样的整型字面量都可以作为模式使用：

match meadow.count_rabbits() {
 0 => {} // 无话可说
 1 => println!("A rabbit is nosing around in the clover."),
 n => println!("There are {} rabbits hopping about in the meadow", n),
}

如果草地上没有兔子，就匹配模式 0；如果只有一只兔子，就匹配模式 1；如果有两只或更多的兔子，就匹配第三个模式，即模式 n。模式 n 只是一个变量名，它可以匹配任何值，匹配的值会移动或复制到一个新的局部变量中。所以在这种情况下， meadow.count_rabbits() 的值会存储在一个新的局部变量 n 中，然后打印出来。

其他字面量也可以用作模式，包括布尔值、字符，甚至字符串：

let calendar = match settings.get_string("calendar") {
 "gregorian" => Calendar::Gregorian,
 "chinese" => Calendar::Chinese,
 "ethiopian" => Calendar::Ethiopian,
 other => return parse_error("calendar", other),
};

在这个例子中， other 就像上个例子中的 n 一样充当了包罗万象的模式。这些模式与 switch 语句中的 default 分支起着相同的作用，用于匹配与任何其他模式都无法匹配的值。

如果你需要一个包罗万象的模式，但又不关心匹配到的值，那么可以用单个下划线 _ 作为模式，这就是 通配符模式：

let caption = match photo.tagged_pet() {
 Pet::Tyrannosaur => "RRRAAAAAHHHHHH",
 Pet::Samoyed => "*dog thoughts*",
 _ => "I'm cute, love me", // 一般性捕获，对任意Pet都生效
};

这里的通配符模式能匹配任意值，但不会将其存储到任何地方。由于 Rust 要求每个 match 表达式都必须处理所有可能的值，因此最后往往需要一个通配符模式。即使你非常确定其他情况不会发生，也必须至少添加一个后备分支，也许是 panic 的分支。

// 有很多种形状（Shape），但我们只支持“选中”一些文本框
// 或者矩形区域中的所有内容。不能选择椭圆或梯形
match document.selection() {
 Shape::TextSpan(start, end) => paint_text_selection(start, end),
 Shape::Rectangle(rect) => paint_rect_selection(rect),
 _ => panic!("unexpected selection type"),
}

10.2.2 元组型模式与结构体型模式

元组型模式匹配元组。每当你想要在单次 match 中获取多条数据时，元组型模式都非常有用：

fn describe_point(x: i32, y: i32) -> &'static str {
 use std::cmp::Ordering::*;
 match (x.cmp(&0), y.cmp(&0)) {
 (Equal, Equal) => "at the origin",
 (_, Equal) => "on the x axis",
 (Equal, _) => "on the y axis",
 (Greater, Greater) => "in the first quadrant",
 (Less, Greater) => "in the second quadrant",
 _ => "somewhere else",
 }
}

结构体型模式使用花括号，就像结构体表达式一样。结构体型模式包含每个字段的子模式：

match balloon.location {
 Point { x: 0, y: height } =>
 println!("straight up {} meters", height),
 Point { x: x, y: y } =>
 println!("at ({}m, {}m)", x, y),
}

在此示例中，如果匹配了第一个分支，则 balloon.location.y 会存储在新的局部变量 height 中。

假设 balloon.location 的值是 Point { x: 30, y: 40 }。像往常一样，Rust 会依次检查每个模式的每个组件，如图 10-6 所示。

图 10-6：与结构体的模式匹配

这会匹配第二个分支，所以输出是 at (30m, 40m)。

像 Point { x: x, y: y } 这样的模式在匹配结构体时很常见，而冗余的名称会造成视觉上的混乱，所以 Rust 对此有一个简写形式： Point 。二者的含义是一样的。 Point 仍会将某个点的 x 字段和 y 字段分别存储在新的本地变量 x 和 y 中。

即使用了简写形式，当我们只关心几个字段时，匹配大型结构体仍然很麻烦：

match get_account(id) {
 ...
 Some(Account {
 name, language, // <---这两个变量才是我们关心的
 id: _, status: _, address: _, birthday: _, eye_color: _,
 pet: _, security_question: _, hashed_innermost_secret: _,
 is_adamantium_preferred_customer: _, }) =>
 language.show_custom_greeting(name),
}

为避免这种情况，可以使用 .. 告诉 Rust 你不关心任何其他字段。

Some(Account { name, language, .. }) =>
 language.show_custom_greeting(name),

10.2.3 数组型模式与切片型模式

数组型模式匹配数组。数组型模式通常用于过滤一些特殊情况的值，并且在处理那些不同位置的值具有不同含义的数组时也非常有用。

例如，在将 HSL（色相、饱和度和亮度）颜色值转换为 RGB（红色、绿色和蓝色）颜色值时，具有零亮度或全亮度的颜色只会是黑色或白色。可以使用 match 表达式来简单地处理这些情况。

fn hsl_to_rgb(hsl: [u8; 3]) -> [u8; 3] {
 match hsl {
 [_, _, 0] => [0, 0, 0],
 [_, _, 255] => [255, 255, 255],
 ...
 }
}

切片型模式也与此相似，但与数组不同，切片具有可变长度，因此切片型模式不仅匹配值，还匹配长度。 .. 在切片型模式中能匹配任意数量的元素。

fn greet_people(names: &[&str]) {
 match names {
 [] => { println!("Hello, nobody.") },
 [a] => { println!("Hello, {}.", a) },
 [a, b] => { println!("Hello, {} and {}.", a, b) },
 [a, .., b] => { println!("Hello, everyone from {} to {}.", a, b) }
 }
}

10.2.4 引用型模式

Rust 模式提供了两种特性来支持引用。 ref 模式会借用已匹配值的一部分。 & 模式会匹配引用。我们会先介绍 ref 模式。

匹配不可复制的值会移动该值。继续以 account 为例，以下代码是无效的：

match account {
 Account { name, language, .. } => {
 ui.greet(&name, &language);
 ui.show_settings(&account); // 错误：借用已移动的值`account`
 }
}

在这里，字段 account.name 和 account.language 会移动到局部变量 name 和 language 中。 account 的其余部分均已丢弃。这就是为什么我们之后不能再借用它的引用。

如果 name 和 language 都是可复制的值，则 Rust 会复制字段而非移动它们，这时上述代码就是有效的。但假设这些是 String 类型，那我们可以做些什么呢？

我们需要一种 借用 而非移动匹配值的模式。 ref 关键字就是这样做的：

match account {
 Account { ref name, ref language, .. } => {
 ui.greet(name, language);
 ui.show_settings(&account); // 正确
 }
}

现在局部变量 name 和 language 是对 account 中相应字段的引用。由于 account 只是被借入而没有被消耗，因此继续调用它的方法是没问题的。

还可以使用 ref mut 来借入可变引用：

match line_result {
 Err(ref err) => log_error(err), // `err`是&Error类型的（共享引用）
 Ok(ref mut line) => { // `line`是&mut String类型的（可变引用）
 trim_comments(line); // 就地修改此字符串
 handle(line);
 }
}

模式 Ok(ref mut line) 能匹配任何成功的结果，并借入其成功值的可变引用。

与 ref 模式相对2的引用型模式是 & 模式。以 & 开头的模式会匹配引用：

match sphere.center() {
 &Point3d { x, y, z } => ...
}

在此示例中，假设 sphere.center() 会返回对 sphere 中的私有字段的引用，这是 Rust 中的常见模式。返回的值是 Point3d 的地址。如果中心位于原点，则 sphere.center() 会返回 &Point3d { x: 0.0, y: 0.0, z: 0.0 }。

模式匹配过程如图 10-7 所示。

图 10-7：与引用的模式匹配

这有点儿棘手，因为 Rust 在这里会追踪一个指针，我们通常会将追踪指针的操作与 * 运算符而不是 & 运算符联系起来。但要记住，模式和表达式是恰恰相反的。表达式 (x, y) 会把两个值放入一个新的元组中，而模式 (x, y) 则会匹配一个元组并分解成两个值。 & 的逻辑也是如此。在表达式中， & 会创建一个引用。在模式中， & 则会匹配一个引用。

匹配引用时会遵循我们所期望的一切规则。生命周期规则仍然有效。你不能通过共享引用获得可变访问权限，而且不能将值从引用中移动出去，即使对可变引用也是如此。当我们匹配 &Point3d { x, y, z } 时，变量 x、 y 和 z 会接受坐标的副本，而原始 Point3d 的值保持不变。这种写法之所以有效，是因为这些字段都是可复制的。如果试图在具有不可复制字段的结构体上这么做，就会出错：

match friend.borrow_car() {
 Some(&Car { engine, .. }) => // 错误：不能把借用的值移动出去
 ...
 None => {}
}

从借来的汽车上搜刮零件可不是君子所为，Rust 同样不会容忍这么做。你可以使用 ref 模式来借用对部件的引用，但并不拥有它：

 Some(&Car { ref engine, .. }) => // 正确，engine是一个引用

再来看一个 & 模式的例子。假设我们有一个遍历字符串中各字符的迭代器 chars，并且它有一个返回 Option<&char>（如果有，则是对下一个字符的引用）的方法 chars.peek()。（ Peekable 迭代器实际上会返回 Option<&ItemType>，我们在第 15 章中会看到。）

程序可以使用 & 模式来获取它所指向的字符。

match chars.peek() {
 Some(&c) => println!("coming up: {:?}", c),
 None => println!("end of chars"),
}

10.2.5 匹配守卫

有时，匹配分支会有一些额外的条件，必须满足这些条件才能视为匹配成功。假设我们正在实现一款棋类游戏，它的棋盘是由六边形组成的，而玩家刚刚通过点击移动了一枚棋子。为了确认点击是有效的，我们可能会做如下尝试：

fn check_move(current_hex: Hex, click: Point) -> game::Result<Hex> {
 match point_to_hex(click) {
 None =>
 Err("That's not a game space."),
 Some(current_hex) => // 如果用户单击current_hex，就会尝试匹配
 //（其实它不起作用：请参见下面的解释）
 Err("You are already there! You must click somewhere else."),
 Some(other_hex) =>
 Ok(other_hex)
 }
}

这失败了，因为模式中的标识符引入了 新变量。这里的模式 Some(current_hex) 创建了一个新的局部变量 current_hex，它遮蔽了同名参数 current_hex。Rust 发出了几个关于此代码的警告——特别是， match 的最后一个分支是不可达的。解决此问题的一种简单方式是在匹配分支中使用 if 表达式：

match point_to_hex(click) {
 None => Err("That's not a game space."),
 Some(hex) => {
 if hex == current_hex {
 Err("You are already there! You must click somewhere else")
 } else {
 Ok(hex)
 }
 }
}

但 Rust 还提供了 匹配守卫，额外的条件必须为真时才能应用此匹配分支，在模式及其分支的 => 标记之间写上 if CONDITION：

match point_to_hex(click) {
 None => Err("That's not a game space."),
 Some(hex) if hex == current_hex =>
 Err("You are already there! You must click somewhere else"),
 Some(hex) => Ok(hex)
}

如果模式匹配成功，但此条件为假，就会继续尝试匹配下一个分支。

10.2.6 匹配多种可能性

对于形如 pat1 | pat2 的模式，如果能匹配其中的任何一个子模式，则认为匹配成功：

let at_end = match chars.peek() {
 Some(&'\r' | &'\n') | None => true,
 _ => false,
};

在表达式中， | 是按位或运算符，但在这里，它更像正则表达式中的 | 符号。如果 chars. peek() 为 None，或者是某个持有回车符、换行符的 Some，则把 at_end 设置为 true。

使用 ..= 匹配整个范围的值。范围型模式包括开始值和结束值，因此 '0' ..= '9' 会匹配所有 ASCII 数字：

match next_char {
 '0'..='9' => self.read_number(),
 'a'..='z' | 'A'..='Z' => self.read_word(),
 ' ' | '\t' | '\n' => self.skip_whitespace(),
 _ => self.handle_punctuation(),
}

Rust 中还允许使用像 x.. 这样的范围型模式，该模式会匹配从 x 到其类型最大值的任何值。但是，目前模式中还不允许使用其他的开区间范围（如 0..100 或 ..100）以及无限范围（如 ..）。

10.2.7 使用@模式绑定

最后， x @ pattern 会与给定的 pattern 精确匹配，但成功时，它不会为匹配到的值的各个部分创建变量，而是会创建单个变量 x 并将整个值移动或复制到其中。假设你有如下代码：

match self.get_selection() {
 Shape::Rect(top_left, bottom_right) => {
 optimized_paint(&Shape::Rect(top_left, bottom_right))
 }
 other_shape => {
 paint_outline(other_shape.get_outline())
 }
}

请注意，第一个分支解包出一个 Shape::Rect 值，却只是为了在下一行重建一个相同的 Shape::Rect 值。像这种代码可以用 @ 模式重写：

 rect @ Shape::Rect(..) => {
 optimized_paint(&rect)
 }

@ 模式对于各种范围模式也很有用。

match chars.next() {
 Some(digit @ '0'..='9') => read_number(digit, chars),
 ...
},

10.2.8 模式能用在哪里

尽管模式在 match 表达式中作用最为突出，但它们也可以出现在其他一些地方，通常用于代替标识符。但无论出现在哪里，其含义都是一样的：Rust 不是要将值存储到单个变量中，而是使用模式匹配来拆分值。

这意味着模式可用于：

// 把结构体解包成3个局部变量……
let Track { album, track_number, title, .. } = song;

// ……解包某个作为函数参数传入的元组
fn distance_to((x, y): (f64, f64)) -> f64 { ... }

// ……迭代某个HashMap上的键和值
for (id, document) in &cache_map {
 println!("Document #{}: {}", id, document.title);
}

// ……自动对闭包参数解引用（当其他代码给你传入引用，
// 而你更想要一个副本时会很有用）
let sum = numbers.fold(0, |a, &num| a + num);

上述示例中的每一个都节省了两三行样板代码。同样的概念也存在于其他一些语言中：JavaScript 中叫作 解构，而 Python 中叫作 解包。

请注意，上述 4 个示例中都使用了确保匹配的模式。模式 Point3d { x, y, z } 会匹配 Point3d 结构体类型的每个可能值， (x, y) 会匹配任何一个 (f64, f64) 值对，等等。这种始终都可以匹配的模式在 Rust 中是很特殊的，它们叫作 不可反驳模式，是唯一能同时用于此处展示的 4 个位置（ let 之后、函数参数中、 for 之后，以及闭包参数中）的模式。

可反驳模式 是一种可能不会匹配的模式，比如 Ok(x) 不会匹配错误结果，而 '0' ..= '9' 不会匹配字符 'Q'。可反驳模式可以用在 match 的分支中，因为 match 就是为此而设计的：如果一个模式无法匹配，那么很清楚接下来会发生什么。在 Rust 程序中，前面的 4 个示例确实是模式可以派上用场的地方，但在这些地方语言不允许匹配失败。

if let 表达式和 while let 表达式中也允许使用可反驳模式，这些模式可用于：

// ……处理只有一个枚举值的特例
if let RoughTime::InTheFuture(_, _) = user.date_of_birth() {
 user.set_time_traveler(true);
}

// ……只有当查表成功时才运行某些代码
if let Some(document) = cache_map.get(&id) {
 return send_cached_response(document);
}

// ……重复尝试某些事，直到成功
while let Err(err) = present_cheesy_anti_robot_task() {
 log_robot_attempt(err);
 // 让用户再试一次（此用户仍然可能是人类）
}

// ……在某个迭代器上手动循环
while let Some(_) = lines.peek() {
 read_paragraph(&mut lines);
}

有关这些表达式的详细信息，请参阅 6.5.1 节和 6.5.2 节。

10.2.9 填充二叉树

早些时候我们曾承诺要展示如何实现方法 BinaryTree::add()，它能将一个节点添加到如下的 BinaryTree 类型中：

// `T`的有序集合
enum BinaryTree<T> {
 Empty,
 NonEmpty(Box<TreeNode<T>>),
}

// BinaryTree的部件
struct TreeNode<T> {
 element: T,
 left: BinaryTree<T>,
 right: BinaryTree<T>,
}

你现在对模式的了解已经足以写出此方法了。对二叉搜索树的解释超出了本书的范畴，如果你已经很熟悉这个主题，可以自己看看它在 Rust 中的表现。

 1 impl<T: Ord> BinaryTree<T> {
 2 fn add(&mut self, value: T) {
 3 match *self {
 4 BinaryTree::Empty => {
 5 *self = BinaryTree::NonEmpty(Box::new(TreeNode {
 6 element: value,
 7 left: BinaryTree::Empty,
 8 right: BinaryTree::Empty,
 9 }))
10 }
11 BinaryTree::NonEmpty(ref mut node) => {
12 if value <= node.element {
13 node.left.add(value);
14 } else {
15 node.right.add(value);
16 }
17 }
18 }
19 }
20 }

第 1 行告诉 Rust 我们正在为有序类型的 BinaryTree 定义一个方法。这与我们在泛型结构体上定义方法的语法是完全相同的，详见 9.5 节。

如果现有的树 *self 是空的，那就很简单了。运行第 5~9 行代码，将 Empty 树更改为 NonEmpty 树即可。此处对 Box::new() 的调用在堆中分配了一个新的 TreeNode。当完成时，树就会包含一个元素。它的左右子树都是 Empty。

如果 *self 不为空，那么我们就会匹配第 11 行代码的模式：

BinaryTree::NonEmpty(ref mut node) => {

该模式借用了对 Box<TreeNode<T>> 的可变引用，因此我们可以访问和修改该树节点中的数据。该引用名为 node，位于第 12~16 行代码的作用域内。由于此节点中已经有了一个元素，因此代码必须递归调用 .add() 以将此新元素添加到左子树或右子树中。

新方法可以像下面这样使用。

let mut tree = BinaryTree::Empty;
tree.add("Mercury");
tree.add("Venus");
...

10.3 大局观

Rust 的枚举对系统编程来说可能是新的，但它并不是新思想。它一直顶着各种听起来就很学术的名字（比如 代数数据类型）在传播，已经在函数式编程语言中存在四十多年了。目前还不清楚为什么在 C 系列的传承中很少有其他语言支持这种枚举。或许只是因为对编程语言的设计者来说，要将变体、引用、可变性和内存安全这 4 项内容结合使用极具挑战性。函数式编程语言抵触可变性。与之相反，C 的联合体具有变体、指针和可变性——但非常不安全，即使在 C 中，它们也只会在迫不得已时使用。Rust 的借用检查器简直就是魔法，它不必做丝毫妥协就能将上述 4 项内容结合起来。

编程就是数据处理。一个小巧、快速、优雅的程序与一个庞大、缓慢、杂乱无章、充斥着各种补丁和虚拟方法调用的程序之间的区别在于，数据是否被转换成了正确的形态。

这就是枚举所针对的“问题空间”。它们是将数据表达为正确形态的设计工具。对于值可能是 A、可能是 B，也可能两者都不是的情况，枚举在每个维度上都比类层次结构表现得要好：更快、更安全、代码更少且更容易文档化。

这里的限制因素是灵活性。枚举的最终用户无法通过扩展枚举来添加新变体，只能通过更改枚举声明来添加。当这种情况发生时，现有代码就会被破坏。我们必须重新审视任何单独匹配枚举的每个变体的 match 表达式，因为它需要一个新的分支来处理这个新变体。在某些情况下，为了简单性而牺牲灵活性是很明智的。毕竟，JSON 的语法结构已经定型，不需要灵活性了。在另外一些情况下，当枚举发生变化时，重新审视枚举的所有使用场合正是我们应该做的。例如，当在编译器中使用 enum 来表示编程语言的各种运算符时，添加新运算符 本来就应该 涉及处理运算符的所有代码。

但有时确实需要更大的灵活性。针对这些情况，Rust 设计了一些特型，这就是第 11 章的主题。

第 11 章 特型与泛型(1)

第 11 章 特型与泛型

计算机科学家倾向于处理非统一性结构（情形 1、情形 2、情形 3），而数学家则倾向于找一个统一的公理来管理整个体系。

——高德纳

编程领域的伟大发现之一，就是可以编写能对许多不同类型（ 甚至是尚未发明的类型）的值进行操作的代码。下面是两个例子。

• Vec<T> 是泛型的：你可以创建任意类型值的向量，包括在你的程序中定义的连 Vec 的作者都不曾设想的类型。
• 许多类型有 .write() 方法，包括 File 和 TcpStream。你的代码可以通过引用来获取任意写入器，并向它发送数据。你的代码不必关心写入器的类型。以后，如果有人添加了一种新型写入器，你的代码也能够直接支持。

当然，这种能力对 Rust 来说并不是什么新鲜事。这就是所谓的 多态性，在 20 世纪 70 年代，它是最新且最热门的编程语言技术。到了现在，多态性实际上已经成了通用技术。Rust 通过两个相关联的特性来支持多态：特型和泛型。许多程序员熟悉这些概念，但 Rust 受到 Haskell 类型类（typeclass）的启发，采用了一种全新的方式。

特型 是 Rust 体系中的接口或抽象基类。乍一看，它们和 Java 或 C# 中的接口差不多。写入字节的特型称为 std::io::Write，它在标准库中的定义开头部分是这样的：

trait Write {
 fn write(&mut self, buf: &[u8]) -> Result<usize>;
 fn flush(&mut self) -> Result<()>;

 fn write_all(&mut self, buf: &[u8]) -> Result<()> { ... }
 ...
}

此特型还提供了几个方法，我们只展示了前 3 个。

File 和 TcpStream 这两个标准类型以及 Vec<u8> 都实现了 std::io::Write。这 3 种类型都提供了 .write()、 .flush() 等方法。使用写入器而不关心其具体类型的代码如下所示：

use std::io::Write;

fn say_hello(out: &mut dyn Write) -> std::io::Result<()> {
 out.write_all(b"hello world\n")?;
 out.flush()
}

out 的类型是 &mut dyn Write，意思是“对实现了 Write 特型的任意值的可变引用”。我们可以将任何此类值的可变引用传给 say_hello：

use std::fs::File;
let mut local_file = File::create("hello.txt")?;
say_hello(&mut local_file)?; // 正常

let mut bytes = vec![];
say_hello(&mut bytes)?; // 同样正常
assert_eq!(bytes, b"hello world\n");

本章展示特型的用法、工作原理，以及如何定义你自己的特型。其实，除了前面介绍的用法，特型还有很多其他用法：我们会使用特型为现有类型添加扩展方法，甚至可以在 str、 bool 等内置类型上添加；我们会解释为什么向类型添加特型不需要额外的内存，以及如何在不需要虚方法调用开销的情况下使用特型；我们会看到，某些内置特型其实是 Rust 为运算符重载和其他特性提供的语言级钩子；我们会介绍 Self 类型、关联函数和关联类型，这是 Rust 从 Haskell 中借来的三大特性，它们优雅地解决了其他语言中要通过变通和入侵才能解决的问题。

泛型 是 Rust 中多态的另一种形式。与 C++ 模板一样，泛型函数或泛型类型可以和不同类型的值一起使用：

/// 给定两个值，找出哪个更小
fn min<T: Ord>(value1: T, value2: T) -> T {
 if value1 <= value2 {
 value1
 } else {
 value2
 }
}

此函数中的 <T: Ord> 表明 min 函数可以与实现了 Ord 特型的任意类型（任意有序类型） T 的参数一起使用。像这样的要求称为 限界，因为它对 T 可能的类型范围做了限制。编译器会针对你实际用到的每种类型 T 生成一份单独的机器码。

泛型和特型紧密相关：泛型函数会在限界中使用特型来阐明它能针对哪些类型的参数进行调用。因此，我们还会讨论 &mut dyn Write 和 <T: Write> 的相似之处、不同之处，以及如何在特型的这两种使用方式之间做出选择。

11.1 使用特型

特型是一种语言特性，我们 可以 说某类型支持或不支持某个特型。大多数情况下，特型代表着一种能力，即一个类型能做什么。

• 实现了 std::io::Write 的值能写出一些字节。
• 实现了 std::iter::Iterator 的值能生成一系列值。
• 实现了 std::clone::Clone 的值能在内存中克隆自身。
• 实现了 std::fmt::Debug 的值能用带有 {:?} 格式说明符的 println!() 打印出来。

这 4 个特型都是 Rust 标准库的一部分，许多标准类型实现了它们。

• std::fs::File 实现了 Write 特型，它能将一些字节写入本地文件。 std::net::TcpStream 能写入网络连接。 Vec<u8> 也实现了 Write，对字节向量的每次 .write() 调用都会将一些数据追加到向量末尾。
• Range<i32>（表达式 0..10 的类型）实现了 Iterator 特型，一些与切片、哈希表等关联的迭代器类型同样实现了 Iterator 特型。
• 大多数标准库类型实现了 Clone。没实现 Clone 的主要是一些像 TcpStream 这样的类型，因为它们代表的不仅仅是内存中的数据。
• 同样，大多数标准库类型支持 Debug。

关于特型方法有一条值得注意的规则：特型本身必须在作用域内。否则，它的所有方法都是不可见的：

let mut buf: Vec<u8> = vec![];
buf.write_all(b"hello")?; // 错误：没有名为`write_all`的方法

在这种情况下，编译器会打印出一条友好的错误消息，建议添加 use std::io::Write;，这确实可以解决问题：

use std::io::Write;

let mut buf: Vec<u8> = vec![];
buf.write_all(b"hello")?; // 正确

之所以 Rust 会有这条规则，是因为你可以使用特型为任意类型添加新方法——甚至是像 u32 和 str 这样的标准库类型（正如我们将在本章后面看到的那样）。而第三方 crate 也可以这样做。显然，这可能导致命名冲突。但是由于 Rust 会要求你导入自己想用的特型，因此 crate 可以放心地利用这种超能力。只有导入两个特型，才会发生冲突，将具有相同名称的方法添加到同一个类型中。这在实践中非常罕见。（如果确实遇到冲突，你可以使用带完全限定符的方法名明确写出自己想要的内容，本章后面会介绍。）

Clone 和 Iterator 的各个方法在没有任何特殊导入的情况下就能工作，因为默认情况下它们始终在作用域中：它们是标准库预导入的一部分，Rust 会把这些名称自动导入每个模块中。事实上，预导入主要就是一些精心挑选的特型。第 13 章会介绍其中的许多内容。

C++ 程序员和 C# 程序员可能已经看出来了，特型方法类似于虚方法。不过，特型方法的调用仍然很快，与任何其他方法调用一样快。一言以蔽之，这里没有多态。很明显， buf 一定是向量，而不可能是文件或网络连接。编译器可以生成对 Vec<u8>::write() 的简单调用，甚至可以内联该方法。（C++ 和 C# 通常也会这样做，不过有时会因为子类的缘故而无法做到。）只有通过 &mut dyn Write 调用时才会产生动态派发（也叫虚方法调用）的开销，类型上的 dyn 关键字指出了这一点。 dyn Write 叫作 特型对象，11.1.1 节会介绍特型对象的一些技术细节，以及它们与泛型函数的比较。

11.1.1 特型对象

在 Rust 中使用特型编写多态代码有两种方法：特型对象和泛型。我们将首先介绍特型对象，然后会在 11.1.2 节转向泛型。

Rust 不允许 dyn Write 类型的变量：

use std::io::Write;

let mut buf: Vec<u8> = vec![];
let writer: dyn Write = buf; // 错误：`Write`的大小不是常量

变量的大小必须是编译期已知的，而那些实现了 Write 的类型可以是任意大小。

如果你是 C# 程序员或 Java 程序员，可能会对此感到惊讶，但原因其实很简单。在 Java 中， OutputStream 类型（类似于 std::io::Write 的 Java 标准接口）的变量其实是对任何实现了 OutputStream 的对象的引用。它本身就是引用，无须显式说明。C# 和大多数其他语言中的接口也一样。

我们在 Rust 中也想这么做，但在 Rust 中，引用是显式的：

let mut buf: Vec<u8> = vec![];
let writer: &mut dyn Write = &mut buf; // 正确

对特型类型（如 writer）的引用叫作 特型对象。与任何其他引用一样，特型对象指向某个值，它具有生命周期，并且可以是可变或共享的。

特型对象的与众不同之处在于，Rust 通常无法在编译期间知道引用目标的类型。因此，特型对象要包含一些关于引用目标类型的额外信息。这仅供 Rust 自己在幕后使用：当你调用 writer.write(data) 时，Rust 需要使用类型信息来根据 *writer 的具体类型动态调用正确的 write 方法。你不能直接查询这些类型信息，Rust 也不支持从特型对象 &mut dyn Write 向下转型回像 Vec<u8> 这样的具体类型。

特型对象的内存布局

在内存中，特型对象是一个胖指针，由指向值的指针和指向表示该值类型的虚表的指针组成。因此，每个特型对象会占用两个机器字，如图 11-1 所示。

C++ 也有这种运行期类型信息，叫作 虚表 或 vtable。就像在 C++ 中一样，在 Rust 中，虚表只会在编译期生成一次，并由同一类型的所有对象共享。图 11-1 中深色部分展示的所有内容（包括虚表）都是 Rust 的私有实现细节。同样，这些都不是你可以直接访问的字段和数据结构。当你调用特型对象的方法时，该语言会自动使用虚表来确定要调用哪个实现。

图 11-1：内存中的特型对象

经验丰富的 C++ 程序员可能会注意到 Rust 和 C++ 在内存使用上略有不同。在 C++ 中，虚表指针或 vptr 是作为结构体的一部分存储的，而 Rust 使用的是胖指针方案。结构体本身只包含自己的字段。这样一来，每个结构体就可以实现几十个特型而不必包含几十个 vptr 了。甚至连 i32 这样大小不足以容纳 vptr 的类型都可以实现特型。

Rust 在需要时会自动将普通引用转换为特型对象。这就是为什么我们能够在这个例子中把 &mut local_file 传给 say_hello：

let mut local_file = File::create("hello.txt")?;
say_hello(&mut local_file)?;

&mut local_file 的类型是 &mut File， say_hello 的参数类型是 &mut dyn Write。由于 File 也是一种写入器，因此 Rust 允许这样操作，它会自动将普通引用转换为特型对象。

同样，Rust 会愉快地将 Box<File> 转换为 Box<dyn Write>，这是一个拥有在堆中分配的写入器的值：

let w: Box<dyn Write> = Box::new(local_file);

和 &mut dyn Write 一样， Box<dyn Write> 也是一个胖指针，即包含写入器本身的地址和虚表的地址。其他指针类型（如 Rc<dyn Write>）同样如此。

这种转换是创建特型对象的唯一方法。编译器在这里真正做的事非常简单。在发生转换的地方，Rust 知道引用目标的真实类型（在本例中为 File），因此它只要加上适当的虚表的地址，把常规指针变成胖指针就可以了。

11.1.2 泛型函数与类型参数

本章在开头展示过一个以特型对象为参数的 say_hello() 函数。现在，让我们把该函数重写为泛型函数：

fn say_hello<W: Write>(out: &mut W) -> std::io::Result<()> {
 out.write_all(b"hello world\n")?;
 out.flush()
}

只有类型签名发生了变化：

fn say_hello(out: &mut dyn Write) // 普通函数

fn say_hello<W: Write>(out: &mut W) // 泛型函数

短语 <W: Write> 把函数变成了泛型形式。此短语叫作 类型参数。这意味着在这个函数的整个函数体中， W 都代表着某种实现了 Write 特型的类型。按照惯例，类型参数通常是单个大写字母。

W 代表哪种类型取决于泛型函数的使用方式：

say_hello(&mut local_file)?; // 调用say_hello::<File>

say_hello(&mut bytes)?; // 调用say_hello::<Vec<u8>>

当你将 &mut local_file 传给泛型函数 say_hello() 时，其实调用的是 say_hello::<File>()。Rust 会为此函数生成一份机器码，以调用 File::write_all() 方法和 File::flush() 方法。当你传入 &mut bytes 时，其实是在调用 say_hello::<Vec<u8>>()。Rust 会为这个版本的函数生成单独的机器码，以调用相应的 Vec<u8> 方法。在这两种情况下，Rust 都会从参数的类型推断出类型 W，这个过程叫作 单态化，编译器会自动处理这一切。

你总是可以明确写出类型参数：

say_hello::<File>(&mut local_file)?;

但一般无此必要，因为 Rust 通常可以通过查看参数来推断出类型参数。在这里， say_hello 泛型函数需要一个 &mut W 参数，我们向它传入了一个 &mut File，所以 Rust 断定 W = File。

如果你调用的泛型函数没有任何能提供有用线索的参数，则可能需要把它明确写出来：

// 调用无参数的泛型方法collect<C>()
let v1 = (0 .. 1000).collect(); // 错误：无法推断类型
let v2 = (0 .. 1000).collect::<Vec<i32>>(); // 正确