Rust 编程语言

The Rust Programming Language

由 Steve Klabnik、Carol Nichols 和 Chris Krycho 编写，并得到了 Rust 社区的贡献

by Steve Klabnik, Carol Nichols, and Chris Krycho, with contributions from the Rust Community

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

This version of the text assumes you’re using Rust 1.90.0 (released 2025-09-18) or later with edition = "2024" in the Cargo.toml file of all projects to configure them to use Rust 2024 Edition idioms. See the “Installation” section of Chapter 1 for instructions on installing or updating Rust, and see Appendix E for information on editions.

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

The HTML format is available online at https://doc.rust-lang.org/stable/book/ and offline with installations of Rust made with rustup; run rustup doc --book to open.

此外还有多个社区 翻译版本。

Several community translations are also available.

本书可从 No Starch Press 购买纸质版和电子书格式。

This text is available in paperback and ebook format from No Starch Press.

🚨 想要更具互动性的学习体验吗？尝试一下 Rust Book 的另一个版本，其特色包括：测验、高亮、可视化等等：https://rust-book.cs.brown.edu

🚨 Want a more interactive learning experience? Try out a different version of the Rust Book, featuring: quizzes, highlighting, visualizations, and more: https://rust-book.cs.brown.edu

前言

Foreword

Rust 编程语言在短短几年内取得了长足的进步，从最初由一小群爱好者组成的萌芽社区创建和孵化，发展成为世界上最受喜爱和最受欢迎的编程语言之一。回首往事，Rust 的力量和前景必然会引起人们的关注，并在系统编程领域占据一席之地。但不可预见的是，全球范围内兴趣和创新的增长渗透到了开源社区，并催化了各行各业的大规模采用。

The Rust programming language has come a long way in a few short years, from its creation and incubation by a small and nascent community of enthusiasts, to becoming one of the most loved and in-demand programming languages in the world. Looking back, it was inevitable that the power and promise of Rust would turn heads and gain a foothold in systems programming. What was not inevitable was the global growth in interest and innovation that permeated through open source communities and catalyzed wide-scale adoption across industries.

此时此刻，我们可以轻而易举地指出 Rust 所提供的精彩特性，来解释这种兴趣和采用率的爆炸式增长。谁不想要内存安全、以及快速性能、以及友好的编译器、以及卓越的工具，还有许多其他出色的特性呢？你今天看到的 Rust 语言结合了系统编程领域多年的研究与一个充满活力且充满激情的社区的实践智慧。这门语言的设计富有目的性，制作精良，为开发者提供了一个工具，使编写安全、快速且可靠的代码变得更加容易。

At this point in time, it is easy to point to the wonderful features that Rust has to offer to explain this explosion in interest and adoption. Who doesn’t want memory safety, and fast performance, and a friendly compiler, and great tooling, among a host of other wonderful features? The Rust language you see today combines years of research in systems programming with the practical wisdom of a vibrant and passionate community. This language was designed with purpose and crafted with care, offering developers a tool that makes it easier to write safe, fast, and reliable code.

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

But what makes Rust truly special is its roots in empowering you, the user, to achieve your goals. This is a language that wants you to succeed, and the principle of empowerment runs through the core of the community that builds, maintains, and advocates for this language. Since the previous edition of this definitive text, Rust has further developed into a truly global and trusted language. The Rust Project is now robustly supported by the Rust Foundation, which also invests in key initiatives to ensure that Rust is secure, stable, and sustainable.

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

This edition of The Rust Programming Language is a comprehensive update, reflecting the language’s evolution over the years and providing valuable new information. But it is not just a guide to syntax and libraries—it’s an invitation to join a community that values quality, performance, and thoughtful design. Whether you’re a seasoned developer looking to explore Rust for the first time or an experienced Rustacean looking to refine your skills, this edition offers something for everyone.

Rust 的历程是一个协作、学习和迭代的过程。这门语言及其生态系统的成长是其背后充满活力、多元化社区的直接体现。成千上万开发者的贡献，从核心语言设计者到业余贡献者，造就了 Rust 这样独特且强大的工具。通过拿起这本书，你不仅是在学习一门新的编程语言，你还在加入一场让软件变得更好、更安全、更令人愉悦的运动。

The Rust journey has been one of collaboration, learning, and iteration. The growth of the language and its ecosystem is a direct reflection of the vibrant, diverse community behind it. The contributions of thousands of developers, from core language designers to casual contributors, are what make Rust such a unique and powerful tool. By picking up this book, you’re not just learning a new programming language—you’re joining a movement to make software better, safer, and more enjoyable to work with.

欢迎来到 Rust 社区！

Welcome to the Rust community!

— Bec Rumbul，Rust Foundation 执行董事

• Bec Rumbul, Executive Director of the Rust Foundation

介绍

Introduction

注意：本书的这个版本与 No Starch Press 出版的纸质书和电子书形式的《The Rust Programming Language》相同。

Note: This edition of the book is the same as The Rust Programming Language available in print and ebook format from No Starch Press.

欢迎阅读《Rust 程序设计语言》，这是一本关于 Rust 的入门书籍。Rust 编程语言能帮助你编写更快、更可靠的软件。在编程语言设计中，高层的人机交互工程学与底层的控制权往往互不相容；Rust 则挑战了这一冲突。通过平衡强大的技术能力和卓越的开发者体验，Rust 让你能够控制底层细节（如内存使用），而无需承担传统底层控制所带来的种种不便。

Welcome to The Rust Programming Language, an introductory book about Rust. The Rust programming language helps you write faster, more reliable software. High-level ergonomics and low-level control are often at odds in programming language design; Rust challenges that conflict. Through balancing powerful technical capacity and a great developer experience, Rust gives you the option to control low-level details (such as memory usage) without all the hassle traditionally associated with such control.

Rust 为谁准备

Who Rust Is For

Rust 对于许多人来说都是理想的选择，原因各不相同。让我们来看看其中最重要的几个群体。

Rust is ideal for many people for a variety of reasons. Let’s look at a few of the most important groups.

开发团队

Teams of Developers

事实证明，对于拥有不同系统编程知识水平的大型开发团队，Rust 是一件高效的协作工具。底层代码容易出现各种微妙的 bug，在大多数其他语言中，这些 bug 只能通过经验丰富的开发者进行广泛测试和细致的代码审查才能发现。在 Rust 中，编译器扮演了“守门员”的角色，它会拒绝编译包含这些隐蔽 bug（包括并发 bug）的代码。通过与编译器并肩工作，团队可以将时间花在关注程序的逻辑上，而不是去追踪 bug。

Rust is proving to be a productive tool for collaborating among large teams of developers with varying levels of systems programming knowledge. Low-level code is prone to various subtle bugs, which in most other languages can only be caught through extensive testing and careful code review by experienced developers. In Rust, the compiler plays a gatekeeper role by refusing to compile code with these elusive bugs, including concurrency bugs. By working alongside the compiler, the team can spend its time focusing on the program’s logic rather than chasing down bugs.

Rust 还为系统编程领域带来了现代化的开发者工具：

Rust also brings contemporary developer tools to the systems programming world:

• Cargo 是内置的依赖管理器和构建工具，它使得在 Rust 生态系统中添加、编译和管理依赖变得轻松且一致。

• rustfmt 格式化工具确保了开发者之间统一的代码风格。

• Rust Language Server 为集成开发环境（IDE）提供了代码补全和内联错误消息功能。

• Cargo, the included dependency manager and build tool, makes adding, compiling, and managing dependencies painless and consistent across the Rust ecosystem.

• The rustfmt formatting tool ensures a consistent coding style across developers.

• The Rust Language Server powers integrated development environment (IDE) integration for code completion and inline error messages.

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

By using these and other tools in the Rust ecosystem, developers can be productive while writing systems-level code.

学生

Students

Rust 适合学生和那些对学习系统概念感兴趣的人。通过 Rust，许多人学习了诸如操作系统开发之类的课题。Rust 社区非常友好，乐于回答学生的问题。通过本书等努力，Rust 团队希望让系统概念对更多人（尤其是编程新手）而言更加平易近人。

Rust is for students and those who are interested in learning about systems concepts. Using Rust, many people have learned about topics like operating systems development. The community is very welcoming and happy to answer students’ questions. Through efforts such as this book, the Rust teams want to make systems concepts more accessible to more people, especially those new to programming.

公司

Companies

数百家大大小小的公司在生产环境中使用 Rust 执行各种任务，包括命令行工具、Web 服务、DevOps 工具、嵌入式设备、音频和视频分析与转码、加密货币、生物信息学、搜索引擎、物联网应用、机器学习，甚至是 Firefox 网络浏览器的核心部分。

Hundreds of companies, large and small, use Rust in production for a variety of tasks, including command line tools, web services, DevOps tooling, embedded devices, audio and video analysis and transcoding, cryptocurrencies, bioinformatics, search engines, Internet of Things applications, machine learning, and even major parts of the Firefox web browser.

开源开发者

Open Source Developers

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

Rust is for people who want to build the Rust programming language, community, developer tools, and libraries. We’d love to have you contribute to the Rust language.

重视速度和稳定性的人

People Who Value Speed and Stability

Rust 适合那些在语言中渴求速度和稳定性的人。所谓速度，我们既指 Rust 代码运行的速度，也指 Rust 让你编写程序的速度。Rust 编译器的检查确保了在增加功能和重构时的稳定性。这与那些没有这些检查的语言中脆弱的遗留代码形成鲜明对比，开发者往往不敢修改它们。通过追求零成本抽象（zero-cost abstractions）——即编译为底层代码后与手动编写的代码一样快的高级特性——Rust 努力让安全的代码也成为高效的代码。

Rust is for people who crave speed and stability in a language. By speed, we mean both how quickly Rust code can run and the speed at which Rust lets you write programs. The Rust compiler’s checks ensure stability through feature additions and refactoring. This is in contrast to the brittle legacy code in languages without these checks, which developers are often afraid to modify. By striving for zero-cost abstractions—higher-level features that compile to lower-level code as fast as code written manually—Rust endeavors to make safe code be fast code as well.

Rust 语言也希望能支持许多其他用户；这里提到的仅仅是一些最大的利益相关者。总的来说，Rust 最大的野心是通过提供安全性“与”生产力、速度“与”易用性，来消除程序员们已经接受了几十年的权衡取舍。尝试一下 Rust，看看它的选择是否适合你。

The Rust language hopes to support many other users as well; those mentioned here are merely some of the biggest stakeholders. Overall, Rust’s greatest ambition is to eliminate the trade-offs that programmers have accepted for decades by providing safety and productivity, speed and ergonomics. Give Rust a try, and see if its choices work for you.

本书为谁准备

Who This Book Is For

本书假设你已经用另一种编程语言写过代码，但并不假设是哪一种。我们努力使这些材料能被拥有各种编程背景的人广泛理解。我们不会花很多时间讨论什么是编程，或者如何思考编程。如果你完全是编程新手，阅读一本专门提供编程入门的书籍会更有帮助。

This book assumes that you’ve written code in another programming language, but it doesn’t make any assumptions about which one. We’ve tried to make the material broadly accessible to those from a wide variety of programming backgrounds. We don’t spend a lot of time talking about what programming is or how to think about it. If you’re entirely new to programming, you would be better served by reading a book that specifically provides an introduction to programming.

如何使用本书

How to Use This Book

通常，本书假设你是从头到尾按顺序阅读。后面的章节建立在前面章节的概念之上，而前面的章节可能不会深入探讨某个特定话题的细节，但会在后面的章节中重新审视该话题。

In general, this book assumes that you’re reading it in sequence from front to back. Later chapters build on concepts in earlier chapters, and earlier chapters might not delve into details on a particular topic but will revisit the topic in a later chapter.

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

You’ll find two kinds of chapters in this book: concept chapters and project chapters. In concept chapters, you’ll learn about an aspect of Rust. In project chapters, we’ll build small programs together, applying what you’ve learned so far. Chapter 2, Chapter 12, and Chapter 21 are project chapters; the rest are concept chapters.

第 1 章 解释了如何安装 Rust，如何编写 “Hello, world!” 程序，以及如何使用 Cargo——Rust 的包管理器和构建工具。第 2 章 是编写 Rust 程序的动手实践介绍，带你构建一个猜数游戏。在这里，我们从高层讲解概念，后续章节将提供更多细节。如果你想马上动手实践，第 2 章就是为你准备的。如果你是一个特别细致的学习者，喜欢在继续下一步之前学习每一个细节，你可能想跳过第 2 章直接进入 第 3 章，它涵盖了与其他编程语言相似的 Rust 特性；然后，当你想要通过项目应用所学的细节时，再回到第 2 章。

Chapter 1 explains how to install Rust, how to write a “Hello, world!” program, and how to use Cargo, Rust’s package manager and build tool. Chapter 2 is a hands-on introduction to writing a program in Rust, having you build up a number-guessing game. Here, we cover concepts at a high level, and later chapters will provide additional detail. If you want to get your hands dirty right away, Chapter 2 is the place for that. If you’re a particularly meticulous learner who prefers to learn every detail before moving on to the next, you might want to skip Chapter 2 and go straight to Chapter 3, which covers Rust features that are similar to those of other programming languages; then, you can return to Chapter 2 when you’d like to work on a project applying the details you’ve learned.

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

In Chapter 4, you’ll learn about Rust’s ownership system. Chapter 5 discusses structs and methods. Chapter 6 covers enums, match expressions, and the if let and let...else control flow constructs. You’ll use structs and enums to make custom types.

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

In Chapter 7, you’ll learn about Rust’s module system and about privacy rules for organizing your code and its public application programming interface (API). Chapter 8 discusses some common collection data structures that the standard library provides: vectors, strings, and hash maps. Chapter 9 explores Rust’s error-handling philosophy and techniques.

第 10 章 深入探讨泛型（generics）、trait 和生命周期（lifetimes），它们让你有能力定义适用于多种类型的代码。第 11 章 全部关于测试，即使有 Rust 的安全保证，测试对于确保程序逻辑正确也是必要的。在 第 12 章，我们将构建自己版本的 grep 命令行工具子集功能，用于在文件中搜索文本。为此，我们将使用前面章节中讨论过的许多概念。

Chapter 10 digs into generics, traits, and lifetimes, which give you the power to define code that applies to multiple types. Chapter 11 is all about testing, which even with Rust’s safety guarantees is necessary to ensure that your program’s logic is correct. In Chapter 12, we’ll build our own implementation of a subset of functionality from the grep command line tool that searches for text within files. For this, we’ll use many of the concepts we discussed in the previous chapters.

第 13 章 探索闭包和迭代器：这些 Rust 特性源自函数式编程语言。在 第 14 章，我们将更深入地研究 Cargo，并讨论与他人分享库的最佳实践。第 15 章 讨论标准库提供的智能指针以及启用其功能的 trait。

Chapter 13 explores closures and iterators: features of Rust that come from functional programming languages. In Chapter 14, we’ll examine Cargo in more depth and talk about best practices for sharing your libraries with others. Chapter 15 discusses smart pointers that the standard library provides and the traits that enable their functionality.

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

In Chapter 16, we’ll walk through different models of concurrent programming and talk about how Rust helps you program in multiple threads fearlessly. In Chapter 17, we build on that by exploring Rust’s async and await syntax, along with tasks, futures, and streams, and the lightweight concurrency model they enable.

第 18 章 看看 Rust 的习惯用法与你可能熟悉的面向对象编程原则相比如何。第 19 章 是关于模式和模式匹配的参考，它们是贯穿 Rust 程序表达思想的强大方式。第 20 章 包含了一系列感兴趣的高级话题，包括不安全 Rust（unsafe Rust）、宏，以及更多关于生命周期、trait、类型、函数和闭包的内容。

Chapter 18 looks at how Rust idioms compare to object-oriented programming principles you might be familiar with. Chapter 19 is a reference on patterns and pattern matching, which are powerful ways of expressing ideas throughout Rust programs. Chapter 20 contains a smorgasbord of advanced topics of interest, including unsafe Rust, macros, and more about lifetimes, traits, types, functions, and closures.

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

In Chapter 21, we’ll complete a project in which we’ll implement a low-level multithreaded web server!

最后，一些附录以更像参考手册的形式包含了关于该语言的有用信息。附录 A 涵盖 Rust 的关键字，附录 B 涵盖 Rust 的运算符和符号，附录 C 涵盖标准库提供的可派生 trait，附录 D 涵盖一些有用的开发工具，附录 E 解释 Rust 的版本（editions）。在 附录 F 中，你可以找到本书的译本，而在 附录 G 中，我们将介绍 Rust 是如何开发的以及什么是 nightly Rust。

Finally, some appendixes contain useful information about the language in a more reference-like format. Appendix A covers Rust’s keywords, Appendix B covers Rust’s operators and symbols, Appendix C covers derivable traits provided by the standard library, Appendix D covers some useful development tools, and Appendix E explains Rust editions. In Appendix F, you can find translations of the book, and in Appendix G we’ll cover how Rust is made and what nightly Rust is.

阅读本书没有错误的方式：如果你想跳着看，那就去吧！如果遇到困惑，你可能需要跳回前面的章节。但请以适合你的方式进行。

There is no wrong way to read this book: If you want to skip ahead, go for it! You might have to jump back to earlier chapters if you experience any confusion. But do whatever works for you.

学习 Rust 过程中的一个重要部分是学习如何阅读编译器显示的错误消息：这些消息将引导你编写出可运行的代码。因此，我们将提供许多无法编译的示例，并附上编译器在每种情况下会向你显示的错误消息。请记住，如果你输入并运行一个随机示例，它可能无法编译！请确保阅读周围的文本，以查看你尝试运行的示例是否原本就是要报错的。在大多数情况下，我们会引导你找到任何无法编译代码的正确版本。Ferris 也会帮助你区分那些本就不该运行的代码：

An important part of the process of learning Rust is learning how to read the error messages the compiler displays: These will guide you toward working code. As such, we’ll provide many examples that don’t compile along with the error message the compiler will show you in each situation. Know that if you enter and run a random example, it may not compile! Make sure you read the surrounding text to see whether the example you’re trying to run is meant to error. In most situations, we’ll lead you to the correct version of any code that doesn’t compile. Ferris will also help you distinguish code that isn’t meant to work:

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

Meaning

This code does not compile!

This code panics!

This code does not produce the desired behavior.

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

In most situations, we’ll lead you to the correct version of any code that doesn’t compile.

源代码

Source Code

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

The source files from which this book is generated can be found on GitHub.

入门

Getting Started

让我们开始你的 Rust 旅程吧！有很多东西需要学习，但每段旅程都有起点。在本章中，我们将讨论：

Let’s start your Rust journey! There’s a lot to learn, but every journey starts somewhere. In this chapter, we’ll discuss:

• 在 Linux、macOS 和 Windows 上安装 Rust

• Installing Rust on Linux, macOS, and Windows

• 编写一个打印 Hello, world! 的程序

• Writing a program that prints Hello, world!

• 使用 cargo，Rust 的包管理器和构建系统

• Using cargo, Rust’s package manager and build system

安装

安装

Installation

第一步是安装 Rust。我们将通过 rustup 下载 Rust，这是一个用于管理 Rust 版本和相关工具的命令行工具。下载过程需要互联网连接。

The first step is to install Rust. We’ll download Rust through rustup, a command line tool for managing Rust versions and associated tools. You’ll need an internet connection for the download.

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

Note: If you prefer not to use rustup for some reason, please see the Other Rust Installation Methods page for more options.

以下步骤将安装 Rust 编译器的最新稳定版本。Rust 的稳定性保证确保了本书中所有能编译的示例在较新的 Rust 版本中将继续保持可编译。不同版本之间的输出可能会有细微差别，因为 Rust 经常改进错误消息和警告。换句话说，你使用这些步骤安装的任何较新的 Rust 稳定版本，都应该能如预期般配合本书内容运行。

The following steps install the latest stable version of the Rust compiler. Rust’s stability guarantees ensure that all the examples in the book that compile will continue to compile with newer Rust versions. The output might differ slightly between versions because Rust often improves error messages and warnings. In other words, any newer, stable version of Rust you install using these steps should work as expected with the content of this book.

命令行标记法

Command Line Notation

在本章以及整本书中，我们将展示一些在终端中使用的命令。你应该在终端中输入的行都以 $ 开头。你不需要输入 $ 字符；它是显示的命令行提示符，用于指示每个命令的开始。不以 $ 开头的行通常显示上一个命令的输出。此外，PowerShell 特定的示例将使用 > 而不是 $。

In this chapter and throughout the book, we’ll show some commands used in the terminal. Lines that you should enter in a terminal all start with $. You don’t need to type the $ character; it’s the command line prompt shown to indicate the start of each command. Lines that don’t start with $ typically show the output of the previous command. Additionally, PowerShell-specific examples will use > rather than $.

在 Linux 或 macOS 上安装 rustup

Installing rustup on Linux or macOS

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

If you’re using Linux or macOS, open a terminal and enter the following command:

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

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

The command downloads a script and starts the installation of the rustup tool, which installs the latest stable version of Rust. You might be prompted for your password. If the install is successful, the following line will appear:

Rust is installed now. Great!

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

You will also need a linker, which is a program that Rust uses to join its compiled outputs into one file. It is likely you already have one. If you get linker errors, you should install a C compiler, which will typically include a linker. A C compiler is also useful because some common Rust packages depend on C code and will need a C compiler.

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

On macOS, you can get a C compiler by running:

$ xcode-select --install

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

Linux users should generally install GCC or Clang, according to their distribution’s documentation. For example, if you use Ubuntu, you can install the build-essential package.

在 Windows 上安装 rustup

Installing rustup on Windows

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

On Windows, go to https://www.rust-lang.org/tools/install and follow the instructions for installing Rust. At some point in the installation, you’ll be prompted to install Visual Studio. This provides a linker and the native libraries needed to compile programs. If you need more help with this step, see https://rust-lang.github.io/rustup/installation/windows-msvc.html.

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

The rest of this book uses commands that work in both cmd.exe and PowerShell. If there are specific differences, we’ll explain which to use.

故障排除

Troubleshooting

要检查你是否正确安装了 Rust，请打开 shell 并输入以下行：

To check whether you have Rust installed correctly, open a shell and enter this line:

$ rustc --version

你应该能看到已发布的最新稳定版本的版本号、提交哈希和提交日期，格式如下：

You should see the version number, commit hash, and commit date for the latest stable version that has been released, in the following format:

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

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

If you see this information, you have installed Rust successfully! If you don’t see this information, check that Rust is in your %PATH% system variable as follows.

在 Windows CMD 中，使用：

In Windows CMD, use:

> echo %PATH%

在 PowerShell 中，使用：

In PowerShell, use:

> echo $env:Path

在 Linux 和 macOS 中，使用：

In Linux and macOS, use:

$ echo $PATH

如果一切正确但 Rust 仍然无法运行，你可以在很多地方获得帮助。在 社区页面 上了解如何与其他 Rustaceans（我们给自己的一个俏皮昵称）取得联系。

If that’s all correct and Rust still isn’t working, there are a number of places you can get help. Find out how to get in touch with other Rustaceans (a silly nickname we call ourselves) on the community page.

更新与卸载

Updating and Uninstalling

通过 rustup 安装 Rust 后，更新到新发布的版本非常简单。在你的 shell 中，运行以下更新脚本：

Once Rust is installed via rustup, updating to a newly released version is easy. From your shell, run the following update script:

$ rustup update

要卸载 Rust 和 rustup，请在你的 shell 中运行以下卸载脚本：

To uninstall Rust and rustup, run the following uninstall script from your shell:

$ rustup self uninstall

阅读本地文档

Reading the Local Documentation

Rust 的安装还包括一份本地文档副本，以便你可以离线阅读。运行 rustup doc 可以在浏览器中打开本地文档。

The installation of Rust also includes a local copy of the documentation so that you can read it offline. Run rustup doc to open the local documentation in your browser.

每当标准库提供了一个类型或函数，而你不确定它的作用或如何使用它时，请使用应用编程接口（API）文档来查找！

Any time a type or function is provided by the standard library and you’re not sure what it does or how to use it, use the application programming interface (API) documentation to find out!

使用文本编辑器和 IDE

Using Text Editors and IDEs

本书不对你编写 Rust 代码所使用的工具做任何假设。几乎任何文本编辑器都可以完成这项工作！不过，许多文本编辑器和集成开发环境（IDE）都内置了对 Rust 的支持。你总能在 Rust 网站的 工具页面 上找到许多编辑器和 IDE 的最新列表。

This book makes no assumptions about what tools you use to author Rust code. Just about any text editor will get the job done! However, many text editors and integrated development environments (IDEs) have built-in support for Rust. You can always find a fairly current list of many editors and IDEs on the tools page on the Rust website.

离线学习本书

Working Offline with This Book

在一些示例中，我们将使用标准库之外的 Rust 包。要完成这些示例，你可能需要互联网连接，或者提前下载这些依赖项。要提前下载依赖项，你可以运行以下命令。（稍后我们将详细解释 cargo 是什么以及这些命令的作用。）

In several examples, we will use Rust packages beyond the standard library. To work through those examples, you will either need to have an internet connection or to have downloaded those dependencies ahead of time. To download the dependencies ahead of time, you can run the following commands. (We’ll explain what cargo is and what each of these commands does in detail later.)

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

这将缓存这些包的下载，这样你以后就不需要再下载它们了。运行此命令后，你不需要保留 get-dependencies 文件夹。如果你已经运行了此命令，可以在本书其余部分的所有 cargo 命令中使用 --offline 标志，以使用这些缓存版本，而不是尝试连接网络。

This will cache the downloads for these packages so you will not need to download them later. Once you have run this command, you do not need to keep the get-dependencies folder. If you have run this command, you can use the --offline flag with all cargo commands in the rest of the book to use these cached versions instead of attempting to use the network.

Hello, World!

你好，世界！

Hello, World!

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

Now that you’ve installed Rust, it’s time to write your first Rust program. It’s traditional when learning a new language to write a little program that prints the text Hello, world! to the screen, so we’ll do the same here!

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

Note: This book assumes basic familiarity with the command line. Rust makes no specific demands about your editing or tooling or where your code lives, so if you prefer to use an IDE instead of the command line, feel free to use your favorite IDE. Many IDEs now have some degree of Rust support; check the IDE’s documentation for details. The Rust team has been focusing on enabling great IDE support via rust-analyzer. See Appendix D for more details.

项目目录设置

Project Directory Setup

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

You’ll start by making a directory to store your Rust code. It doesn’t matter to Rust where your code lives, but for the exercises and projects in this book, we suggest making a projects directory in your home directory and keeping all your projects there.

打开终端并输入以下命令，在 projects 目录内创建一个 projects 目录和一个用于“Hello, world!”项目的目录。

Open a terminal and enter the following commands to make a projects directory and a directory for the “Hello, world!” project within the projects directory.

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

For Linux, macOS, and PowerShell on Windows, enter this:

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

对于 Windows CMD，请输入：

For Windows CMD, enter this:

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

Rust 程序基础

Rust Program Basics

接下来，创建一个新的源文件并将其命名为 main.rs。Rust 文件总是以 .rs 扩展名结尾。如果在文件名中使用了多个单词，惯例是使用下划线来分隔它们。例如，使用 hello_world.rs 而不是 helloworld.rs。

Next, make a new source file and call it main.rs. Rust files always end with the .rs extension. If you’re using more than one word in your filename, the convention is to use an underscore to separate them. For example, use hello_world.rs rather than helloworld.rs.

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

Now open the main.rs file you just created and enter the code in Listing 1-1.

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

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

Save the file and go back to your terminal window in the ~/projects/hello_world directory. On Linux or macOS, enter the following commands to compile and run the file:

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

在 Windows 上，输入命令 .\main 而不是 ./main：

On Windows, enter the command .\main instead of ./main:

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

无论你的操作系统是什么，字符串 Hello, world! 都应该打印到终端。如果你没有看到这个输出，请回顾安装章节的 “故障排除” 部分以寻求帮助。

Regardless of your operating system, the string Hello, world! should print to the terminal. If you don’t see this output, refer back to the “Troubleshooting” part of the Installation section for ways to get help.

如果 Hello, world! 成功打印了，恭喜你！你正式编写了一个 Rust 程序。这让你成为了一名 Rust 程序员——欢迎加入！

If Hello, world! did print, congratulations! You’ve officially written a Rust program. That makes you a Rust programmer—welcome!

Rust 程序的解剖

The Anatomy of a Rust Program

让我们详细回顾一下这个 “Hello, world!” 程序。这是拼图的第一块：

Let’s review this “Hello, world!” program in detail. Here’s the first piece of the puzzle:

fn main() {

}

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

These lines define a function named main. The main function is special: It is always the first code that runs in every executable Rust program. Here, the first line declares a function named main that has no parameters and returns nothing. If there were parameters, they would go inside the parentheses (()).

函数体被包裹在 {} 中。Rust 要求所有函数体都要使用花括号。将左花括号与函数声明放在同一行，并在中间添加一个空格，这是一种良好的风格。

The function body is wrapped in {}. Rust requires curly brackets around all function bodies. It’s good style to place the opening curly bracket on the same line as the function declaration, adding one space in between.

注意：如果你想在所有 Rust 项目中坚持标准风格，可以使用名为 rustfmt 的自动格式化工具将代码格式化为特定风格（更多关于 rustfmt 的信息请参阅 附录 D）。Rust 团队已经在标准的 Rust 发行版中包含了这个工具，就像 rustc 一样，所以它应该已经安装在你的电脑上了！

Note: If you want to stick to a standard style across Rust projects, you can use an automatic formatter tool called rustfmt to format your code in a particular style (more on rustfmt in Appendix D). The Rust team has included this tool with the standard Rust distribution, as rustc is, so it should already be installed on your computer!

main 函数的函数体包含以下代码：

The body of the main function holds the following code:

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

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

This line does all the work in this little program: It prints text to the screen. There are three important details to notice here.

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

First, println! calls a Rust macro. If it had called a function instead, it would be entered as println (without the !). Rust macros are a way to write code that generates code to extend Rust syntax, and we’ll discuss them in more detail in Chapter 20. For now, you just need to know that using a ! means that you’re calling a macro instead of a normal function and that macros don’t always follow the same rules as functions.

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

Second, you see the "Hello, world!" string. We pass this string as an argument to println!, and the string is printed to the screen.

第三，我们以分号 (;) 结束该行，这表示该表达式已结束，下一个表达式已准备好开始。大多数 Rust 代码行都以分号结尾。

Third, we end the line with a semicolon (;), which indicates that this expression is over, and the next one is ready to begin. Most lines of Rust code end with a semicolon.

编译与执行

Compilation and Execution

你刚刚运行了一个新创建的程序，所以让我们检查一下该过程中的每个步骤。

You’ve just run a newly created program, so let’s examine each step in the process.

在运行 Rust 程序之前，你必须使用 Rust 编译器对其进行编译，方法是输入 rustc 命令并向其传递源文件的名称，如下所示：

Before running a Rust program, you must compile it using the Rust compiler by entering the rustc command and passing it the name of your source file, like this:

$ rustc main.rs

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

If you have a C or C++ background, you’ll notice that this is similar to gcc or clang. After compiling successfully, Rust outputs a binary executable.

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

On Linux, macOS, and PowerShell on Windows, you can see the executable by entering the ls command in your shell:

$ ls
main  main.rs

在 Linux 和 macOS 上，你会看到两个文件。在 Windows 的 PowerShell 上，你会看到与使用 CMD 时相同的三个文件。在 Windows 的 CMD 上，你应该输入以下内容：

On Linux and macOS, you’ll see two files. With PowerShell on Windows, you’ll see the same three files that you would see using CMD. With CMD on Windows, you would enter the following:

> dir /B %= /B 选项表示仅显示文件名 =%
main.exe
main.pdb
main.rs

这显示了带有 .rs 扩展名的源代码文件、可执行文件（在 Windows 上为 main.exe，但在所有其他平台上为 main），以及在使用 Windows 时包含调试信息的 .pdb 扩展名文件。从这里，你可以运行 main 或 main.exe 文件，如下所示：

This shows the source code file with the .rs extension, the executable file (main.exe on Windows, but main on all other platforms), and, when using Windows, a file containing debugging information with the .pdb extension. From here, you run the main or main.exe file, like this:

$ ./main # 或者在 Windows 上使用 .\main

如果你的 main.rs 是你的 “Hello, world!” 程序，这一行将在你的终端打印出 Hello, world!。

If your main.rs is your “Hello, world!” program, this line prints Hello, world! to your terminal.

如果你更熟悉 Ruby、Python 或 JavaScript 等动态语言，你可能不习惯将编译和运行程序作为单独的步骤。Rust 是一种“预编译”（ahead-of-time compiled）语言，这意味着你可以编译一个程序并将可执行文件交给别人，即使他们没有安装 Rust 也可以运行它。如果你给别人一个 .rb、.py 或 .js 文件，他们需要分别安装 Ruby、Python 或 JavaScript 的实现。但在那些语言中，你只需要一个命令即可编译并运行程序。语言设计中的一切都是权衡。

If you’re more familiar with a dynamic language, such as Ruby, Python, or JavaScript, you might not be used to compiling and running a program as separate steps. Rust is an ahead-of-time compiled language, meaning you can compile a program and give the executable to someone else, and they can run it even without having Rust installed. If you give someone a .rb, .py, or .js file, they need to have a Ruby, Python, or JavaScript implementation installed (respectively). But in those languages, you only need one command to compile and run your program. Everything is a trade-off in language design.

对于简单的程序，仅使用 rustc 进行编译就可以了，但随着项目的增长，你将希望管理所有选项并使共享代码变得容易。接下来，我们将向你介绍 Cargo 工具，它将帮助你编写实际应用中的 Rust 程序。

Just compiling with rustc is fine for simple programs, but as your project grows, you’ll want to manage all the options and make it easy to share your code. Next, we’ll introduce you to the Cargo tool, which will help you write real-world Rust programs.

Hello, Cargo!

你好，Cargo！

Hello, Cargo!

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

Cargo is Rust’s build system and package manager. Most Rustaceans use this tool to manage their Rust projects because Cargo handles a lot of tasks for you, such as building your code, downloading the libraries your code depends on, and building those libraries. (We call the libraries that your code needs dependencies.)

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

The simplest Rust programs, like the one we’ve written so far, don’t have any dependencies. If we had built the “Hello, world!” project with Cargo, it would only use the part of Cargo that handles building your code. As you write more complex Rust programs, you’ll add dependencies, and if you start a project using Cargo, adding dependencies will be much easier to do.

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

Because the vast majority of Rust projects use Cargo, the rest of this book assumes that you’re using Cargo too. Cargo comes installed with Rust if you used the official installers discussed in the “Installation” section. If you installed Rust through some other means, check whether Cargo is installed by entering the following in your terminal:

$ cargo --version

如果你看到版本号，说明你已经安装了它！如果你看到错误，例如 command not found，请查看你的安装方法的文档，以确定如何单独安装 Cargo。

If you see a version number, you have it! If you see an error, such as command not found, look at the documentation for your method of installation to determine how to install Cargo separately.

使用 Cargo 创建项目

Creating a Project with Cargo

让我们使用 Cargo 创建一个新项目，看看它与我们最初的 “Hello, world!” 项目有何不同。导航回到你的 projects 目录（或者你决定存储代码的任何地方）。然后，在任何操作系统上运行以下命令：

Let’s create a new project using Cargo and look at how it differs from our original “Hello, world!” project. Navigate back to your projects directory (or wherever you decided to store your code). Then, on any operating system, run the following:

$ cargo new hello_cargo
$ cd hello_cargo

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

The first command creates a new directory and project called hello_cargo. We’ve named our project hello_cargo, and Cargo creates its files in a directory of the same name.

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

Go into the hello_cargo directory and list the files. You’ll see that Cargo has generated two files and one directory for us: a Cargo.toml file and a src directory with a main.rs file inside.

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

It has also initialized a new Git repository along with a .gitignore file. Git files won’t be generated if you run cargo new within an existing Git repository; you can override this behavior by using cargo new --vcs=git.

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

Note: Git is a common version control system. You can change cargo new to use a different version control system or no version control system by using the --vcs flag. Run cargo new --help to see the available options.

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

