导论

本书是 Rust 编程语言的主要参考资料。它提供三类内容

  • 非正式地描述每个语言构造及其用法的章节。
  • 非正式地描述内存模型、并发模型、运行时服务、链接模型和调试设施的章节。
  • 提供设计原理和对影响设计的语言的参考的附录章节。

警告

本书尚不完整。记录所有内容需要一些时间。请参阅 GitHub issues，了解本书中尚未记录的内容。

Rust 发布版本

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

本书的最新版本（与最新的 Rust 版本对应）始终可以在 https://doc.rust-lang.net.cn/reference/ 找到。旧版本可以通过在 “reference” 目录前添加 Rust 版本号来找到。例如，Rust 1.49.0 的参考手册位于 https://doc.rust-lang.net.cn/1.49.0/reference/。

参考手册不是什么

本书不是该语言的入门教程。假定读者已对该语言有一定背景知识。有另一本单独的书可以帮助获得这种背景知识。

本书也不是该语言分发版本中包含的标准库的参考手册。这些库通过从其源代码中提取文档属性来单独记录。许多你可能认为是语言特性的功能在 Rust 中是库特性，因此你正在寻找的内容可能在那里，而不是在这里。

类似地，本书通常不记录作为工具的 rustc 或 Cargo 的具体细节。rustc 有自己的书。Cargo 有一本包含参考手册的书。有一些页面，例如linkage，仍然描述了 rustc 如何工作。

本书也仅作为稳定版 Rust 中可用内容的参考手册。对于正在开发中的不稳定特性，请参阅Unstable Book。

Rust 编译器，包括 rustc，会执行优化。本参考手册没有指定哪些优化是允许的或不允许的。相反，将编译后的程序视为一个黑盒。你只能通过运行它、输入数据和观察其输出来探究它。以这种方式发生的一切都必须符合本参考手册所说的内容。

最后，本书不具有规范性。它可能包含特定于 rustc 本身的细节，不应将其视为 Rust 语言的规范。我们计划将来编写这样一本书，在此之前，本参考手册是我们最接近规范的内容。

如何使用本书

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

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

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

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

话虽如此，阅读本书没有错误的方法。按照你认为最有帮助的方式阅读即可。

约定

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

  • 定义术语的语句会以斜体包含该术语。当该术语在该章节之外使用时，通常会链接到包含此定义的章节。

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

  • 语言因 crate 编译所使用的版本而产生的差异会放在一个引用块中，该引用块以粗体的“版本差异：”开头。

    版本差异：在 2015 版本中，这种语法是有效的，但在 2018 版本中被禁止。

  • 包含有关本书状态的有用信息或指出有用但不完全在范围内的信息的注释会放在注释块中。

    注意

    这是一个示例注释。

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

    警告

    这是一个示例警告。

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

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

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

    除非另有说明，所有示例均按照最新版本编写。

  • 语法和词法结构位于引用块中，第一行以粗体上标的“Lexer”或“Syntax”开头。

    Syntax
    ExampleGrammar:
          ~ 表达式（Expression）
       | box 表达式（Expression）

    更多详细信息请参阅标记法（Notation）。

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

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

    警告

    规则的组织结构目前正在调整中。暂时，这些标识符名称在不同发布版本之间是不稳定的，如果它们发生变化，指向这些规则的链接可能会失效。我们打算在组织结构确定后稳定这些标识符，以便规则名称的链接在不同发布版本之间不会断开。

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

    将规则链接到测试是一项正在进行的工作。请参阅测试摘要（Test summary）章节以获取概述。

贡献

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

您可以通过在 Rust 参考手册仓库中提交 issue 或发送 pull request 来贡献本书。如果本书没有回答您的问题，并且您认为该问题的答案应该在本书的范围内，请随时提交 issue 或在 Zulip 的 t-lang/doc 流中提问。了解人们最常使用本书来做什么有助于我们将精力集中在改进这些章节上。我们也希望本参考手册尽可能具有规范性，因此如果您发现任何错误或是非规范性但未特别指出的内容，也请提交 issue。