简介

本书是 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 功能，请参阅 Unstable Book。

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

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

如何使用本书

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

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

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

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

话虽如此，阅读本书没有错误的方法。以您认为最有助于您的方式阅读即可。

约定

像所有技术书籍一样，本书在显示信息的方式上也有某些约定。这些约定在此处记录。

  • 定义术语的语句将该术语包含在斜体中。每当在该章节之外使用该术语时，通常是链接到具有此定义的章节。

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

  • 根据 crate 编译时所用的 edition，语言中的差异位于以 粗体 “Edition differences:” 开头的块引用中。

    Edition differences：在 2015 edition 中，此语法是有效的，但在 2018 edition 中已禁用。

  • 包含有关本书状态的有用信息或指出有用但大多超出范围的信息的注释位于以 粗体 “Note:” 开头的块引用中。

    Note：这是一个示例注释。

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

    警告： 这是一个示例警告。

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

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

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

    除非另有说明，否则所有示例均针对最新 edition 编写。

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

    语法
    示例语法:
          ~ 表达式
       | box 表达式

    有关更多详细信息，请参阅 Notation。

  • 规则标识符出现在每个语言规则之前的方括号中。这些标识符提供了一种引用语言中特定规则的方法。规则标识符使用句点分隔从最通用到最具体的部分（例如 destructors.scope.nesting.function-body）。

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

警告： 规则的组织目前正在变化中。目前，这些标识符名称在版本之间不稳定，如果更改，则指向这些规则的链接可能会失败。我们计划在组织结构稳定后稳定这些标识符，以便指向规则名称的链接在版本之间不会中断。

贡献

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

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