Open Cargo.toml in your text editor of choice. It should look similar to the code in Listing 1-2.

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

[dependencies]

此文件采用 TOML (Tom’s Obvious, Minimal Language，Tom 的显而易见的、极简的语言) 格式，这是 Cargo 的配置格式。

This file is in the TOML (Tom’s Obvious, Minimal Language) format, which is Cargo’s configuration format.

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

The first line, [package], is a section heading that indicates that the following statements are configuring a package. As we add more information to this file, we’ll add other sections.

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

The next three lines set the configuration information Cargo needs to compile your program: the name, the version, and the edition of Rust to use. We’ll talk about the edition key in Appendix E.

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

The last line, [dependencies], is the start of a section for you to list any of your project’s dependencies. In Rust, packages of code are referred to as crates. We won’t need any other crates for this project, but we will in the first project in Chapter 2, so we’ll use this dependencies section then.

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

Now open src/main.rs and take a look:

文件名：src/main.rs Filename: src/main.rs

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

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

Cargo has generated a “Hello, world!” program for you, just like the one we wrote in Listing 1-1! So far, the differences between our project and the project Cargo generated are that Cargo placed the code in the src directory, and we have a Cargo.toml configuration file in the top directory.

Cargo 期望你的源文件位于 src 目录内。顶级项目目录仅用于存放 README 文件、许可信息、配置文件以及与代码无关的其他任何内容。使用 Cargo 有助于你组织项目。每件东西都有它的位置，并且每件东西都在它的位置上。

Cargo expects your source files to live inside the src directory. The top-level project directory is just for README files, license information, configuration files, and anything else not related to your code. Using Cargo helps you organize your projects. There’s a place for everything, and everything is in its place.

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

If you started a project that doesn’t use Cargo, as we did with the “Hello, world!” project, you can convert it to a project that does use Cargo. Move the project code into the src directory and create an appropriate Cargo.toml file. One easy way to get that Cargo.toml file is to run cargo init, which will create it for you automatically.

构建并运行 Cargo 项目

Building and Running a Cargo Project

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

Now let’s look at what’s different when we build and run the “Hello, world!” program with Cargo! From your hello_cargo directory, build your project by entering the following command:

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

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

This command creates an executable file in target/debug/hello_cargo (or target\debug\hello_cargo.exe on Windows) rather than in your current directory. Because the default build is a debug build, Cargo puts the binary in a directory named debug. You can run the executable with this command:

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

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

If all goes well, Hello, world! should print to the terminal. Running cargo build for the first time also causes Cargo to create a new file at the top level: Cargo.lock. This file keeps track of the exact versions of dependencies in your project. This project doesn’t have dependencies, so the file is a bit sparse. You won’t ever need to change this file manually; Cargo manages its contents for you.

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

We just built a project with cargo build and ran it with ./target/debug/hello_cargo, but we can also use cargo run to compile the code and then run the resultant executable all in one command:

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

使用 cargo run 比记住运行 cargo build 然后使用二进制文件的完整路径更方便，因此大多数开发者使用 cargo run。

Using cargo run is more convenient than having to remember to run cargo build and then use the whole path to the binary, so most developers use cargo run.

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

Notice that this time we didn’t see output indicating that Cargo was compiling hello_cargo. Cargo figured out that the files hadn’t changed, so it didn’t rebuild but just ran the binary. If you had modified your source code, Cargo would have rebuilt the project before running it, and you would have seen this output:

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

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

Cargo also provides a command called cargo check. This command quickly checks your code to make sure it compiles but doesn’t produce an executable:

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

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

Why would you not want an executable? Often, cargo check is much faster than cargo build because it skips the step of producing an executable. If you’re continually checking your work while writing the code, using cargo check will speed up the process of letting you know if your project is still compiling! As such, many Rustaceans run cargo check periodically as they write their program to make sure it compiles. Then, they run cargo build when they’re ready to use the executable.

让我们回顾一下到目前为止我们学到的关于 Cargo 的知识：

Let’s recap what we’ve learned so far about Cargo:

• 我们可以使用 cargo new 创建一个项目。

• 我们可以使用 cargo build 构建一个项目。

• 我们可以使用 cargo run 在一个步骤中构建并运行项目。

• 我们可以使用 cargo check 在不产生二进制文件的情况下构建项目以检查错误。

• Cargo 不会将构建结果保存在与代码相同的目录中，而是将其存储在 target/debug 目录中。

• We can create a project using cargo new.

• We can build a project using cargo build.

• We can build and run a project in one step using cargo run.

• We can build a project without producing a binary to check for errors using cargo check.

• Instead of saving the result of the build in the same directory as our code, Cargo stores it in the target/debug directory.

使用 Cargo 的另一个优点是，无论你使用的是哪种操作系统，命令都是相同的。因此，从现在起，我们不再为 Linux 和 macOS 还是 Windows 提供特定说明。

An additional advantage of using Cargo is that the commands are the same no matter which operating system you’re working on. So, at this point, we’ll no longer provide specific instructions for Linux and macOS versus Windows.

发布构建

Building for Release

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

When your project is finally ready for release, you can use cargo build --release to compile it with optimizations. This command will create an executable in target/release instead of target/debug. The optimizations make your Rust code run faster, but turning them on lengthens the time it takes for your program to compile. This is why there are two different profiles: one for development, when you want to rebuild quickly and often, and another for building the final program you’ll give to a user that won’t be rebuilt repeatedly and that will run as fast as possible. If you’re benchmarking your code’s running time, be sure to run cargo build --release and benchmark with the executable in target/release.

利用 Cargo 的约定

Leveraging Cargo’s Conventions

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

With simple projects, Cargo doesn’t provide a lot of value over just using rustc, but it will prove its worth as your programs become more intricate. Once programs grow to multiple files or need a dependency, it’s much easier to let Cargo coordinate the build.

即使 hello_cargo 项目很简单，它现在也使用了你在 Rust 职业生涯的剩余时间里将使用的许多真实工具。事实上，要在任何现有项目上工作，你可以使用以下命令通过 Git 检出代码，进入该项目目录并构建：

Even though the hello_cargo project is simple, it now uses much of the real tooling you’ll use in the rest of your Rust career. In fact, to work on any existing projects, you can use the following commands to check out the code using Git, change to that project’s directory, and build:

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

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

For more information about Cargo, check out its documentation.

总结

Summary

你的 Rust 之旅已经有了一个很好的开始！在本章中，你学习了如何：

You’re already off to a great start on your Rust journey! In this chapter, you learned how to:

• 使用 rustup 安装最新的 Rust 稳定版本。

• 更新到较新的 Rust 版本。

• 打开本地安装的文档。

• 直接使用 rustc 编写并运行 “Hello, world!” 程序。

• 使用 Cargo 的约定创建并运行一个新项目。

• Install the latest stable version of Rust using rustup.

• Update to a newer Rust version.

• Open locally installed documentation.

• Write and run a “Hello, world!” program using rustc directly.

• Create and run a new project using the conventions of Cargo.

现在是构建一个更充实的程序以适应阅读和编写 Rust 代码的好时机。因此，在第 2 章中，我们将构建一个猜数字游戏程序。如果你更愿意先学习常见的编程概念在 Rust 中是如何工作的，请参阅第 3 章，然后再返回第 2 章。

This is a great time to build a more substantial program to get used to reading and writing Rust code. So, in Chapter 2, we’ll build a guessing game program. If you would rather start by learning how common programming concepts work in Rust, see Chapter 3 and then return to Chapter 2.

编写猜数字游戏

Programming a Guessing Game

让我们通过一起完成一个实战项目来深入了解 Rust！本章将通过展示如何在真实程序中使用一些常见的 Rust 概念来向你介绍它们。你将学习到 let、match、方法、关联函数、外部 crate 等等！在接下来的章节中，我们将更详细地探讨这些想法。在本章中，你只需练习基础知识。

Let’s jump into Rust by working through a hands-on project together! This chapter introduces you to a few common Rust concepts by showing you how to use them in a real program. You’ll learn about let, match, methods, associated functions, external crates, and more! In the following chapters, we’ll explore these ideas in more detail. In this chapter, you’ll just practice the fundamentals.

我们将实现一个经典的编程入门问题：猜数字游戏。它的工作原理如下：程序将生成一个 1 到 100 之间的随机整数。然后它会提示玩家输入一个猜测。在输入猜测后，程序将指示该猜测是太低还是太高。如果猜测正确，游戏将打印一条祝贺消息并退出。

We’ll implement a classic beginner programming problem: a guessing game. Here’s how it works: The program will generate a random integer between 1 and 100. It will then prompt the player to enter a guess. After a guess is entered, the program will indicate whether the guess is too low or too high. If the guess is correct, the game will print a congratulatory message and exit.

设置新项目

Setting Up a New Project

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

To set up a new project, go to the projects directory that you created in Chapter 1 and make a new project using Cargo, like so:

$ cargo new guessing_game
$ cd guessing_game

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

The first command, cargo new, takes the name of the project (guessing_game) as the first argument. The second command changes to the new project’s directory.

查看生成的 Cargo.toml 文件：

Look at the generated Cargo.toml file:

文件名：Cargo.toml Filename: Cargo.toml

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

[dependencies]

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

As you saw in Chapter 1, cargo new generates a “Hello, world!” program for you. Check out the src/main.rs file:

文件名：src/main.rs Filename: src/main.rs

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

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

Now let’s compile this “Hello, world!” program and run it in the same step using the cargo run command:

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

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

The run command comes in handy when you need to rapidly iterate on a project, as we’ll do in this game, quickly testing each iteration before moving on to the next one.

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

Reopen the src/main.rs file. You’ll be writing all the code in this file.

处理猜测

Processing a Guess

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

The first part of the guessing game program will ask for user input, process that input, and check that the input is in the expected form. To start, we’ll allow the player to input a guess. Enter the code in Listing 2-1 into src/main.rs.

use std::io;

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

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

    let mut guess = String::new();

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

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

这段代码包含很多信息，所以让我们逐行过一遍。为了获取用户输入并将其作为输出打印，我们需要将 io 输入/输出库引入作用域。io 库来自标准库，即 std：

This code contains a lot of information, so let’s go over it line by line. To obtain user input and then print the result as output, we need to bring the io input/output library into scope. The io library comes from the standard library, known as std:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

By default, Rust has a set of items defined in the standard library that it brings into the scope of every program. This set is called the prelude, and you can see everything in it in the standard library documentation.

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

If a type you want to use isn’t in the prelude, you have to bring that type into scope explicitly with a use statement. Using the std::io library provides you with a number of useful features, including the ability to accept user input.

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

As you saw in Chapter 1, the main function is the entry point into the program:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

The fn syntax declares a new function; the parentheses, (), indicate there are no parameters; and the curly bracket, {, starts the body of the function.

正如你在第 1 章中学到的，println! 是一个将字符串打印到屏幕上的宏：

As you also learned in Chapter 1, println! is a macro that prints a string to the screen:

use std::io;

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

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

    let mut guess = String::new();

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

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

这段代码打印了一个提示，说明游戏是什么并请求用户输入。

This code is printing a prompt stating what the game is and requesting input from the user.

使用变量存储值

Storing Values with Variables

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

Next, we’ll create a variable to store the user input, like this:

use std::io;

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

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

    let mut guess = String::new();

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

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

现在程序变得有趣了！这一小行里发生了很多事情。我们使用 let 语句来创建变量。这是另一个例子：

Now the program is getting interesting! There’s a lot going on in this little line. We use the let statement to create the variable. Here’s another example:

let apples = 5;

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

This line creates a new variable named apples and binds it to the value 5. In Rust, variables are immutable by default, meaning once we give the variable a value, the value won’t change. We’ll be discussing this concept in detail in the “Variables and Mutability” section in Chapter 3. To make a variable mutable, we add mut before the variable name:

let apples = 5; // 不可变
let mut bananas = 5; // 可变

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

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

Note: The // syntax starts a comment that continues until the end of the line. Rust ignores everything in comments. We’ll discuss comments in more detail in Chapter 3.

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

Returning to the guessing game program, you now know that let mut guess will introduce a mutable variable named guess. The equal sign (=) tells Rust we want to bind something to the variable now. On the right of the equal sign is the value that guess is bound to, which is the result of calling String::new, a function that returns a new instance of a String. String is a string type provided by the standard library that is a growable, UTF-8 encoded bit of text.

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

The :: syntax in the ::new line indicates that new is an associated function of the String type. An associated function is a function that’s implemented on a type, in this case String. This new function creates a new, empty string. You’ll find a new function on many types because it’s a common name for a function that makes a new value of some kind.

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

In full, the let mut guess = String::new(); line has created a mutable variable that is currently bound to a new, empty instance of a String. Whew!

接收用户输入

Receiving User Input

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

Recall that we included the input/output functionality from the standard library with use std::io; on the first line of the program. Now we’ll call the stdin function from the io module, which will allow us to handle user input:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

If we hadn’t imported the io module with use std::io; at the beginning of the program, we could still use the function by writing this function call as std::io::stdin. The stdin function returns an instance of std::io::Stdin, which is a type that represents a handle to the standard input for your terminal.

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

Next, the line .read_line(&mut guess) calls the read_line method on the standard input handle to get input from the user. We’re also passing &mut guess as the argument to read_line to tell it what string to store the user input in. The full job of read_line is to take whatever the user types into standard input and append that into a string (without overwriting its contents), so we therefore pass that string as an argument. The string argument needs to be mutable so that the method can change the string’s content.

& 表示该参数是一个 引用 (reference)，它为你提供了一种方法，让代码的多个部分访问同一份数据，而无需在内存中多次复制该数据。引用是一个复杂的功能，而 Rust 的主要优势之一就是使用引用的安全性和简便性。你不需要了解很多细节就能完成这个程序。目前，你只需要知道，与变量一样，引用默认也是不可变的。因此，你需要写成 &mut guess 而不是 &guess 来使其可变。（第 4 章将更全面地解释引用。）

The & indicates that this argument is a reference, which gives you a way to let multiple parts of your code access one piece of data without needing to copy that data into memory multiple times. References are a complex feature, and one of Rust’s major advantages is how safe and easy it is to use references. You don’t need to know a lot of those details to finish this program. For now, all you need to know is that, like variables, references are immutable by default. Hence, you need to write &mut guess rather than &guess to make it mutable. (Chapter 4 will explain references more thoroughly.)

使用 Result 处理潜在错误

Handling Potential Failure with Result

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

We’re still working on this line of code. We’re now discussing a third line of text, but note that it’s still part of a single logical line of code. The next part is this method:

use std::io;

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

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

    let mut guess = String::new();

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

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

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

We could have written this code as:

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

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

However, one long line is difficult to read, so it’s best to divide it. It’s often wise to introduce a newline and other whitespace to help break up long lines when you call a method with the .method_name() syntax. Now let’s discuss what this line does.

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

As mentioned earlier, read_line puts whatever the user enters into the string we pass to it, but it also returns a Result value. Result is an enumeration, often called an enum, which is a type that can be in one of multiple possible states. We call each possible state a variant.

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

Chapter 6 will cover enums in more detail. The purpose of these Result types is to encode error-handling information.

Result 的变体是 Ok 和 Err。Ok 变体表示操作成功，它包含成功生成的值。Err 变体表示操作失败，它包含有关操作如何失败或为何失败的信息。

Result’s variants are Ok and Err. The Ok variant indicates the operation was successful, and it contains the successfully generated value. The Err variant means the operation failed, and it contains information about how or why the operation failed.

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

Values of the Result type, like values of any type, have methods defined on them. An instance of Result has an expect method that you can call. If this instance of Result is an Err value, expect will cause the program to crash and display the message that you passed as an argument to expect. If the read_line method returns an Err, it would likely be the result of an error coming from the underlying operating system. If this instance of Result is an Ok value, expect will take the return value that Ok is holding and return just that value to you so that you can use it. In this case, that value is the number of bytes in the user’s input.

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

If you don’t call expect, the program will compile, but you’ll get a warning:

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

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

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

Rust warns that you haven’t used the Result value returned from read_line, indicating that the program hasn’t handled a possible error.

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

The right way to suppress the warning is to actually write error-handling code, but in our case we just want to crash this program when a problem occurs, so we can use expect. You’ll learn about recovering from errors in Chapter 9.

使用 println! 占位符打印值

Printing Values with println! Placeholders

除了结束花括号，到目前为止代码中只有一行需要讨论：

Aside from the closing curly bracket, there’s only one more line to discuss in the code so far:

use std::io;

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

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

    let mut guess = String::new();

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

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

这行打印现在包含用户输入的字符串。{} 这对花括号是一个占位符：把 {} 想象成固定值的小螃蟹钳。打印变量的值时，变量名可以放在花括号内。打印表达式求值的结果时，在格式字符串中放置空花括号，然后在格式字符串后面跟随一个逗号分隔的表达式列表，按相同顺序打印在每个空花括号占位符中。在一次 println! 调用中打印一个变量和一个表达式的结果看起来像这样：

This line prints the string that now contains the user’s input. The {} set of curly brackets is a placeholder: Think of {} as little crab pincers that hold a value in place. When printing the value of a variable, the variable name can go inside the curly brackets. When printing the result of evaluating an expression, place empty curly brackets in the format string, then follow the format string with a comma-separated list of expressions to print in each empty curly bracket placeholder in the same order. Printing a variable and the result of an expression in one call to println! would look like this:

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

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

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

This code would print x = 5 and y + 2 = 12.

测试第一部分

Testing the First Part

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

Let’s test the first part of the guessing game. Run it using cargo run:

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

至此，游戏的第一部分已经完成：我们正在从键盘获取输入并将其打印出来。

At this point, the first part of the game is done: We’re getting input from the keyboard and then printing it.

生成一个秘密数字

Generating a Secret Number

接下来，我们需要生成一个用户将尝试猜测的秘密数字。秘密数字每次都应该不同，这样游戏玩多次才有意思。我们将使用 1 到 100 之间的随机数，这样游戏就不会太难。Rust 的标准库中尚未包含随机数功能。然而，Rust 团队确实提供了一个具有上述功能的 rand crate。

Next, we need to generate a secret number that the user will try to guess. The secret number should be different every time so that the game is fun to play more than once. We’ll use a random number between 1 and 100 so that the game isn’t too difficult. Rust doesn’t yet include random number functionality in its standard library. However, the Rust team does provide a rand crate with said functionality.

使用 Crate 增加功能

Increasing Functionality with a Crate

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

Remember that a crate is a collection of Rust source code files. The project we’ve been building is a binary crate, which is an executable. The rand crate is a library crate, which contains code that is intended to be used in other programs and can’t be executed on its own.

Cargo 对外部 crate 的协调正是 Cargo 的闪光点所在。在我们编写使用 rand 的代码之前，我们需要修改 Cargo.toml 文件，将 rand crate 包含为依赖项。现在打开该文件，并在 Cargo 为你创建的 [dependencies] 部分标题下方添加以下行。请务必按照此处的版本号准确指定 rand，否则本教程中的代码示例可能无法工作：

Cargo’s coordination of external crates is where Cargo really shines. Before we can write code that uses rand, we need to modify the Cargo.toml file to include the rand crate as a dependency. Open that file now and add the following line to the bottom, beneath the [dependencies] section header that Cargo created for you. Be sure to specify rand exactly as we have here, with this version number, or the code examples in this tutorial may not work:

文件名：Cargo.toml Filename: Cargo.toml

[dependencies]
rand = "0.8.5"

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

In the Cargo.toml file, everything that follows a header is part of that section that continues until another section starts. In [dependencies], you tell Cargo which external crates your project depends on and which versions of those crates you require. In this case, we specify the rand crate with the semantic version specifier 0.8.5. Cargo understands Semantic Versioning (sometimes called SemVer), which is a standard for writing version numbers. The specifier 0.8.5 is actually shorthand for ^0.8.5, which means any version that is at least 0.8.5 but below 0.9.0.

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

Cargo considers these versions to have public APIs compatible with version 0.8.5, and this specification ensures that you’ll get the latest patch release that will still compile with the code in this chapter. Any version 0.9.0 or greater is not guaranteed to have the same API as what the following examples use.

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

Now, without changing any of the code, let’s build the project, as shown in Listing 2-2.

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

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

You may see different version numbers (but they will all be compatible with the code, thanks to SemVer!) and different lines (depending on the operating system), and the lines may be in a different order.

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

When we include an external dependency, Cargo fetches the latest versions of everything that dependency needs from the registry, which is a copy of data from Crates.io. Crates.io is where people in the Rust ecosystem post their open source Rust projects for others to use.

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

After updating the registry, Cargo checks the [dependencies] section and downloads any crates listed that aren’t already downloaded. In this case, although we only listed rand as a dependency, Cargo also grabbed other crates that rand depends on to work. After downloading the crates, Rust compiles them and then compiles the project with the dependencies available.

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

If you immediately run cargo build again without making any changes, you won’t get any output aside from the Finished line. Cargo knows it has already downloaded and compiled the dependencies, and you haven’t changed anything about them in your Cargo.toml file. Cargo also knows that you haven’t changed anything about your code, so it doesn’t recompile that either. With nothing to do, it simply exits.

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

If you open the src/main.rs file, make a trivial change, and then save it and build again, you’ll only see two lines of output:

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

这些行显示 Cargo 只根据你对 src/main.rs 文件的微小改动来更新构建。你的依赖项没有改变，所以 Cargo 知道它可以重用已经为它们下载并编译好的内容。

These lines show that Cargo only updates the build with your tiny change to the src/main.rs file. Your dependencies haven’t changed, so Cargo knows it can reuse what it has already downloaded and compiled for those.

确保可重现的构建

Ensuring Reproducible Builds

Cargo 拥有一种机制，可以确保你或任何其他人在构建代码时，每次都能重新构建出相同的产物：除非你另行指定，否则 Cargo 将仅使用你指定的依赖项版本。例如，假设下周 rand crate 的 0.8.6 版本发布了，该版本包含一个重要的错误修复，但也包含一个会导致你的代码崩溃的回退 (regression)。为了处理这个问题，Rust 在你第一次运行 cargo build 时创建了 Cargo.lock 文件，所以我们现在在 guessing_game 目录中有了这个文件。

Cargo has a mechanism that ensures that you can rebuild the same artifact every time you or anyone else builds your code: Cargo will use only the versions of the dependencies you specified until you indicate otherwise. For example, say that next week version 0.8.6 of the rand crate comes out, and that version contains an important bug fix, but it also contains a regression that will break your code. To handle this, Rust creates the Cargo.lock file the first time you run cargo build, so we now have this in the guessing_game directory.

当你第一次构建项目时，Cargo 会找出符合标准的所有依赖项版本，然后将它们写入 Cargo.lock 文件。将来构建项目时，Cargo 会看到 Cargo.lock 文件已存在，并使用其中指定的版本，而不是再次进行找出版本的所有工作。这让你自动拥有了可重现的构建。换句话说，由于有了 Cargo.lock 文件，你的项目将保持在 0.8.5，直到你显式升级。由于 Cargo.lock 文件对于可重现的构建很重要，因此它通常会与项目中的其余代码一起检入源控制系统。

When you build a project for the first time, Cargo figures out all the versions of the dependencies that fit the criteria and then writes them to the Cargo.lock file. When you build your project in the future, Cargo will see that the Cargo.lock file exists and will use the versions specified there rather than doing all the work of figuring out versions again. This lets you have a reproducible build automatically. In other words, your project will remain at 0.8.5 until you explicitly upgrade, thanks to the Cargo.lock file. Because the Cargo.lock file is important for reproducible builds, it’s often checked into source control with the rest of the code in your project.

更新 Crate 以获取新版本

Updating a Crate to Get a New Version

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

When you do want to update a crate, Cargo provides the command update, which will ignore the Cargo.lock file and figure out all the latest versions that fit your specifications in Cargo.toml. Cargo will then write those versions to the Cargo.lock file. Otherwise, by default, Cargo will only look for versions greater than 0.8.5 and less than 0.9.0. If the rand crate has released the two new versions 0.8.6 and 0.999.0, you would see the following if you ran cargo update:

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

Cargo 忽略了 0.999.0 的发布。此时，你还会注意到 Cargo.lock 文件发生了变化，注明你现在使用的 rand crate 版本是 0.8.6。要使用 rand 版本 0.999.0 或 0.999.x 系列中的任何版本，你必须像这样更新 Cargo.toml 文件（实际上不要做这个修改，因为接下来的示例假设你使用的是 rand 0.8）：

Cargo ignores the 0.999.0 release. At this point, you would also notice a change in your Cargo.lock file noting that the version of the rand crate you are now using is 0.8.6. To use rand version 0.999.0 or any version in the 0.999.x series, you’d have to update the Cargo.toml file to look like this instead (don’t actually make this change because the following examples assume you’re using rand 0.8):

[dependencies]
rand = "0.999.0"

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

The next time you run cargo build, Cargo will update the registry of crates available and reevaluate your rand requirements according to the new version you have specified.

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

There’s a lot more to say about Cargo and its ecosystem, which we’ll discuss in Chapter 14, but for now, that’s all you need to know. Cargo makes it very easy to reuse libraries, so Rustaceans are able to write smaller projects that are assembled from a number of packages.

生成随机数

Generating a Random Number

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

Let’s start using rand to generate a number to guess. The next step is to update src/main.rs, as shown in Listing 2-3.

use std::io;

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

首先，我们添加 use rand::Rng; 这行。Rng trait 定义了随机数生成器实现的方法，为了使用这些方法，该 trait 必须在作用域内。第 10 章将详细介绍 trait。

First, we add the line use rand::Rng;. The Rng trait defines methods that random number generators implement, and this trait must be in scope for us to use those methods. Chapter 10 will cover traits in detail.

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

Next, we’re adding two lines in the middle. In the first line, we call the rand::thread_rng function that gives us the particular random number generator we’re going to use: one that is local to the current thread of execution and is seeded by the operating system. Then, we call the gen_range method on the random number generator. This method is defined by the Rng trait that we brought into scope with the use rand::Rng; statement. The gen_range method takes a range expression as an argument and generates a random number in the range. The kind of range expression we’re using here takes the form start..=end and is inclusive on the lower and upper bounds, so we need to specify 1..=100 to request a number between 1 and 100.

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

Note: You won’t just know which traits to use and which methods and functions to call from a crate, so each crate has documentation with instructions for using it. Another neat feature of Cargo is that running the cargo doc --open command will build documentation provided by all your dependencies locally and open it in your browser. If you’re interested in other functionality in the rand crate, for example, run cargo doc --open and click rand in the sidebar on the left.

第二个新行打印秘密数字。这在开发程序时对测试很有用，但我们会在最终版本中将其删除。如果程序一开始就打印出答案，那就没什么游戏性了！

The second new line prints the secret number. This is useful while we’re developing the program to be able to test it, but we’ll delete it from the final version. It’s not much of a game if the program prints the answer as soon as it starts!

试着多运行几次程序：

Try running the program a few times:

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

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

你应该会得到不同的随机数，且它们都应该是 1 到 100 之间的数字。做得好！

You should get different random numbers, and they should all be numbers between 1 and 100. Great job!

比较猜测与秘密数字

Comparing the Guess to the Secret Number

现在我们有了用户输入和一个随机数，我们可以比较它们了。这一步如示例 2-4 所示。请注意，正如我们将要解释的那样，这段代码暂时还不能编译。

Now that we have user input and a random number, we can compare them. That step is shown in Listing 2-4. Note that this code won’t compile just yet, as we will explain.

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

use rand::Rng;

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

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

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

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

    let mut guess = String::new();

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

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

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

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

First, we add another use statement, bringing a type called std::cmp::Ordering into scope from the standard library. The Ordering type is another enum and has the variants Less, Greater, and Equal. These are the three outcomes that are possible when you compare two values.

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

Then, we add five new lines at the bottom that use the Ordering type. The cmp method compares two values and can be called on anything that can be compared. It takes a reference to whatever you want to compare with: Here, it’s comparing guess to secret_number. Then, it returns a variant of the Ordering enum we brought into scope with the use statement. We use a match expression to decide what to do next based on which variant of Ordering was returned from the call to cmp with the values in guess and secret_number.

match 表达式由 arms (分支) 组成。一个 arm 由一个与之匹配的 pattern (模式) 以及如果给定的值符合该 arm 的模式则应运行的代码组成。Rust 获取给定的 match 值，并依次查看每个 arm 的模式。模式和 match 结构是 Rust 强大的功能：它们让你表达代码可能遇到的各种情况，并确保你处理了所有这些情况。这些功能将分别在第 6 章和第 19 章中详细讨论。

A match expression is made up of arms. An arm consists of a pattern to match against, and the code that should be run if the value given to match fits that arm’s pattern. Rust takes the value given to match and looks through each arm’s pattern in turn. Patterns and the match construct are powerful Rust features: They let you express a variety of situations your code might encounter, and they make sure you handle them all. These features will be covered in detail in Chapter 6 and Chapter 19, respectively.

让我们用在这里使用的 match 表达式走一个例子。假设用户猜了 50，而这次随机生成的秘密数字是 38。

Let’s walk through an example with the match expression we use here. Say that the user has guessed 50 and the randomly generated secret number this time is 38.

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

When the code compares 50 to 38, the cmp method will return Ordering::Greater because 50 is greater than 38. The match expression gets the Ordering::Greater value and starts checking each arm’s pattern. It looks at the first arm’s pattern, Ordering::Less, and sees that the value Ordering::Greater does not match Ordering::Less, so it ignores the code in that arm and moves to the next arm. The next arm’s pattern is Ordering::Greater, which does match Ordering::Greater! The associated code in that arm will execute and print Too big! to the screen. The match expression ends after the first successful match, so it won’t look at the last arm in this scenario.

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

However, the code in Listing 2-4 won’t compile yet. Let’s try it:

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

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

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

The core of the error states that there are mismatched types. Rust has a strong, static type system. However, it also has type inference. When we wrote let mut guess = String::new(), Rust was able to infer that guess should be a String and didn’t make us write the type. The secret_number, on the other hand, is a number type. A few of Rust’s number types can have a value between 1 and 100: i32, a 32-bit number; u32, an unsigned 32-bit number; i64, a 64-bit number; as well as others. Unless otherwise specified, Rust defaults to an i32, which is the type of secret_number unless you add type information elsewhere that would cause Rust to infer a different numerical type. The reason for the error is that Rust cannot compare a string and a number type.

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

Ultimately, we want to convert the String the program reads as input into a number type so that we can compare it numerically to the secret number. We do so by adding this line to the main function body:

文件名：src/main.rs Filename: src/main.rs

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

use rand::Rng;

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

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

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

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

    // --snip--

    let mut guess = String::new();

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

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

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

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

这行代码是：

The line is:

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

我们创建了一个名为 guess 的变量。但等等，程序不是已经有一个名为 guess 的变量了吗？确实如此，但好在 Rust 允许我们用一个新值来 遮蔽 (shadow) guess 之前的值。Shadowing 允许我们重用 guess 变量名，而不是强迫我们创建两个唯一的变量，例如 guess_str 和 guess。我们将在 第 3 章 中更详细地讨论这一点，但目前请记住，当你想将一个值从一种类型转换为另一种类型时，通常会使用此功能。

We create a variable named guess. But wait, doesn’t the program already have a variable named guess? It does, but helpfully Rust allows us to shadow the previous value of guess with a new one. Shadowing lets us reuse the guess variable name rather than forcing us to create two unique variables, such as guess_str and guess, for example. We’ll cover this in more detail in Chapter 3, but for now, know that this feature is often used when you want to convert a value from one type to another type.

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

We bind this new variable to the expression guess.trim().parse(). The guess in the expression refers to the original guess variable that contained the input as a string. The trim method on a String instance will eliminate any whitespace at the beginning and end, which we must do before we can convert the string to a u32, which can only contain numerical data. The user must press enter to satisfy read_line and input their guess, which adds a newline character to the string. For example, if the user types 5 and presses enter, guess looks like this: 5\n. The \n represents “newline.” (On Windows, pressing enter results in a carriage return and a newline, \r\n.) The trim method eliminates \n or \r\n, resulting in just 5.

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

The parse method on strings converts a string to another type. Here, we use it to convert from a string to a number. We need to tell Rust the exact number type we want by using let guess: u32. The colon (:) after guess tells Rust we’ll annotate the variable’s type. Rust has a few built-in number types; the u32 seen here is an unsigned, 32-bit integer. It’s a good default choice for a small positive number. You’ll learn about other number types in Chapter 3.

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

Additionally, the u32 annotation in this example program and the comparison with secret_number means Rust will infer that secret_number should be a u32 as well. So, now the comparison will be between two values of the same type!

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

The parse method will only work on characters that can logically be converted into numbers and so can easily cause errors. If, for example, the string contained A👍%, there would be no way to convert that to a number. Because it might fail, the parse method returns a Result type, much as the read_line method does (discussed earlier in “Handling Potential Failure with Result”). We’ll treat this Result the same way by using the expect method again. If parse returns an Err Result variant because it couldn’t create a number from the string, the expect call will crash the game and print the message we give it. If parse can successfully convert the string to a number, it will return the Ok variant of Result, and expect will return the number that we want from the Ok value.

现在运行程序：

Let’s run the program now:

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

不错！即使猜测之前添加了空格，程序仍然算出用户猜的是 76。多次运行程序以验证不同种类输入的各种行为：正确猜中数字、猜一个过高的数字以及猜一个过低的数字。

Nice! Even though spaces were added before the guess, the program still figured out that the user guessed 76. Run the program a few times to verify the different behavior with different kinds of input: Guess the number correctly, guess a number that is too high, and guess a number that is too low.

我们现在已经完成了游戏的大部分工作，但用户只能进行一次猜测。让我们通过添加循环来改变这一点！

We have most of the game working now, but the user can make only one guess. Let’s change that by adding a loop!

使用循环允许多次猜测

Allowing Multiple Guesses with Looping

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

The loop keyword creates an infinite loop. We’ll add a loop to give users more chances at guessing the number:

文件名：src/main.rs Filename: src/main.rs

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

use rand::Rng;

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

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

    // --snip--

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

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

        // --snip--


        let mut guess = String::new();

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

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

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

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

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

As you can see, we’ve moved everything from the guess input prompt onward into a loop. Be sure to indent the lines inside the loop another four spaces each and run the program again. The program will now ask for another guess forever, which actually introduces a new problem. It doesn’t seem like the user can quit!

用户始终可以使用键盘快捷键 ctrl-C 来中断程序。但正如 “比较猜测与秘密数字” 中关于 parse 的讨论提到的，还有另一种方法可以逃离这个贪婪的怪物：如果用户输入非数字答案，程序将崩溃。我们可以利用这一点来允许用户退出，如下所示：

The user could always interrupt the program by using the keyboard shortcut ctrl-C. But there’s another way to escape this insatiable monster, as mentioned in the parse discussion in “Comparing the Guess to the Secret Number”: If the user enters a non-number answer, the program will crash. We can take advantage of that to allow the user to quit, as shown here:

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

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

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

Typing quit will quit the game, but as you’ll notice, so will entering any other non-number input. This is suboptimal, to say the least; we want the game to also stop when the correct number is guessed.

猜对后退出

Quitting After a Correct Guess

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

Let’s program the game to quit when the user wins by adding a break statement:

文件名：src/main.rs Filename: src/main.rs

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

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

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

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

        // --snip--

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

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

Adding the break line after You win! makes the program exit the loop when the user guesses the secret number correctly. Exiting the loop also means exiting the program, because the loop is the last part of main.

处理无效输入

Handling Invalid Input

为了进一步完善游戏的表现，与其在用户输入非数字时使程序崩溃，不如让游戏忽略非数字，以便用户可以继续猜测。我们可以通过修改将 guess 从 String 转换为 u32 的那行代码来实现，如示例 2-5 所示。

To further refine the game’s behavior, rather than crashing the program when the user inputs a non-number, let’s make the game ignore a non-number so that the user can continue guessing. We can do that by altering the line where guess is converted from a String to a u32, as shown in Listing 2-5.

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

use rand::Rng;

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

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

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

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

        let mut guess = String::new();

        // --snip--

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

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

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

        // --snip--

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

我们将 expect 调用切换为 match 表达式，以便从出错时崩溃转变为处理错误。请记住，parse 返回一个 Result 类型，而 Result 是一个包含 Ok 和 Err 变体的枚举。我们在这里使用 match 表达式，就像我们处理 cmp 方法的 Ordering 结果一样。

We switch from an expect call to a match expression to move from crashing on an error to handling the error. Remember that parse returns a Result type and Result is an enum that has the variants Ok and Err. We’re using a match expression here, as we did with the Ordering result of the cmp method.

如果 parse 能够成功地将字符串转换为数字，它将返回一个包含生成数字的 Ok 值。该 Ok 值将匹配第一个 arm 的模式，而 match 表达式将直接返回 parse 产生的并放在 Ok 值内的 num 值。该数字最终会出现在我们正在创建的新 guess 变量中。

If parse is able to successfully turn the string into a number, it will return an Ok value that contains the resultant number. That Ok value will match the first arm’s pattern, and the match expression will just return the num value that parse produced and put inside the Ok value. That number will end up right where we want it in the new guess variable we’re creating.

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

If parse is not able to turn the string into a number, it will return an Err value that contains more information about the error. The Err value does not match the Ok(num) pattern in the first match arm, but it does match the Err(_) pattern in the second arm. The underscore, _, is a catch-all value; in this example, we’re saying we want to match all Err values, no matter what information they have inside them. So, the program will execute the second arm’s code, continue, which tells the program to go to the next iteration of the loop and ask for another guess. So, effectively, the program ignores all errors that parse might encounter!

现在程序中的一切都应该按预期工作了。让我们试试：

Now everything in the program should work as expected. Let’s try it:

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

棒极了！只需最后一个小调整，我们就完成了猜数字游戏。回想一下，程序仍然在打印秘密数字。这对于测试很有效，但它毁了游戏。让我们删除输出秘密数字的 println!。示例 2-6 显示了最终代码。

Awesome! With one tiny final tweak, we will finish the guessing game. Recall that the program is still printing the secret number. That worked well for testing, but it ruins the game. Let’s delete the println! that outputs the secret number. Listing 2-6 shows the final code.

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

use rand::Rng;

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

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

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

        let mut guess = String::new();

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

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

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

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

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

At this point, you’ve successfully built the guessing game. Congratulations!

总结

Summary

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

This project was a hands-on way to introduce you to many new Rust concepts: let, match, functions, the use of external crates, and more. In the next few chapters, you’ll learn about these concepts in more detail. Chapter 3 covers concepts that most programming languages have, such as variables, data types, and functions, and shows how to use them in Rust. Chapter 4 explores ownership, a feature that makes Rust different from other languages. Chapter 5 discusses structs and method syntax, and Chapter 6 explains how enums work.

常见编程概念

Common Programming Concepts

本章介绍几乎所有编程语言中都会出现的概念，以及它们在 Rust 中是如何工作的。许多编程语言的核心都有很多共同之处。本章介绍的概念都不是 Rust 特有的，但我们将在 Rust 的背景下讨论它们，并解释使用它们的约定。

This chapter covers concepts that appear in almost every programming language and how they work in Rust. Many programming languages have much in common at their core. None of the concepts presented in this chapter are unique to Rust, but we’ll discuss them in the context of Rust and explain the conventions around using them.

具体来说，你将学习变量、基本类型、函数、注释和控制流。这些基础知识将出现在每个 Rust 程序中，及早学习它们将为你打下坚实的基础。

Specifically, you’ll learn about variables, basic types, functions, comments, and control flow. These foundations will be in every Rust program, and learning them early will give you a strong core to start from.

关键字

Keywords

Rust 语言有一组保留给语言本身使用的“关键字”（keywords），就像其他语言一样。请记住，你不能将这些词用作变量或函数的名称。大多数关键字具有特殊含义，你将使用它们在 Rust 程序中执行各种任务；少数关键字目前没有关联的功能，但已为将来可能添加到 Rust 的功能而保留。你可以在 附录 A 中找到关键字列表。

The Rust language has a set of keywords that are reserved for use by the language only, much as in other languages. Keep in mind that you cannot use these words as names of variables or functions. Most of the keywords have special meanings, and you’ll be using them to do various tasks in your Rust programs; a few have no current functionality associated with them but have been reserved for functionality that might be added to Rust in the future. You can find the list of the keywords in Appendix A.

变量与可变性

变量与可变性

Variables and Mutability

正如在“使用变量存储值”部分所提到的，默认情况下，变量是不可变的。这是 Rust 为你提供的众多暗示之一，旨在让你编写代码时能利用 Rust 提供的安全性和便捷的并发性。不过，你仍然可以选择让变量变得可变。让我们探讨一下 Rust 为何以及如何鼓励你优先使用不可变性，以及为什么有时你可能想要弃用它。

As mentioned in the “Storing Values with Variables” section, by default, variables are immutable. This is one of many nudges Rust gives you to write your code in a way that takes advantage of the safety and easy concurrency that Rust offers. However, you still have the option to make your variables mutable. Let’s explore how and why Rust encourages you to favor immutability and why sometimes you might want to opt out.

当变量不可变时，一旦某个值绑定到一个名称上，你就不能更改该值。为了说明这一点，在你的 projects 目录中使用 cargo new variables 生成一个名为 variables 的新项目。

When a variable is immutable, once a value is bound to a name, you can’t change that value. To illustrate this, generate a new project called variables in your projects directory by using cargo new variables.

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

Then, in your new variables directory, open src/main.rs and replace its code with the following code, which won’t compile just yet:

文件名：src/main.rs Filename: src/main.rs

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

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

Save and run the program using cargo run. You should receive an error message regarding an immutability error, as shown in this output:

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

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

这个例子展示了编译器如何帮助你发现程序中的错误。编译器错误可能会令人沮丧，但实际上它们只意味着你的程序还没有安全地执行你想要它做的事情；它们并不意味着你不是一个好的程序员！即使是资深的 Rustaceans 仍然会遇到编译器错误。

This example shows how the compiler helps you find errors in your programs. Compiler errors can be frustrating, but really they only mean your program isn’t safely doing what you want it to do yet; they do not mean that you’re not a good programmer! Experienced Rustaceans still get compiler errors.

你收到了错误消息 cannot assign twice to immutable variable `x`（不能对不可变变量 x 进行二次赋值），因为你尝试为不可变的 x 变量分配第二个值。

You received the error message cannot assign twice to immutable variable `x` because you tried to assign a second value to the immutable x variable.

当我们尝试更改指定为不可变的值时收到编译时错误是很重要的，因为这种情况会导致 bug。如果代码的一部分基于值永远不会改变的假设运行，而代码的另一部分改变了该值，那么第一部分代码可能无法实现其设计功能。这种 bug 的原因在事后可能很难追踪，尤其是当第二段代码只是有时更改值时。Rust 编译器保证当你声明一个值不会改变时，它就真的不会改变，所以你不需要自己去跟踪它。因此，你的代码更容易推导。

It’s important that we get compile-time errors when we attempt to change a value that’s designated as immutable, because this very situation can lead to bugs. If one part of our code operates on the assumption that a value will never change and another part of our code changes that value, it’s possible that the first part of the code won’t do what it was designed to do. The cause of this kind of bug can be difficult to track down after the fact, especially when the second piece of code changes the value only sometimes. The Rust compiler guarantees that when you state that a value won’t change, it really won’t change, so you don’t have to keep track of it yourself. Your code is thus easier to reason through.

但可变性可能非常有用，并且可以使代码编写更方便。虽然变量默认是不可变的，但你可以通过在变量名前添加 mut 来使其可变，正如你在第 2 章中所做的那样。添加 mut 还向代码的未来读者传达了意图，表明代码的其他部分将更改此变量的值。

But mutability can be very useful and can make code more convenient to write. Although variables are immutable by default, you can make them mutable by adding mut in front of the variable name as you did in Chapter 2. Adding mut also conveys intent to future readers of the code by indicating that other parts of the code will be changing this variable’s value.

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

For example, let’s change src/main.rs to the following:

文件名：src/main.rs Filename: src/main.rs

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

当我们现在运行程序时，我们得到如下结果：

When we run the program now, we get this:

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

使用 mut 时，允许我们将绑定到 x 的值从 5 更改为 6。最终，决定是否使用可变性取决于你，取决于你认为在特定情况下什么最清晰。

We’re allowed to change the value bound to x from 5 to 6 when mut is used. Ultimately, deciding whether to use mutability or not is up to you and depends on what you think is clearest in that particular situation.

声明常量

Declaring Constants

与不可变变量类似，常量也是绑定到名称且不允许更改的值，但常量和变量之间有一些区别。

Like immutable variables, constants are values that are bound to a name and are not allowed to change, but there are a few differences between constants and variables.

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

First, you aren’t allowed to use mut with constants. Constants aren’t just immutable by default—they’re always immutable. You declare constants using the const keyword instead of the let keyword, and the type of the value must be annotated. We’ll cover types and type annotations in the next section, “Data Types”, so don’t worry about the details right now. Just know that you must always annotate the type.

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

Constants can be declared in any scope, including the global scope, which makes them useful for values that many parts of code need to know about.

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

The last difference is that constants may be set only to a constant expression, not the result of a value that could only be computed at runtime.

这是一个常量声明的例子：

Here’s an example of a constant declaration:

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

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

The constant’s name is THREE_HOURS_IN_SECONDS, and its value is set to the result of multiplying 60 (the number of seconds in a minute) by 60 (the number of minutes in an hour) by 3 (the number of hours we want to count in this program). Rust’s naming convention for constants is to use all uppercase with underscores between words. The compiler is able to evaluate a limited set of operations at compile time, which lets us choose to write out this value in a way that’s easier to understand and verify, rather than setting this constant to the value 10,800. See the Rust Reference’s section on constant evaluation for more information on what operations can be used when declaring constants.

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

Constants are valid for the entire time a program runs, within the scope in which they were declared. This property makes constants useful for values in your application domain that multiple parts of the program might need to know about, such as the maximum number of points any player of a game is allowed to earn, or the speed of light.

将整个程序中使用的硬编码值命名为常量，有助于向代码未来的维护者传达该值的含义。如果以后需要更新硬编码值，你的代码中也只需在一处进行更改。

Naming hardcoded values used throughout your program as constants is useful in conveying the meaning of that value to future maintainers of the code. It also helps to have only one place in your code that you would need to change if the hardcoded value needed to be updated in the future.

重影（Shadowing）

Shadowing

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

As you saw in the guessing game tutorial in Chapter 2, you can declare a new variable with the same name as a previous variable. Rustaceans say that the first variable is shadowed by the second, which means that the second variable is what the compiler will see when you use the name of the variable. In effect, the second variable overshadows the first, taking any uses of the variable name to itself until either it itself is shadowed or the scope ends. We can shadow a variable by using the same variable’s name and repeating the use of the let keyword as follows:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let x = 5;

    let x = x + 1;

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

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

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

This program first binds x to a value of 5. Then, it creates a new variable x by repeating let x =, taking the original value and adding 1 so that the value of x is 6. Then, within an inner scope created with the curly brackets, the third let statement also shadows x and creates a new variable, multiplying the previous value by 2 to give x a value of 12. When that scope is over, the inner shadowing ends and x returns to being 6. When we run this program, it will output the following:

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

重影与将变量标记为 mut 不同，因为如果我们不小心尝试在不使用 let 关键字的情况下重新为该变量赋值，我们将得到一个编译时错误。通过使用 let，我们可以对一个值执行几次转换，但在这些转换完成后，变量仍然是不可变的。

Shadowing is different from marking a variable as mut because we’ll get a compile-time error if we accidentally try to reassign to this variable without using the let keyword. By using let, we can perform a few transformations on a value but have the variable be immutable after those transformations have completed.

mut 和重影之间的另一个区别是，因为当我们再次使用 let 关键字时实际上是创建了一个新变量，所以我们可以更改值的类型，但重复使用相同的名称。例如，假设我们的程序通过输入空格字符要求用户显示他们想要在某些文本之间留出多少空格，然后我们想将该输入存储为一个数字：

The other difference between mut and shadowing is that because we’re effectively creating a new variable when we use the let keyword again, we can change the type of the value but reuse the same name. For example, say our program asks a user to show how many spaces they want between some text by inputting space characters, and then we want to store that input as a number:

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

第一个 spaces 变量是字符串类型，第二个 spaces 变量是数字类型。因此，重影使我们不必想出不同的名称，如 spaces_str 和 spaces_num；相反，我们可以重复使用更简单的 spaces 名称。但是，如果我们尝试为此使用 mut，如下所示，我们将得到一个编译时错误：

The first spaces variable is a string type, and the second spaces variable is a number type. Shadowing thus spares us from having to come up with different names, such as spaces_str and spaces_num; instead, we can reuse the simpler spaces name. However, if we try to use mut for this, as shown here, we’ll get a compile-time error:

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

错误提示我们不允许更改变量的类型：

The error says we’re not allowed to mutate a variable’s type:

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

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

既然我们已经探讨了变量的工作原理，现在让我们来看看它们可以拥有的更多数据类型。

Now that we’ve explored how variables work, let’s look at more data types they can have.

数据类型

数据类型

Data Types

Rust 中的每一个值都有其特定的数据类型（data type），这告诉 Rust 它被指定为什么样的数据，以便它知道如何处理这些数据。我们将研究两种数据类型子集：标量类型和复合类型。

Every value in Rust is of a certain data type, which tells Rust what kind of data is being specified so that it knows how to work with that data. We’ll look at two data type subsets: scalar and compound.

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

Keep in mind that Rust is a statically typed language, which means that it must know the types of all variables at compile time. The compiler can usually infer what type we want to use based on the value and how we use it. In cases when many types are possible, such as when we converted a String to a numeric type using parse in the “Comparing the Guess to the Secret Number” section in Chapter 2, we must add a type annotation, like this:

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

如果我们不添加上面代码中显示的 : u32 类型标注，Rust 将显示以下错误，这意味着编译器需要我们提供更多信息才能知道我们要使用哪种类型：

If we don’t add the : u32 type annotation shown in the preceding code, Rust will display the following error, which means the compiler needs more information from us to know which type we want to use:

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

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

你会看到其他数据类型的不同类型标注。

You’ll see different type annotations for other data types.

标量类型

Scalar Types

标量（scalar）类型代表单个值。Rust 有四种主要的标量类型：整数、浮点数、布尔值和字符。你可能从其他编程语言中认识这些类型。让我们跳入它们在 Rust 中是如何工作的。

A scalar type represents a single value. Rust has four primary scalar types: integers, floating-point numbers, Booleans, and characters. You may recognize these from other programming languages. Let’s jump into how they work in Rust.

整数类型

Integer Types

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

An integer is a number without a fractional component. We used one integer type in Chapter 2, the u32 type. This type declaration indicates that the value it’s associated with should be an unsigned integer (signed integer types start with i instead of u) that takes up 32 bits of space. Table 3-1 shows the built-in integer types in Rust. We can use any of these variants to declare the type of an integer value.

表 3-1：Rust 中的整数类型 Table 3-1: Integer Types in Rust

每个变体都可以是有符号的或无符号的，并且具有明确的大小。有符号（signed）和无符号（unsigned）是指数字是否可能为负数——换句话说，数字是否需要带有符号（有符号），或者它是否永远为正数因此可以在没有符号的情况下表示（无符号）。这就像在纸上写数字一样：当符号很重要时，数字会显示加号或减号；但是，当可以安全地假设数字为正数时，它就不显示符号。有符号数使用二进制补码表示法存储。

Each variant can be either signed or unsigned and has an explicit size. Signed and unsigned refer to whether it’s possible for the number to be negative—in other words, whether the number needs to have a sign with it (signed) or whether it will only ever be positive and can therefore be represented without a sign (unsigned). It’s like writing numbers on paper: When the sign matters, a number is shown with a plus sign or a minus sign; however, when it’s safe to assume the number is positive, it’s shown with no sign. Signed numbers are stored using two’s complement representation.

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

Each signed variant can store numbers from −(2^{n − 1}) to 2^{n − 1} − 1 inclusive, where n is the number of bits that variant uses. So, an i8 can store numbers from −(2⁷) to 2⁷ − 1, which equals −128 to 127. Unsigned variants can store numbers from 0 to 2ⁿ − 1, so a u8 can store numbers from 0 to 2⁸ − 1, which equals 0 to 255.

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

Additionally, the isize and usize types depend on the architecture of the computer your program is running on: 64 bits if you’re on a 64-bit architecture and 32 bits if you’re on a 32-bit architecture.

你可以按照表 3-2 中所示的任何形式编写整型字面量。请注意，可以是多种数值类型的数字字面量允许使用类型后缀（例如 57u8）来指定类型。数字字面量还可以使用 _ 作为视觉分隔符，使数字更易读，例如 1_000，其值与你指定 1000 时的值相同。

You can write integer literals in any of the forms shown in Table 3-2. Note that number literals that can be multiple numeric types allow a type suffix, such as 57u8, to designate the type. Number literals can also use _ as a visual separator to make the number easier to read, such as 1_000, which will have the same value as if you had specified 1000.

表 3-2：Rust 中的整型字面量 Table 3-2: Integer Literals in Rust

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

So how do you know which type of integer to use? If you’re unsure, Rust’s defaults are generally good places to start: Integer types default to i32. The primary situation in which you’d use isize or usize is when indexing some sort of collection.

整数溢出

Integer Overflow

假设你有一个 u8 类型的变量，它可以持有 0 到 255 之间的值。如果你尝试将变量更改为该范围之外的值（例如 256），则会发生整数溢出（integer overflow），这可能导致两种行为之一。当你以调试模式编译时，Rust 会包含整数溢出检查，如果发生这种行为，会导致程序在运行时恐慌（panic）。当程序带着错误退出时，Rust 使用“恐慌”这个术语；我们将在第 9 章的“使用 panic! 处理不可恢复的错误”部分中更深入地讨论恐慌。

Let’s say you have a variable of type u8 that can hold values between 0 and 255. If you try to change the variable to a value outside that range, such as 256, integer overflow will occur, which can result in one of two behaviors. When you’re compiling in debug mode, Rust includes checks for integer overflow that cause your program to panic at runtime if this behavior occurs. Rust uses the term panicking when a program exits with an error; we’ll discuss panics in more depth in the “Unrecoverable Errors with panic!” section in Chapter 9.

当你使用 --release 标志以发布模式编译时，Rust 不包含会导致恐慌的整数溢出检查。相反，如果发生溢出，Rust 会执行二进制补码回绕（two’s complement wrapping）。简而言之，大于该类型所能持有的最大值的数值会“回绕”到该类型所能持有的最小值。在 u8 的情况下，值 256 变为 0，值 257 变为 1，依此类推。程序不会恐慌，但变量的值可能不是你预期的值。依赖整数溢出的回绕行为被认为是一个错误。

When you’re compiling in release mode with the --release flag, Rust does not include checks for integer overflow that cause panics. Instead, if overflow occurs, Rust performs two’s complement wrapping. In short, values greater than the maximum value the type can hold “wrap around” to the minimum of the values the type can hold. In the case of a u8, the value 256 becomes 0, the value 257 becomes 1, and so on. The program won’t panic, but the variable will have a value that probably isn’t what you were expecting it to have. Relying on integer overflow’s wrapping behavior is considered an error.

为了显式地处理可能发生的溢出，你可以使用标准库为原始数值类型提供的这些方法系列：

To explicitly handle the possibility of overflow, you can use these families of methods provided by the standard library for primitive numeric types:

• 使用 wrapping_* 方法在所有模式下进行回绕，例如 wrapping_add。

• Wrap in all modes with the wrapping_* methods, such as wrapping_add.

• 如果发生溢出，使用 checked_* 方法返回 None 值。

• Return the None value if there is overflow with the checked_* methods.

• 使用 overflowing_* 方法返回该值和一个指示是否发生溢出的布尔值。

• Return the value and a Boolean indicating whether there was overflow with the overflowing_* methods.

• 使用 saturating_* 方法使数值饱和在值的最小值或最大值处。

• Saturate at the value’s minimum or maximum values with the saturating_* methods.

浮点类型

Floating-Point Types

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

Rust also has two primitive types for floating-point numbers, which are numbers with decimal points. Rust’s floating-point types are f32 and f64, which are 32 bits and 64 bits in size, respectively. The default type is f64 because on modern CPUs, it’s roughly the same speed as f32 but is capable of more precision. All floating-point types are signed.

这是一个展示浮点数实际应用的例子：

Here’s an example that shows floating-point numbers in action:

文件名：src/main.rs Filename: src/main.rs

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

    let y: f32 = 3.0; // f32
}

