简介

本书是 Rust 编程语言的主要参考文档。

Rust 版本发布

Rust 每六周发布一次新版本。 该语言的第一个稳定版本是 Rust 1.0.0，随后是 Rust 1.1.0，依此类推。 工具（rustc、cargo 等）和文档（[标准库]、本书等）随语言版本一起发布。

本书的最新版本（与最新 Rust 版本匹配）始终可以在 https://doc.rust-lang.org/reference/ 找到。 之前的版本可以通过在 “reference” 目录之前添加 Rust 版本来找到。 例如，Rust 1.49.0 的参考文档位于 https://doc.rust-lang.org/1.49.0/reference/。

参考文档不是什么

本书不作为该语言的入门教程。 假定读者已经具备该语言的背景知识。 另外有一本书籍可以帮助获取这种背景知识。

本书也不作为语言发行版中包含的[标准库]的参考文档。 这些库通过从其源代码中提取文档属性来单独记录。 许多您可能认为是语言特性的功能在 Rust 中是库特性，所以您要查找的内容可能在那里，而不是在这里。

同样，本书通常不记录 rustc 作为工具或 Cargo 的具体细节。 rustc 有自己的书籍。 Cargo 有一本书籍，其中包含一个参考文档。 有几页（如链接）仍然描述了 rustc 的工作方式。

本书也仅作为稳定版 Rust 中可用功能的参考。 关于正在开发的不稳定功能，请参阅不稳定之书。

Rust 编译器（包括 rustc）会执行优化。 参考文档不指定允许或禁止哪些优化。 相反，将编译后的程序视为一个黑盒。 您只能通过运行它、输入数据并观察其输出来探测。 以这种方式发生的一切都必须符合参考文档的说明。

如何使用本书

本书不假定您是按顺序阅读本书。 每章通常可以独立阅读，但会交叉链接到其他章节，以获取它们引用但未讨论的语言方面。

阅读本文档有两种主要方式。

第一种是回答特定问题。 如果您知道哪一章回答了该问题，可以直接跳转到目录中的那一章。 否则，您可以按 s 或单击顶部栏上的放大镜来搜索与问题相关的关键字。 例如，假设您想知道在 let 语句中创建的临时值何时被丢弃。 如果您不知道临时值的生命周期是在表达式章节中定义的，您可以搜索 “temporary let”，第一个搜索结果将带您到该部分。

第二种是总体上提高您对语言某个方面的了解。 在这种情况下，只需浏览目录直到看到您想了解更多的内容，然后开始阅读。 如果某个链接看起来很有趣，请单击它，并阅读该部分。

话虽如此，阅读本书没有错误的方式。请以您认为最有帮助的方式阅读。

约定

与所有技术书籍一样，本书在显示信息方面有一定的约定。 这些约定在此处记录。

• 定义术语的语句将该术语用斜体表示。 当该术语在该章节之外使用时，通常是链接到包含此定义的部分。

  示例术语是术语定义的一个示例。

• 主要文本描述最新的稳定版本。与之前版本的区别在版本块中分开：

  2018 Edition differences

  在 2018 版本之前，行为是这样的。从 2018 版本开始，行为是那样的。

• 包含有关书籍状态的有用信息或指出有用但大多超出范围的信息的注释在注释块中。

  Note

  这是一个示例注释。

• 示例块展示了一个演示某些规则或指出某些有趣方面的示例。某些示例可能有隐藏行，可以通过将鼠标悬停或点击示例时出现的眼睛图标来查看。

  Example

  这是一个代码示例。

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

• 显示语言中不健全行为或可能令人困惑的语言特性交互的警告在特殊警告框中。

  Warning

  这是一个示例警告。

• 文本中内联的代码片段在 <code> 标签内。

  较长的代码示例在语法高亮框中，右上角有用于复制、执行和显示隐藏行的控件。

  // This is a hidden line.
  fn main() {
      println!("This is a code example");
  }

  除非另有说明，所有示例都是为最新版本编写的。

• 语法和词法产物在符号约定章节中描述。

• 规则标识符出现在每个语言规则之前，用方括号括起来。这些标识符提供了一种引用和链接到语言中特定规则的方式（例如）。规则标识符使用句点将部分从最一般到最具体分开（例如 destructors.scope.nesting.function-body）。在窄屏幕上，规则名称将折叠显示为 [*]。

  可以单击规则名称以链接到该规则。

  Warning

  规则的组织目前仍在变化中。暂时来说，这些标识符名称在版本之间不稳定，如果更改了，指向这些规则的链接可能会失效。我们打算在组织稳定后稳定这些名称，以便指向规则名称的链接不会在版本之间中断。

• 有关联测试的规则将在其下方包含一个 Tests 链接（在窄屏幕上，链接为 [T]）。单击该链接将弹出一个测试列表，可以单击查看测试。例如，请参阅 input.encoding.utf8。

  将规则链接到测试是一项正在进行的工作。有关概述，请参阅[测试摘要][Test summary]章节。

贡献

我们欢迎各种形式的贡献。

您可以通过打开 issue 或向 Rust 参考文档仓库 发送 pull request 来为本书做出贡献。 如果本书没有回答您的问题，并且您认为其答案在其范围内，请不要犹豫提交 issue或在 Zulip 上的 t-lang/doc 流中询问。 了解人们最常使用本书做什么有助于我们将注意力集中在使这些部分尽可能好上。 当然，如果您发现任何错误或非规范但未特别指出的内容，也请提交 issue。