浮点数是根据 IEEE-754 标准表示的。

Floating-point numbers are represented according to the IEEE-754 standard.

数值运算

Numeric Operations

Rust 支持你对所有数字类型所期望的基本数学运算：加法、减法、乘法、除法和取余。整数除法会向零截断到最近的整数。以下代码显示了你如何在 let 语句中使用各种数值运算：

Rust supports the basic mathematical operations you’d expect for all the number types: addition, subtraction, multiplication, division, and remainder. Integer division truncates toward zero to the nearest integer. The following code shows how you’d use each numeric operation in a let statement:

文件名：src/main.rs Filename: src/main.rs

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

    // subtraction
    let difference = 95.5 - 4.3;

    // multiplication
    let product = 4 * 30;

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

    // remainder
    let remainder = 43 % 5;
}

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

Each expression in these statements uses a mathematical operator and evaluates to a single value, which is then bound to a variable. Appendix B contains a list of all operators that Rust provides.

布尔类型

The Boolean Type

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

As in most other programming languages, a Boolean type in Rust has two possible values: true and false. Booleans are one byte in size. The Boolean type in Rust is specified using bool. For example:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let t = true;

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

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

The main way to use Boolean values is through conditionals, such as an if expression. We’ll cover how if expressions work in Rust in the “Control Flow” section.

字符类型

The Character Type

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

Rust’s char type is the language’s most primitive alphabetic type. Here are some examples of declaring char values:

文件名：src/main.rs Filename: src/main.rs

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

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

Note that we specify char literals with single quotation marks, as opposed to string literals, which use double quotation marks. Rust’s char type is 4 bytes in size and represents a Unicode scalar value, which means it can represent a lot more than just ASCII. Accented letters; Chinese, Japanese, and Korean characters; emojis; and zero-width spaces are all valid char values in Rust. Unicode scalar values range from U+0000 to U+D7FF and U+E000 to U+10FFFF inclusive. However, a “character” isn’t really a concept in Unicode, so your human intuition for what a “character” is may not match up with what a char is in Rust. We’ll discuss this topic in detail in “Storing UTF-8 Encoded Text with Strings” in Chapter 8.

复合类型

Compound Types

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

Compound types can group multiple values into one type. Rust has two primitive compound types: tuples and arrays.

元组类型

The Tuple Type

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

A tuple is a general way of grouping together a number of values with a variety of types into one compound type. Tuples have a fixed length: Once declared, they cannot grow or shrink in size.

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

We create a tuple by writing a comma-separated list of values inside parentheses. Each position in the tuple has a type, and the types of the different values in the tuple don’t have to be the same. We’ve added optional type annotations in this example:

文件名：src/main.rs Filename: src/main.rs

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

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

The variable tup binds to the entire tuple because a tuple is considered a single compound element. To get the individual values out of a tuple, we can use pattern matching to destructure a tuple value, like this:

文件名：src/main.rs Filename: src/main.rs

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

    let (x, y, z) = tup;

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

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

This program first creates a tuple and binds it to the variable tup. It then uses a pattern with let to take tup and turn it into three separate variables, x, y, and z. This is called destructuring because it breaks the single tuple into three parts. Finally, the program prints the value of y, which is 6.4.

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

We can also access a tuple element directly by using a period (.) followed by the index of the value we want to access. For example:

文件名：src/main.rs Filename: src/main.rs

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

    let five_hundred = x.0;

    let six_point_four = x.1;

    let one = x.2;
}

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

This program creates the tuple x and then accesses each element of the tuple using their respective indices. As with most programming languages, the first index in a tuple is 0.

没有任何值的元组有一个特殊的名称：单元类型（unit）。该值及其相应的类型都写作 ()，代表一个空值或空返回类型。如果表达式不返回任何其他值，则它们会隐式返回单元值。

The tuple without any values has a special name, unit. This value and its corresponding type are both written () and represent an empty value or an empty return type. Expressions implicitly return the unit value if they don’t return any other value.

数组类型

The Array Type

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

Another way to have a collection of multiple values is with an array. Unlike a tuple, every element of an array must have the same type. Unlike arrays in some other languages, arrays in Rust have a fixed length.

我们将数组中的值写在方括号内，并以逗号分隔：

We write the values in an array as a comma-separated list inside square brackets:

文件名：src/main.rs Filename: src/main.rs

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

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

Arrays are useful when you want your data allocated on the stack, the same as the other types we have seen so far, rather than the heap (We will discuss the stack and the heap more in Chapter 4) or when you want to ensure that you always have a fixed number of elements. An array isn’t as flexible as the vector type, though. A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size because its contents live on the heap. If you’re unsure whether to use an array or a vector, chances are you should use a vector. Chapter 8 discusses vectors in more detail.

但是，当你确定元素数量不需要更改时，数组会更有用。例如，如果你在程序中使用月份的名称，你可能会使用数组而不是 vector，因为你知道它将始终包含 12 个元素：

However, arrays are more useful when you know the number of elements will not need to change. For example, if you were using the names of the month in a program, you would probably use an array rather than a vector because you know it will always contain 12 elements:

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

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

You write an array’s type using square brackets with the type of each element, a semicolon, and then the number of elements in the array, like so:

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

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

Here, i32 is the type of each element. After the semicolon, the number 5 indicates the array contains five elements.

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

You can also initialize an array to contain the same value for each element by specifying the initial value, followed by a semicolon, and then the length of the array in square brackets, as shown here:

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

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

The array named a will contain 5 elements that will all be set to the value 3 initially. This is the same as writing let a = [3, 3, 3, 3, 3]; but in a more concise way.

访问数组元素

Array Element Access

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

An array is a single chunk of memory of a known, fixed size that can be allocated on the stack. You can access elements of an array using indexing, like this:

文件名：src/main.rs Filename: src/main.rs

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

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

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

In this example, the variable named first will get the value 1 because that is the value at index [0] in the array. The variable named second will get the value 2 from index [1] in the array.

无效的数组元素访问

Invalid Array Element Access

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

Let’s see what happens if you try to access an element of an array that is past the end of the array. Say you run this code, similar to the guessing game in Chapter 2, to get an array index from the user:

文件名：src/main.rs Filename: src/main.rs

use std::io;

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

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

    let mut index = String::new();

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

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

    let element = a[index];

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

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

This code compiles successfully. If you run this code using cargo run and enter 0, 1, 2, 3, or 4, the program will print out the corresponding value at that index in the array. If you instead enter a number past the end of the array, such as 10, you’ll see output like this:

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

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

The program resulted in a runtime error at the point of using an invalid value in the indexing operation. The program exited with an error message and didn’t execute the final println! statement. When you attempt to access an element using indexing, Rust will check that the index you’ve specified is less than the array length. If the index is greater than or equal to the length, Rust will panic. This check has to happen at runtime, especially in this case, because the compiler can’t possibly know what value a user will enter when they run the code later.

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

This is an example of Rust’s memory safety principles in action. In many low-level languages, this kind of check is not done, and when you provide an incorrect index, invalid memory can be accessed. Rust protects you against this kind of error by immediately exiting instead of allowing the memory access and continuing. Chapter 9 discusses more of Rust’s error handling and how you can write readable, safe code that neither panics nor allows invalid memory access.

函数

函数

Functions

函数在 Rust 代码中非常普遍。你已经见过语言中最重要的函数之一：main 函数，它是许多程序的入口点。你也见过 fn 关键字，它允许你声明新的函数。

Functions are prevalent in Rust code. You’ve already seen one of the most important functions in the language: the main function, which is the entry point of many programs. You’ve also seen the fn keyword, which allows you to declare new functions.

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

Rust code uses snake case as the conventional style for function and variable names, in which all letters are lowercase and underscores separate words. Here’s a program that contains an example function definition:

文件名：src/main.rs Filename: src/main.rs

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

    another_function();
}

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

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

We define a function in Rust by entering fn followed by a function name and a set of parentheses. The curly brackets tell the compiler where the function body begins and ends.

我们可以通过输入函数名后跟一对圆括号来调用定义的任何函数。因为程序中定义了 another_function，所以可以在 main 函数内部调用它。注意，我们在源代码中将 another_function 定义在 main 函数“之后”；我们也可以将其定义在之前。Rust 不在乎你在哪里定义函数，只要它们被定义在调用者可见的作用域内的某个地方即可。

We can call any function we’ve defined by entering its name followed by a set of parentheses. Because another_function is defined in the program, it can be called from inside the main function. Note that we defined another_function after the main function in the source code; we could have defined it before as well. Rust doesn’t care where you define your functions, only that they’re defined somewhere in a scope that can be seen by the caller.

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

Let’s start a new binary project named functions to explore functions further. Place the another_function example in src/main.rs and run it. You should see the following output:

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

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

The lines execute in the order in which they appear in the main function. First the “Hello, world!” message prints, and then another_function is called and its message is printed.

参数

Parameters

我们可以定义带有“参数”（parameters）的函数，参数是属于函数签名一部分的特殊变量。当函数有参数时，你可以为这些参数提供具体的值。从技术上讲，这些具体的值被称为“实参”（arguments），但在日常对话中，人们倾向于交替使用“形参”（parameter）和“实参”（argument）这两个词，无论是指函数定义中的变量还是调用函数时传入的具体值。

We can define functions to have parameters, which are special variables that are part of a function’s signature. When a function has parameters, you can provide it with concrete values for those parameters. Technically, the concrete values are called arguments, but in casual conversation, people tend to use the words parameter and argument interchangeably for either the variables in a function’s definition or the concrete values passed in when you call a function.

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

In this version of another_function we add a parameter:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    another_function(5);
}

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

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

Try running this program; you should get the following output:

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

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

The declaration of another_function has one parameter named x. The type of x is specified as i32. When we pass 5 in to another_function, the println! macro puts 5 where the pair of curly brackets containing x was in the format string.

在函数签名中，你“必须”声明每个参数的类型。这是 Rust 设计中的一个刻意决定：在函数定义中要求类型注解意味着编译器几乎不需要你在代码的其他地方使用它们来推断你的意图。如果编译器知道函数期望的类型，它也能提供更有帮助的错误信息。

In function signatures, you must declare the type of each parameter. This is a deliberate decision in Rust’s design: Requiring type annotations in function definitions means the compiler almost never needs you to use them elsewhere in the code to figure out what type you mean. The compiler is also able to give more-helpful error messages if it knows what types the function expects.

定义多个参数时，请用逗号分隔参数声明，如下所示：

When defining multiple parameters, separate the parameter declarations with commas, like this:

文件名：src/main.rs Filename: src/main.rs

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

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

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

This example creates a function named print_labeled_measurement with two parameters. The first parameter is named value and is an i32. The second is named unit_label and is type char. The function then prints text containing both the value and the unit_label.

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

Let’s try running this code. Replace the program currently in your functions project’s src/main.rs file with the preceding example and run it using cargo run:

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

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

Because we called the function with 5 as the value for value and 'h' as the value for unit_label, the program output contains those values.

语句和表达式

Statements and Expressions

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

Function bodies are made up of a series of statements optionally ending in an expression. So far, the functions we’ve covered haven’t included an ending expression, but you have seen an expression as part of a statement. Because Rust is an expression-based language, this is an important distinction to understand. Other languages don’t have the same distinctions, so let’s look at what statements and expressions are and how their differences affect the bodies of functions.

• 语句（Statements）是执行某些操作且不返回值的指令。

• 表达式（Expressions）计算并产生一个结果值。

• Statements are instructions that perform some action and do not return a value.

• Expressions evaluate to a resultant value.

让我们看一些例子。

Let’s look at some examples.

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

We’ve actually already used statements and expressions. Creating a variable and assigning a value to it with the let keyword is a statement. In Listing 3-1, let y = 6; is a statement.

fn main() {
    let y = 6;
}

函数定义也是语句；整个前面的示例本身就是一个语句。（正如我们很快就会看到的，调用函数则不是语句。）

Function definitions are also statements; the entire preceding example is a statement in itself. (As we’ll see shortly, calling a function is not a statement, though.)

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

Statements do not return values. Therefore, you can’t assign a let statement to another variable, as the following code tries to do; you’ll get an error:

文件名：src/main.rs Filename: src/main.rs

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

当你运行这个程序时，得到的错误如下所示：

When you run this program, the error you’ll get looks like this:

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

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

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

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

The let y = 6 statement does not return a value, so there isn’t anything for x to bind to. This is different from what happens in other languages, such as C and Ruby, where the assignment returns the value of the assignment. In those languages, you can write x = y = 6 and have both x and y have the value 6; that is not the case in Rust.

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

Expressions evaluate to a value and make up most of the rest of the code that you’ll write in Rust. Consider a math operation, such as 5 + 6, which is an expression that evaluates to the value 11. Expressions can be part of statements: In Listing 3-1, the 6 in the statement let y = 6; is an expression that evaluates to the value 6. Calling a function is an expression. Calling a macro is an expression. A new scope block created with curly brackets is an expression, for example:

文件名：src/main.rs Filename: src/main.rs

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

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

这个表达式：

This expression:

{
    let x = 3;
    x + 1
}

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

is a block that, in this case, evaluates to 4. That value gets bound to y as part of the let statement. Note the x + 1 line without a semicolon at the end, which is unlike most of the lines you’ve seen so far. Expressions do not include ending semicolons. If you add a semicolon to the end of an expression, you turn it into a statement, and it will then not return a value. Keep this in mind as you explore function return values and expressions next.

具有返回值的函数

Functions with Return Values

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

Functions can return values to the code that calls them. We don’t name return values, but we must declare their type after an arrow (->). In Rust, the return value of the function is synonymous with the value of the final expression in the block of the body of a function. You can return early from a function by using the return keyword and specifying a value, but most functions return the last expression implicitly. Here’s an example of a function that returns a value:

文件名：src/main.rs Filename: src/main.rs

fn five() -> i32 {
    5
}

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

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

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

There are no function calls, macros, or even let statements in the five function—just the number 5 by itself. That’s a perfectly valid function in Rust. Note that the function’s return type is specified too, as -> i32. Try running this code; the output should look like this:

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

five 中的 5 是函数的返回值，这就是为什么返回类型是 i32。让我们更详细地研究一下。有两个重要部分：首先，行 let x = five(); 显示我们正在使用函数的返回值来初始化一个变量。因为函数 five 返回 5，所以该行与以下行相同：

The 5 in five is the function’s return value, which is why the return type is i32. Let’s examine this in more detail. There are two important bits: First, the line let x = five(); shows that we’re using the return value of a function to initialize a variable. Because the function five returns a 5, that line is the same as the following:

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

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

Second, the five function has no parameters and defines the type of the return value, but the body of the function is a lonely 5 with no semicolon because it’s an expression whose value we want to return.

让我们看另一个例子：

Let’s look at another example:

文件名：src/main.rs Filename: src/main.rs

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

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

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

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

Running this code will print The value of x is: 6. But what happens if we place a semicolon at the end of the line containing x + 1, changing it from an expression to a statement?

文件名：src/main.rs Filename: src/main.rs

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

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

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

编译这段代码将产生如下错误：

Compiling this code will produce an error, as follows:

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

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

主要的错误信息 mismatched types（类型不匹配）揭示了这段代码的核心问题。函数 plus_one 的定义说它将返回一个 i32，但语句不会求得一个值，这由单元类型 () 表示。因此，没有返回任何东西，这与函数定义相矛盾并导致错误。在这个输出中，Rust 提供了一条可能有助于纠正此问题的消息：它建议删除分号，这将修复该错误。

The main error message, mismatched types, reveals the core issue with this code. The definition of the function plus_one says that it will return an i32, but statements don’t evaluate to a value, which is expressed by (), the unit type. Therefore, nothing is returned, which contradicts the function definition and results in an error. In this output, Rust provides a message to possibly help rectify this issue: It suggests removing the semicolon, which would fix the error.

注释

注释

Comments

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

All programmers strive to make their code easy to understand, but sometimes extra explanation is warranted. In these cases, programmers leave comments in their source code that the compiler will ignore but that people reading the source code may find useful.

这是一个简单的注释：

Here’s a simple comment:

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

在 Rust 中，惯用的注释风格是以两个斜杠开始注释，注释一直持续到行尾。对于超出单行的注释，你需要在每一行都包含 //，如下所示：

In Rust, the idiomatic comment style starts a comment with two slashes, and the comment continues until the end of the line. For comments that extend beyond a single line, you’ll need to include // on each line, like this:

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

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

Comments can also be placed at the end of lines containing code:

文件名：src/main.rs Filename: src/main.rs

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

但你更常见到它们被用这种格式，即注释位于其所注解代码上方独立的一行：

But you’ll more often see them used in this format, with the comment on a separate line above the code it’s annotating:

文件名：src/main.rs Filename: src/main.rs

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

Rust 还有另一种注释，即文档注释，我们将在第 14 章的“将 Crate 发布到 Crates.io”部分进行讨论。

Rust also has another kind of comment, documentation comments, which we’ll discuss in the “Publishing a Crate to Crates.io” section of Chapter 14.

控制流

控制流

Control Flow

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

The ability to run some code depending on whether a condition is true and the ability to run some code repeatedly while a condition is true are basic building blocks in most programming languages. The most common constructs that let you control the flow of execution of Rust code are if expressions and loops.

if 表达式

if Expressions

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

An if expression allows you to branch your code depending on conditions. You provide a condition and then state, “If this condition is met, run this block of code. If the condition is not met, do not run this block of code.”

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

Create a new project called branches in your projects directory to explore the if expression. In the src/main.rs file, input the following:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let number = 3;

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

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

All if expressions start with the keyword if, followed by a condition. In this case, the condition checks whether or not the variable number has a value less than 5. We place the block of code to execute if the condition is true immediately after the condition inside curly brackets. Blocks of code associated with the conditions in if expressions are sometimes called arms, just like the arms in match expressions that we discussed in the “Comparing the Guess to the Secret Number” section of Chapter 2.

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

Optionally, we can also include an else expression, which we chose to do here, to give the program an alternative block of code to execute should the condition evaluate to false. If you don’t provide an else expression and the condition is false, the program will just skip the if block and move on to the next bit of code.

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

Try running this code; you should see the following output:

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

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

Let’s try changing the value of number to a value that makes the condition false to see what happens:

fn main() {
    let number = 7;

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

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

Run the program again, and look at the output:

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

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

It’s also worth noting that the condition in this code must be a bool. If the condition isn’t a bool, we’ll get an error. For example, try running the following code:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let number = 3;

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

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

The if condition evaluates to a value of 3 this time, and Rust throws an error:

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

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

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

The error indicates that Rust expected a bool but got an integer. Unlike languages such as Ruby and JavaScript, Rust will not automatically try to convert non-Boolean types to a Boolean. You must be explicit and always provide if with a Boolean as its condition. If we want the if code block to run only when a number is not equal to 0, for example, we can change the if expression to the following:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let number = 3;

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

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

Running this code will print number was something other than zero.

使用 else if 处理多个条件

Handling Multiple Conditions with else if

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

You can use multiple conditions by combining if and else in an else if expression. For example:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let number = 6;

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

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

This program has four possible paths it can take. After running it, you should see the following output:

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

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

When this program executes, it checks each if expression in turn and executes the first body for which the condition evaluates to true. Note that even though 6 is divisible by 2, we don’t see the output number is divisible by 2, nor do we see the number is not divisible by 4, 3, or 2 text from the else block. That’s because Rust only executes the block for the first true condition, and once it finds one, it doesn’t even check the rest.

使用过多的 else if 表达式会使代码显得杂乱，因此如果你有多个 else if，你可能需要重构代码。第 6 章介绍了一种强大的 Rust 分支结构，称为 match，专门用于这些情况。

Using too many else if expressions can clutter your code, so if you have more than one, you might want to refactor your code. Chapter 6 describes a powerful Rust branching construct called match for these cases.

在 let 语句中使用 if

Using if in a let Statement

因为 if 是一个表达式，我们可以将其用于 let 语句的右侧，以将结果分配给变量，如示例 3-2 所示。

Because if is an expression, we can use it on the right side of a let statement to assign the outcome to a variable, as in Listing 3-2.

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

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

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

The number variable will be bound to a value based on the outcome of the if expression. Run this code to see what happens:

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

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

Remember that blocks of code evaluate to the last expression in them, and numbers by themselves are also expressions. In this case, the value of the whole if expression depends on which block of code executes. This means the values that have the potential to be results from each arm of the if must be the same type; in Listing 3-2, the results of both the if arm and the else arm were i32 integers. If the types are mismatched, as in the following example, we’ll get an error:

文件名：src/main.rs Filename: src/main.rs

fn main() {
    let condition = true;

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

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

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

When we try to compile this code, we’ll get an error. The if and else arms have value types that are incompatible, and Rust indicates exactly where to find the problem in the program:

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

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

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

The expression in the if block evaluates to an integer, and the expression in the else block evaluates to a string. This won’t work, because variables must have a single type, and Rust needs to know definitively at compile time what type the number variable is. Knowing the type of number lets the compiler verify the type is valid everywhere we use number. Rust wouldn’t be able to do that if the type of number was only determined at runtime; the compiler would be more complex and would make fewer guarantees about the code if it had to keep track of multiple hypothetical types for any variable.

使用循环重复执行

Repetition with Loops

多次执行一个代码块通常很有用。为了完成这个任务，Rust 提供了几种循环（loops），它们会运行循环体内的代码直到结束，然后立即返回开头。为了实验循环，让我们创建一个名为 loops 的新项目。

It’s often useful to execute a block of code more than once. For this task, Rust provides several loops, which will run through the code inside the loop body to the end and then start immediately back at the beginning. To experiment with loops, let’s make a new project called loops.

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

Rust has three kinds of loops: loop, while, and for. Let’s try each one.

使用 loop 重复代码

Repeating Code with loop

loop 关键字告诉 Rust 一遍又一遍地执行一个代码块，直到永远或者直到你显式地告诉它停止。

The loop keyword tells Rust to execute a block of code over and over again either forever or until you explicitly tell it to stop.

作为一个例子，将 loops 目录中的 src/main.rs 文件更改为如下形式：

As an example, change the src/main.rs file in your loops directory to look like this:

文件名：src/main.rs Filename: src/main.rs

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

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

When we run this program, we’ll see again! printed over and over continuously until we stop the program manually. Most terminals support the keyboard shortcut ctrl-C to interrupt a program that is stuck in a continual loop. Give it a try:

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

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

The symbol ^C represents where you pressed ctrl-C.

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

You may or may not see the word again! printed after the ^C, depending on where the code was in the loop when it received the interrupt signal.

幸运的是，Rust 还提供了一种使用代码跳出循环的方法。你可以将 break 关键字放在循环中，以告诉程序何时停止执行循环。回想一下，我们在第 2 章“猜对后退出”部分在猜谜游戏中执行了此操作，以便在用户通过猜对数字获胜时退出程序。

Fortunately, Rust also provides a way to break out of a loop using code. You can place the break keyword within the loop to tell the program when to stop executing the loop. Recall that we did this in the guessing game in the “Quitting After a Correct Guess” section of Chapter 2 to exit the program when the user won the game by guessing the correct number.

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

We also used continue in the guessing game, which in a loop tells the program to skip over any remaining code in this iteration of the loop and go to the next iteration.

从循环中返回值

Returning Values from Loops

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

One of the uses of a loop is to retry an operation you know might fail, such as checking whether a thread has completed its job. You might also need to pass the result of that operation out of the loop to the rest of your code. To do this, you can add the value you want returned after the break expression you use to stop the loop; that value will be returned out of the loop so that you can use it, as shown here:

fn main() {
    let mut counter = 0;

    let result = loop {
        counter += 1;

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

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

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

Before the loop, we declare a variable named counter and initialize it to 0. Then, we declare a variable named result to hold the value returned from the loop. On every iteration of the loop, we add 1 to the counter variable, and then check whether the counter is equal to 10. When it is, we use the break keyword with the value counter * 2. After the loop, we use a semicolon to end the statement that assigns the value to result. Finally, we print the value in result, which in this case is 20.

你也可以从循环内部 return。break 仅退出当前循环，而 return 总是退出当前函数。

You can also return from inside a loop. While break only exits the current loop, return always exits the current function.

使用循环标签在多个循环之间消除歧义

Disambiguating with Loop Labels

如果你有嵌套循环，break 和 continue 将应用于此时最内层的循环。你可以选择在循环上指定一个“循环标签”（loop label），然后将其与 break 或 continue 配合使用，以指定这些关键字应用于带标签的循环，而不是最内层的循环。循环标签必须以单引号开头。这是一个包含两个嵌套循环的示例：

If you have loops within loops, break and continue apply to the innermost loop at that point. You can optionally specify a loop label on a loop that you can then use with break or continue to specify that those keywords apply to the labeled loop instead of the innermost loop. Loop labels must begin with a single quote. Here’s an example with two nested loops:

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

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

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

外层循环具有标签 'counting_up，它将从 0 计数到 2。没有标签的内层循环从 10 倒数到 9。第一个未指定标签的 break 将仅退出内层循环。break 'counting_up; 语句将退出外层循环。此代码打印：

The outer loop has the label 'counting_up, and it will count up from 0 to 2. The inner loop without a label counts down from 10 to 9. The first break that doesn’t specify a label will exit the inner loop only. The break 'counting_up; statement will exit the outer loop. This code prints:

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

使用 while 进行条件循环

Streamlining Conditional Loops with while

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

A program will often need to evaluate a condition within a loop. While the condition is true, the loop runs. When the condition ceases to be true, the program calls break, stopping the loop. It’s possible to implement behavior like this using a combination of loop, if, else, and break; you could try that now in a program, if you’d like. However, this pattern is so common that Rust has a built-in language construct for it, called a while loop. In Listing 3-3, we use while to loop the program three times, counting down each time, and then, after the loop, to print a message and exit.

fn main() {
    let mut number = 3;

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

        number -= 1;
    }

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

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

This construct eliminates a lot of nesting that would be necessary if you used loop, if, else, and break, and it’s clearer. While a condition evaluates to true, the code runs; otherwise, it exits the loop.

使用 for 遍历集合

Looping Through a Collection with for

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

You can choose to use the while construct to loop over the elements of a collection, such as an array. For example, the loop in Listing 3-4 prints each element in the array a.

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

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

        index += 1;
    }
}

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

Here, the code counts up through the elements in the array. It starts at index 0 and then loops until it reaches the final index in the array (that is, when index < 5 is no longer true). Running this code will print every element in the array:

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

如预期的那样，所有五个数组值都出现在终端中。即使 index 在某个点会达到 5，循环在尝试从数组中获取第六个值之前就会停止执行。

All five array values appear in the terminal, as expected. Even though index will reach a value of 5 at some point, the loop stops executing before trying to fetch a sixth value from the array.

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

However, this approach is error-prone; we could cause the program to panic if the index value or test condition is incorrect. For example, if you changed the definition of the a array to have four elements but forgot to update the condition to while index < 4, the code would panic. It’s also slow, because the compiler adds runtime code to perform the conditional check of whether the index is within the bounds of the array on every iteration through the loop.

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

As a more concise alternative, you can use a for loop and execute some code for each item in a collection. A for loop looks like the code in Listing 3-5.

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

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

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

When we run this code, we’ll see the same output as in Listing 3-4. More importantly, we’ve now increased the safety of the code and eliminated the chance of bugs that might result from going beyond the end of the array or not going far enough and missing some items. Machine code generated from for loops can be more efficient as well because the index doesn’t need to be compared to the length of the array at every iteration.

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

Using the for loop, you wouldn’t need to remember to change any other code if you changed the number of values in the array, as you would with the method used in Listing 3-4.

for 循环的安全性且简洁性使其成为 Rust 中最常用的循环结构。即使在你想将某些代码运行特定次数的情况下（例如示例 3-3 中使用 while 循环的倒计时示例），大多数 Rustaceans 也会使用 for 循环。方法是使用标准库提供的 Range，它按顺序生成从一个数字开始并在另一个数字之前结束的所有数字。

The safety and conciseness of for loops make them the most commonly used loop construct in Rust. Even in situations in which you want to run some code a certain number of times, as in the countdown example that used a while loop in Listing 3-3, most Rustaceans would use a for loop. The way to do that would be to use a Range, provided by the standard library, which generates all numbers in sequence starting from one number and ending before another number.

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

Here’s what the countdown would look like using a for loop and another method we’ve not yet talked about, rev, to reverse the range:

文件名：src/main.rs Filename: src/main.rs

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

这段代码看起来更漂亮一些，不是吗？

This code is a bit nicer, isn’t it?

总结

Summary

你做到了！这是一个相当大的章节：你学习了变量、标量和复合数据类型、函数、注释、if 表达式和循环！为了练习本章讨论的概念，请尝试构建程序来执行以下操作：

You made it! This was a sizable chapter: You learned about variables, scalar and compound data types, functions, comments, if expressions, and loops! To practice with the concepts discussed in this chapter, try building programs to do the following:

• 在华氏温度和摄氏温度之间转换温度。

• 生成第 n 个斐波那契数。

• 打印圣诞颂歌“圣诞节的十二天”的歌词，利用歌曲中的重复部分。

• Convert temperatures between Fahrenheit and Celsius.

• Generate the nth Fibonacci number.

• Print the lyrics to the Christmas carol “The Twelve Days of Christmas,” taking advantage of the repetition in the song.

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

When you’re ready to move on, we’ll talk about a concept in Rust that doesn’t commonly exist in other programming languages: ownership.

理解所有权

Understanding Ownership

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

Ownership is Rust’s most unique feature and has deep implications for the rest of the language. It enables Rust to make memory safety guarantees without needing a garbage collector, so it’s important to understand how ownership works. In this chapter, we’ll talk about ownership as well as several related features: borrowing, slices, and how Rust lays data out in memory.

什么是所有权？

什么是所有权？

What Is Ownership?

“所有权”（Ownership）是一套管理 Rust 程序如何管理内存的规则。所有程序在运行时都必须管理它们使用计算机内存的方式。一些语言具有垃圾回收机制，在程序运行时定期寻找不再使用的内存；在其他语言中，程序员必须显式地分配和释放内存。Rust 采用了第三种方法：内存通过一个所有权系统进行管理，该系统有一套编译器检查的规则。如果违反了任何规则，程序将无法编译。在程序运行时，所有权的功能都不会减慢程序的运行速度。

Ownership is a set of rules that govern how a Rust program manages memory. All programs have to manage the way they use a computer’s memory while running. Some languages have garbage collection that regularly looks for no-longer-used memory as the program runs; in other languages, the programmer must explicitly allocate and free the memory. Rust uses a third approach: Memory is managed through a system of ownership with a set of rules that the compiler checks. If any of the rules are violated, the program won’t compile. None of the features of ownership will slow down your program while it’s running.

因为所有权对许多程序员来说是一个新概念，所以确实需要一些时间来适应。好消息是，你对 Rust 和所有权系统的规则越熟悉，你就越容易自然地开发出既安全又高效的代码。坚持下去！

Because ownership is a new concept for many programmers, it does take some time to get used to. The good news is that the more experienced you become with Rust and the rules of the ownership system, the easier you’ll find it to naturally develop code that is safe and efficient. Keep at it!

当你理解了所有权，你就为理解使 Rust 独特的功能打下了坚实的基础。在本章中，你将通过学习一些专注于非常常见的数据结构（字符串）的示例来学习所有权。

When you understand ownership, you’ll have a solid foundation for understanding the features that make Rust unique. In this chapter, you’ll learn ownership by working through some examples that focus on a very common data structure: strings.

栈和堆

The Stack and the Heap

许多编程语言不要求你经常思考栈和堆。但在像 Rust 这样的系统编程语言中，一个值是在栈上还是在堆上会影响语言的行为方式，以及你为什么必须做出某些决定。本章稍后将结合栈和堆来描述所有权的部分内容，因此这里先做一个简要的解释作为准备。

Many programming languages don’t require you to think about the stack and the heap very often. But in a systems programming language like Rust, whether a value is on the stack or the heap affects how the language behaves and why you have to make certain decisions. Parts of ownership will be described in relation to the stack and the heap later in this chapter, so here is a brief explanation in preparation.

栈和堆都是你的代码在运行时可以使用的内存部分，但它们的结构方式不同。栈按接收值的顺序存储值，并按相反的顺序移除值。这被称为“后进先出”（last in, first out (LIFO)）。想象一叠盘子：当你添加更多盘子时，你把它们放在堆的最上面，当你需要一个盘子时，你从最上面拿走一个。从中间或底部添加或移除盘子就不那么方便了！添加数据被称为“压入栈”（pushing onto the stack），移除数据被称为“弹出栈”（popping off the stack）。所有存储在栈上的数据都必须具有已知的、固定的大小。在编译时大小未知或大小可能发生变化的数据必须存储在堆上。

Both the stack and the heap are parts of memory available to your code to use at runtime, but they are structured in different ways. The stack stores values in the order it gets them and removes the values in the opposite order. This is referred to as last in, first out (LIFO). Think of a stack of plates: When you add more plates, you put them on top of the pile, and when you need a plate, you take one off the top. Adding or removing plates from the middle or bottom wouldn’t work as well! Adding data is called pushing onto the stack, and removing data is called popping off the stack. All data stored on the stack must have a known, fixed size. Data with an unknown size at compile time or a size that might change must be stored on the heap instead.

堆的组织性较差：当你把数据放在堆上时，你会请求一定量的空间。内存分配器在堆中找到一个足够大的空位，将其标记为正在使用，并返回一个“指针”（pointer），即该位置的地址。这个过程被称为“在堆上分配”（allocating on the heap），有时简称为“分配”（allocating）（将值压入栈不被视为分配）。因为指向堆的指针是已知的、固定的大小，所以你可以将指针存储在栈上，但当你想要实际数据时，必须跟随指针。想象一下在餐厅就座。当你进入时，你说明你的人数，服务生会找一张适合所有人的空桌子并带你过去。如果你组里有人迟到了，他们可以询问你坐在哪里来找到你。

The heap is less organized: When you put data on the heap, you request a certain amount of space. The memory allocator finds an empty spot in the heap that is big enough, marks it as being in use, and returns a pointer, which is the address of that location. This process is called allocating on the heap and is sometimes abbreviated as just allocating (pushing values onto the stack is not considered allocating). Because the pointer to the heap is a known, fixed size, you can store the pointer on the stack, but when you want the actual data, you must follow the pointer. Think of being seated at a restaurant. When you enter, you state the number of people in your group, and the host finds an empty table that fits everyone and leads you there. If someone in your group comes late, they can ask where you’ve been seated to find you.

压入栈比在堆上分配快，因为分配器永远不需要搜索存储新数据的地方；那个位置总是在栈的最顶端。相比之下，在堆上分配空间需要更多的工作，因为分配器必须首先找到一个足够大的空间来容纳数据，然后进行记账工作以准备下一次分配。

Pushing to the stack is faster than allocating on the heap because the allocator never has to search for a place to store new data; that location is always at the top of the stack. Comparatively, allocating space on the heap requires more work because the allocator must first find a big enough space to hold the data and then perform bookkeeping to prepare for the next allocation.

访问堆中的数据通常比访问栈上的数据慢，因为你必须通过指针才能到达那里。如果现代处理器在内存中跳跃较少，它们的速度会更快。继续这个类比，考虑餐厅的服务员接受许多桌子的订单。在移到下一张桌子之前，在一张桌子上拿走所有的订单是最有效的。从 A 桌拿一个订单，然后从 B 桌拿一个，然后再从 A 桌拿一个，然后再从 B 桌拿一个，这将是一个慢得多的过程。出于同样的理由，如果处理器处理与其他数据接近的数据（如在栈上），而不是较远的数据（如在堆上），它通常能更好地完成工作。

Accessing data in the heap is generally slower than accessing data on the stack because you have to follow a pointer to get there. Contemporary processors are faster if they jump around less in memory. Continuing the analogy, consider a server at a restaurant taking orders from many tables. It’s most efficient to get all the orders at one table before moving on to the next table. Taking an order from table A, then an order from table B, then one from A again, and then one from B again would be a much slower process. By the same token, a processor can usually do its job better if it works on data that’s close to other data (as it is on the stack) rather than farther away (as it can be on the heap).

当你的代码调用一个函数时，传递给函数的值（可能包括指向堆上数据的指针）和函数的局部变量会被压入栈。当函数结束时，这些值会从栈中弹出。

When your code calls a function, the values passed into the function (including, potentially, pointers to data on the heap) and the function’s local variables get pushed onto the stack. When the function is over, those values get popped off the stack.

跟踪代码的哪些部分正在使用堆上的哪些数据，最大限度地减少堆上的重复数据量，以及清理堆上未使用的数据以防止空间耗尽，这些都是所有权要解决的问题。一旦你理解了所有权，你就不需要经常考虑栈和堆了。但知道所有权的主要目的是管理堆数据，可以帮助解释它为什么以这种方式工作。

Keeping track of what parts of code are using what data on the heap, minimizing the amount of duplicate data on the heap, and cleaning up unused data on the heap so that you don’t run out of space are all problems that ownership addresses. Once you understand ownership, you won’t need to think about the stack and the heap very often. But knowing that the main purpose of ownership is to manage heap data can help explain why it works the way it does.

所有权规则

Ownership Rules

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

First, let’s take a look at the ownership rules. Keep these rules in mind as we work through the examples that illustrate them:

• Rust 中的每个值都有一个“所有者”（owner）。

• Each value in Rust has an owner.

• 同一时间只能有一个所有者。

• There can only be one owner at a time.

• 当所有者离开作用域时，该值将被丢弃。

• When the owner goes out of scope, the value will be dropped.

变量作用域

Variable Scope

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

Now that we’re past basic Rust syntax, we won’t include all the fn main() { code in the examples, so if you’re following along, make sure to put the following examples inside a main function manually. As a result, our examples will be a bit more concise, letting us focus on the actual details rather than boilerplate code.

作为所有权的第一个例子，我们将看看一些变量的作用域。“作用域”（scope）是一个项在程序中有效的范围。以以下变量为例：

As a first example of ownership, we’ll look at the scope of some variables. A scope is the range within a program for which an item is valid. Take the following variable:

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

变量 s 指向一个字符串字面量，其中字符串的值被硬编码在程序的文本中。该变量从声明点开始有效，直到当前作用域结束。示例 4-1 显示了一个带有注释说明变量 s 在何处有效的程序。

The variable s refers to a string literal, where the value of the string is hardcoded into the text of our program. The variable is valid from the point at which it’s declared until the end of the current scope. Listing 4-1 shows a program with comments annotating where the variable s would be valid.

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

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

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

In other words, there are two important points in time here:

• 当 s “进入”作用域时，它是有效的。

• When s comes into scope, it is valid.

• 它保持有效，直到它“离开”作用域。

• It remains valid until it goes out of scope.

到目前为止，作用域与变量何时有效之间的关系与其他编程语言类似。现在我们将通过引入 String 类型来在此基础上进行构建。

At this point, the relationship between scopes and when variables are valid is similar to that in other programming languages. Now we’ll build on top of this understanding by introducing the String type.

String 类型

The String Type

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

To illustrate the rules of ownership, we need a data type that is more complex than those we covered in the “Data Types” section of Chapter 3. The types covered previously are of a known size, can be stored on the stack and popped off the stack when their scope is over, and can be quickly and trivially copied to make a new, independent instance if another part of code needs to use the same value in a different scope. But we want to look at data that is stored on the heap and explore how Rust knows when to clean up that data, and the String type is a great example.

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

We’ll concentrate on the parts of String that relate to ownership. These aspects also apply to other complex data types, whether they are provided by the standard library or created by you. We’ll discuss non-ownership aspects of String in Chapter 8.

我们已经见过字符串字面量，其中字符串值被硬编码到我们的程序中。字符串字面量很方便，但它们并不适用于我们可能想要使用文本的每种情况。一个原因是它们是不可变的。另一个原因是，并非每个字符串值在我们编写代码时都能知道：例如，如果我们想要获取用户输入并存储它该怎么办？针对这些情况，Rust 提供了 String 类型。此类型管理在堆上分配的数据，因此能够存储我们在编译时未知的文本量。你可以使用 from 函数从字符串字面量创建一个 String，如下所示：

We’ve already seen string literals, where a string value is hardcoded into our program. String literals are convenient, but they aren’t suitable for every situation in which we may want to use text. One reason is that they’re immutable. Another is that not every string value can be known when we write our code: For example, what if we want to take user input and store it? It is for these situations that Rust has the String type. This type manages data allocated on the heap and as such is able to store an amount of text that is unknown to us at compile time. You can create a String from a string literal using the from function, like so:

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

双冒号 :: 运算符允许我们将这个特定的 from 函数命名空间化在 String 类型下，而不是使用类似于 string_from 之类的名称。我们将在第 5 章的“方法”部分，以及第 7 章“引用模块树中项的路径”中讨论模块命名空间时进一步讨论这种语法。

The double colon :: operator allows us to namespace this particular from function under the String type rather than using some sort of name like string_from. We’ll discuss this syntax more in the “Methods” section of Chapter 5, and when we talk about namespacing with modules in “Paths for Referring to an Item in the Module Tree” in Chapter 7.

这种字符串“可以”被修改：

This kind of string can be mutated:

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

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

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

那么，这里有什么区别呢？为什么 String 可以修改而字面量不能？区别在于这两类如何处理内存。

So, what’s the difference here? Why can String be mutated but literals cannot? The difference is in how these two types deal with memory.

内存与分配

Memory and Allocation

对于字符串字面量，我们在编译时就知道了内容，所以文本被直接硬编码到最终的可执行文件中。这就是为什么字符串字面量快速且高效的原因。但这些特性仅源于字符串字面量的不可变性。不幸的是，对于每一段在编译时大小未知且在运行程序时大小可能发生变化的文本，我们无法将一块内存放入二进制文件中。

In the case of a string literal, we know the contents at compile time, so the text is hardcoded directly into the final executable. This is why string literals are fast and efficient. But these properties only come from the string literal’s immutability. Unfortunately, we can’t put a blob of memory into the binary for each piece of text whose size is unknown at compile time and whose size might change while running the program.

使用 String 类型，为了支持可变的、可增长的文本片段，我们需要在堆上分配一定数量的内存（编译时未知）来保存内容。这意味着：

With the String type, in order to support a mutable, growable piece of text, we need to allocate an amount of memory on the heap, unknown at compile time, to hold the contents. This means:

• 必须在运行时从内存分配器请求内存。

• The memory must be requested from the memory allocator at runtime.

• 当我们用完 String 后，我们需要一种将此内存返回给分配器的方法。

• We need a way of returning this memory to the allocator when we’re done with our String.

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

That first part is done by us: When we call String::from, its implementation requests the memory it needs. This is pretty much universal in programming languages.

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

However, the second part is different. In languages with a garbage collector (GC), the GC keeps track of and cleans up memory that isn’t being used anymore, and we don’t need to think about it. In most languages without a GC, it’s our responsibility to identify when memory is no longer being used and to call code to explicitly free it, just as we did to request it. Doing this correctly has historically been a difficult programming problem. If we forget, we’ll waste memory. If we do it too early, we’ll have an invalid variable. If we do it twice, that’s a bug too. We need to pair exactly one allocate with exactly one free.

Rust 走了一条不同的路：一旦拥有内存的变量离开作用域，内存就会自动返回。这里有一个使用 String 代替字符串字面量的示例 4-1 中的作用域示例版本：

Rust takes a different path: The memory is automatically returned once the variable that owns it goes out of scope. Here’s a version of our scope example from Listing 4-1 using a String instead of a string literal:

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

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

有一个自然的时间点可以将 String 需要的内存返回给分配器：当 s 离开作用域时。当变量离开作用域时，Rust 会为我们调用一个特殊的函数。这个函数被称为 drop，String 的作者可以在其中放入返回内存的代码。Rust 在遇到闭合花括号时会自动调用 drop。

There is a natural point at which we can return the memory our String needs to the allocator: when s goes out of scope. When a variable goes out of scope, Rust calls a special function for us. This function is called drop, and it’s where the author of String can put the code to return the memory. Rust calls drop automatically at the closing curly bracket.

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

Note: In C++, this pattern of deallocating resources at the end of an item’s lifetime is sometimes called Resource Acquisition Is Initialization (RAII). The drop function in Rust will be familiar to you if you’ve used RAII patterns.

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

This pattern has a profound impact on the way Rust code is written. It may seem simple right now, but the behavior of code can be unexpected in more complicated situations when we want to have multiple variables use the data we’ve allocated on the heap. Let’s explore some of those situations now.

变量与数据交互的方式：移动

Variables and Data Interacting with Move

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

Multiple variables can interact with the same data in different ways in Rust. Listing 4-2 shows an example using an integer.

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

我们大概可以猜到这是在做什么：“将值 5 绑定到 x；然后，复制 x 中的值并将其绑定到 y。”我们现在有两个变量 x 和 y，它们都等于 5。这确实是正在发生的事情，因为整数是具有已知的固定大小的简单值，而这两个 5 值被压入栈。

We can probably guess what this is doing: “Bind the value 5 to x; then, make a copy of the value in x and bind it to y.” We now have two variables, x and y, and both equal 5. This is indeed what is happening, because integers are simple values with a known, fixed size, and these two 5 values are pushed onto the stack.

现在让我们看看 String 版本：

Now let’s look at the String version:

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

这看起来非常相似，所以我们可能会假设它的工作方式是相同的：即第二行会复制 s1 中的值并将其绑定到 s2。但这并非完全如此。

This looks very similar, so we might assume that the way it works would be the same: That is, the second line would make a copy of the value in s1 and bind it to s2. But this isn’t quite what happens.

看看图 4-1，了解 String 底层发生了什么。一个 String 由三部分组成，如左图所示：一个指向保存字符串内容的内存的指针、一个长度和一个容量。这组数据存储在栈上。右边是堆中保存内容的内存。

Take a look at Figure 4-1 to see what is happening to String under the covers. A String is made up of three parts, shown on the left: a pointer to the memory that holds the contents of the string, a length, and a capacity. This group of data is stored on the stack. On the right is the memory on the heap that holds the contents.

图 4-1：存储绑定到 s1 的值 "hello" 的 String 在内存中的表示 Figure 4-1: The representation in memory of a String holding the value "hello" bound to s1

长度是 String 内容当前使用的内存量（以字节为单位）。容量是 String 从分配器接收到的内存总量（以字节为单位）。长度和容量之间的差异很重要，但在这种情况下并不重要，所以现在可以忽略容量。

The length is how much memory, in bytes, the contents of the String are currently using. The capacity is the total amount of memory, in bytes, that the String has received from the allocator. The difference between length and capacity matters, but not in this context, so for now, it’s fine to ignore the capacity.

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

When we assign s1 to s2, the String data is copied, meaning we copy the pointer, the length, and the capacity that are on the stack. We do not copy the data on the heap that the pointer refers to. In other words, the data representation in memory looks like Figure 4-2.

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

这种表示“并不”像图 4-3 所示，如果 Rust 同时也复制了堆数据，内存就会是这个样子。如果 Rust 这样做，如果堆上的数据很大，操作 s2 = s1 可能会在运行时性能方面非常昂贵。

The representation does not look like Figure 4-3, which is what memory would look like if Rust instead copied the heap data as well. If Rust did this, the operation s2 = s1 could be very expensive in terms of runtime performance if the data on the heap were large.

图 4-3：如果 Rust 也复制堆数据，s2 = s1 可能做的另一种可能性 Figure 4-3: Another possibility for what s2 = s1 might do if Rust copied the heap data as well

之前我们说过，当变量离开作用域时，Rust 会自动调用 drop 函数并为该变量清理堆内存。但图 4-2 显示两个数据指针指向同一个位置。这是一个问题：当 s2 和 s1 离开作用域时，它们都会尝试释放相同的内存。这被称为“二次释放”（double free）错误，是我们之前提到的内存安全漏洞之一。释放两次内存会导致内存损坏，这可能会导致安全漏洞。

Earlier, we said that when a variable goes out of scope, Rust automatically calls the drop function and cleans up the heap memory for that variable. But Figure 4-2 shows both data pointers pointing to the same location. This is a problem: When s2 and s1 go out of scope, they will both try to free the same memory. This is known as a double free error and is one of the memory safety bugs we mentioned previously. Freeing memory twice can lead to memory corruption, which can potentially lead to security vulnerabilities.

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

To ensure memory safety, after the line let s2 = s1;, Rust considers s1 as no longer valid. Therefore, Rust doesn’t need to free anything when s1 goes out of scope. Check out what happens when you try to use s1 after s2 is created; it won’t work:

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

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

你会得到如下错误，因为 Rust 阻止你使用已失效的引用：

You’ll get an error like this because Rust prevents you from using the invalidated reference:

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

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

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

If you’ve heard the terms shallow copy and deep copy while working with other languages, the concept of copying the pointer, length, and capacity without copying the data probably sounds like making a shallow copy. But because Rust also invalidates the first variable, instead of being called a shallow copy, it’s known as a move. In this example, we would say that s1 was moved into s2. So, what actually happens is shown in Figure 4-4.

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

这解决了我们的问题！只有 s2 有效，当它离开作用域时，只有它会释放内存，任务完成。

That solves our problem! With only s2 valid, when it goes out of scope it alone will free the memory, and we’re done.

此外，这隐含了一个设计选择：Rust 永远不会自动创建数据的“深”拷贝。因此，任何“自动”复制都可以被认为是运行时性能开销较小的。

In addition, there’s a design choice that’s implied by this: Rust will never automatically create “deep” copies of your data. Therefore, any automatic copying can be assumed to be inexpensive in terms of runtime performance.

作用域与赋值

Scope and Assignment

反过来，对于作用域、所有权与通过 drop 函数释放内存之间的关系也是如此。当你给现有变量分配一个全新的值时，Rust 会立即调用 drop 并释放原始值的内存。例如，考虑这段代码：

The inverse of this is true for the relationship between scoping, ownership, and memory being freed via the drop function as well. When you assign a completely new value to an existing variable, Rust will call drop and free the original value’s memory immediately. Consider this code, for example:

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

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

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

We initially declare a variable s and bind it to a String with the value "hello". Then, we immediately create a new String with the value "ahoy" and assign it to s. At this point, nothing is referring to the original value on the heap at all. Figure 4-5 illustrates the stack and heap data now:

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

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

The original string thus immediately goes out of scope. Rust will run the drop function on it and its memory will be freed right away. When we print the value at the end, it will be "ahoy, world!".

变量与数据交互的方式：克隆

Variables and Data Interacting with Clone

如果我们“确实”想要深度复制 String 的堆数据，而不只是栈数据，我们可以使用一个常用的方法叫做 clone。我们将在第 5 章讨论方法语法，但因为方法在许多编程语言中都是一个通用功能，你可能以前见过它们。

If we do want to deeply copy the heap data of the String, not just the stack data, we can use a common method called clone. We’ll discuss method syntax in Chapter 5, but because methods are a common feature in many programming languages, you’ve probably seen them before.

这是 clone 方法的一个示例：

Here’s an example of the clone method in action:

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

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

这工作得很好，并显式地产生了如图 4-3 所示的行为，即堆数据“确实”被复制了。

This works just fine and explicitly produces the behavior shown in Figure 4-3, where the heap data does get copied.

当你看到对 clone 的调用时，你就知道某些任意代码正在被执行，并且该代码可能开销很大。这是一个视觉指示，表明正在发生一些不同的事情。

When you see a call to clone, you know that some arbitrary code is being executed and that code may be expensive. It’s a visual indicator that something different is going on.

只在栈上的数据：拷贝

Stack-Only Data: Copy

还有一个我们还没谈到的细节。这段使用整数的代码（其中一部分在示例 4-2 中显示）是有效且可以运行的：

There’s another wrinkle we haven’t talked about yet. This code using integers—part of which was shown in Listing 4-2—works and is valid:

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

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

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

But this code seems to contradict what we just learned: We don’t have a call to clone, but x is still valid and wasn’t moved into y.

原因是像整数这样在编译时具有已知大小的类型完全存储在栈上，所以实际值的副本可以快速制作。这意味着没有理由在我们创建变量 y 后阻止 x 继续有效。换句话说，这里深拷贝和浅拷贝没有区别，所以调用 clone 不会做任何与通常的浅拷贝不同的事情，我们可以省略它。

The reason is that types such as integers that have a known size at compile time are stored entirely on the stack, so copies of the actual values are quick to make. That means there’s no reason we would want to prevent x from being valid after we create the variable y. In other words, there’s no difference between deep and shallow copying here, so calling clone wouldn’t do anything different from the usual shallow copying, and we can leave it out.

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

Rust has a special annotation called the Copy trait that we can place on types that are stored on the stack, as integers are (we’ll talk more about traits in Chapter 10). If a type implements the Copy trait, variables that use it do not move, but rather are trivially copied, making them still valid after assignment to another variable.

如果一个类型或其任何部分实现了 Drop trait，Rust 将不允许我们用 Copy 来注解该类型。如果该类型在值离开作用域时需要发生一些特殊处理，而我们又给该类型添加了 Copy 注解，我们就会得到一个编译时错误。要了解如何向你的类型添加 Copy 注解以实现该 trait，请参阅附录 C 中的“派生 Trait”。

Rust won’t let us annotate a type with Copy if the type, or any of its parts, has implemented the Drop trait. If the type needs something special to happen when the value goes out of scope and we add the Copy annotation to that type, we’ll get a compile-time error. To learn about how to add the Copy annotation to your type to implement the trait, see “Derivable Traits” in Appendix C.

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

So, what types implement the Copy trait? You can check the documentation for the given type to be sure, but as a general rule, any group of simple scalar values can implement Copy, and nothing that requires allocation or is some form of resource can implement Copy. Here are some of the types that implement Copy:

• 所有整数类型，如 u32。

• All the integer types, such as u32.

• 布尔类型 bool，值为 true 和 false。

• The Boolean type, bool, with values true and false.

• 所有浮点类型，如 f64。

• All the floating-point types, such as f64.

• 字符类型 char。

• The character type, char.

• 元组，如果它们仅包含也实现 Copy 的类型。例如，(i32, i32) 实现了 Copy，但 (i32, String) 不实现。

• Tuples, if they only contain types that also implement Copy. For example, (i32, i32) implements Copy, but (i32, String) does not.

所有权与函数

Ownership and Functions

将值传递给函数机制与将值赋给变量的机制类似。向函数传递变量将发生移动或复制，就像赋值一样。示例 4-3 有一个带有注释的例子，显示了变量进入和离开作用域的位置。

The mechanics of passing a value to a function are similar to those when assigning a value to a variable. Passing a variable to a function will move or copy, just as assignment does. Listing 4-3 has an example with some annotations showing where variables go into and out of scope.

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

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

    let x = 5;                      // x comes into scope

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

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

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

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

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

If we tried to use s after the call to takes_ownership, Rust would throw a compile-time error. These static checks protect us from mistakes. Try adding code to main that uses s and x to see where you can use them and where the ownership rules prevent you from doing so.

返回值与作用域

Return Values and Scope

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

Returning values can also transfer ownership. Listing 4-4 shows an example of a function that returns some value, with similar annotations as those in Listing 4-3.

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

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

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

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

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

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

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

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

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

The ownership of a variable follows the same pattern every time: Assigning a value to another variable moves it. When a variable that includes data on the heap goes out of scope, the value will be cleaned up by drop unless ownership of the data has been moved to another variable.

虽然这可行，但在每个函数中获取所有权然后返回所有权有点乏味。如果我们想让函数使用值但不获取所有权呢？非常恼人的是，如果我们想再次使用它，任何我们传入的东西也需要被传回来，此外还可能需要返回函数体产生的任何数据。

While this works, taking ownership and then returning ownership with every function is a bit tedious. What if we want to let a function use a value but not take ownership? It’s quite annoying that anything we pass in also needs to be passed back if we want to use it again, in addition to any data resulting from the body of the function that we might want to return as well.

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

Rust does let us return multiple values using a tuple, as shown in Listing 4-5.

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

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

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

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

    (s, length)
}

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

But this is too much ceremony and a lot of work for a concept that should be common. Luckily for us, Rust has a feature for using a value without transferring ownership: references.

引用与借用

引用与借用

References and Borrowing

示例 4-5 中元组代码的问题在于，我们必须将 String 返回给调用函数，以便在调用 calculate_length 之后仍能使用该 String，因为 String 已被移动到了 calculate_length 中。相反，我们可以提供对 String 值的“引用”（reference）。引用类似于指针，因为它是一个地址，我们可以跟随该地址访问存储在该地址的数据；该数据由其他某个变量所有。与指针不同，引用保证在引用的生命周期内指向特定类型的有效值。

The issue with the tuple code in Listing 4-5 is that we have to return the String to the calling function so that we can still use the String after the call to calculate_length, because the String was moved into calculate_length. Instead, we can provide a reference to the String value. A reference is like a pointer in that it’s an address we can follow to access the data stored at that address; that data is owned by some other variable. Unlike a pointer, a reference is guaranteed to point to a valid value of a particular type for the life of that reference.

下面是你如何定义和使用一个 calculate_length 函数，该函数将对象的引用作为参数，而不是获取值的所有权：

Here is how you would define and use a calculate_length function that has a reference to an object as a parameter instead of taking ownership of the value:

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

    let len = calculate_length(&s1);

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

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

首先，请注意变量声明和函数返回值中的所有元组代码都消失了。其次，请注意我们将 &s1 传递给 calculate_length，并且在其定义中，我们接收 &String 而不是 String。这些 & 符号代表“引用”，它们允许你引用某个值而不获取其所有权。图 4-6 描绘了这个概念。

First, notice that all the tuple code in the variable declaration and the function return value is gone. Second, note that we pass &s1 into calculate_length and, in its definition, we take &String rather than String. These ampersands represent references, and they allow you to refer to some value without taking ownership of it. Figure 4-6 depicts this concept.

图 4-6：&String s 指向 String s1 的图解 Figure 4-6: A diagram of &String s pointing at String s1

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

Note: The opposite of referencing by using & is dereferencing, which is accomplished with the dereference operator, *. We’ll see some uses of the dereference operator in Chapter 8 and discuss details of dereferencing in Chapter 15.

让我们仔细看看这里的函数调用：

Let’s take a closer look at the function call here:

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

    let len = calculate_length(&s1);

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

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

&s1 语法允许我们创建一个引用，该引用“引用”了 s1 的值，但不拥有它。因为引用不拥有它，所以当引用停止使用时，它指向的值不会被丢弃。

The &s1 syntax lets us create a reference that refers to the value of s1 but does not own it. Because the reference does not own it, the value it points to will not be dropped when the reference stops being used.

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

Likewise, the signature of the function uses & to indicate that the type of the parameter s is a reference. Let’s add some explanatory annotations:

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

    let len = calculate_length(&s1);

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

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

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

The scope in which the variable s is valid is the same as any function parameter’s scope, but the value pointed to by the reference is not dropped when s stops being used, because s doesn’t have ownership. When functions have references as parameters instead of the actual values, we won’t need to return the values in order to give back ownership, because we never had ownership.

我们将创建引用的行为称为“借用”（borrowing）。就像在现实生活中一样，如果一个人拥有某样东西，你可以从他们那里借用。当你用完后，你必须还回去。你不拥有它。

We call the action of creating a reference borrowing. As in real life, if a person owns something, you can borrow it from them. When you’re done, you have to give it back. You don’t own it.

那么，如果我们尝试修改借来的东西会发生什么呢？尝试示例 4-6 中的代码。剧透警告：它行不通！

So, what happens if we try to modify something we’re borrowing? Try the code in Listing 4-6. Spoiler alert: It doesn’t work!

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

    change(&s);
}

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

这是错误信息：

Here’s the error:

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

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

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

Just as variables are immutable by default, so are references. We’re not allowed to modify something we have a reference to.

可变引用

Mutable References

我们可以修复示例 4-6 中的代码，通过一些小改动来允许我们修改借用的值，即改用“可变引用”（mutable reference）：

We can fix the code from Listing 4-6 to allow us to modify a borrowed value with just a few small tweaks that use, instead, a mutable reference:

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

    change(&mut s);
}

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

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

First, we change s to be mut. Then, we create a mutable reference with &mut s where we call the change function and update the function signature to accept a mutable reference with some_string: &mut String. This makes it very clear that the change function will mutate the value it borrows.

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

Mutable references have one big restriction: If you have a mutable reference to a value, you can have no other references to that value. This code that attempts to create two mutable references to s will fail:

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

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

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

这是错误信息：

Here’s the error:

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

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

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

This error says that this code is invalid because we cannot borrow s as mutable more than once at a time. The first mutable borrow is in r1 and must last until it’s used in the println!, but between the creation of that mutable reference and its usage, we tried to create another mutable reference in r2 that borrows the same data as r1.

限制在同一时间内对同一数据进行多个可变引用，是为了以一种非常受控的方式允许修改。这是新 Rustacean 感到吃力的地方，因为大多数语言允许你随时随地进行修改。拥有此限制的好处是 Rust 可以在编译时防止数据竞争。“数据竞争”（data race）类似于竞态条件，当发生以下三种行为时会发生：

The restriction preventing multiple mutable references to the same data at the same time allows for mutation but in a very controlled fashion. It’s something that new Rustaceans struggle with because most languages let you mutate whenever you’d like. The benefit of having this restriction is that Rust can prevent data races at compile time. A data race is similar to a race condition and happens when these three behaviors occur:

• 两个或多个指针同时访问相同的数据。

• Two or more pointers access the same data at the same time.

• 至少有一个指针被用于向数据写入。

• At least one of the pointers is being used to write to the data.

• 没有使用任何机制来同步对数据的访问。

• There’s no mechanism being used to synchronize access to the data.

数据竞争会导致未定义行为，并且当你尝试在运行时追踪它们时，可能难以诊断和修复；Rust 通过拒绝编译具有数据竞争的代码来防止此问题！

Data races cause undefined behavior and can be difficult to diagnose and fix when you’re trying to track them down at runtime; Rust prevents this problem by refusing to compile code with data races!

一如既往，我们可以使用花括号来创建一个新作用域，从而允许存在多个可变引用，只是不能是“同时”存在的：

As always, we can use curly brackets to create a new scope, allowing for multiple mutable references, just not simultaneous ones:

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

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

    let r2 = &mut s;
}

Rust 对于结合可变引用和不可变引用也强制执行类似的规则。这段代码会导致错误：

Rust enforces a similar rule for combining mutable and immutable references. This code results in an error:

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

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

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

这是错误信息：

Here’s the error:

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

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

哇！当我们对同一个值有一个不可变引用时，我们“也”不能有一个可变引用。

Whew! We also cannot have a mutable reference while we have an immutable one to the same value.

不可变引用的使用者不希望值在他们眼皮底下突然改变！然而，允许存在多个不可变引用，因为仅仅读取数据的人都没有能力影响其他人读取数据。

Users of an immutable reference don’t expect the value to suddenly change out from under them! However, multiple immutable references are allowed because no one who is just reading the data has the ability to affect anyone else’s reading of the data.

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

Note that a reference’s scope starts from where it is introduced and continues through the last time that reference is used. For instance, this code will compile because the last usage of the immutable references is in the println!, before the mutable reference is introduced:

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

    let r1 = &s; // no problem
    let r2 = &s; // no problem
    println!("{r1} and {r2}");
    // Variables r1 and r2 will not be used after this point.

    let r3 = &mut s; // no problem
    println!("{r3}");
}

不可变引用 r1 和 r2 的作用域在它们最后一次使用的 println! 之后结束，这发生在创建可变引用 r3 之前。这些作用域不重叠，所以此代码是被允许的：编译器可以判断出在作用域结束之前的某个点，引用已不再被使用。

The scopes of the immutable references r1 and r2 end after the println! where they are last used, which is before the mutable reference r3 is created. These scopes don’t overlap, so this code is allowed: The compiler can tell that the reference is no longer being used at a point before the end of the scope.

尽管借用错误有时可能令人沮丧，但请记住，这是 Rust 编译器在尽早（在编译时而不是在运行时）指出潜在的错误，并向你显示问题的确切位置。这样，你就不必追踪为什么你的数据不是你想象中的那样了。

Even though borrowing errors may be frustrating at times, remember that it’s the Rust compiler pointing out a potential bug early (at compile time rather than at runtime) and showing you exactly where the problem is. Then, you don’t have to track down why your data isn’t what you thought it was.

悬垂引用

Dangling References

在具有指针的语言中，很容易由于释放了一些内存而保留了指向该内存的指针，从而错误地创建了“悬垂指针”（dangling pointer）——即引用了一个可能已被分配给其他人的内存位置的指针。相比之下，在 Rust 中，编译器保证引用永远不会是悬垂引用：如果你有一个对某些数据的引用，编译器将确保数据在引用离开作用域之前不会离开作用域。

In languages with pointers, it’s easy to erroneously create a dangling pointer—a pointer that references a location in memory that may have been given to someone else—by freeing some memory while preserving a pointer to that memory. In Rust, by contrast, the compiler guarantees that references will never be dangling references: If you have a reference to some data, the compiler will ensure that the data will not go out of scope before the reference to the data does.

让我们尝试创建一个悬垂引用，看看 Rust 如何通过编译时错误来防止它们：

Let’s try to create a dangling reference to see how Rust prevents them with a compile-time error:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String {
    let s = String::from("hello");

    &s
}

这是错误信息：

Here’s the error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0106]: missing lifetime specifier
 --> src/main.rs:5:16
  |
5 | fn dangle() -> &String {
  |                ^ expected named lifetime parameter
  |
  = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from
help: consider using the `'static` lifetime, but this is uncommon unless you're returning a borrowed value from a `const` or a `static`
  |
5 | fn dangle() -> &'static String {
  |                 +++++++
help: instead, you are more likely to want to return an owned value
  |
5 - fn dangle() -> &String {
5 + fn dangle() -> String {
  |

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

此错误消息提到了一个我们尚未介绍的功能：生命周期。我们将在第 10 章详细讨论生命周期。但是，如果你忽略关于生命周期的部分，该消息确实包含了此代码为何存在问题的关键：

This error message refers to a feature we haven’t covered yet: lifetimes. We’ll discuss lifetimes in detail in Chapter 10. But, if you disregard the parts about lifetimes, the message does contain the key to why this code is a problem:

this function's return type contains a borrowed value, but there is no value
for it to be borrowed from

让我们仔细看看 dangle 代码的每个阶段究竟发生了什么：

Let’s take a closer look at exactly what’s happening at each stage of our dangle code:

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope and is dropped, so its memory goes away.
  // Danger!

因为 s 是在 dangle 内部创建的，当 dangle 的代码运行结束时，s 将被释放。但我们尝试返回一个指向它的引用。这意味着此引用将指向一个无效的 String。这可不行！Rust 不会让我们这样做。

Because s is created inside dangle, when the code of dangle is finished, s will be deallocated. But we tried to return a reference to it. That means this reference would be pointing to an invalid String. That’s no good! Rust won’t let us do this.

这里的解决方案是直接返回 String：

The solution here is to return the String directly:

fn main() {
    let string = no_dangle();
}

fn no_dangle() -> String {
    let s = String::from("hello");

    s
}

这没有任何问题。所有权被移出，没有任何东西被释放。

This works without any problems. Ownership is moved out, and nothing is deallocated.

引用的规则

The Rules of References

让我们回顾一下我们讨论过的关于引用的内容：

Let’s recap what we’ve discussed about references:

• 在任何给定的时间，你要么只能有一个可变引用，要么可以有任意数量的不可变引用。

• At any given time, you can have either one mutable reference or any number of immutable references.

• 引用必须始终有效。

• References must always be valid.

接下来，我们将看看另一种引用：切片（slices）。

Next, we’ll look at a different kind of reference: slices.

切片类型

切片类型

The Slice Type

“切片”（Slices）允许你引用集合中一段连续的元素序列。切片是一种引用，因此它不具有所有权。

Slices let you reference a contiguous sequence of elements in a collection. A slice is a kind of reference, so it does not have ownership.

这里有一个小的编程问题：编写一个函数，接收一个由空格分隔的单词字符串，并返回它在该字符串中找到的第一个单词。如果函数在字符串中没有找到空格，则说明整个字符串就是一个单词，因此应该返回整个字符串。

Here’s a small programming problem: Write a function that takes a string of words separated by spaces and returns the first word it finds in that string. If the function doesn’t find a space in the string, the whole string must be one word, so the entire string should be returned.

注意：为了介绍切片，我们在本节中仅假设 ASCII 编码；关于 UTF-8 处理的更透彻讨论见第 8 章的“使用字符串存储 UTF-8 编码的文本”部分。

Note: For the purposes of introducing slices, we are assuming ASCII only in this section; a more thorough discussion of UTF-8 handling is in the “Storing UTF-8 Encoded Text with Strings” section of Chapter 8.

让我们看看在不使用切片的情况下如何编写此函数的签名，以理解切片将解决的问题：

Let’s work through how we’d write the signature of this function without using slices, to understand the problem that slices will solve:

fn first_word(s: &String) -> ?

first_word 函数有一个 &String 类型的参数。我们不需要所有权，所以这没问题。（在惯用的 Rust 中，除非需要，否则函数不会获取参数的所有权，随着深入学习，其原因会变得更加清晰。）但是我们应该返回什么呢？我们并没有一个真正的方法来谈论字符串的“一部分”。但是，我们可以返回由空格指示的单词结尾的索引。让我们尝试一下，如示例 4-7 所示。

The first_word function has a parameter of type &String. We don’t need ownership, so this is fine. (In idiomatic Rust, functions do not take ownership of their arguments unless they need to, and the reasons for that will become clear as we keep going.) But what should we return? We don’t really have a way to talk about part of a string. However, we could return the index of the end of the word, indicated by a space. Let’s try that, as shown in Listing 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

因为我们需要逐个检查 String 的元素并判断是否为空格，所以我们将使用 as_bytes 方法将 String 转换为字节数组。

Because we need to go through the String element by element and check whether a value is a space, we’ll convert our String to an array of bytes using the as_bytes method.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

接下来，我们使用 iter 方法在字节数组上创建一个迭代器：

Next, we create an iterator over the array of bytes using the iter method:

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

我们将在第 13 章中更详细地讨论迭代器。现在，你只需知道 iter 是一个返回集合中每个元素的方法，而 enumerate 包装了 iter 的结果，并将每个元素作为元组的一部分返回。enumerate 返回的元组的第一个元素是索引，第二个元素是该元素的引用。这比我们自己计算索引要方便一些。

We’ll discuss iterators in more detail in Chapter 13. For now, know that iter is a method that returns each element in a collection and that enumerate wraps the result of iter and returns each element as part of a tuple instead. The first element of the tuple returned from enumerate is the index, and the second element is a reference to the element. This is a bit more convenient than calculating the index ourselves.

因为 enumerate 方法返回一个元组，所以我们可以使用模式来解构该元组。我们将在第 6 章中更多地讨论模式。在 for 循环中，我们指定了一个模式，其中 i 代表元组中的索引，而 &item 代表元组中的单个字节。因为我们从 .iter().enumerate() 获得的是元素的引用，所以我们在模式中使用 &。

Because the enumerate method returns a tuple, we can use patterns to destructure that tuple. We’ll be discussing patterns more in Chapter 6. In the for loop, we specify a pattern that has i for the index in the tuple and &item for the single byte in the tuple. Because we get a reference to the element from .iter().enumerate(), we use & in the pattern.

在 for 循环内部，我们使用字节字面量语法搜索代表空格的字节。如果找到了空格，我们就返回该位置。否则，我们通过使用 s.len() 返回字符串的长度。

Inside the for loop, we search for the byte that represents the space by using the byte literal syntax. If we find a space, we return the position. Otherwise, we return the length of the string by using s.len().

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {}

现在我们有了一种找出字符串中第一个单词结尾索引的方法，但这里有一个问题。我们单独返回了一个 usize，但它只有在 &String 的上下文中才是有意义的数字。换句话说，因为它是一个与 String 分离的值，所以无法保证它在将来仍然有效。考虑示例 4-8 中使用了示例 4-7 中 first_word 函数的程序。

We now have a way to find out the index of the end of the first word in the string, but there’s a problem. We’re returning a usize on its own, but it’s only a meaningful number in the context of the &String. In other words, because it’s a separate value from the String, there’s no guarantee that it will still be valid in the future. Consider the program in Listing 4-8 that uses the first_word function from Listing 4-7.

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

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

    let word = first_word(&s); // word will get the value 5

    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but s no longer has any content that we
    // could meaningfully use with the value 5, so word is now totally invalid!
}

这个程序编译时不会报错，即使我们在调用 s.clear() 之后使用 word 也是如此。因为 word 与 s 的状态完全没有联系，所以 word 仍然包含值 5。我们可以将值 5 与变量 s 配合使用，尝试提取出第一个单词，但这将是一个错误，因为自我们将 5 保存到 word 以来，s 的内容已经发生了变化。

This program compiles without any errors and would also do so if we used word after calling s.clear(). Because word isn’t connected to the state of s at all, word still contains the value 5. We could use that value 5 with the variable s to try to extract the first word out, but this would be a bug because the contents of s have changed since we saved 5 in word.

必须担心 word 中的索引与 s 中的数据不同步是乏味且容易出错的！如果我们编写一个 second_word 函数，管理这些索引会变得更加脆弱。它的签名必须看起来像这样：

Having to worry about the index in word getting out of sync with the data in s is tedious and error-prone! Managing these indices is even more brittle if we write a second_word function. Its signature would have to look like this:

fn second_word(s: &String) -> (usize, usize) {

现在我们正在跟踪起始索引“和”结束索引，我们甚至有更多从特定状态的数据计算出来的、但与该状态完全没有关联的值。我们有三个不相关的变量散落在各处，需要保持同步。

Now we’re tracking a starting and an ending index, and we have even more values that were calculated from data in a particular state but aren’t tied to that state at all. We have three unrelated variables floating around that need to be kept in sync.

幸运的是，Rust 有一个解决这个问题的方案：字符串切片（string slices）。

Luckily, Rust has a solution to this problem: string slices.

字符串切片

String Slices

“字符串切片”（string slice）是对 String 中连续元素序列的引用，它看起来像这样：

A string slice is a reference to a contiguous sequence of the elements of a String, and it looks like this:

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

    let hello = &s[0..5];
    let world = &s[6..11];
}

hello 不是对整个 String 的引用，而是对 String 一部分的引用，这由额外的 [0..5] 指定。我们通过在方括号内指定 [starting_index..ending_index] 来创建切片，其中 starting_index 是切片中的第一个位置，而 ending_index 比切片中的最后一个位置大一。在内部，切片数据结构存储切片的起始位置和长度，长度对应于 ending_index 减去 starting_index。所以，在 let world = &s[6..11]; 的情况下，world 将是一个包含指向 s 索引 6 处字节的指针以及长度值 5 的切片。

Rather than a reference to the entire String, hello is a reference to a portion of the String, specified in the extra [0..5] bit. We create slices using a range within square brackets by specifying [starting_index..ending_index], where starting_index is the first position in the slice and ending_index is one more than the last position in the slice. Internally, the slice data structure stores the starting position and the length of the slice, which corresponds to ending_index minus starting_index. So, in the case of let world = &s[6..11];, world would be a slice that contains a pointer to the byte at index 6 of s with a length value of 5.

图 4-7 的图示显示了这一点。

Figure 4-7 shows this in a diagram.

图 4-7：引用 String 一部分的字符串切片 Figure 4-7: A string slice referring to part of a String

使用 Rust 的 .. 范围语法，如果你想从索引 0 开始，可以省略两个点之前的值。换句话说，以下写法是等价的：

With Rust’s .. range syntax, if you want to start at index 0, you can drop the value before the two periods. In other words, these are equal:

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

let slice = &s[0..2];
let slice = &s[..2];
}

同理，如果你的切片包含 String 的最后一个字节，你可以省略末尾的数字。这意味着以下写法是等价的：

By the same token, if your slice includes the last byte of the String, you can drop the trailing number. That means these are equal:

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

let len = s.len();

let slice = &s[3..len];
let slice = &s[3..];
}

你也可以省略两个值来获取整个字符串的切片。所以，以下写法是等价的：

You can also drop both values to take a slice of the entire string. So, these are equal:

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

let len = s.len();

let slice = &s[0..len];
let slice = &s[..];
}

注意：字符串切片范围索引必须位于有效的 UTF-8 字符边界处。如果你尝试在多字节字符中间创建字符串切片，你的程序将因错误而退出。

Note: String slice range indices must occur at valid UTF-8 character boundaries. If you attempt to create a string slice in the middle of a multibyte character, your program will exit with an error.

了解了这些信息后，让我们重写 first_word 以返回一个切片。代表“字符串切片”的类型写作 &str：

With all this information in mind, let’s rewrite first_word to return a slice. The type that signifies “string slice” is written as &str:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

fn main() {}

我们以与示例 4-7 相同的方式获取单词结尾的索引，即寻找第一次出现的空格。当我们找到空格时，我们使用字符串的开头和空格索引作为起始和结束索引返回一个字符串切片。

We get the index for the end of the word the same way we did in Listing 4-7, by looking for the first occurrence of a space. When we find a space, we return a string slice using the start of the string and the index of the space as the starting and ending indices.

现在当我们调用 first_word 时，我们得到一个与底层数据相关联的单一值。该值由切片起始点的引用和切片中的元素数量组成。

Now when we call first_word, we get back a single value that is tied to the underlying data. The value is made up of a reference to the starting point of the slice and the number of elements in the slice.

返回切片对于 second_word 函数也同样有效：

Returning a slice would also work for a second_word function:

fn second_word(s: &String) -> &str {

我们现在拥有了一个简单直观的 API，它更不容易出错，因为编译器将确保对 String 的引用保持有效。还记得示例 4-8 程序中的错误吗？当时我们获取了第一个单词结尾的索引，但随后清空了字符串，导致索引无效。那段代码逻辑上是不正确的，但没有显示任何即时错误。如果我们继续在清空后的字符串上使用第一个单词的索引，问题稍后就会显现。切片使这种错误变得不可能，并让我们更早地知道代码存在问题。使用切片版本的 first_word 将抛出编译时错误：

We now have a straightforward API that’s much harder to mess up because the compiler will ensure that the references into the String remain valid. Remember the bug in the program in Listing 4-8, when we got the index to the end of the first word but then cleared the string so our index was invalid? That code was logically incorrect but didn’t show any immediate errors. The problems would show up later if we kept trying to use the first word index with an emptied string. Slices make this bug impossible and let us know much sooner that we have a problem with our code. Using the slice version of first_word will throw a compile-time error:

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    let word = first_word(&s);

    s.clear(); // error!

    println!("the first word is: {word}");
}

这是编译器错误：

Here’s the compiler error:

$ cargo run
   Compiling ownership v0.1.0 (file:///projects/ownership)
error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable
  --> src/main.rs:18:5
   |
16 |     let word = first_word(&s);
   |                           -- immutable borrow occurs here
17 |
18 |     s.clear(); // error!
   |     ^^^^^^^^^ mutable borrow occurs here
19 |
20 |     println!("the first word is: {word}");
   |                                   ---- immutable borrow later used here

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

回想借用规则，如果我们对某样东西有一个不可变引用，我们就不能同时也获得一个可变引用。因为 clear 需要截断 String，所以它需要获得一个可变引用。在调用 clear 之后的 println! 使用了 word 中的引用，所以此时不可变引用必须仍然有效。Rust 不允许 clear 中的可变引用和 word 中的不可变引用同时存在，编译失败。Rust 不仅使我们的 API 更易于使用，还在编译时消除了一整类错误！

Recall from the borrowing rules that if we have an immutable reference to something, we cannot also take a mutable reference. Because clear needs to truncate the String, it needs to get a mutable reference. The println! after the call to clear uses the reference in word, so the immutable reference must still be active at that point. Rust disallows the mutable reference in clear and the immutable reference in word from existing at the same time, and compilation fails. Not only has Rust made our API easier to use, but it has also eliminated an entire class of errors at compile time!

字符串字面量作为切片

String Literals as Slices

回想一下我们谈到的字符串字面量存储在二进制文件内部。现在我们了解了切片，就可以正确理解字符串字面量了：

Recall that we talked about string literals being stored inside the binary. Now that we know about slices, we can properly understand string literals:

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

这里 s 的类型是 &str：它是一个指向二进制文件特定点的切片。这也是为什么字符串字面量是不可变的；&str 是一个不可变引用。

The type of s here is &str: It’s a slice pointing to that specific point of the binary. This is also why string literals are immutable; &str is an immutable reference.

字符串切片作为参数

String Slices as Parameters

既然知道可以获取字面量和 String 值的切片，这引导我们对 first_word 进行最后一项改进，那就是它的签名：

Knowing that you can take slices of literals and String values leads us to one more improvement on first_word, and that’s its signature:

fn first_word(s: &String) -> &str {

经验丰富的 Rustacean 会改写为示例 4-9 所示的签名，因为它允许我们在 &String 值和 &str 值上使用相同的函数。

A more experienced Rustacean would write the signature shown in Listing 4-9 instead because it allows us to use the same function on both &String values and &str values.

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

如果我们有一个字符串切片，我们可以直接传递它。如果我们有一个 String，我们可以传递 String 的切片或对 String 的引用。这种灵活性利用了“解引用强制转换”（deref coercions），这是我们将在第 15 章的“在函数和方法中使用解引用强制转换”部分介绍的功能。

If we have a string slice, we can pass that directly. If we have a String, we can pass a slice of the String or a reference to the String. This flexibility takes advantage of deref coercions, a feature we will cover in the “Using Deref Coercions in Functions and Methods” section of Chapter 15.

定义一个接受字符串切片而不是 String 引用的函数，可以使我们的 API 在不丢失任何功能的情况下更加通用和有用：

Defining a function to take a string slice instead of a reference to a String makes our API more general and useful without losing any functionality:

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }

    &s[..]
}

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

    // `first_word` works on slices of `String`s, whether partial or whole.
    let word = first_word(&my_string[0..6]);
    let word = first_word(&my_string[..]);
    // `first_word` also works on references to `String`s, which are equivalent
    // to whole slices of `String`s.
    let word = first_word(&my_string);

    let my_string_literal = "hello world";

    // `first_word` works on slices of string literals, whether partial or
    // whole.
    let word = first_word(&my_string_literal[0..6]);
    let word = first_word(&my_string_literal[..]);

    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    let word = first_word(my_string_literal);
}

其他切片

Other Slices

正如你可能想象的那样，字符串切片是专门针对字符串的。但也有更通用的切片类型。考虑这个数组：

String slices, as you might imagine, are specific to strings. But there’s a more general slice type too. Consider this array:

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

正如我们可能想要引用字符串的一部分一样，我们也可能想要引用数组的一部分。我们会这样做：

Just as we might want to refer to part of a string, we might want to refer to part of an array. We’d do so like this:

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

let slice = &a[1..3];

assert_eq!(slice, &[2, 3]);
}

该切片的类型是 &[i32]。它的工作方式与字符串切片相同，通过存储首个元素的引用和长度。你将对各种其他集合使用此类切片。我们将在第 8 章讨论 vector 时详细讨论这些集合。

This slice has the type &[i32]. It works the same way as string slices do, by storing a reference to the first element and a length. You’ll use this kind of slice for all sorts of other collections. We’ll discuss these collections in detail when we talk about vectors in Chapter 8.

总结

Summary

所有权、借用和切片的概念确保了 Rust 程序在编译时的内存安全。Rust 语言赋予你像其他系统编程语言一样控制内存使用的权力。但是，让数据的所有者在所有者离开作用域时自动清理该数据，意味着你不需要为了获得这种控制权而编写和调试额外的代码。

The concepts of ownership, borrowing, and slices ensure memory safety in Rust programs at compile time. The Rust language gives you control over your memory usage in the same way as other systems programming languages. But having the owner of data automatically clean up that data when the owner goes out of scope means you don’t have to write and debug extra code to get this control.

所有权影响了 Rust 的许多其他部分的运作方式，因此我们将在本书的后续章节中进一步讨论这些概念。让我们继续进入第 5 章，看看如何在 struct（结构体）中对多块数据进行分组。

Ownership affects how lots of other parts of Rust work, so we’ll talk about these concepts further throughout the rest of the book. Let’s move on to Chapter 5 and look at grouping pieces of data together in a struct.

使用结构体来组织相关数据

Using Structs to Structure Related Data

“结构体”（struct 或 structure）是一种自定义数据类型，它允许你将多个相关的、构成一个有意义组的值打包并命名。如果你熟悉面向对象的语言，结构体就像对象的“数据属性”。在本章中，我们将比较元组与结构体，在现有知识的基础上，展示何时结构体是更好的数据分组方式。

A struct, or structure, is a custom data type that lets you package together and name multiple related values that make up a meaningful group. If you’re familiar with an object-oriented language, a struct is like an object’s data attributes. In this chapter, we’ll compare and contrast tuples with structs to build on what you already know and demonstrate when structs are a better way to group data.

我们将演示如何定义和实例化结构体。我们将讨论如何定义关联函数，特别是称为“方法”（methods）的那类关联函数，以指定与结构体类型相关联的行为。结构体和枚举（在第 6 章中讨论）是为你程序的领域创建新类型的构建块，以充分利用 Rust 的编译时类型检查。

We’ll demonstrate how to define and instantiate structs. We’ll discuss how to define associated functions, especially the kind of associated functions called methods, to specify behavior associated with a struct type. Structs and enums (discussed in Chapter 6) are the building blocks for creating new types in your program’s domain to take full advantage of Rust’s compile-time type checking.

定义并实例化结构体

定义和实例化结构体

Defining and Instantiating Structs

结构体类似于“元组类型”部分讨论的元组，因为两者都持有多个相关的值。与元组一样，结构体的各部分可以是不同的类型。与元组不同的是，在结构体中，你将为每部分数据命名，以便清楚地了解这些值的含义。添加这些名称意味着结构体比元组更灵活：你不必依赖数据的顺序来指定或访问实例的值。

Structs are similar to tuples, discussed in “The Tuple Type” section, in that both hold multiple related values. Like tuples, the pieces of a struct can be different types. Unlike with tuples, in a struct you’ll name each piece of data so it’s clear what the values mean. Adding these names means that structs are more flexible than tuples: You don’t have to rely on the order of the data to specify or access the values of an instance.

要定义结构体，我们输入关键字 struct 并为整个结构体命名。结构体的名称应该描述被分组在一起的数据片段的意义。然后，在花括号内，我们定义数据片段的名称和类型，我们称之为“字段”（fields）。例如，示例 5-1 显示了一个存储用户帐户信息的结构体。

To define a struct, we enter the keyword struct and name the entire struct. A struct’s name should describe the significance of the pieces of data being grouped together. Then, inside curly brackets, we define the names and types of the pieces of data, which we call fields. For example, Listing 5-1 shows a struct that stores information about a user account.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {}

在我们定义了结构体之后，要使用它，我们要通过为每个字段指定具体值来创建该结构体的“实例”（instance）。我们通过声明结构体的名称来创建一个实例，然后添加包含 key: value 对的花括号，其中键是字段的名称，值是我们想要存储在这些字段中的数据。我们不必按照在结构体中声明字段的相同顺序来指定字段。换句话说，结构体定义就像该类型的通用模板，而实例则用特定数据填充该模板以创建该类型的值。例如，我们可以声明一个特定用户，如示例 5-2 所示。

To use a struct after we’ve defined it, we create an instance of that struct by specifying concrete values for each of the fields. We create an instance by stating the name of the struct and then add curly brackets containing key: value pairs, where the keys are the names of the fields and the values are the data we want to store in those fields. We don’t have to specify the fields in the same order in which we declared them in the struct. In other words, the struct definition is like a general template for the type, and instances fill in that template with particular data to create values of the type. For example, we can declare a particular user as shown in Listing 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };
}

要从结构体中获取特定值，我们使用点表示法。例如，要访问此用户的电子邮件地址，我们使用 user1.email。如果实例是可变的，我们可以通过使用点表示法并赋值给特定字段来更改值。示例 5-3 显示了如何更改可变 User 实例中 email 字段的值。

To get a specific value from a struct, we use dot notation. For example, to access this user’s email address, we use user1.email. If the instance is mutable, we can change a value by using the dot notation and assigning into a particular field. Listing 5-3 shows how to change the value in the email field of a mutable User instance.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    let mut user1 = User {
        active: true,
        username: String::from("someusername123"),
        email: String::from("someone@example.com"),
        sign_in_count: 1,
    };

    user1.email = String::from("anotheremail@example.com");
}

注意，整个实例必须是可变的；Rust 不允许我们仅将某些字段标记为可变。与任何表达式一样，我们可以构造结构体的新实例作为函数体中的最后一个表达式，以隐式返回该新实例。

Note that the entire instance must be mutable; Rust doesn’t allow us to mark only certain fields as mutable. As with any expression, we can construct a new instance of the struct as the last expression in the function body to implicitly return that new instance.

示例 5-4 显示了一个 build_user 函数，该函数返回具有给定电子邮件和用户名的 User 实例。active 字段获取值 true，sign_in_count 获取值 1。

Listing 5-4 shows a build_user function that returns a User instance with the given email and username. The active field gets the value true, and the sign_in_count gets a value of 1.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username: username,
        email: email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

将函数参数命名为与结构体字段相同的名称是有道理的，但是必须重复 email 和 username 字段名称和变量有点乏味。如果结构体有更多字段，重复每个名称会变得更加烦人。幸运的是，有一个方便的简写！

It makes sense to name the function parameters with the same name as the struct fields, but having to repeat the email and username field names and variables is a bit tedious. If the struct had more fields, repeating each name would get even more annoying. Luckily, there’s a convenient shorthand!

使用字段初始化简写

Using the Field Init Shorthand

因为示例 5-4 中的参数名称和结构体字段名称完全相同，我们可以使用“字段初始化简写”（field init shorthand）语法来重写 build_user，使其行为完全相同，但没有 username 和 email 的重复，如示例 5-5 所示。

Because the parameter names and the struct field names are exactly the same in Listing 5-4, we can use the field init shorthand syntax to rewrite build_user so that it behaves exactly the same but doesn’t have the repetition of username and email, as shown in Listing 5-5.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn build_user(email: String, username: String) -> User {
    User {
        active: true,
        username,
        email,
        sign_in_count: 1,
    }
}

fn main() {
    let user1 = build_user(
        String::from("someone@example.com"),
        String::from("someusername123"),
    );
}

在这里，我们正在创建一个 User 结构体的新实例，它有一个名为 email 的字段。我们想要将 email 字段的值设置为 build_user 函数的 email 参数中的值。因为 email 字段和 email 参数具有相同的名称，我们只需要写 email 而不是 email: email。

Here, we’re creating a new instance of the User struct, which has a field named email. We want to set the email field’s value to the value in the email parameter of the build_user function. Because the email field and the email parameter have the same name, we only need to write email rather than email: email.

使用结构体更新语法从其他实例创建实例

Creating Instances with Struct Update Syntax

创建一个结构体的新实例，其中包含另一个相同类型实例的大部分值，但更改其中的一部分，这通常很有用。你可以使用“结构体更新语法”（struct update syntax）来做到这一点。

It’s often useful to create a new instance of a struct that includes most of the values from another instance of the same type, but changes some of them. You can do this using struct update syntax.

首先，在示例 5-6 中，我们展示了如何在 user2 中以常规方式创建一个新的 User 实例，而不使用更新语法。我们为 email 设置了一个新值，但在其他方面使用我们在示例 5-2 中创建的 user1 中的相同值。

First, in Listing 5-6 we show how to create a new User instance in user2 in the regular way, without the update syntax. We set a new value for email but otherwise use the same values from user1 that we created in Listing 5-2.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        active: user1.active,
        username: user1.username,
        email: String::from("another@example.com"),
        sign_in_count: user1.sign_in_count,
    };
}

使用结构体更新语法，我们可以用更少的代码实现相同的效果，如示例 5-7 所示。语法 .. 指定未显式设置的剩余字段应具有与给定实例中的字段相同的值。

Using struct update syntax, we can achieve the same effect with less code, as shown in Listing 5-7. The syntax .. specifies that the remaining fields not explicitly set should have the same value as the fields in the given instance.

struct User {
    active: bool,
    username: String,
    email: String,
    sign_in_count: u64,
}

fn main() {
    // --snip--

    let user1 = User {
        email: String::from("someone@example.com"),
        username: String::from("someusername123"),
        active: true,
        sign_in_count: 1,
    };

    let user2 = User {
        email: String::from("another@example.com"),
        ..user1
    };
}

示例 5-7 中的代码也在 user2 中创建了一个实例，该实例具有不同的 email 值，但具有与 user1 相同的 username、active 和 sign_in_count 字段值。..user1 必须放在最后，以指定任何剩余字段都应从 user1 中的相应字段获取它们的值，但我们可以选择以任何顺序为任意数量的字段指定值，而不必考虑结构体定义中字段的顺序。

The code in Listing 5-7 also creates an instance in user2 that has a different value for email but has the same values for the username, active, and sign_in_count fields from user1. The ..user1 must come last to specify that any remaining fields should get their values from the corresponding fields in user1, but we can choose to specify values for as many fields as we want in any order, regardless of the order of the fields in the struct’s definition.

请注意，结构体更新语法像赋值一样使用 =；这是因为它会移动数据，正如我们在“变量与数据交互的方式：移动”部分看到的那样。在这个例子中，在创建 user2 之后，我们不能再使用 user1，因为 user1 的 username 字段中的 String 被移动到了 user2 中。如果我们为 user2 的 email 和 username 都提供了新的 String 值，从而仅使用 user1 的 active 和 sign_in_count 值，那么在创建 user2 之后 user1 仍然有效。active 和 sign_in_count 都是实现了 Copy trait 的类型，因此我们在“只在栈上的数据：拷贝”部分讨论的行为将适用。在这个例子中，我们仍然可以使用 user1.email，因为它的值没有从 user1 中移出。

Note that the struct update syntax uses = like an assignment; this is because it moves the data, just as we saw in the “Variables and Data Interacting with Move” section. In this example, we can no longer use user1 after creating user2 because the String in the username field of user1 was moved into user2. If we had given user2 new String values for both email and username, and thus only used the active and sign_in_count values from user1, then user1 would still be valid after creating user2. Both active and sign_in_count are types that implement the Copy trait, so the behavior we discussed in the “Stack-Only Data: Copy” section would apply. We can also still use user1.email in this example, because its value was not moved out of user1.

使用元组结构体创建不同的类型

Creating Different Types with Tuple Structs

Rust 还支持类似于元组的结构体，称为“元组结构体”（tuple structs）。元组结构体具有结构体名称提供的附加含义，但没有与其字段相关联的名称；相反，它们只有字段的类型。当你想要给整个元组一个名称，并使该元组成为与其他元组不同的类型，且像在常规结构体中那样为每个字段命名会显得冗长或多余时，元组结构体非常有用。

Rust also supports structs that look similar to tuples, called tuple structs. Tuple structs have the added meaning the struct name provides but don’t have names associated with their fields; rather, they just have the types of the fields. Tuple structs are useful when you want to give the whole tuple a name and make the tuple a different type from other tuples, and when naming each field as in a regular struct would be verbose or redundant.

要定义元组结构体，以 struct 关键字和结构体名称开头，后跟元组中的类型。例如，在这里我们定义并使用两个名为 Color 和 Point 的元组结构体：

To define a tuple struct, start with the struct keyword and the struct name followed by the types in the tuple. For example, here we define and use two tuple structs named Color and Point:

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

fn main() {
    let black = Color(0, 0, 0);
    let origin = Point(0, 0, 0);
}

注意，black 和 origin 值是不同的类型，因为它们是不同元组结构体的实例。你定义的每个结构体都是它自己的类型，即使结构体内的字段可能具有相同的类型。例如，一个接收 Color 类型参数的函数不能将 Point 作为参数，即使这两种类型都由三个 i32 值组成。除此之外，元组结构体实例与元组类似，你可以将它们解构为各自的部分，并且可以使用 . 后跟索引来访问单个值。与元组不同，元组结构体要求你在解构它们时命名结构体的类型。例如，我们会写 let Point(x, y, z) = origin; 来将 origin 点中的值解构到名为 x、y 和 z 的变量中。

Note that the black and origin values are different types because they’re instances of different tuple structs. Each struct you define is its own type, even though the fields within the struct might have the same types. For example, a function that takes a parameter of type Color cannot take a Point as an argument, even though both types are made up of three i32 values. Otherwise, tuple struct instances are similar to tuples in that you can destructure them into their individual pieces, and you can use a . followed by the index to access an individual value. Unlike tuples, tuple structs require you to name the type of the struct when you destructure them. For example, we would write let Point(x, y, z) = origin; to destructure the values in the origin point into variables named x, y, and z.

定义类单元结构体

Defining Unit-Like Structs

你还可以定义没有任何字段的结构体！这些被称为“类单元结构体”（unit-like structs），因为它们的行为类似于 ()，即我们在“元组类型”部分提到的单元类型。当你需要在某种类型上实现 trait，但没有任何想要存储在类型本身中的数据时，类单元结构体非常有用。我们将在第 10 章讨论 trait。这里有一个声明和实例化一个名为 AlwaysEqual 的单元结构体的例子：

You can also define structs that don’t have any fields! These are called unit-like structs because they behave similarly to (), the unit type that we mentioned in “The Tuple Type” section. Unit-like structs can be useful when you need to implement a trait on some type but don’t have any data that you want to store in the type itself. We’ll discuss traits in Chapter 10. Here’s an example of declaring and instantiating a unit struct named AlwaysEqual:

struct AlwaysEqual;

fn main() {
    let subject = AlwaysEqual;
}

要定义 AlwaysEqual，我们使用 struct 关键字、我们想要的名称，然后是一个分号。不需要花括号或圆括号！然后，我们可以以类似的方式在 subject 变量中获得 AlwaysEqual 的一个实例：使用我们定义的名称，不带任何花括号或圆括号。想象一下，稍后我们将为此类型实现行为，使得 AlwaysEqual 的每个实例始终等于任何其他类型的每个实例，或许是为了测试目的而获得一个已知的结果。我们不需要任何数据来实现这种行为！你将在第 10 章中看到如何定义 trait 并在任何类型（包括类单元结构体）上实现它们。

To define AlwaysEqual, we use the struct keyword, the name we want, and then a semicolon. No need for curly brackets or parentheses! Then, we can get an instance of AlwaysEqual in the subject variable in a similar way: using the name we defined, without any curly brackets or parentheses. Imagine that later we’ll implement behavior for this type such that every instance of AlwaysEqual is always equal to every instance of any other type, perhaps to have a known result for testing purposes. We wouldn’t need any data to implement that behavior! You’ll see in Chapter 10 how to define traits and implement them on any type, including unit-like structs.

结构体数据的所有权

Ownership of Struct Data

在示例 5-1 的 User 结构体定义中，我们使用了拥有的 String 类型而不是 &str 字符串切片类型。这是一个深思熟虑的选择，因为我们希望该结构体的每个实例都拥有其所有数据，并希望该数据在整个结构体有效期间保持有效。

In the User struct definition in Listing 5-1, we used the owned String type rather than the &str string slice type. This is a deliberate choice because we want each instance of this struct to own all of its data and for that data to be valid for as long as the entire struct is valid.

结构体也可以存储对由其他东西拥有的数据的引用，但这样做需要使用“生命周期”（lifetimes），这是我们将在第 10 章讨论的 Rust 功能。生命周期确保结构体引用的数据与结构体本身一样长久有效。假设你尝试在不指定生命周期的情况下在结构体中存储引用，如下所示在 src/main.rs 中；这行不通：

It’s also possible for structs to store references to data owned by something else, but to do so requires the use of lifetimes, a Rust feature that we’ll discuss in Chapter 10. Lifetimes ensure that the data referenced by a struct is valid for as long as the struct is. Let’s say you try to store a reference in a struct without specifying lifetimes, like the following in src/main.rs; this won’t work:

struct User {
    active: bool,
    username: &str,
    email: &str,
    sign_in_count: u64,
}

fn main() {
    let user1 = User {
        active: true,
        username: "someusername123",
        email: "someone@example.com",
        sign_in_count: 1,
    };
}

编译器会抱怨它需要生命周期标识符：

The compiler will complain that it needs lifetime specifiers:

$ cargo run
   Compiling structs v0.1.0 (file:///projects/structs)
error[E0106]: missing lifetime specifier
 --> src/main.rs:3:15
  |
3 |     username: &str,
  |               ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 ~     username: &'a str,
  |

error[E0106]: missing lifetime specifier
 --> src/main.rs:4:12
  |
4 |     email: &str,
  |            ^ expected named lifetime parameter
  |
help: consider introducing a named lifetime parameter
  |
1 ~ struct User<'a> {
2 |     active: bool,
3 |     username: &str,
4 ~     email: &'a str,
  |

For more information about this error, try `rustc --explain E0106`.
error: could not compile `structs` (bin "structs") due to 2 previous errors

在第 10 章中，我们将讨论如何修复这些错误，以便你可以在结构体中存储引用，但现在，我们将使用像 String 这样的拥有类型而不是像 &str 这样的引用来修复此类错误。

In Chapter 10, we’ll discuss how to fix these errors so that you can store references in structs, but for now, we’ll fix errors like these using owned types like String instead of references like &str.

结构体示例程序

一个使用结构体的示例程序

An Example Program Using Structs

为了理解我们何时可能想要使用结构体，让我们编写一个计算长方形面积的程序。我们将从使用单个变量开始，然后重构程序，直到改为使用结构体。

To understand when we might want to use structs, let’s write a program that calculates the area of a rectangle. We’ll start by using single variables and then refactor the program until we’re using structs instead.

让我们用 Cargo 创建一个名为 rectangles 的新二进制项目，它将接收以像素为单位的长方形宽度和高度，并计算该长方形的面积。示例 5-8 展示了一个简短的程序，它是我们项目 src/main.rs 中实现该功能的一种方式。

Let’s make a new binary project with Cargo called rectangles that will take the width and height of a rectangle specified in pixels and calculate the area of the rectangle. Listing 5-8 shows a short program with one way of doing exactly that in our project’s src/main.rs.

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

现在，使用 cargo run 运行此程序：

Now, run this program using cargo run:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/rectangles`
The area of the rectangle is 1500 square pixels.

此代码通过使用每个维度调用 area 函数成功算出了长方形的面积，但我们可以做更多工作来使此代码清晰易读。

This code succeeds in figuring out the area of the rectangle by calling the area function with each dimension, but we can do more to make this code clear and readable.

此代码的问题在 area 的签名中显而易见：

The issue with this code is evident in the signature of area:

fn main() {
    let width1 = 30;
    let height1 = 50;

    println!(
        "The area of the rectangle is {} square pixels.",
        area(width1, height1)
    );
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

area 函数本应计算“一个”长方形的面积，但我们编写的函数有两个参数，并且在我们的程序中没有任何地方清楚地表明这两个参数是相关的。将宽度和高度分组在一起会使代码更具可读性且更易于管理。我们已经在第 3 章的“元组类型”部分讨论了实现这一目标的一种方法：使用元组。

The area function is supposed to calculate the area of one rectangle, but the function we wrote has two parameters, and it’s not clear anywhere in our program that the parameters are related. It would be more readable and more manageable to group width and height together. We’ve already discussed one way we might do that in “The Tuple Type” section of Chapter 3: by using tuples.

使用元组重构

Refactoring with Tuples

示例 5-9 展示了我们程序的另一个使用元组的版本。

Listing 5-9 shows another version of our program that uses tuples.

fn main() {
    let rect1 = (30, 50);

    println!(
        "The area of the rectangle is {} square pixels.",
        area(rect1)
    );
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

在某种程度上，这个程序更好了。元组让我们可以增加一些结构，并且我们现在只传递一个参数。但从另一个角度看，这个版本不够清晰：元组没有为其元素命名，因此我们必须通过索引访问元组的部分，这使得我们的计算不够直观。

In one way, this program is better. Tuples let us add a bit of structure, and we’re now passing just one argument. But in another way, this version is less clear: Tuples don’t name their elements, so we have to index into the parts of the tuple, making our calculation less obvious.

对于面积计算来说，混淆宽度和高度并不重要，但如果我们想在屏幕上绘制长方形，那就有关系了！我们必须记住 width 是元组索引 0，而 height 是元组索引 1。如果别人要使用我们的代码，他们会更难理解并记住这一点。因为我们没有在代码中传达数据的含义，所以现在更容易引入错误。

Mixing up the width and height wouldn’t matter for the area calculation, but if we want to draw the rectangle on the screen, it would matter! We would have to keep in mind that width is the tuple index 0 and height is the tuple index 1. This would be even harder for someone else to figure out and keep in mind if they were to use our code. Because we haven’t conveyed the meaning of our data in our code, it’s now easier to introduce errors.

使用结构体重构：赋予更多意义

Refactoring with Structs

我们使用结构体通过标记数据来增加意义。我们可以将正在使用的元组转换为结构体，既为整体命名，也为部分命名，如示例 5-10 所示。

We use structs to add meaning by labeling the data. We can transform the tuple we’re using into a struct with a name for the whole as well as names for the parts, as shown in Listing 5-10.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        area(&rect1)
    );
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

在这里，我们定义了一个结构体并将其命名为 Rectangle。在花括号内，我们将字段定义为 width 和 height，两者的类型都是 u32。然后，在 main 中，我们创建了一个具体的 Rectangle 实例，其宽度为 30，高度为 50。

Here, we’ve defined a struct and named it Rectangle. Inside the curly brackets, we defined the fields as width and height, both of which have type u32. Then, in main, we created a particular instance of Rectangle that has a width of 30 and a height of 50.

我们的 area 函数现在定义了一个参数，我们将其命名为 rectangle ，其类型是结构体 Rectangle 实例的一个不可变借用。正如第 4 章提到的，我们想要借用结构体而不是获取其所有权。这样，main 就可以保留其所有权并继续使用 rect1，这也是我们在函数签名和调用函数的地方使用 & 的原因。

Our area function is now defined with one parameter, which we’ve named rectangle, whose type is an immutable borrow of a struct Rectangle instance. As mentioned in Chapter 4, we want to borrow the struct rather than take ownership of it. This way, main retains its ownership and can continue using rect1, which is the reason we use the & in the function signature and where we call the function.

area 函数访问 Rectangle 实例的 width 和 height 字段（注意访问借用的结构体实例的字段不会移动字段值，这就是为什么你经常看到结构体的借用）。我们的 area 函数签名现在准确地表达了我们的意图：使用 Rectangle 的 width 和 height 字段来计算它的面积。这传达了宽度和高度是相互关联的，并且它赋予了值描述性的名称，而不是使用元组索引值 0 和 1。这对清晰度来说是一个胜利。

The area function accesses the width and height fields of the Rectangle instance (note that accessing fields of a borrowed struct instance does not move the field values, which is why you often see borrows of structs). Our function signature for area now says exactly what we mean: Calculate the area of Rectangle, using its width and height fields. This conveys that the width and height are related to each other, and it gives descriptive names to the values rather than using the tuple index values of 0 and 1. This is a win for clarity.

通过派生 Trait 增加有用功能

Adding Functionality with Derived Traits

如果在调试程序时能够打印 Rectangle 的实例并查看其所有字段的值，那将会很有用。示例 5-11 尝试像我们在前几章中那样使用 println! 宏。然而，这行不通。

It’d be useful to be able to print an instance of Rectangle while we’re debugging our program and see the values for all its fields. Listing 5-11 tries using the println! macro as we have used in previous chapters. This won’t work, however.

struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1}");
}

当我们编译这段代码时，会得到一个错误，核心信息如下：

error[E0277]: `Rectangle` doesn't implement `std::fmt::Display`

println! 宏可以进行多种格式化，默认情况下，花括号告诉 println! 使用称为 Display 的格式：旨在直接供最终用户消费的输出。到目前为止我们见过的原始类型默认都实现了 Display，因为你只想以一种方式向用户显示 1 或任何其他原始类型。但对于结构体，println! 应该如何格式化输出就不那么明确了，因为有更多的显示可能性：你想要逗号吗？你想要打印花括号吗？所有的字段都应该显示吗？由于这种歧义，Rust 不会尝试猜测我们想要什么，并且结构体没有提供用于 println! 和 {} 占位符的 Display 实现。

The println! macro can do many kinds of formatting, and by default, the curly brackets tell println! to use formatting known as Display: output intended for direct end user consumption. The primitive types we’ve seen so far implement Display by default because there’s only one way you’d want to show a 1 or any other primitive type to a user. But with structs, the way println! should format the output is less clear because there are more display possibilities: Do you want commas or not? Do you want to print the curly brackets? Should all the fields be shown? Due to this ambiguity, Rust doesn’t try to guess what we want, and structs don’t have a provided implementation of Display to use with println! and the {} placeholder.

如果我们继续阅读错误信息，会发现这条有用的提示：

   |                        |`Rectangle` cannot be formatted with the default formatter
   |                        required by this formatting parameter

让我们试试看！println! 宏调用现在将变成 println!("rect1 is {rect1:?}");。在花括号内放入标识符 :? 告诉 println! 我们想要使用一种名为 Debug 的输出格式。Debug trait 使我们能够以一种对开发人员有用的方式打印我们的结构体，以便我们在调试代码时可以看到它的值。

Let’s try it! The println! macro call will now look like println!("rect1 is {rect1:?}");. Putting the specifier :? inside the curly brackets tells println! we want to use an output format called Debug. The Debug trait enables us to print our struct in a way that is useful for developers so that we can see its value while we’re debugging our code.

修改后编译代码。哎呀！我们仍然得到一个错误：

error[E0277]: `Rectangle` doesn't implement `Debug`

但编译器再次给了我们一条有用的提示：

   |                        required by this formatting parameter
   |

Rust “确实”包含打印调试信息的功能，但我们必须显式地选择让该功能对我们的结构体可用。为此，我们在结构体定义之前添加外部属性 #[derive(Debug)]，如示例 5-12 所示。

Rust does include functionality to print out debugging information, but we have to explicitly opt in to make that functionality available for our struct. To do that, we add the outer attribute #[derive(Debug)] just before the struct definition, as shown in Listing 5-12.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!("rect1 is {rect1:?}");
}

现在当我们运行程序时，不会得到任何错误，并且会看到以下输出：

Now when we run the program, we won’t get any errors, and we’ll see the following output:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle { width: 30, height: 50 }

不错！虽然不是最漂亮的输出，但它显示了此实例所有字段的值，这在调试期间肯定会有所帮助。当我们的结构体较大时，让输出更易于阅读会更有用；在这些情况下，我们可以在 println! 字符串中使用 {:#?} 代替 {:?}。在这个例子中，使用 {:#?} 风格将输出以下内容：

Nice! It’s not the prettiest output, but it shows the values of all the fields for this instance, which would definitely help during debugging. When we have larger structs, it’s useful to have output that’s a bit easier to read; in those cases, we can use {:#?} instead of {:?} in the println! string. In this example, using the {:#?} style will output the following:

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
     Running `target/debug/rectangles`
rect1 is Rectangle {
    width: 30,
    height: 50,
}

另一种使用 Debug 格式打印值的方法是使用 dbg! 宏，它会获取表达式的所有权（与 println! 接收引用相反），打印代码中调用 dbg! 宏的文件名和行号，以及该表达式的结果值，最后返回该值的所有权。

Another way to print out a value using the Debug format is to use the dbg! macro, which takes ownership of an expression (as opposed to println!, which takes a reference), prints the file and line number of where that dbg! macro call occurs in your code along with the resultant value of that expression, and returns ownership of the value.

注意：调用 dbg! 宏会打印到标准错误控制台流（stderr），而 println! 则是打印到标准输出控制台流（stdout）。我们将在第 12 章的“将错误重定向到标准错误”部分更多地讨论 stderr 和 stdout。

Note: Calling the dbg! macro prints to the standard error console stream (stderr), as opposed to println!, which prints to the standard output console stream (stdout). We’ll talk more about stderr and stdout in the “Redirecting Errors to Standard Error” section in Chapter 12.

这里有一个例子，我们对分配给 width 字段的值以及 rect1 中整个结构体的值感兴趣：

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

fn main() {
    let scale = 2;
    let rect1 = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    };

    dbg!(&rect1);
}

我们可以将 dbg! 放在表达式 30 * scale 周围，由于 dbg! 会返回表达式值的所有权，width 字段将获得与我们没有在那调用 dbg! 时相同的值。我们不希望 dbg! 获取 rect1 的所有权，因此在下一次调用中我们使用了 rect1 的引用。以下是此示例输出的样子：

$ cargo run
   Compiling rectangles v0.1.0 (file:///projects/rectangles)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
     Running `target/debug/rectangles`
[src/main.rs:10:16] 30 * scale = 60
[src/main.rs:14:5] &rect1 = Rectangle {
    width: 60,
    height: 50,
}

我们可以看到第一部分输出源自 src/main.rs 第 10 行，我们正在调试表达式 30 * scale，其结果值为 60（为整数实现的 Debug 格式化是仅打印它们的值）。在 src/main.rs 第 14 行调用的 dbg! 输出 &rect1 的值，即 Rectangle 结构体。此输出使用了 Rectangle 类型的漂亮 Debug 格式化。当你想要弄清楚代码在做什么时，dbg! 宏真的非常有帮助！

We can see the first bit of output came from src/main.rs line 10 where we’re debugging the expression 30 * scale, and its resultant value is 60 (the Debug formatting implemented for integers is to print only their value). The dbg! call on line 14 of src/main.rs outputs the value of &rect1, which is the Rectangle struct. This output uses the pretty Debug formatting of the Rectangle type. The dbg! macro can be really helpful when you’re trying to figure out what your code is doing!

除了 Debug trait 之外，Rust 还为我们提供了许多 trait，供我们与 derive 属性一起使用，以便为我们的自定义类型增加有用的行为。这些 trait 及其行为列在附录 C中。我们将在第 10 章介绍如何使用自定义行为实现这些 trait，以及如何创建你自己的 trait。除了 derive 之外还有许多其他属性；更多信息请参阅 Rust 参考手册的“属性”部分。

In addition to the Debug trait, Rust has provided a number of traits for us to use with the derive attribute that can add useful behavior to our custom types. Those traits and their behaviors are listed in Appendix C. We’ll cover how to implement these traits with custom behavior as well as how to create your own traits in Chapter 10. There are also many attributes other than derive; for more information, see the “Attributes” section of the Rust Reference.

我们的 area 函数非常具体：它只计算长方形的面积。将此行为更紧密地与我们的 Rectangle 结构体联系起来会很有帮助，因为它不适用于任何其他类型。让我们来看看如何通过将 area 函数转变为定义在 Rectangle 类型上的 area “方法”来继续重构此代码。

Our area function is very specific: It only computes the area of rectangles. It would be helpful to tie this behavior more closely to our Rectangle struct because it won’t work with any other type. Let’s look at how we can continue to refactor this code by turning the area function into an area method defined on our Rectangle type.

方法语法

方法

Methods

方法类似于函数：我们使用 fn 关键字和名称来声明它们，它们可以有参数和返回值，并且包含一些当从其他地方调用方法时运行的代码。与函数不同，方法定义在结构体（或枚举或 trait 对象，我们分别在第 6 章和第 18 章中介绍）的上下文中，并且它们的第一个参数总是 self，它代表调用该方法的结构体实例。

Methods are similar to functions: We declare them with the fn keyword and a name, they can have parameters and a return value, and they contain some code that’s run when the method is called from somewhere else. Unlike functions, methods are defined within the context of a struct (or an enum or a trait object, which we cover in Chapter 6 and Chapter 18, respectively), and their first parameter is always self, which represents the instance of the struct the method is being called on.

方法语法

Method Syntax

让我们更改将 Rectangle 实例作为参数的 area 函数，改为在 Rectangle 结构体上定义一个 area 方法，如示例 5-13 所示。

Let’s change the area function that has a Rectangle instance as a parameter and instead make an area method defined on the Rectangle struct, as shown in Listing 5-13.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    println!(
        "The area of the rectangle is {} square pixels.",
        rect1.area()
    );
}

为了在 Rectangle 的上下文中定义该函数，我们为 Rectangle 启动一个 impl（implementation，实现）块。此 impl 块中的所有内容都将与 Rectangle 类型相关联。然后，我们将 area 函数移至 impl 的花括号内，并将签名中以及函数体中所有位置的第一个（在本例中也是唯一的）参数更改为 self。在调用 area 函数并将 rect1 作为参数传递的 main 中，我们可以改为使用“方法语法”在我们的 Rectangle 实例上调用 area 方法。方法语法位于实例之后：我们添加一个点，后跟方法名、圆括号和任何参数。

To define the function within the context of Rectangle, we start an impl (implementation) block for Rectangle. Everything within this impl block will be associated with the Rectangle type. Then, we move the area function within the impl curly brackets and change the first (and in this case, only) parameter to be self in the signature and everywhere within the body. In main, where we called the area function and passed rect1 as an argument, we can instead use method syntax to call the area method on our Rectangle instance. The method syntax goes after an instance: We add a dot followed by the method name, parentheses, and any arguments.

在 area 的签名中，我们使用 &self 而不是 rectangle: &Rectangle。&self 实际上是 self: &Self 的简写。在 impl 块内部，类型 Self 是 impl 块所针对的类型的别名。方法的第一个参数必须有一个名为 self 且类型为 Self 的参数，因此 Rust 允许你在第一个参数位置仅使用名称 self 来缩写它。注意，我们仍然需要在 self 简写前面使用 & 来指示此方法借用了 Self 实例，就像我们在 rectangle: &Rectangle 中所做的那样。方法可以获取 self 的所有权，不可变地借用 self（如我们在这里所做的），或者可变地借用 self，就像处理任何其他参数一样。

In the signature for area, we use &self instead of rectangle: &Rectangle. The &self is actually short for self: &Self. Within an impl block, the type Self is an alias for the type that the impl block is for. Methods must have a parameter named self of type Self for their first parameter, so Rust lets you abbreviate this with only the name self in the first parameter spot. Note that we still need to use the & in front of the self shorthand to indicate that this method borrows the Self instance, just as we did in rectangle: &Rectangle. Methods can take ownership of self, borrow self immutably, as we’ve done here, or borrow self mutably, just as they can any other parameter.

我们在这里选择 &self 的原因与在函数版本中使用 &Rectangle 的原因相同：我们不想获取所有权，我们只想读取结构体中的数据，而不是写入它。如果我们想在方法执行过程中更改调用该方法的实例，我们将使用 &mut self 作为第一个参数。通过仅使用 self 作为第一个参数来获取实例所有权的方法很少见；这种技术通常用于当方法将 self 转换为其他东西，并且你希望防止调用者在转换后使用原始实例时。

We chose &self here for the same reason we used &Rectangle in the function version: We don’t want to take ownership, and we just want to read the data in the struct, not write to it. If we wanted to change the instance that we’ve called the method on as part of what the method does, we’d use &mut self as the first parameter. Having a method that takes ownership of the instance by using just self as the first parameter is rare; this technique is usually used when the method transforms self into something else and you want to prevent the caller from using the original instance after the transformation.

使用方法而不是函数的主要原因，除了提供方法语法和不必在每个方法的签名中重复 self 的类型之外，还在于组织性。我们将可以使用某种类型的实例进行的所有操作都放在一个 impl 块中，而不是让代码的未来用户在向他们提供的库中的各个位置搜索 Rectangle 的功能。

The main reason for using methods instead of functions, in addition to providing method syntax and not having to repeat the type of self in every method’s signature, is for organization. We’ve put all the things we can do with an instance of a type in one impl block rather than making future users of our code search for capabilities of Rectangle in various places in the library we provide.

请注意，我们可以选择给方法起一个与结构体字段之一相同的名称。例如，我们可以在 Rectangle 上定义一个也名为 width 的方法：

Note that we can choose to give a method the same name as one of the struct’s fields. For example, we can define a method on Rectangle that is also named width:

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn width(&self) -> bool {
        self.width > 0
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };

    if rect1.width() {
        println!("The rectangle has a nonzero width; it is {}", rect1.width);
    }
}

在这里，我们选择让 width 方法在实例的 width 字段值大于 0 时返回 true，在值为 0 时返回 false：我们可以在同名方法中使用同名实字段来实现任何目的。在 main 中，当我们给 rect1.width 加上圆括号时，Rust 知道我们指的是 width 方法。当我们不使用圆括号时，Rust 知道我们指的是 width 字段。

Here, we’re choosing to make the width method return true if the value in the instance’s width field is greater than 0 and false if the value is 0: We can use a field within a method of the same name for any purpose. In main, when we follow rect1.width with parentheses, Rust knows we mean the method width. When we don’t use parentheses, Rust knows we mean the field width.

通常（但并非总是），当我们给一个方法起一个与字段相同的名称时，我们希望它仅返回字段中的值而不执行其他操作。像这样的方法被称为“getter”，Rust 不会像其他一些语言那样为结构体字段自动实现它们。Getter 很有用，因为你可以将字段设为私有而将方法设为公开，从而作为类型公开 API 的一部分，实现对该字段的只读访问。我们将在第 7 章讨论什么是公开和私有，以及如何将字段或方法指定为公开或私有。

Often, but not always, when we give a method the same name as a field we want it to only return the value in the field and do nothing else. Methods like this are called getters, and Rust does not implement them automatically for struct fields as some other languages do. Getters are useful because you can make the field private but the method public and thus enable read-only access to that field as part of the type’s public API. We will discuss what public and private are and how to designate a field or method as public or private in Chapter 7.

-> 运算符在哪里？

Where’s the -> Operator?

在 C 和 C++ 中，调用方法使用两种不同的运算符：如果你直接在对象上调用方法，使用 .；如果你在对象的指针上调用方法并且需要先解引用指针，使用 ->。换句话说，如果 object 是一个指针，object->something() 类似于 (*object).something()。

In C and C++, two different operators are used for calling methods: You use . if you’re calling a method on the object directly and -> if you’re calling the method on a pointer to the object and need to dereference the pointer first. In other words, if object is a pointer, object->something() is similar to (*object).something().

Rust 没有与 -> 运算符等效的运算符；相反，Rust 有一个名为“自动引用和解引用”（automatic referencing and dereferencing）的功能。调用方法是 Rust 中少数具有此行为的地方之一。

Rust doesn’t have an equivalent to the -> operator; instead, Rust has a feature called automatic referencing and dereferencing. Calling methods is one of the few places in Rust with this behavior.

它是这样工作的：当你使用 object.something() 调用方法时，Rust 会自动添加 &、&mut 或 *，以便 object 匹配方法的签名。换句话说，以下写法是相同的：

Here’s how it works: When you call a method with object.something(), Rust automatically adds in &, &mut, or * so that object matches the signature of the method. In other words, the following are the same:

#![allow(unused)]
fn main() {
#[derive(Debug,Copy,Clone)]
struct Point {
    x: f64,
    y: f64,
}

impl Point {
   fn distance(&self, other: &Point) -> f64 {
       let x_squared = f64::powi(other.x - self.x, 2);
       let y_squared = f64::powi(other.y - self.y, 2);

       f64::sqrt(x_squared + y_squared)
   }
}
let p1 = Point { x: 0.0, y: 0.0 };
let p2 = Point { x: 5.0, y: 6.5 };
p1.distance(&p2);
(&p1).distance(&p2);
}

第一种写法看起来整洁得多。这种自动引用行为之所以有效，是因为方法有一个明确的接收者——self 的类型。给定方法的接收者和名称，Rust 可以明确地找出该方法是在读取（&self）、修改（&mut self）还是消耗（self）。Rust 为方法接收者隐式进行借用的事实，是使所有权在实践中符合人体工程学的重要部分。

The first one looks much cleaner. This automatic referencing behavior works because methods have a clear receiver—the type of self. Given the receiver and name of a method, Rust can figure out definitively whether the method is reading (&self), mutating (&mut self), or consuming (self). The fact that Rust makes borrowing implicit for method receivers is a big part of making ownership ergonomic in practice.

带有更多参数的方法

Methods with More Parameters

让我们通过在 Rectangle 结构体上实现第二个方法来练习使用方法。这次我们希望 Rectangle 的一个实例接收 Rectangle 的另一个实例，并如果第二个 Rectangle 可以完全放入 self（第一个 Rectangle）内部，则返回 true；否则，它应该返回 false。也就是说，一旦我们定义了 can_hold 方法，我们希望能够编写示例 5-14 所示的程序。

Let’s practice using methods by implementing a second method on the Rectangle struct. This time we want an instance of Rectangle to take another instance of Rectangle and return true if the second Rectangle can fit completely within self (the first Rectangle); otherwise, it should return false. That is, once we’ve defined the can_hold method, we want to be able to write the program shown in Listing 5-14.

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

预期的输出如下所示，因为 rect2 的两个维度都小于 rect1 的维度，但 rect3 比 rect1 更宽：

The expected output would look like the following because both dimensions of rect2 are smaller than the dimensions of rect1, but rect3 is wider than rect1:

Can rect1 hold rect2? true
Can rect1 hold rect3? false

我们知道我们想定义一个方法，因此它将在 impl Rectangle 块内。方法名称将是 can_hold ，它将接收另一个 Rectangle 的不可变借用作为参数。我们可以通过查看调用该方法的代码来了解参数的类型：rect1.can_hold(&rect2) 传入了 &rect2，它是对 Rectangle 实例 rect2 的一个不可变借用。这是有道理的，因为我们只需要读取 rect2（而不是写入，那意味着我们需要一个可变借用），并且我们希望 main 保留 rect2 的所有权，以便在调用 can_hold 方法后我们可以再次使用它。can_hold 的返回值将是一个布尔值，实现将分别检查 self 的宽度和高度是否大于另一个 Rectangle 的宽度和高度。让我们将新的 can_hold 方法添加到示例 5-13 的 impl 块中，如示例 5-15 所示。

We know we want to define a method, so it will be within the impl Rectangle block. The method name will be can_hold, and it will take an immutable borrow of another Rectangle as a parameter. We can tell what the type of the bit. The method name will be can_hold, and it will take an immutable borrow parameter will be by looking at the code that calls the method: rect1.can_hold(&rect2) passes in &rect2, which is an immutable borrow to rect2, an instance of Rectangle. This makes sense because we only need to read rect2 (rather than write, which would mean we’d need a mutable borrow), and we want main to retain ownership of rect2 so that we can use it again after calling the can_hold method. The return value of can_hold will be a Boolean, and the implementation will check whether the width and height of self are greater than the width and height of the other Rectangle, respectively. Let’s add the new can_hold method to the impl block from Listing 5-13, shown in Listing 5-15.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

当我们使用示例 5-14 中的 main 函数运行此代码时，我们将获得所需的输出。方法可以接收多个参数，我们将这些参数在 self 参数之后添加到签名中，这些参数的作用与函数中的参数完全相同。

When we run this code with the main function in Listing 5-14, we’ll get our desired output. Methods can take multiple parameters that we add to the signature after the self parameter, and those parameters work just like parameters in functions.

关联函数

Associated Functions

在 impl 块中定义的所有函数都被称为“关联函数”（associated functions），因为它们与以 impl 命名的类型相关联。我们可以定义不以 self 作为第一个参数的关联函数（因此它们不是方法），因为它们不需要类型的实例来工作。我们已经使用过一个这样的函数：定义在 String 类型上的 String::from 函数。

All functions defined within an impl block are called associated functions because they’re associated with the type named after the impl. We can define associated functions that don’t have self as their first parameter (and thus are not methods) because they don’t need an instance of the type to work with. We’ve already used one function like this: the String::from function that’s defined on the String type.

非方法的关联函数通常用于返回结构体新实例的构造函数。这些函数通常被命名为 new，但 new 并不是一个特殊的名称，也不是内置在语言中的。例如，我们可以选择提供一个名为 square 的关联函数，它接收一个维度参数并将其同时用作宽度和高度，从而更容易创建一个正方形的 Rectangle ，而不必指定两次相同的值：

Associated functions that aren’t methods are often used for constructors that will return a new instance of the struct. These are often called new, but new isn’t a special name and isn’t built into the language. For example, we could choose to provide an associated function named square that would have one dimension parameter and use that as both width and height, thus making it easier to create a square Rectangle rather than having to specify the same value twice:

文件名：src/main.rs Filename: src/main.rs

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn square(size: u32) -> Self {
        Self {
            width: size,
            height: size,
        }
    }
}

fn main() {
    let sq = Rectangle::square(3);
}

返回类型中以及函数体中的 Self 关键字出现在 impl 关键字之后的类型的别名，在本例中即为 Rectangle。

The Self keywords in the return type and in the body of the function are aliases for the type that appears after the impl keyword, which in this case is Rectangle.

要调用此关联函数，我们使用带有结构体名称的 :: 语法；let sq = Rectangle::square(3); 就是一个例子。此函数由结构体命名空间化：:: 语法既用于关联函数，也用于由模块创建的命名空间。我们将在第 7 章中讨论模块。

To call this associated function, we use the :: syntax with the struct name; let sq = Rectangle::square(3); is an example. This function is namespaced by the struct: The :: syntax is used for both associated functions and namespaces created by modules. We’ll discuss modules in Chapter 7.

多个 impl 块

Multiple impl Blocks

每个结构体允许有多个 impl 块。例如，示例 5-15 等同于示例 5-16 所示的代码，其中每个方法都在其自己的 impl 块中。

Each struct is allowed to have multiple impl blocks. For example, Listing 5-15 is equivalent to the code shown in Listing 5-16, which has each method in its own impl block.

#[derive(Debug)]
struct Rectangle {
    width: u32,
    height: u32,
}

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

fn main() {
    let rect1 = Rectangle {
        width: 30,
        height: 50,
    };
    let rect2 = Rectangle {
        width: 10,
        height: 40,
    };
    let rect3 = Rectangle {
        width: 60,
        height: 45,
    };

    println!("Can rect1 hold rect2? {}", rect1.can_hold(&rect2));
    println!("Can rect1 hold rect3? {}", rect1.can_hold(&rect3));
}

虽然在这里没有理由将这些方法分成多个 impl 块，但这是有效的语法。我们将在第 10 章看到多个 impl 块很有用的情况，届时我们将讨论泛型和 trait。

There’s no reason to separate these methods into multiple impl blocks here, but this is valid syntax. We’ll see a case in which multiple impl blocks are useful in Chapter 10, where we discuss generic types and traits.

总结

Summary

结构体让你可以创建对你的领域有意义的自定义类型。通过使用结构体，你可以将关联的数据片段保持连接，并为每个部分命名以使你的代码清晰。在 impl 块中，你可以定义与你的类型相关联的函数，而方法是一种关联函数，让你指定结构体实例具有的行为。

Structs let you create custom types that are meaningful for your domain. By using structs, you can keep associated pieces of data connected to each other and name each piece to make your code clear. In impl blocks, you can define functions that are associated with your type, and methods are a kind of associated function that let you specify the behavior that instances of your structs have.

但结构体并不是创建自定义类型的唯一方式：让我们转向 Rust 的枚举（enum）功能，为你的工具箱添加另一个工具。

But structs aren’t the only way you can create custom types: Let’s turn to Rust’s enum feature to add another tool to your toolbox.

枚举和模式匹配

Enums and Pattern Matching

在本章中，我们将讨论枚举（enumerations），也简称为“枚举”（enums）。枚举允许你通过枚举其可能存在的“变体”（variants）来定义一种类型。首先，我们将定义并使用一个枚举，展示枚举如何将意义与数据一起编码。接下来，我们将探索一个特别有用的枚举，名为 Option，它表达了一个值既可以是某个东西，也可以是无。然后，我们将了解 match 表达式中的模式匹配如何轻松地为枚举的不同值运行不同的代码。最后，我们将介绍 if let 结构是如何在代码中处理枚举的另一个方便且简洁的惯用法。

In this chapter, we’ll look at enumerations, also referred to as enums. Enums allow you to define a type by enumerating its possible variants. First we’ll define and use an enum to show how an enum can encode meaning along with data. Next, we’ll explore a particularly useful enum, called Option, which expresses that a value can be either something or nothing. Then, we’ll look at how pattern matching in the match expression makes it easy to run different code for different values of an enum. Finally, we’ll cover how the if let construct is another convenient and concise idiom available to handle enums in your code.

定义枚举

定义枚举

Defining an Enum

结构体让你能够将相关的字段和数据分组，比如具有 width 和 height 的 Rectangle；而枚举则让你能够表达一个值是某一组可能值中的一个。例如，我们可能想说 Rectangle 是可能形状集合中的一个，该集合还包括 Circle（圆形）和 Triangle（三角形）。为此，Rust 允许我们将这些可能性编码为一个枚举。

Where structs give you a way of grouping together related fields and data, like a Rectangle with its width and height, enums give you a way of saying a value is one of a possible set of values. For example, we may want to say that Rectangle is one of a set of possible shapes that also includes Circle and Triangle. To do this, Rust allows us to encode these possibilities as an enum.

让我们看一个我们可能想在代码中表达的情况，看看为什么在这种情况下枚举比结构体更有用且更合适。假设我们需要处理 IP 地址。目前，IP 地址有两种主要标准：版本四和版本六。因为我们的程序只会遇到这两种 IP 地址的可能性，所以我们可以“枚举”所有可能的变体，这就是“枚举”名称的由来。

Let’s look at a situation we might want to express in code and see why enums are useful and more appropriate than structs in this case. Say we need to work with IP addresses. Currently, two major standards are used for IP addresses: version four and version six. Because these are the only possibilities for an IP address that our program will come across, we can enumerate all possible variants, which is where enumeration gets its name.

任何 IP 地址要么是版本四地址，要么是版本六地址，但不能同时是两者。IP 地址的这种属性使得枚举数据结构非常合适，因为枚举值只能是其变体之一。版本四和版本六地址从根本上说仍然都是 IP 地址，因此当代码处理适用于任何类型 IP 地址的情况时，它们应该被视为相同的类型。

Any IP address can be either a version four or a version six address, but not both at the same time. That property of IP addresses makes the enum data structure appropriate because an enum value can only be one of its variants. Both version four and version six addresses are still fundamentally IP addresses, so they should be treated as the same type when the code is handling situations that apply to any kind of IP address.

我们可以通过定义 IpAddrKind 枚举并列出 IP 地址可能的类型 V4 和 V6 来在代码中表达这个概念。这些是枚举的变体：

We can express this concept in code by defining an IpAddrKind enumeration and listing the possible kinds an IP address can be, V4 and V6. These are the variants of the enum:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

IpAddrKind 现在是一个自定义数据类型，我们可以在代码的其他地方使用它。

IpAddrKind is now a custom data type that we can use elsewhere in our code.

枚举值

Enum Values

我们可以像这样创建 IpAddrKind 两个变体的每一个实例：

We can create instances of each of the two variants of IpAddrKind like this:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

注意，枚举的变体命名空间在其标识符之下，我们使用双冒号来分隔两者。这很有用，因为现在 IpAddrKind::V4 和 IpAddrKind::V6 这两个值都属于同一个类型：IpAddrKind。例如，我们可以定义一个接受任何 IpAddrKind 的函数：

Note that the variants of the enum are namespaced under its identifier, and we use a double colon to separate the two. This is useful because now both values IpAddrKind::V4 and IpAddrKind::V6 are of the same type: IpAddrKind. We can then, for instance, define a function that takes any IpAddrKind:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

我们可以使用任何变体来调用此函数：

And we can call this function with either variant:

enum IpAddrKind {
    V4,
    V6,
}

fn main() {
    let four = IpAddrKind::V4;
    let six = IpAddrKind::V6;

    route(IpAddrKind::V4);
    route(IpAddrKind::V6);
}

fn route(ip_kind: IpAddrKind) {}

使用枚举还有更多优势。再深入思考我们的 IP 地址类型，目前我们还没有办法存储实际的 IP 地址“数据”；我们只知道它是哪种“类型”。鉴于你刚刚在第 5 章中学习了结构体，你可能会想用结构体来解决这个问题，如示例 6-1 所示。

Using enums has even more advantages. Thinking more about our IP address type, at the moment we don’t have a way to store the actual IP address data; we only know what kind it is. Given that you just learned about structs in Chapter 5, you might be tempted to tackle this problem with structs as shown in Listing 6-1.

fn main() {
    enum IpAddrKind {
        V4,
        V6,
    }

    struct IpAddr {
        kind: IpAddrKind,
        address: String,
    }

    let home = IpAddr {
        kind: IpAddrKind::V4,
        address: String::from("127.0.0.1"),
    };

    let loopback = IpAddr {
        kind: IpAddrKind::V6,
        address: String::from("::1"),
    };
}

在这里，我们定义了一个结构体 IpAddr，它有两个字段：一个是 kind 字段，其类型为 IpAddrKind（我们之前定义的枚举）；另一个是 address 字段，类型为 String。我们有两个此结构体的实例。第一个是 home，它的 kind 值为 IpAddrKind::V4，关联的地址数据为 127.0.0.1。第二个实例是 loopback。它的 kind 值为 IpAddrKind::V6，关联的地址为 ::1。我们使用结构体将 kind 和 address 值捆绑在一起，因此现在变体与值关联起来了。

Here, we’ve defined a struct IpAddr that has two fields: a kind field that is of type IpAddrKind (the enum we defined previously) and an address field of type String. We have two instances of this struct. The first is home, and it has the value IpAddrKind::V4 as its kind with associated address data of 127.0.0.1. The second instance is loopback. It has the other variant of IpAddrKind as its kind value, V6, and has address ::1 associated with it. We’ve used a struct to bundle the kind and address values together, so now the variant is associated with the value.

然而，仅使用枚举来表示相同的概念更为简洁：我们不使用结构体内部的枚举，而是直接将数据放入每个枚举变体中。IpAddr 枚举的新定义表明 V4 和 V6 变体都将具有关联的 String 值：

However, representing the same concept using just an enum is more concise: Rather than an enum inside a struct, we can put data directly into each enum variant. This new definition of the IpAddr enum says that both V4 and V6 variants will have associated String values:

fn main() {
    enum IpAddr {
        V4(String),
        V6(String),
    }

    let home = IpAddr::V4(String::from("127.0.0.1"));

    let loopback = IpAddr::V6(String::from("::1"));
}

我们直接将数据附加到枚举的每个变体，因此不需要额外的结构体。在这里，也更容易看到枚举工作的另一个细节：我们定义的每个枚举变体名称也变成了一个构造枚举实例的函数。也就是说，IpAddr::V4() 是一个函数调用，它接收一个 String 参数并返回 IpAddr 类型的一个实例。由于定义了枚举，我们自动获得了这个定义的构造函数。

We attach data to each variant of the enum directly, so there is no need for an extra struct. Here, it’s also easier to see another detail of how enums work: The name of each enum variant that we define also becomes a function that constructs an instance of the enum. That is, IpAddr::V4() is a function call that takes a String argument and returns an instance of the IpAddr type. We automatically get this constructor function defined as a result of defining the enum.

使用枚举而不是结构体还有另一个优势：每个变体可以具有不同类型和数量的关联数据。版本四 IP 地址总是有四个数值组成部分，其值在 0 到 255 之间。如果我们想将 V4 地址存储为四个 u8 值，但仍将 V6 地址表示为一个 String 值，使用结构体就无法做到。枚举可以轻松处理这种情况：

There’s another advantage to using an enum rather than a struct: Each variant can have different types and amounts of associated data. Version four IP addresses will always have four numeric components that will have values between 0 and 255. If we wanted to store V4 addresses as four u8 values but still express V6 addresses as one String value, we wouldn’t be able to with a struct. Enums handle this case with ease:

fn main() {
    enum IpAddr {
        V4(u8, u8, u8, u8),
        V6(String),
    }

    let home = IpAddr::V4(127, 0, 0, 1);

    let loopback = IpAddr::V6(String::from("::1"));
}

我们展示了几种定义数据结构来存储版本四和版本六 IP 地址的不同方法。然而，事实证明，想要存储 IP 地址并编码它们的类型是非常普遍的需求，以至于标准库中已经有一个我们可以使用的定义！ 让我们看看标准库是如何定义 IpAddr 的。它具有我们定义并使用的完全相同的枚举和变体，但它以两个不同结构体的形式将地址数据嵌入到变体内部，这两个结构体针对每个变体进行了不同的定义：

We’ve shown several different ways to define data structures to store version four and version six IP addresses. However, as it turns out, wanting to store IP addresses and encode which kind they are is so common that the standard library has a definition we can use! Let’s look at how the standard library defines IpAddr. It has the exact enum and variants that we’ve defined and used, but it embeds the address data inside the variants in the form of two different structs, which are defined differently for each variant:

#![allow(unused)]
fn main() {
struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}
}

这段代码说明你可以将任何类型的数据放入枚举变体中：例如字符串、数值类型或结构体。你甚至可以包含另一个枚举！此外，标准库类型的复杂程度通常不会比你自己想出的复杂多少。

This code illustrates that you can put any kind of data inside an enum variant: strings, numeric types, or structs, for example. You can even include another enum! Also, standard library types are often not much more complicated than what you might come up with.

注意，即使标准库包含 IpAddr 的定义，我们仍然可以创建并使用我们自己的定义而不会发生冲突，因为我们还没有将标准库的定义引入我们的作用域。我们将在第 7 章更多地讨论将类型引入作用域。

Note that even though the standard library contains a definition for IpAddr, we can still create and use our own definition without conflict because we haven’t brought the standard library’s definition into our scope. We’ll talk more about bringing types into scope in Chapter 7.

让我们看看示例 6-2 中的另一个枚举例子：这个枚举在其变体中嵌入了各种各样的类型。

Let’s look at another example of an enum in Listing 6-2: This one has a wide variety of types embedded in its variants.

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

fn main() {}

这个枚举有四个不同类型的变体：

This enum has four variants with different types:

• Quit：完全没有关联数据。

• Quit: Has no data associated with it at all

• Move：具有命名字段，就像结构体一样。

• Move: Has named fields, like a struct does

• Write：包含一个 String。

• Write: Includes a single String

• ChangeColor：包含三个 i32 值。

• ChangeColor: Includes three i32 values

定义一个具有像示例 6-2 这种变体的枚举，类似于定义不同种类的结构体，不同之处在于枚举不使用 struct 关键字，并且所有变体都归组在 Message 类型下。以下结构体可以持有与前述枚举变体相同的数据：

Defining an enum with variants such as the ones in Listing 6-2 is similar to defining different kinds of struct definitions, except the enum doesn’t use the struct keyword and all the variants are grouped together under the Message type. The following structs could hold the same data that the preceding enum variants hold:

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

fn main() {}

但是，如果我们使用这些不同的结构体（每个结构体都有自己的类型），我们就无法像使用示例 6-2 中定义的单一类型的 Message 枚举那样，轻易地定义一个接受这些任何一种消息的函数。

But if we used the different structs, each of which has its own type, we couldn’t as easily define a function to take any of these kinds of messages as we could with the Message enum defined in Listing 6-2, which is a single type.

枚举和结构体之间还有一个相似之处：就像我们可以使用 impl 在结构体上定义方法一样，我们也能够在枚举上定义方法。这是一个我们可以在 Message 枚举上定义的名为 call 的方法：

There is one more similarity between enums and structs: Just as we’re able to define methods on structs using impl, we’re also able to define methods on enums. Here’s a method named call that we could define on our Message enum:

fn main() {
    enum Message {
        Quit,
        Move { x: i32, y: i32 },
        Write(String),
        ChangeColor(i32, i32, i32),
    }

    impl Message {
        fn call(&self) {
            // method body would be defined here
        }
    }

    let m = Message::Write(String::from("hello"));
    m.call();
}

方法体将使用 self 来获取我们调用方法的那个值。在这个例子中，我们创建了一个变量 m，它的值为 Message::Write(String::from("hello"))，这就是当 m.call() 运行时 call 方法体中的 self。

The body of the method would use self to get the value that we called the method on. In this example, we’ve created a variable m that has the value Message::Write(String::from("hello")), and that is what self will be in the body of the call method when m.call() runs.

让我们看看标准库中另一个非常常见且有用的枚举：Option。

Let’s look at another enum in the standard library that is very common and useful: Option.

Option 枚举

The Option Enum

本节将探讨 Option 的案例研究，它是标准库定义的另一个枚举。Option 类型编码了一个非常常见的场景，即一个值可能存在，也可能不存在。

This section explores a case study of Option, which is another enum defined by the standard library. The Option type encodes the very common scenario in which a value could be something, or it could be nothing.

例如，如果你请求一个非空列表中的第一个项目，你会得到一个值。如果你请求一个空列表中的第一个项目，你会一无所获。从类型系统的角度表达这个概念意味着编译器可以检查你是否处理了你应该处理的所有情况；这种功能可以防止其他编程语言中极其常见的错误。

For example, if you request the first item in a non-empty list, you would get a value. If you request the first item in an empty list, you would get nothing. Expressing this concept in terms of the type system means the compiler can check whether you’ve handled all the cases you should be handling; this functionality can prevent bugs that are extremely common in other programming languages.

编程语言设计通常考虑包含哪些功能，但排除哪些功能也很重要。Rust 没有许多其他语言所具有的空值（null）功能。空值（Null）是一个表示那里没有值的值。在具有空值的语言中，变量始终处于两种状态之一：空或非空。

Programming language design is often thought of in terms of which features you include, but the features you exclude are important too. Rust doesn’t have the null feature that many other languages have. Null is a value that means there is no value there. In languages with null, variables can always be in one of two states: null or not-null.

托尼·霍尔（Tony Hoare），空值的发明者，在他 2009 年的演讲《空引用：价值十亿美元的错误》中这样说道：

In his 2009 presentation “Null References: The Billion Dollar Mistake,” Tony Hoare, the inventor of null, had this to say:

我称它为我价值十亿美元的错误。当时，我正在为一种面向对象语言设计第一个全面的引用类型系统。我的目标是确保所有引用的使用都绝对安全，由编译器自动执行检查。但我禁不住诱惑，加入了一个空引用，仅仅是因为它实现起来非常容易。这导致了无数的错误、漏洞和系统崩溃，在过去的四十年里可能造成了十亿美元的痛苦和损失。

I call it my billion-dollar mistake. At that time, I was designing the first comprehensive type system for references in an object-oriented language. My goal was to ensure that all use of references should be absolutely safe, with checking performed automatically by the compiler. But I couldn’t resist the temptation to put in a null reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system crashes, which have probably caused a billion dollars of pain and damage in the last forty years.

空值的问题在于，如果你尝试将空值作为非空值使用，你会得到某种类型的错误。由于这种空或非空的属性无处不在，极其容易犯这种错误。

The problem with null values is that if you try to use a null value as a not-null value, you’ll get an error of some kind. Because this null or not-null property is pervasive, it’s extremely easy to make this kind of error.

然而，空值试图表达的概念仍然是一个有用的概念：空值是一个当前由于某种原因而无效或缺失的值。

However, the concept that null is trying to express is still a useful one: A null is a value that is currently invalid or absent for some reason.

问题实际上不在于概念，而在于具体的实现。因此，Rust 没有空值，但它确实有一个可以编码值存在或缺失概念的枚举。这个枚举就是 Option<T>，它由标准库定义如下：

The problem isn’t really with the concept but with the particular implementation. As such, Rust does not have nulls, but it does have an enum that can encode the concept of a value being present or absent. This enum is Option<T>, and it is defined by the standard library as follows:

#![allow(unused)]
fn main() {
enum Option<T> {
    None,
    Some(T),
}
}

Option<T> 枚举非常有用，以至于它甚至被包含在预导入模块（prelude）中；你不需要显式地将其引入作用域。它的变体也包含在预导入模块中：你可以直接使用 Some 和 None，而不需要 Option:: 前缀。Option<T> 枚举仍然只是一个普通枚举，而 Some(T) 和 None 仍然是 Option<T> 类型的变体。

The Option<T> enum is so useful that it’s even included in the prelude; you don’t need to bring it into scope explicitly. Its variants are also included in the prelude: You can use Some and None directly without the Option:: prefix. The Option<T> enum is still just a regular enum, and Some(T) and None are still variants of type Option<T>.

<T> 语法是我们尚未谈论的 Rust 功能。它是一个泛型类型参数，我们将在第 10 章更详细地介绍泛型。目前，你只需要知道 <T> 意味着 Option 枚举的 Some 变体可以持有任何类型的一块数据，并且每个用来替代 T 的具体类型都会使整体 Option<T> 类型成为不同的类型。下面是一些使用 Option 值持有数值类型和字符类型的例子：

The <T> syntax is a feature of Rust we haven’t talked about yet. It’s a generic type parameter, and we’ll cover generics in more detail in Chapter 10. For now, all you need to know is that <T> means that the Some variant of the Option enum can hold one piece of data of any type, and that each concrete type that gets used in place of T makes the overall Option<T> type a different type. Here are some examples of using Option values to hold number types and char types:

fn main() {
    let some_number = Some(5);
    let some_char = Some('e');

    let absent_number: Option<i32> = None;
}

some_number 的类型是 Option<i32>。some_char 的类型是 Option<char>，这是一个不同的类型。Rust 可以推断这些类型，因为我们在 Some 变体中指定了一个值。对于 absent_number，Rust 要求我们注解整体的 Option 类型：编译器无法仅通过观察 None 值来推断相应的 Some 变体将持有的类型。在这里，我们告诉 Rust 我们希望 absent_number 的类型为 Option<i32>。

The type of some_number is Option<i32>. The type of some_char is Option<char>, which is a different type. Rust can infer these types because we’ve specified a value inside the Some variant. For absent_number, Rust requires us to annotate the overall Option type: The compiler can’t infer the type that the corresponding Some variant will hold by looking only at a None value. Here, we tell Rust that we mean for absent_number to be of type Option<i32>.

当我们有一个 Some 值时，我们知道值是存在的，并且值被保存在 Some 内部。当我们有一个 None 值时，从某种意义上说，它和空值的意思一样：我们没有一个有效的值。那么，为什么拥有 Option<T> 会比拥有空值更好呢？

When we have a Some value, we know that a value is present, and the value is held within the Some. When we have a None value, in some sense it means the same thing as null: We don’t have a valid value. So, why is having Option<T> any better than having null?

简而言之，因为 Option<T> 和 T（其中 T 可以是任何类型）是不同的类型，编译器不允许我们将 Option<T> 值当作肯定是一个有效值来使用。例如，这段代码无法编译，因为它尝试将 i8 加到 Option<i8> 上：

In short, because Option<T> and T (where T can be any type) are different types, the compiler won’t let us use an Option<T> value as if it were definitely a valid value. For example, this code won’t compile, because it’s trying to add an i8 to an Option<i8>:

fn main() {
    let x: i8 = 5;
    let y: Option<i8> = Some(5);

    let sum = x + y;
}

如果我们运行这段代码，会得到如下错误信息：

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0277]: cannot add `Option<i8>` to `i8`
 --> src/main.rs:5:17
  |
5 |     let sum = x + y;
  |                 ^ no implementation for `i8 + Option<i8>`
  |
  = help: the trait `Add<Option<i8>>` is not implemented for `i8`
  = help: the following other types implement trait `Add<Rhs>`:
            `&i8` implements `Add<i8>`
            `&i8` implements `Add`
            `i8` implements `Add<&i8>`
            `i8` implements `Add`

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

语气强烈！实际上，这条错误信息意味着 Rust 不明白如何将 i8 和 Option<i8> 相加，因为它们是不同的类型。当我们在 Rust 中拥有一个像 i8 这样类型的值时，编译器将确保我们始终拥有一个有效值。我们可以自信地继续，而不必在使用该值之前检查空值。只有当我们拥有一个 Option<i8>（或者我们正在处理的任何类型的值）时，我们才必须担心可能没有值，并且编译器将确保我们在使用该值之前处理了那种情况。

Intense! In effect, this error message means that Rust doesn’t understand how to add an i8 and an Option<i8>, because they’re different types. When we have a value of a type like i8 in Rust, the compiler will ensure that we always have a valid value. We can proceed confidently without having to check for null before using that value. Only when we have an Option<i8> (or whatever type of value we’re working with) do we have to worry about possibly not having a value, and the compiler will make sure we handle that case before using the value.

换句话说，在你对 Option<T> 执行 T 操作之前，你必须将其转换为 T。通常，这有助于捕捉空值最常见的问题之一：假设某物不是空值，而实际上它是空值。

In other words, you have to convert an Option<T> to a T before you can perform T operations with it. Generally, this helps catch one of the most common issues with null: assuming that something isn’t null when it actually is.

消除错误地假设非空值的风险有助于你对代码更有信心。为了拥有一个可能为空的值，你必须显式地通过将该值的类型设为 Option<T> 来选择加入。然后，当你使用该值时，你被要求显式地处理该值为空的情况。只要一个值的类型不是 Option<T>，你就可以安全地假设该值不是空值。这是 Rust 为限制空值的普遍性并提高 Rust 代码安全性而做出的深思熟虑的设计决定。

Eliminating the risk of incorrectly assuming a not-null value helps you be more confident in your code. In order to have a value that can possibly be null, you must explicitly opt in by making the type of that value Option<T>. Then, when you use that value, you are required to explicitly handle the case when the value is null. Everywhere that a value has a type that isn’t an Option<T>, you can safely assume that the value isn’t null. This was a deliberate design decision for Rust to limit null’s pervasiveness and increase the safety of Rust code.

那么，当你拥有一个 Option<T> 类型的值时，如何从 Some 变体中获取 T 值以便使用该值呢？Option<T> 枚举拥有大量在各种情况下都有用的方法；你可以在其文档中查看它们。熟悉 Option<T> 上的方法将在你的 Rust 旅程中极其有用。

So how do you get the T value out of a Some variant when you have a value of type Option<T> so that you can use that value? The Option<T> enum has a large number of methods that are useful in a variety of situations; you can check them out in its documentation. Becoming familiar with the methods on Option<T> will be extremely useful in your journey with Rust.

通常，为了使用 Option<T> 值，你希望拥有能够处理每个变体的代码。你希望一些代码仅在你拥有 Some(T) 值时运行，并且这些代码被允许使用内部的 T。你希望另一些代码仅在你拥有 None 值时运行，并且这些代码没有 T 值可用。match 表达式是一个控制流结构，当与枚举一起使用时，它正是这样做的：它将根据枚举的变体运行不同的代码，并且这些代码可以使用匹配值内部的数据。

In general, in order to use an Option<T> value, you want to have code that will handle each variant. You want some code that will run only when you have a Some(T) value, and this code is allowed to use the inner T. You want some other code to run only if you have a None value, and that code doesn’t have a T value available. The match expression is a control flow construct that does just this when used with enums: It will run different code depending on which variant of the enum it has, and that code can use the data inside the matching value.

match 控制流结构

match 控制流结构

The match Control Flow Construct

Rust 有一个极其强大的控制流结构，叫做 match，它允许你将一个值与一系列模式进行比较，并根据哪个模式匹配来执行代码。模式可以由字面量值、变量名、通配符和许多其他东西组成；第 19 章涵盖了所有不同种类的模式及其作用。match 的强大之处在于模式的表达能力，以及编译器会确认所有可能的情况都已得到处理。

Rust has an extremely powerful control flow construct called match that allows you to compare a value against a series of patterns and then execute code based on which pattern matches. Patterns can be made up of literal values, variable names, wildcards, and many other things; Chapter 19 covers all the different kinds of patterns and what they do. The power of match comes from the expressiveness of the patterns and the fact that the compiler confirms that all possible cases are handled.

你可以把 match 表达式想象成一台硬币分拣机：硬币滑落下一条轨道，轨道上散布着大小不一的孔，每枚硬币都会掉进它遇到的第一个适合它的孔里。同样地，值会经过 match 中的每个模式，在值“适合”的第一个模式处，该值会掉进相关的代码块中，以便在执行期间使用。

Think of a match expression as being like a coin-sorting machine: Coins slide down a track with variously sized holes along it, and each coin falls through the first hole it encounters that it fits into. In the same way, values go through each pattern in a match, and at the first pattern the value “fits,” the value falls into the associated code block to be used during execution.

说到硬币，让我们用它们作为使用 match 的例子！我们可以编写一个函数，它接收一个未知的美国硬币，并以与分拣机类似的方式，确定它是哪种硬币并返回其以美分为单位的值，如示例 6-3 所示。

Speaking of coins, let’s use them as an example using match! We can write a function that takes an unknown US coin and, in a similar way as the counting machine, determines which coin it is and returns its value in cents, as shown in Listing 6-3.

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

让我们分解 value_in_cents 函数中的 match。首先，我们列出 match 关键字，后跟一个表达式，在本例中是值 coin。这看起来与 if 使用的条件表达式非常相似，但有一个很大的区别：对于 if，条件需要计算为布尔值，但在这里它可以是任何类型。本例中 coin 的类型是我们第一行定义的 Coin 枚举。

Let’s break down the match in the value_in_cents function. First, we list the match keyword followed by an expression, which in this case is the value coin. This seems very similar to a conditional expression used with if, but there’s a big difference: With if, the condition needs to evaluate to a Boolean value, but here it can be any type. The type of coin in this example is the Coin enum that we defined on the first line.

接下来是 match 的“分支”（arms）。一个分支由两部分组成：一个模式和一些代码。这里的第一个分支有一个模式，它是值 Coin::Penny，然后是 => 运算符，用于分隔模式和要运行的代码。在本例中，代码只是值 1。每个分支与下一个分支之间用逗号分隔。

Next are the match arms. An arm has two parts: a pattern and some code. The first arm here has a pattern that is the value Coin::Penny and then the => operator that separates the pattern and the code to run. The code in this case is just the value 1. Each arm is separated from the next with a comma.

当 match 表达式执行时，它会按顺序将结果值与每个分支的模式进行比较。如果一个模式匹配该值，则执行与该模式关联的代码。如果该模式不匹配该值，执行将继续到下一个分支，就像在硬币分拣机中一样。我们可以根据需要拥有任意数量的分支：在示例 6-3 中，我们的 match 有四个分支。

When the match expression executes, it compares the resultant value against the pattern of each arm, in order. If a pattern matches the value, the code associated with that pattern is executed. If that pattern doesn’t match the value, execution continues to the next arm, much as in a coin-sorting machine. We can have as many arms as we need: In Listing 6-3, our match has four arms.

与每个分支关联的代码是一个表达式，而匹配分支中表达式的结果值就是整个 match 表达式返回的值。

The code associated with each arm is an expression, and the resultant value of the expression in the matching arm is the value that gets returned for the entire match expression.

如果匹配分支的代码很短，我们通常不使用花括号，就像示例 6-3 中每个分支只返回一个值那样。如果你想在匹配分支中运行多行代码，必须使用花括号，此时分支后面的逗号是可选的。例如，以下代码在每次使用 Coin::Penny 调用该方法时都会打印 “Lucky penny!”，但它仍然返回代码块的最后一个值 1：

We don’t typically use curly brackets if the match arm code is short, as it is in Listing 6-3 where each arm just returns a value. If you want to run multiple lines of code in a match arm, you must use curly brackets, and the comma following the arm is then optional. For example, the following code prints “Lucky penny!” every time the method is called with a Coin::Penny, but it still returns the last value of the block, 1:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        }
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

fn main() {}

绑定到值的模式

Patterns That Bind to Values

匹配分支的另一个有用特性是，它们可以绑定到匹配模式的值的部分。这就是我们如何从枚举变体中提取值的方法。

Another useful feature of match arms is that they can bind to the parts of the values that match the pattern. This is how we can extract values out of enum variants.

作为一个例子，让我们更改一个枚举变体以在其内部持有数据。从 1999 年到 2008 年，美国铸造了 25 美分硬币（quarter），其一面针对 50 个州分别采用了不同的设计。其他硬币都没有州设计，因此只有 25 美分硬币具有此额外值。我们可以通过更改 Quarter 变体以包含存储在其内部的 UsState 值来将此信息添加到我们的 enum 中，我们在示例 6-4 中已经这样做了。

As an example, let’s change one of our enum variants to hold data inside it. From 1999 through 2008, the United States minted quarters with different designs for each of the 50 states on one side. No other coins got state designs, so only quarters have this extra value. We can add this information to our enum by changing the Quarter variant to include a UsState value stored inside it, which we’ve done in Listing 6-4.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {}

让我们设想一个朋友正试图收集所有 50 个州的 25 美分硬币。当我们按硬币类型分拣零钱时，我们还会喊出与每枚 25 美分硬币相关的州的名称，这样如果是我们朋友没有的那个州，他们就可以将其添加到他们的收藏中。

Let’s imagine that a friend is trying to collect all 50 state quarters. While we sort our loose change by coin type, we’ll also call out the name of the state associated with each quarter so that if it’s one our friend doesn’t have, they can add it to their collection.

在此代码的匹配表达式中，我们在匹配变体 Coin::Quarter 值的模式中添加了一个名为 state 的变量。当匹配到 Coin::Quarter 时，state 变量将绑定到该 25 美分硬币所属州的值。然后，我们可以在该分支的代码中使用 state，如下所示：

In the match expression for this code, we add a variable called state to the pattern that matches values of the variant Coin::Quarter. When a Coin::Quarter matches, the state variable will bind to the value of that quarter’s state. Then, we can use state in the code for that arm, like so:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u8 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {state:?}!");
            25
        }
    }
}

fn main() {
    value_in_cents(Coin::Quarter(UsState::Alaska));
}

如果我们调用 value_in_cents(Coin::Quarter(UsState::Alaska))，coin 将是 Coin::Quarter(UsState::Alaska)。当我们将该值与每个匹配分支进行比较时，在到达 Coin::Quarter(state) 之前，它们都不匹配。届时，state 的绑定将是值 UsState::Alaska。然后我们可以在 println! 表达式中使用该绑定，从而从 Quarter 的 Coin 枚举变体中提取出内部的州值。

If we were to call value_in_cents(Coin::Quarter(UsState::Alaska)), coin would be Coin::Quarter(UsState::Alaska). When we compare that value with each of the match arms, none of them match until we reach Coin::Quarter(state). At that point, the binding for state will be the value UsState::Alaska. We can then use that binding in the println! expression, thus getting the inner state value out of the Coin enum variant for Quarter.

匹配 Option<T>

The Option<T> match Pattern

在上一节中，我们想在使用 Option<T> 时从 Some 情况中提取出内部的 T 值；我们也可以像处理 Coin 枚举一样，使用 match 处理 Option<T>！我们将比较 Option<T> 的变体，而不是比较硬币，但 match 表达式的工作方式保持不变。

In the previous section, we wanted to get the inner T value out of the Some case when using Option<T>; we can also handle Option<T> using match, as we did with the Coin enum! Instead of comparing coins, we’ll compare the variants of Option<T>, but the way the match expression works remains the same.

假设我们要编写一个函数，它接收一个 Option<i32>，如果有值在内部，就给该值加 1。如果内部没有值，函数应返回 None 值，并且不尝试执行任何操作。

Let’s say we want to write a function that takes an Option<i32> and, if there’s a value inside, adds 1 to that value. If there isn’t a value inside, the function should return the None value and not attempt to perform any operations.

由于有了 match，这个函数非常容易编写，看起来就像示例 6-5。

This function is very easy to write, thanks to match, and will look like Listing 6-5.

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

让我们更详细地研究一下 plus_one 的第一次执行。当我们调用 plus_one(five) 时，plus_one 体内的变量 x 将具有值 Some(5)。然后我们将其与每个匹配分支进行比较：

Let’s examine the first execution of plus_one in more detail. When we call plus_one(five), the variable x in the body of plus_one will have the value Some(5). We then compare that against each match arm:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 值不匹配模式 None，所以我们继续下一个分支：

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

The Some(5) value doesn’t match the pattern None, so we continue to the next arm:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

Some(5) 匹配 Some(i) 吗？是的！我们有相同的变体。i 绑定到 Some 中包含的值，所以 i 取值 5。然后执行匹配分支中的代码，所以我们给 i 的值加 1，并创建一个内部总和为 6 的新 Some 值。

Does Some(5) match Some(i)? It does! We have the same variant. The i binds to the value contained in Some, so i takes the value 5. The code in the match arm is then executed, so we add 1 to the value of i and create a new Some value with our total 6 inside.

现在让我们考虑示例 6-5 中 plus_one 的第二次调用，其中 x 是 None。我们进入 match 并与第一个分支比较：

Now let’s consider the second call of plus_one in Listing 6-5, where x is None. We enter the match and compare to the first arm:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            None => None,
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

匹配成功！没有值可以相加，所以程序停止并返回 => 右侧的 None 值。因为第一个分支匹配了，所以不会再比较其他分支。

It matches! There’s no value to add to, so the program stops and returns the None value on the right side of =>. Because the first arm matched, no other arms are compared.

将 match 和枚举结合使用在许多情况下都很有用。你会在 Rust 代码中经常看到这种模式：针对枚举进行 match，将一个变量绑定到内部数据，然后根据其执行代码。起初这有点棘手，但一旦习惯了，你就会希望所有语言都有这个功能。它始终是用户的最爱。

Combining match and enums is useful in many situations. You’ll see this pattern a lot in Rust code: match against an enum, bind a variable to the data inside, and then execute code based on it. It’s a bit tricky at first, but once you get used to it, you’ll wish you had it in all languages. It’s consistently a user favorite.

匹配是穷尽的

Matches Are Exhaustive

我们还需要讨论 match 的另一个方面：分支的模式必须涵盖所有可能性。考虑一下我们 plus_one 函数的这个版本，它有一个 bug 且无法编译：

There’s one other aspect of match we need to discuss: The arms’ patterns must cover all possibilities. Consider this version of our plus_one function, which has a bug and won’t compile:

fn main() {
    fn plus_one(x: Option<i32>) -> Option<i32> {
        match x {
            Some(i) => Some(i + 1),
        }
    }

    let five = Some(5);
    let six = plus_one(five);
    let none = plus_one(None);
}

我们没有处理 None 的情况，所以这段代码会导致 bug。幸运的是，这是 Rust 知道如何捕捉的 bug。如果我们尝试编译这段代码，我们会得到这个错误：

$ cargo run
   Compiling enums v0.1.0 (file:///projects/enums)
error[E0004]: non-exhaustive patterns: `None` not covered
 --> src/main.rs:3:15
  |
3 |         match x {
  |               ^ pattern `None` not covered
  |
note: `Option<i32>` defined here
 --> /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:593:1
 ::: /rustc/1159e78c4747b02ef996e55082b704c09b970588/library/core/src/option.rs:597:5
  |
  = note: not covered
  = note: the matched value is of type `Option<i32>`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown
  |
4 ~             Some(i) => Some(i + 1),
5 ~             None => todo!(),
  |

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

Rust 知道我们没有涵盖所有可能的情况，甚至知道我们忘记了哪个模式！Rust 中的匹配是“穷尽的”（exhaustive）：为了使代码有效，我们必须穷尽最后一种可能性。特别是在 Option<T> 的情况下，当 Rust 阻止我们忘记显式处理 None 情况时，它保护我们免于假设拥有一个值（而实际上可能是空值），从而使前面讨论的价值十亿美元的错误变得不可能。

Rust knows that we didn’t cover every possible case and even knows which pattern we forgot! Matches in Rust are exhaustive: We must exhaust every last possibility in order for the code to be valid. Especially in the case of Option<T>, when Rust prevents us from forgetting to explicitly handle the None case, it protects us from assuming that we have a value when we might have null, thus making the billion-dollar mistake discussed earlier impossible.

通配模式和 _ 占位符

Catch-All Patterns and the _ Placeholder

使用枚举，我们还可以对几个特定值采取特殊操作，但对所有其他值采取一个默认操作。想象一下，我们正在实现一个游戏，如果你掷骰子掷到 3，你的角色不会移动，而是会得到一顶漂亮的新帽子。如果你掷到 7，你的角色会失去一顶漂亮的帽子。对于所有其他值，你的角色会在游戏板上移动相应格数。这里有一个实现该逻辑的 match，骰子的结果是硬编码的而不是随机值，所有其他逻辑由没有函数体的函数表示，因为实际实现它们超出了本例的范围：

Using enums, we can also take special actions for a few particular values, but for all other values take one default action. Imagine we’re implementing a game where, if you roll a 3 on a dice roll, your player doesn’t move but instead gets a fancy new hat. If you roll a 7, your player loses a fancy hat. For all other values, your player moves that number of spaces on the game board. Here’s a match that implements that logic, with the result of the dice roll hardcoded rather than a random value, and all other logic represented by functions without bodies because actually implementing them is out of scope for this example:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        other => move_player(other),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn move_player(num_spaces: u8) {}
}

对于前两个分支，模式是字面量值 3 和 7。对于涵盖所有其他可能值的最后一个分支，模式是我们选择命名为 other 的变量。为 other 分支运行的代码通过将其传递给 move_player 函数来使用该变量。

For the first two arms, the patterns are the literal values 3 and 7. For the last arm that covers every other possible value, the pattern is the variable we’ve chosen to name other. The code that runs for the other arm uses the variable by passing it to the move_player function.

即使我们没有列出 u8 可能具有的所有值，这段代码也可以编译，因为最后一个模式将匹配所有未明确列出的值。这个通配模式满足了 match 必须是穷尽的要求。注意我们必须把通配分支放在最后，因为模式是按顺序评估的。如果我们把通配分支放在前面，其他分支将永远不会运行，所以如果你在通配分支后面添加分支，Rust 会警告你！

This code compiles, even though we haven’t listed all the possible values a u8 can have, because the last pattern will match all values not specifically listed. This catch-all pattern meets the requirement that match must be exhaustive. Note that we have to put the catch-all arm last because the patterns are evaluated in order. If we had put the catch-all arm earlier, the other arms would never run, so Rust will warn us if we add arms after a catch-all!

当我们想要一个通配模式但又不想“使用”通配模式中的值时，Rust 还有一个模式可以使用：_ 是一个特殊的模式，它匹配任何值且不绑定到该值。这告诉 Rust 我们不打算使用该值，所以 Rust 不会警告我们变量未使用。

Rust also has a pattern we can use when we want a catch-all but don’t want to use the value in the catch-all pattern: _ is a special pattern that matches any value and does not bind to that value. This tells Rust we aren’t going to use the value, so Rust won’t warn us about an unused variable.

让我们改变游戏规则：现在，如果你掷出 3 或 7 以外的任何数字，你必须重新掷一次。我们不再需要使用通配值，所以我们可以将代码改为使用 _ 而不是名为 other 的变量：

Let’s change the rules of the game: Now, if you roll anything other than a 3 or a 7, you must roll again. We no longer need to use the catch-all value, so we can change our code to use _ instead of the variable named other:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => reroll(),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
    fn reroll() {}
}

这个例子也满足了穷尽性要求，因为我们在最后一个分支中显式地忽略了所有其他值；我们没有遗漏任何东西。

This example also meets the exhaustiveness requirement because we’re explicitly ignoring all other values in the last arm; we haven’t forgotten anything.

最后，我们再次更改游戏规则，如果你掷出 3 或 7 以外的任何数字，你的回合什么都不会发生。我们可以通过使用单元值（我们在“元组类型”部分提到的空元组类型）作为 _ 分支对应的代码来表达这一点：

Finally, we’ll change the rules of the game one more time so that nothing else happens on your turn if you roll anything other than a 3 or a 7. We can express that by using the unit value (the empty tuple type we mentioned in “The Tuple Type” section) as the code that goes with the _ arm:

fn main() {
    let dice_roll = 9;
    match dice_roll {
        3 => add_fancy_hat(),
        7 => remove_fancy_hat(),
        _ => (),
    }

    fn add_fancy_hat() {}
    fn remove_fancy_hat() {}
}

在这里，我们显式地告诉 Rust 我们不会使用任何不匹配前面分支模式的其他值，并且在这种情况下我们不想运行任何代码。

Here, we’re telling Rust explicitly that we aren’t going to use any other value that doesn’t match a pattern in an earlier arm, and we don’t want to run any code in this case.

关于模式和匹配的内容，我们将在第 19 章中进一步讨论。现在，我们要继续讨论 if let 语法，它在 match 表达式显得有点冗长的情况下非常有用。

There’s more about patterns and matching that we’ll cover in Chapter 19. For now, we’re going to move on to the if let syntax, which can be useful in situations where the match expression is a bit wordy.

使用 if let 和 let...else 的简洁控制流

使用 if let 和 let...else 的简洁控制流

Concise Control Flow with if let and let...else

if let 语法让你可以将 if 和 let 结合成一种更不冗长的方式，来处理匹配一个模式的值，同时忽略其余模式。考虑示例 6-6 中的程序，它在 config_max 变量中匹配 Option<u8> 值，但只想在值是 Some 变体时执行代码。

The if let syntax lets you combine if and let into a less verbose way to handle values that match one pattern while ignoring the rest. Consider the program in Listing 6-6 that matches on an Option<u8> value in the config_max variable but only wants to execute code if the value is the Some variant.

fn main() {
    let config_max = Some(3u8);
    match config_max {
        Some(max) => println!("The maximum is configured to be {max}"),
        _ => (),
    }
}

如果值是 Some，我们通过在模式中将值绑定到变量 max 来打印出 Some 变体中的值。我们不想对 None 值做任何事情。为了满足 match 表达式，我们必须在仅处理一个变体后添加 _ => ()，这是添加起来很烦人的样板代码。

If the value is Some, we print out the value in the Some variant by binding the value to the variable max in the pattern. We don’t want to do anything with the None value. To satisfy the match expression, we have to add _ => () after processing just one variant, which is annoying boilerplate code to add.

相反，我们可以使用 if let 以更短的方式编写这段代码。以下代码的行为与示例 6-6 中的 match 相同：

Instead, we could write this in a shorter way using if let. The following code behaves the same as the match in Listing 6-6:

fn main() {
    let config_max = Some(3u8);
    if let Some(max) = config_max {
        println!("The maximum is configured to be {max}");
    }
}

语法 if let 接收一个模式和一个表达式，两者用等号分隔。它的工作方式与 match 相同，其中表达式被提供给 match，而模式是其第一个分支。在本例中，模式是 Some(max)，而 max 绑定到 Some 内部的值。然后我们可以在 if let 块的正文中使用 max，方式与在相应的 match 分支中使用 max 相同。if let 块中的代码仅在值匹配模式时运行。

The syntax if let takes a pattern and an expression separated by an equal sign. It works the same way as a match, where the expression is given to the match and the pattern is its first arm. In this case, the pattern is Some(max), and the max binds to the value inside the Some. We can then use max in the body of the if let block in the same way we used max in the corresponding match arm. The code in the if let block only runs if the value matches the pattern.

使用 if let 意味着更少的输入、更少的缩进和更少的样板代码。然而，你失去了 match 强制执行的穷尽性检查，该检查确保你没有忘记处理任何情况。在 match 和 if let 之间做出选择取决于你在特定情况下正在做什么，以及获得简洁性是否是失去穷尽性检查的合适折衷。

Using if let means less typing, less indentation, and less boilerplate code. However, you lose the exhaustive checking match enforces that ensures that you aren’t forgetting to handle any cases. Choosing between match and if let depends on what you’re doing in your particular situation and whether gaining conciseness is an appropriate trade-off for losing exhaustive checking.

换句话说，你可以将 if let 看作是 match 的语法糖，它在值匹配一个模式时运行代码，然后忽略所有其他值。

In other words, you can think of if let as syntax sugar for a match that runs code when the value matches one pattern and then ignores all other values.

我们可以在 if let 中包含 else。与 else 搭配的代码块与在等效于 if let 和 else 的 match 表达式中与 _ 情况搭配的代码块相同。回想示例 6-4 中的 Coin 枚举定义，其中 Quarter 变体还持有一个 UsState 值。如果我们想在宣布 25 美分硬币所属州的同时，也清点我们看到的所有非 25 美分硬币，我们可以用 match 表达式这样做：

We can include an else with an if let. The block of code that goes with the else is the same as the block of code that would go with the _ case in the match expression that is equivalent to the if let and else. Recall the Coin enum definition in Listing 6-4, where the Quarter variant also held a UsState value. If we wanted to count all non-quarter coins we see while also announcing the state of the quarters, we could do that with a match expression, like this:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    match coin {
        Coin::Quarter(state) => println!("State quarter from {state:?}!"),
        _ => count += 1,
    }
}

或者我们可以使用 if let 和 else 表达式，像这样：

Or we could use an if let and else expression, like this:

#[derive(Debug)]
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn main() {
    let coin = Coin::Penny;
    let mut count = 0;
    if let Coin::Quarter(state) = coin {
        println!("State quarter from {state:?}!");
    } else {
        count += 1;
    }
}

使用 let...else 保持在“快乐路径”上

Staying on the “Happy Path” with let...else

常见的模式是当值存在时执行某些计算，否则返回一个默认值。继续我们带有 UsState 值的硬币示例，如果我们想根据 25 美分硬币上的州有多古老来说些有趣的话，我们可能会在 UsState 上引入一个方法来检查州的年龄，如下所示：

The common pattern is to perform some computation when a value is present and return a default value otherwise. Continuing with our example of coins with a UsState value, if we wanted to say something funny depending on how old the state on the quarter was, we might introduce a method on UsState to check the age of a state, like so:

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

然后，我们可能会使用 if let 来匹配硬币类型，在条件正文中引入一个 state 变量，如示例 6-7 所示。

Then, we might use if let to match on the type of coin, introducing a state variable within the body of the condition, as in Listing 6-7.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    if let Coin::Quarter(state) = coin {
        if state.existed_in(1900) {
            Some(format!("{state:?} is pretty old, for America!"))
        } else {
            Some(format!("{state:?} is relatively new."))
        }
    } else {
        None
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

这完成了任务，但它将工作推到了 if let 语句的正文中，如果待完成的工作更复杂，可能很难确切地跟随顶级分支是如何关联的。我们也可以利用表达式产生一个值的事实，要么从 if let 产生 state ，要么提前返回，如示例 6-8 所示。（你也可以用 match 做类似的事情。）

That gets the job done, but it has pushed the work into the body of the if let statement, and if the work to be done is more complicated, it might be hard to follow exactly how the top-level branches relate. We could also take advantage of the fact that expressions produce a value either to produce the state from the if let or to return early, as in Listing 6-8. (You could do something similar with a match, too.)

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let state = if let Coin::Quarter(state) = coin {
        state
    } else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

不过，这本身也有点让人烦！if let 的一个分支产生一个值，而另一个分支则完全从函数返回。

This is a bit annoying to follow in its own way, though! One branch of the if let produces a value, and the other one returns from the function entirely.

为了使这种常见的模式更漂亮地表达，Rust 提供了 let...else。let...else 语法在左侧接收一个模式，在右侧接收一个表达式，与 if let 非常相似，但它没有 if 分支，只有 else 分支。如果模式匹配，它将在外部作用域中绑定来自模式的值。如果模式“不”匹配，程序将流入 else 分支，该分支必须从函数返回。

To make this common pattern nicer to express, Rust has let...else. The let...else syntax takes a pattern on the left side and an expression on the right, very similar to if let, but it does not have an if branch, only an else branch. If the pattern matches, it will bind the value from the pattern in the outer scope. If the pattern does not match, the program will flow into the else arm, which must return from the function.

在示例 6-9 中，你可以看到使用 let...else 代替 if let 时示例 6-8 看起来是什么样子的。

In Listing 6-9, you can see how Listing 6-8 looks when using let...else in place of if let.

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

impl UsState {
    fn existed_in(&self, year: u16) -> bool {
        match self {
            UsState::Alabama => year >= 1819,
            UsState::Alaska => year >= 1959,
            // -- snip --
        }
    }
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn describe_state_quarter(coin: Coin) -> Option<String> {
    let Coin::Quarter(state) = coin else {
        return None;
    };

    if state.existed_in(1900) {
        Some(format!("{state:?} is pretty old, for America!"))
    } else {
        Some(format!("{state:?} is relatively new."))
    }
}

fn main() {
    if let Some(desc) = describe_state_quarter(Coin::Quarter(UsState::Alaska)) {
        println!("{desc}");
    }
}

请注意，以这种方式在函数的主体中它保持在“快乐路径”（happy path）上，而不会像 if let 那样为两个分支提供显着不同的控制流。

Notice that it stays on the “happy path” in the main body of the function this way, without having significantly different control flow for two branches the way the if let did.

如果你遇到程序逻辑过于冗长而无法使用 match 表达的情况，请记住 if let 和 let...else 也在你的 Rust 工具箱中。

If you have a situation in which your program has logic that is too verbose to express using a match, remember that if let and let...else are in your Rust toolbox as well.

总结

Summary

我们现在已经介绍了如何使用枚举来创建自定义类型，这些类型可以是枚举值集合中的一个。我们展示了标准库的 Option<T> 类型如何帮助你利用类型系统来预防错误。当枚举值内部包含数据时，你可以根据需要处理的情况数量，使用 match 或 if let 来提取并使用这些值。

We’ve now covered how to use enums to create custom types that can be one of a set of enumerated values. We’ve shown how the standard library’s Option<T> type helps you use the type system to prevent errors. When enum values have data inside them, you can use match or if let to extract and use those values, depending on how many cases you need to handle.

你的 Rust 程序现在可以使用结构体和枚举来表达你领域中的概念。创建要在 API 中使用的自定义类型可确保类型安全：编译器将确保你的函数仅获得每个函数所期望类型的值。

Your Rust programs can now express concepts in your domain using structs and enums. Creating custom types to use in your API ensures type safety: The compiler will make certain your functions only get values of the type each function expects.

为了向你的用户提供组织良好、易于使用且仅公开用户确切需要内容的 API，现在让我们转向 Rust 的模块（modules）。

In order to provide a well-organized API to your users that is straightforward to use and only exposes exactly what your users will need, let’s now turn to Rust’s modules.

Package、Crate 和模块

Packages, Crates, and Modules

当你编写大型程序时，组织代码将变得越来越重要。通过将相关功能分组并将具有不同特性的代码分离，你将明确在哪里可以找到实现特定功能的代码，以及在哪里可以更改功能的工作方式。

As you write large programs, organizing your code will become increasingly important. By grouping related functionality and separating code with distinct features, you’ll clarify where to find code that implements a particular feature and where to go to change how a feature works.

到目前为止，我们编写的程序都在一个文件中的一个模块中。随着项目的增长，你应该通过将代码拆分为多个模块然后再拆分为多个文件来组织代码。一个 package 可以包含多个二进制 crate，以及可选的一个库 crate。随着 package 的增长，你可以将其部分提取到单独的 crate 中，从而成为外部依赖项。本章涵盖了所有这些技术。对于由一组相互关联、共同发展的 package 组成的大型项目，Cargo 提供了 workspace（工作空间），我们将在第 14 章的“Cargo Workspace”中进行介绍。

The programs we’ve written so far have been in one module in one file. As a project grows, you should organize code by splitting it into multiple modules and then multiple files. A package can contain multiple binary crates and optionally one library crate. As a package grows, you can extract parts into separate crates that become external dependencies. This chapter covers all these techniques. For very large projects comprising a set of interrelated packages that evolve together, Cargo provides workspaces, which we’ll cover in “Cargo Workspaces” in Chapter 14.

我们还将讨论封装实现细节，这允许你在更高层次上重用代码：一旦你实现了一个操作，其他代码就可以通过其公共接口调用你的代码，而无需知道实现是如何工作的。你编写代码的方式定义了哪些部分是公开给其他代码使用的，哪些部分是保留更改权的私有实现细节。这是限制你脑子里必须保留细节数量的另一种方法。

We’ll also discuss encapsulating implementation details, which lets you reuse code at a higher level: Once you’ve implemented an operation, other code can call your code via its public interface without having to know how the implementation works. The way you write code defines which parts are public for other code to use and which parts are private implementation details that you reserve the right to change. This is another way to limit the amount of detail you have to keep in your head.

一个相关的概念是作用域：编写代码的嵌套上下文有一组被定义为“在作用域内”的名称。在阅读、编写和编译代码时，程序员和编译器需要知道特定位置的特定名称是指变量、函数、结构体、枚举、模块、常量还是其他项，以及该项的含义。你可以创建作用域，并更改哪些名称在作用域内或作用域外。在同一个作用域内不能有两个同名的项；可以使用工具来解决名称冲突。

A related concept is scope: The nested context in which code is written has a set of names that are defined as “in scope.” When reading, writing, and compiling code, programmers and compilers need to know whether a particular name at a particular spot refers to a variable, function, struct, enum, module, constant, or other item and what that item means. You can create scopes and change which names are in or out of scope. You can’t have two items with the same name in the same scope; tools are available to resolve name conflicts.

Rust 有许多功能允许你管理代码组织，包括公开哪些细节、哪些细节是私有的，以及程序中每个作用域内有哪些名称。这些功能有时统称为“模块系统”（module system），包括：

Rust has a number of features that allow you to manage your code’s organization, including which details are exposed, which details are private, and what names are in each scope in your programs. These features, sometimes collectively referred to as the module system, include:

• Package（包）：让你构建、测试和共享 crate 的 Cargo 功能。

• Packages: A Cargo feature that lets you build, test, and share crates

• Crate（单元包）：产生库或可执行文件的模块树。

• Crates: A tree of modules that produces a library or executable

• 模块（Module）和 use：让你控制路径的组织、作用域和隐私。

• Modules and use: Let you control the organization, scope, and privacy of paths

• 路径（Path）：命名项（如结构体、函数或模块）的方法。

• Paths: A way of naming an item, such as a struct, function, or module

在本章中，我们将涵盖所有这些功能，讨论它们如何交互，并解释如何使用它们来管理作用域。到最后，你应该对模块系统有深刻的理解，并能像专家一样处理作用域！

In this chapter, we’ll cover all these features, discuss how they interact, and explain how to use them to manage scope. By the end, you should have a solid understanding of the module system and be able to work with scopes like a pro!

包和 Crate

Package 和 Crate

Packages and Crates

我们要讨论的模块系统的第一部分是 package（包）和 crate（单元包）。

The first parts of the module system we’ll cover are packages and crates.

Crate 是 Rust 编译器一次考虑的最小代码量。即使你运行 rustc 而不是 cargo 并传递一个源代码文件（正如我们在第 1 章“Rust 程序基础”中所做的那样），编译器也会将该文件视为一个 crate。Crate 可以包含模块，并且这些模块可能定义在随 crate 一起编译的其他文件中，我们将在接下来的章节中看到。

A crate is the smallest amount of code that the Rust compiler considers at a time. Even if you run rustc rather than cargo and pass a single source code file (as we did all the way back in “Rust Program Basics” in Chapter 1), the compiler considers that file to be a crate. Crates can contain modules, and the modules may be defined in other files that get compiled with the crate, as we’ll see in the coming sections.

Crate 有两种形式：二进制 crate 或库 crate。二进制 crate（Binary crates）是可以编译成可运行的可执行文件的程序，例如命令行程序或服务器。每个二进制 crate 必须有一个名为 main 的函数，该函数定义了可执行文件运行时的行为。到目前为止，我们创建的所有 crate 都是二进制 crate。

A crate can come in one of two forms: a binary crate or a library crate. Binary crates are programs you can compile to an executable that you can run, such as a command line program or a server. Each must have a function called main that defines what happens when the executable runs. All the crates we’ve created so far have been binary crates.

库 crate（Library crates）没有 main 函数，且不会编译为可执行文件。相反，它们定义了旨在与多个项目共享的功能。例如，我们在第 2 章中使用的 rand crate 提供了生成随机数的功能。大多数时候 Rustacean 说 “crate” 时指的是库 crate，并且他们将 “crate” 与通用的编程概念“库”（library）互换使用。

Library crates don’t have a main function, and they don’t compile to an executable. Instead, they define functionality intended to be shared with multiple projects. For example, the rand crate we used in Chapter 2 provides functionality that generates random numbers. Most of the time when Rustaceans say “crate,” they mean library crate, and they use “crate” interchangeably with the general programming concept of a “library.”

Crate root（单元包根）是 Rust 编译器开始并构成 crate 根模块的源文件（我们将在“使用模块控制作用域和隐私”中深入解释模块）。

The crate root is a source file that the Rust compiler starts from and makes up the root module of your crate (we’ll explain modules in depth in “Control Scope and Privacy with Modules”).

Package 是提供一组功能的一个或多个 crate 的捆绑。Package 包含一个 Cargo.toml 文件，该文件描述了如何构建这些 crate。Cargo 实际上是一个 package，它包含你一直用来构建代码的命令行工具的二进制 crate。Cargo package 还包含二进制 crate 所依赖的库 crate。其他项目可以依赖 Cargo 库 crate 来使用 Cargo 命令行工具使用的相同逻辑。

A package is a bundle of one or more crates that provides a set of functionality. A package contains a Cargo.toml file that describes how to build those crates. Cargo is actually a package that contains the binary crate for the command line tool you’ve been using to build your code. The Cargo package also contains a library crate that the binary crate depends on. Other projects can depend on the Cargo library crate to use the same logic the Cargo command line tool uses.

一个 package 可以包含任意数量的二进制 crate，但最多只能包含一个库 crate。一个 package 必须包含至少一个 crate，无论是库 crate 还是二进制 crate。

A package can contain as many binary crates as you like, but at most only one library crate. A package must contain at least one crate, whether that’s a library or binary crate.

让我们看看创建一个 package 时会发生什么。首先，我们输入命令 cargo new my-project：

Let’s walk through what happens when we create a package. First, we enter the command cargo new my-project:

$ cargo new my-project
     Created binary (application) `my-project` package
$ ls my-project
Cargo.toml
src
$ ls my-project/src
main.rs

运行 cargo new my-project 后，我们使用 ls 查看 Cargo 创建了什么。在 my-project 目录中，有一个 Cargo.toml 文件，为我们提供了一个 package。还有一个包含 main.rs 的 src 目录。在文本编辑器中打开 Cargo.toml，注意没有提到 src/main.rs。Cargo 遵循一项约定，即 src/main.rs 是与 package 同名的二进制 crate 的 crate root。同样，Cargo 知道如果 package 目录包含 src/lib.rs，则 package 包含一个与 package 同名的库 crate，并且 src/lib.rs 是其 crate root。Cargo 将 crate root 文件传递给 rustc 以构建库或二进制文件。

After we run cargo new my-project, we use ls to see what Cargo creates. In the my-project directory, there’s a Cargo.toml file, giving us a package. There’s also a src directory that contains main.rs. Open Cargo.toml in your text editor and note that there’s no mention of src/main.rs. Cargo follows a convention that src/main.rs is the crate root of a binary crate with the same name as the package. Likewise, Cargo knows that if the package directory contains src/lib.rs, the package contains a library crate with the same name as the package, and src/lib.rs is its crate root. Cargo passes the crate root files to rustc to build the library or binary.

在这里，我们有一个仅包含 src/main.rs 的 package，这意味着它仅包含一个名为 my-project 的二进制 crate。如果一个 package 包含 src/main.rs 和 src/lib.rs，它就有两个 crate：一个二进制 crate 和一个库 crate，且两者都与 package 同名。通过将文件放置在 src/bin 目录中，一个 package 可以拥有多个二进制 crate：每个文件都将是一个单独的二进制 crate。

Here, we have a package that only contains src/main.rs, meaning it only contains a binary crate named my-project. If a package contains src/main.rs and src/lib.rs, it has two crates: a binary and a library, both with the same name as the package. A package can have multiple binary crates by placing files in the src/bin directory: Each file will be a separate binary crate.

使用模块控制作用域和私有性

使用模块控制作用域和隐私

Control Scope and Privacy with Modules

在本节中，我们将讨论模块和模块系统的其他部分，即：允许你命名的路径（paths）；将路径引入作用域的 use 关键字；以及使项变为公开的 pub 关键字。我们还将讨论 as 关键字、外部 package 以及 glob 运算符。

In this section, we’ll talk about modules and other parts of the module system, namely paths, which allow you to name items; the use keyword that brings a path into scope; and the pub keyword to make items public. We’ll also discuss the as keyword, external packages, and the glob operator.

模块速查表

Modules Cheat Sheet

在深入了解模块和路径的细节之前，这里我们提供了一个关于模块、路径、use 关键字和 pub 关键字在编译器中如何工作，以及大多数开发人员如何组织他们的代码的快速参考。我们将在本章中贯穿这些规则的示例，但这是一个提醒模块如何工作的绝佳参考。

Before we get to the details of modules and paths, here we provide a quick reference on how modules, paths, the use keyword, and the pub keyword work in the compiler, and how most developers organize their code. We’ll be going through examples of each of these rules throughout this chapter, but this is a great place to refer to as a reminder of how modules work.

• 从 crate root 开始：在编译 crate 时，编译器首先在 crate root 文件（通常库 crate 为 src/lib.rs，二进制 crate 为 src/main.rs）中寻找要编译的代码。

• Start from the crate root: When compiling a crate, the compiler first looks in the crate root file (usually src/lib.rs for a library crate and src/main.rs for a binary crate) for code to compile.

• 声明模块：在 crate root 文件中，你可以声明新模块；假设你用 mod garden; 声明了一个 “garden” 模块。编译器将在以下位置寻找模块的代码：

• Declaring modules: In the crate root file, you can declare new modules; say you declare a “garden” module with mod garden;. The compiler will look for the module’s code in these places:

  • 内联（Inline），在取代 mod garden 后面分号的花括号内。

  • Inline, within curly brackets that replace the semicolon following mod garden

  • 在文件 src/garden.rs 中。

  • In the file src/garden.rs

  • 在文件 src/garden/mod.rs 中。

  • In the file src/garden/mod.rs

• 声明子模块：在除 crate root 以外的任何文件中，你都可以声明子模块。例如，你可能在 src/garden.rs 中声明 mod vegetables;。编译器将在以父模块命名的目录下寻找子模块的代码：

• Declaring submodules: In any file other than the crate root, you can declare submodules. For example, you might declare mod vegetables; in src/garden.rs. The compiler will look for the submodule’s code within the directory named for the parent module in these places:

  • 内联，直接跟在 mod vegetables 后面，放在花括号内而不是分号。

  • Inline, directly following mod vegetables, within curly brackets instead of the semicolon

  • 在文件 src/garden/vegetables.rs 中。

  • In the file src/garden/vegetables.rs

  • 在文件 src/garden/vegetables/mod.rs 中。

  • In the file src/garden/vegetables/mod.rs

• 模块中代码的路径：一旦模块成为你 crate 的一部分，你就可以从同一个 crate 的任何其他地方引用该模块中的代码，只要隐私规则允许，使用代码的路径即可。例如，garden vegetables 模块中的 Asparagus 类型将在 crate::garden::vegetables::Asparagus 找到。

• Paths to code in modules: Once a module is part of your crate, you can refer to code in that module from anywhere else in that same crate, as long as the privacy rules allow, using the path to the code. For example, an Asparagus type in the garden vegetables module would be found at crate::garden::vegetables::Asparagus.

• 私有与公开：默认情况下，模块内的代码对其父模块是私有的。要使模块公开，请使用 pub mod 而不是 mod 来声明它。要使公开模块内的项也公开，请在它们的声明前使用 pub。

• Private vs. public: Code within a module is private from its parent modules by default. To make a module public, declare it with pub mod instead of mod. To make items within a public module public as well, use pub before their declarations.

• use 关键字：在一个作用域内，use 关键字可以为项创建快捷方式，以减少长路径的重复。在任何可以引用 crate::garden::vegetables::Asparagus 的作用域内，你都可以使用 use crate::garden::vegetables::Asparagus; 创建快捷方式，从那时起你只需要编写 Asparagus 即可在作用域内使用该类型。

• The use keyword: Within a scope, the use keyword creates shortcuts to items to reduce repetition of long paths. In any scope that can refer to crate::garden::vegetables::Asparagus, you can create a shortcut with use crate::garden::vegetables::Asparagus;, and from then on you only need to write Asparagus to make use of that type in the scope.