简介

本书是 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。

符号约定

语法

以下符号由 词法分析器（Lexer）和 语法（Syntax）语法片段使用：

序列的优先级高于 | 交替。

硬切操作符

语法使用有序交替：解析器从左到右尝试替代方案，并采用第一个匹配的方案。如果某个替代方案在序列中途失败，解析器通常会回溯并尝试下一个替代方案。切操作符（^）会阻止这种情况。一旦序列中 ^ 左侧的所有表达式都已匹配，序列的其余部分必须匹配，否则解析无条件失败。

Mizushima 等人将切操作符引入了解析表达式文法。在 PEG 文献中，软切仅阻止在直接包含的有序选择中回溯 — 外部选择仍然可以恢复。硬切阻止所有经过切点的回溯；失败是确定性的。本文法中使用的 ^ 是硬切。

硬切操作符是必要的，因为 Rust 中的某些词法单元以本身是有效词法单元的前缀开头。例如，c" 开始一个 C 字符串字面量，但单独的 c 是一个有效的标识符。如果没有切，如果 c"\0" 作为 C 字符串字面量词法分析失败（因为 C 字符串中不允许空字节），解析器可能会回溯并将其词法分析为两个词法单元：标识符 c 和字符串字面量 "\0"。c" 之后的切 阻止了这种情况 — 一旦识别出开头的分隔符，解析器就无法回溯。同样的推理适用于字节字面量、字节字符串字面量、原始字符串字面量以及其他以前缀开头的字面量，这些前缀本身是有效的词法单元。

字符串表产物

语法中的某些规则 — 特别是一元运算符、二元运算符和关键字 — 以简化形式给出：作为可打印字符串的列表。这些情况构成了关于词法单元规则的子集，并假定是由 DFA 驱动的词法分析阶段的结果，该阶段操作所有此类字符串表条目的析取。

当此类字符串以 monospace 字体出现在语法中时，它是对此类字符串表产物的单个成员的隐式引用。有关更多信息，请参阅词法单元。

语法可视化

每个语法块下方都有一个按钮，用于切换语法图的显示。方形元素是非终结符规则，圆角矩形是终结符。

词法结构

输入格式

本章描述源文件如何被解释为词法单元序列。

有关程序如何组织到文件中的描述，请参阅包和源文件。

源编码

每个源文件被解释为以 UTF-8 编码的 Unicode 字符序列。

如果文件不是有效的 UTF-8，则是错误。

字节顺序标记移除

如果序列中的第一个字符是 U+FEFF（字节顺序标记），则将其移除。

CRLF 规范化

每对字符 U+000D (CR) 紧接着 U+000A (LF) 被替换为单个 U+000A (LF)。这发生一次，而不是重复发生，因此在规范化之后，输入中仍然可以存在 U+000D (CR) 紧接着 U+000A (LF)（例如，如果原始输入包含 “CR CR LF LF”）。

字符 U+000D (CR) 的其他出现保留在原处（它们被视为空白）。

Shebang 移除

如果存在 shebang，则将其从输入序列中移除（因此被忽略）。

词法分析

然后，生成的字符序列按照本章其余部分的描述转换为词法单元。

Shebang

shebang 是一个可选行，通常在类 Unix 系统中用于指定执行文件的解释器。

shebang 以字符 #! 开头，延伸到第一个 U+000A (LF) 或如果没有 LF 则延伸到 EOF。如果 #! 字符后面跟着 [（忽略任何中间的注释或空白），则该行不被视为 shebang（以避免与内部属性的歧义）。

shebang 可以直接出现在文件开头或可选的字节顺序标记之后。

关键字

Rust 将关键字分为三类：

• 严格
• 保留
• 弱

严格关键字

这些关键字只能在其正确的上下文中使用。它们不能用作以下内容的名称：

• 项
• 变量和函数参数
• 字段和变体
• 类型参数
• 生命周期参数或循环标签
• 宏或属性
• 宏占位符
• 包

以下关键字在所有版本中都存在：

• _
• as
• async
• await
• break
• const
• continue
• crate
• dyn
• else
• enum
• extern
• false
• fn
• for
• if
• impl
• in
• let
• loop
• match
• mod
• move
• mut
• pub
• ref
• return
• self
• Self
• static
• struct
• super
• trait
• true
• type
• unsafe
• use
• where
• while

保留关键字

这些关键字尚未使用，但被保留供将来使用。它们与严格关键字具有相同的限制。其背后的原因是通过禁止当前程序使用这些关键字，使当前程序与 Rust 的未来版本向前兼容。

• abstract
• become
• box
• do
• final
• gen
• macro
• override
• priv
• try
• typeof
• unsized
• virtual
• yield

弱关键字

这些关键字仅在某些上下文中具有特殊含义。例如，可以声明名为 union 的变量或方法。

• 'static
• macro_rules
• raw
• safe
• union

• macro_rules 用于创建自定义宏。

• union 用于声明联合体，仅在联合体声明中使用时才是关键字。

• 'static 用于静态生命周期，不能用作泛型生命周期参数或循环标签

  // error[E0262]: invalid lifetime parameter name: `'static`
  fn invalid_lifetime_parameter<'static>(s: &'static str) -> &'static str { s }
  

• safe 用于函数和静态变量，在外部块中具有意义。

• raw 用于原始借用运算符，仅在匹配原始借用运算符形式（如 &raw const expr 或 &raw mut expr）时才是关键字。

标识符

标识符遵循 Unicode 标准附录 #31 中 Unicode 版本 17.0 的规范，并加上下面描述的附加内容。标识符的一些示例：

• foo
• _identifier
• r#true
• Москва
• 東京

从 UAX #31 使用的配置文件是：

• Start := XID_Start，加上下划线字符 (U+005F)
• Continue := XID_Continue
• Medial := 空

标识符不能是严格或保留关键字，除非使用下面原始标识符中描述的 r# 前缀。

零宽非连接符 (ZWNJ U+200C) 和零宽连接符 (ZWJ U+200D) 字符不允许在标识符中使用。

在以下情况下，标识符被限制为 XID_Start 和 XID_Continue 的 ASCII 子集：

• extern crate 声明（AsClause 标识符除外）
• 在路径中引用的外部 crate 名称
• 从文件系统加载的模块名称（没有 [path 属性]）
• no_mangle 属性的项
• 外部块中的项名称

规范化

标识符使用 Unicode 标准附录 #15 中定义的规范化形式 C (NFC) 进行规范化。如果两个标识符的 NFC 形式相等，则它们相等。

过程和声明宏在其输入中接收规范化的标识符。

原始标识符

原始标识符类似于普通标识符，但以 r# 为前缀。（请注意，r# 前缀不作为实际标识符的一部分。）

与普通标识符不同，原始标识符可以是任何严格或保留关键字，除了上面为 RAW_IDENTIFIER 列出的那些。

使用 RESERVED_RAW_IDENTIFIER 词法单元是错误的。

注释

非文档注释

注释遵循一般的 C++ 风格的行注释（//）和块注释（/* ... */）形式。支持嵌套块注释。

非文档注释被解释为一种空白形式。

文档注释

以恰好三个斜杠（///）开头的行文档注释和块文档注释（/** ... */），都是外部文档注释，被解释为 doc 属性的特殊语法。

也就是说，它们等同于在注释主体周围编写 #[doc="..."]，即 /// Foo 变成 #[doc=" Foo"]，/** Bar */ 变成 #[doc=" Bar "]。因此，它们必须出现在接受外部属性的内容之前。

以 //! 开头的行注释和 /*! ... */ 块注释是应用于注释父级而不是后续项的文档注释。

也就是说，它们等同于在注释主体周围编写 #![doc="..."]。//! 注释通常用于记录占据源文件的模块。

字符 U+000D (CR) 不允许在文档注释中使用。

示例

#![allow(unused)]
fn main() {
//! A doc comment that applies to the implicit anonymous module of this crate

pub mod outer_module {

    //!  - Inner line doc
    //!! - Still an inner line doc (but with a bang at the beginning)

    /*!  - Inner block doc */
    /*!! - Still an inner block doc (but with a bang at the beginning) */

    //   - Only a comment
    ///  - Outer line doc (exactly 3 slashes)
    //// - Only a comment

    /*   - Only a comment */
    /**  - Outer block doc (exactly) 2 asterisks */
    /*** - Only a comment */

    pub mod inner_module {}

    pub mod nested_comments {
        /* In Rust /* we can /* nest comments */ */ */

        // All three types of block comments can contain or be nested inside
        // any other type:

        /*   /* */  /** */  /*! */  */
        /*!  /* */  /** */  /*! */  */
        /**  /* */  /** */  /*! */  */
        pub mod dummy_item {}
    }

    pub mod degenerate_cases {
        // empty inner line doc
        //!

        // empty inner block doc
        /*!*/

        // empty line comment
        //

        // empty outer line doc
        ///

        // empty block comment
        /**/

        pub mod dummy_item {}

        // empty 2-asterisk block isn't a doc block, it is a block comment
        /***/

    }

    /* The next one isn't allowed because outer doc comments
       require an item that will receive the doc */

    /// Where is my item?
  mod boo {}
}
}

空白

空白是任何非空字符串，仅包含具有 Pattern_White_Space Unicode 属性的字符。

Rust 是一种“自由形式“语言，这意味着所有形式的空白仅用于在语法中分隔_词法单元_，没有语义意义。

如果每个空白元素被任何其他合法空白元素（如单个空格字符）替换，Rust 程序具有相同的含义。

词法单元

词法单元（Token）是由正则（非递归）语言定义的语法中的原始产物。Rust 源输入可以分解为以下类型的词法单元：

• 关键字
• 标识符
• 字面量
• 生命周期
• 标点符号
• 分隔符

在本文档的语法中，“简单“词法单元以字符串表产物形式给出，并以 monospace 字体显示。

字面量

字面量是用于字面量表达式的词法单元。

示例

字符和字符串

ASCII 转义

字节转义

Unicode 转义

引号转义

数字

后缀

后缀是跟在字面量主要部分之后（没有中间空白）的字符序列，形式与非原始标识符或关键字相同。

任何类型的字面量（字符串、整数等）带有任何后缀作为词法单元都是有效的。

带有任何后缀的字面量词法单元可以传递给宏而不会产生错误。宏本身将决定如何解释这样的词法单元以及是否产生错误。特别是，通过示例定义的宏的 literal 片段说明符匹配带有任意后缀的字面量词法单元。

#![allow(unused)]
fn main() {
macro_rules! blackhole { ($tt:tt) => () }
macro_rules! blackhole_lit { ($l:literal) => () }

blackhole!("string"suffix); // OK
blackhole_lit!(1suffix); // OK
}

然而，被解释为字面量表达式或模式的字面量词法单元上的后缀是受限的。非数字字面量词法单元上的任何后缀都会被拒绝，数字字面量词法单元只接受以下列表中的后缀。

字符和字符串字面量

字符字面量

字符字面量_是包含在两个 U+0027（单引号）字符内的单个 Unicode 字符，U+0027 本身除外，它必须通过前面的 U+005C 字符（\）进行_转义。

字符串字面量

字符串字面量_是包含在两个 U+0022（双引号）字符内的任意 Unicode 字符序列，U+0022 本身除外，它必须通过前面的 U+005C 字符（\）进行_转义。

换行符（由字符 U+000A (LF) 表示）允许在字符串字面量中使用。字符 U+000D (CR) 不得出现在字符串字面量中。当未转义的 U+005C 字符（\）紧接在换行符之前时，换行符不会出现在词法单元表示的字符串中。有关详细信息，请参阅字符串继续转义。

字符转义

在字符或非原始字符串字面量中可以使用一些额外的_转义_。转义以 U+005C（\）开头，后跟以下形式之一：

• 7 位代码点转义_以 U+0078（x）开头，后跟恰好两个_十六进制数字，值最大为 0x7F。它表示值等于所提供十六进制值的 ASCII 字符。不允许更高的值，因为它们表示 Unicode 代码点还是字节值是不明确的。

• 24 位代码点转义_以 U+0075（u）开头，后跟最多六个_十六进制数字，用大括号 U+007B（{）和 U+007D（}）括起来。它表示等于所提供十六进制值的 Unicode 代码点。该值必须是有效的 Unicode 标量值。

• _空白转义_是字符 U+006E（n）、U+0072（r）或 U+0074（t）之一，分别表示 Unicode 值 U+000A (LF)、U+000D (CR) 或 U+0009 (HT)。

• _空转义_是字符 U+0030（0），表示 Unicode 值 U+0000 (NUL)。

• _反斜杠转义_是字符 U+005C（\），必须进行转义才能表示其本身。

原始字符串字面量

原始字符串字面量不处理任何转义。它们以字符 U+0072（r）开头，后跟少于 256 个字符 U+0023（#）和一个 U+0022（双引号）字符。

_原始字符串体_可以包含除 U+000D (CR) 之外的任何 Unicode 字符序列。它仅由另一个 U+0022（双引号）字符终止，后跟与开头 U+0022（双引号）字符之前相同数量的 U+0023（#）字符。

原始字符串体中包含的所有 Unicode 字符都表示它们本身，字符 U+0022（双引号）（除非后跟至少与用于开始原始字符串字面量相同数量的 U+0023（#）字符）或 U+005C（\）没有任何特殊含义。

字符串字面量示例：

#![allow(unused)]
fn main() {
"foo"; r"foo";                     // foo
"\"foo\""; r#""foo""#;             // "foo"

"foo #\"# bar";
r##"foo #"# bar"##;                // foo #"# bar

"\x52"; "R"; r"R";                 // R
"\\x52"; r"\x52";                  // \x52
}

字节和字节字符串字面量

字节字面量

字节字面量_是单个 ASCII 字符（在 U+0000 到 U+007F 范围内）或单个_转义，前面是字符 U+0062（b）和 U+0027（单引号），后面是字符 U+0027。如果字符 U+0027 存在于字面量中，它必须通过前面的 U+005C（\）字符进行_转义_。它等同于 u8 无符号 8 位整数_数字字面量_。

字节字符串字面量

非原始_字节字符串字面量_是 ASCII 字符和_转义_的序列，前面是字符 U+0062（b）和 U+0022（双引号），后面是字符 U+0022。如果字符 U+0022 存在于字面量中，它必须通过前面的 U+005C（\）字符进行_转义_。或者，字节字符串字面量可以是下面定义的_原始字节字符串字面量_。

换行符（由字符 U+000A (LF) 表示）允许在字节字符串字面量中使用。字符 U+000D (CR) 不得出现在字节字符串字面量中。当未转义的 U+005C 字符（\）紧接在换行符之前时，换行符不会出现在词法单元表示的字符串中。有关详细信息，请参阅字符串继续转义。

在字节或非原始字节字符串字面量中可以使用一些额外的_转义_。转义以 U+005C（\）开头，后跟以下形式之一：

• 字节转义_以 U+0078（x）开头，后跟恰好两个_十六进制数字。它表示等于所提供十六进制值的字节。

• _空白转义_是字符 U+006E（n）、U+0072（r）或 U+0074（t）之一，分别表示字节值 0x0A (ASCII LF)、0x0D (ASCII CR) 或 0x09 (ASCII HT)。

• _空转义_是字符 U+0030（0），表示字节值 0x00 (ASCII NUL)。

• _反斜杠转义_是字符 U+005C（\），必须进行转义才能表示其 ASCII 编码 0x5C。

原始字节字符串字面量

原始字节字符串字面量不处理任何转义。它们以字符 U+0062（b）开头，后跟 U+0072（r），再后跟少于 256 个字符 U+0023（#）和一个 U+0022（双引号）字符。

_原始字符串体_可以包含除 U+000D (CR) 之外的任何 ASCII 字符序列。它仅由另一个 U+0022（双引号）字符终止，后跟与开头 U+0022（双引号）字符之前相同数量的 U+0023（#）字符。原始字节字符串字面量不能包含任何非 ASCII 字节。

原始字符串体中包含的所有字符都表示它们的 ASCII 编码，字符 U+0022（双引号）（除非后跟至少与用于开始原始字符串字面量相同数量的 U+0023（#）字符）或 U+005C（\）没有任何特殊含义。

字节字符串字面量示例：

#![allow(unused)]
fn main() {
b"foo"; br"foo";                     // foo
b"\"foo\""; br#""foo""#;             // "foo"

b"foo #\"# bar";
br##"foo #"# bar"##;                 // foo #"# bar

b"\x52"; b"R"; br"R";                // R
b"\\x52"; br"\x52";                  // \x52
}

C 字符串和原始 C 字符串字面量

C 字符串字面量

C 字符串字面量_是 Unicode 字符和_转义_的序列，前面是字符 U+0063（c）和 U+0022（双引号），后面是字符 U+0022。如果字符 U+0022 存在于字面量中，它必须通过前面的 U+005C（\）字符进行_转义。或者，C 字符串字面量可以是下面定义的_原始 C 字符串字面量_。

C 字符串由字节 0x00 隐式终止，因此 C 字符串字面量 c"" 等同于从字节字符串字面量 b"\x00" 手动构造 &CStr。除了隐式终止符外，字节 0x00 不允许在 C 字符串中使用。

换行符（由字符 U+000A (LF) 表示）允许在 C 字符串字面量中使用。字符 U+000D (CR) 不得出现在 C 字符串字面量中。当未转义的 U+005C 字符（\）紧接在换行符之前时，换行符不会出现在词法单元表示的字符串中。有关详细信息，请参阅字符串继续转义。

在非原始 C 字符串字面量中可以使用一些额外的_转义_。转义以 U+005C（\）开头，后跟以下形式之一：

• 字节转义_以 U+0078（x）开头，后跟恰好两个_十六进制数字。它表示等于所提供十六进制值的字节。

• 24 位代码点转义_以 U+0075（u）开头，后跟最多六个_十六进制数字，用大括号 U+007B（{）和 U+007D（}）括起来。它表示等于所提供十六进制值的 Unicode 代码点，编码为 UTF-8。

• _空白转义_是字符 U+006E（n）、U+0072（r）或 U+0074（t）之一，分别表示字节值 0x0A (ASCII LF)、0x0D (ASCII CR) 或 0x09 (ASCII HT)。

• _反斜杠转义_是字符 U+005C（\），必须进行转义才能表示其 ASCII 编码 0x5C。

C 字符串表示没有定义编码的字节，但 C 字符串字面量可以包含 U+007F 以上的 Unicode 字符。此类字符将被替换为该字符 UTF-8 表示的字节。

以下 C 字符串字面量是等效的：

#![allow(unused)]
fn main() {
c"æ";        // LATIN SMALL LETTER AE (U+00E6)
c"\u{00E6}";
c"\xC3\xA6";
}

原始 C 字符串字面量

原始 C 字符串字面量不处理任何转义。它们以字符 U+0063（c）开头，后跟 U+0072（r），再后跟少于 256 个字符 U+0023（#）和一个 U+0022（双引号）字符。

_原始 C 字符串体_可以包含除 U+0000 (NUL) 和 U+000D (CR) 之外的任何 Unicode 字符序列。它仅由另一个 U+0022（双引号）字符终止，后跟与开头 U+0022（双引号）字符之前相同数量的 U+0023（#）字符。

原始 C 字符串体中包含的所有字符都以 UTF-8 编码表示它们本身。字符 U+0022（双引号）（除非后跟至少与用于开始原始 C 字符串字面量相同数量的 U+0023（#）字符）或 U+005C（\）没有任何特殊含义。

C 字符串和原始 C 字符串字面量示例

#![allow(unused)]
fn main() {
c"foo"; cr"foo";                     // foo
c"\"foo\""; cr#""foo""#;             // "foo"

c"foo #\"# bar";
cr##"foo #"# bar"##;                 // foo #"# bar

c"\x52"; c"R"; cr"R";                // R
c"\\x52"; cr"\x52";                  // \x52
}

数字字面量

数字字面量_是_整数字面量_或_浮点数字面量。识别这两种字面量的语法是混合的。

整数字面量

_整数字面量_有四种形式之一：

• _十进制字面量_以十进制数字开头，后跟十进制数字和_下划线_的任意混合。

• _十六进制字面量_以字符序列 U+0030 U+0078（0x）开头，后跟十六进制数字和下划线的任意混合（至少有一个数字）。

• _八进制字面量_以字符序列 U+0030 U+006F（0o）开头，后跟八进制数字和下划线的任意混合（至少有一个数字）。

• _二进制字面量_以字符序列 U+0030 U+0062（0b）开头，后跟二进制数字和下划线的任意混合（至少有一个数字）。

与任何字面量一样，整数字面量后面可以（直接，没有空格）跟着上面描述的后缀。后缀不能以 e 或 E 开头，因为那将被解释为浮点数字面量的指数。有关这些后缀的效果，请参阅整数字面量表达式。

被接受为字面量表达式的整数字面量示例：

#![allow(unused)]
fn main() {
#![allow(overflowing_literals)]
123;
123i32;
123u32;
123_u32;

0xff;
0xff_u8;
0x01_f32; // integer 7986, not floating-point 1.0
0x01_e3;  // integer 483, not floating-point 1000.0

0o70;
0o70_i16;

0b1111_1111_1001_0000;
0b1111_1111_1001_0000i64;
0b________1;

0usize;

// These are too big for their type, but are accepted as literal expressions.
128_i8;
256_u8;

// This is an integer literal, accepted as a floating-point literal expression.
5f32;
}

请注意，例如 -1i8 被分析为两个词法单元：- 后跟 1i8。

不被接受为字面量表达式的整数字面量示例：

#![allow(unused)]
fn main() {
#[cfg(false)] {
0invalidSuffix;
123AFB43;
0b010a;
0xAB_CD_EF_GH;
0b1111_f32;
}
}

无效整数字面量

某些整数字面量形式是无效的。为避免歧义，词法分析器会拒绝它们，而不是将它们拆分为单独的词法单元。

#![allow(unused)]
fn main() {
0b0102;  // This is not `0b010` followed by `2`.
0o1279;  // This is not `0o127` followed by `9`.
0x80.0;  // This is not `0x80` followed by `.` and `0`.
0b101e;  // This is not a suffixed literal or `0b101` followed by `e`.
0b;      // This is not an integer literal or `0` followed by `b`.
0b_;     // This is not an integer literal or `0` followed by `b_`.
2em;     // This is not a suffixed literal or `2` followed by `em`.
2.0em;   // This is not a suffixed literal or `2.0` followed by `em`.
}

如果无后缀二进制或八进制字面量后面没有中间空白地跟着超出其基数范围的十进制数字，则是错误。

如果无后缀二进制、八进制或十六进制字面量后面没有中间空白地跟着句点字符（受与浮点数字面量中相同的关于句点后可跟内容的限制），则是错误。

如果无后缀二进制或八进制字面量后面没有中间空白地跟着字符 e 或 E，则是错误。

如果基数前缀后面（在任何可选的前导下划线之后）没有至少一个其基数的有效数字，则是错误。

元组索引

元组索引用于引用元组、元组结构体和元组枚举变体的字段。

元组索引直接与字面量词法单元进行比较。元组索引以 0 开头，每个后续索引将值递增 1 作为十进制值。因此，只有十进制值会匹配，并且该值不能有任何额外的 0 前缀字符。

元组索引不能包含任何后缀（如 usize）。

#![allow(unused)]
fn main() {
let example = ("dog", "cat", "horse");
let dog = example.0;
let cat = example.1;
// The following examples are invalid.
let cat = example.01;  // ERROR no field named `01`
let horse = example.0b10;  // ERROR no field named `0b10`
let unicorn = example.0usize; // ERROR suffixes on a tuple index are invalid
let underscore = example.0_0; // ERROR no field `0_0` on type `(&str, &str, &str)`
}

浮点数字面量

_浮点数字面量_有两种形式之一：

• 十进制字面量_后跟句点字符 U+002E（.）。这后面可以选择性地跟着另一个十进制字面量，带有可选的_指数。
• 单个_十进制字面量_后跟_指数_。

与整数字面量一样，浮点数字面量后面可以跟后缀，只要后缀前的部分不以 U+002E（.）结尾。如果字面量不包含指数，则后缀不能以 e 或 E 开头。有关这些后缀的效果，请参阅浮点数字面量表达式。

被接受为字面量表达式的浮点数字面量示例：

#![allow(unused)]
fn main() {
123.0f64;
0.1f64;
0.1f32;
12E+99_f64;
let x: f64 = 2.;
}

最后一个例子不同，因为不能对以句点结尾的浮点字面量使用后缀语法。2.f64 将尝试在 2 上调用名为 f64 的方法。

请注意，例如 -1.0 被分析为两个词法单元：- 后跟 1.0。

不被接受为字面量表达式的浮点数字面量示例：

#![allow(unused)]
fn main() {
#[cfg(false)] {
2.0f80;
2e5f80;
2e5e6;
2.0e5e6;
1.3e10u64;
}
}

如果浮点数字面量的指数没有数字，则是错误。

#![allow(unused)]
fn main() {
2e;   // This is not a floating-point literal or `2` followed by `e`.
2.0e; // This is not a floating-point literal or `2.0` followed by `e`.
}

生命周期和循环标签

生命周期参数和循环标签使用 LIFETIME_OR_LABEL 词法单元。词法分析器将接受任何 LIFETIME_TOKEN，例如可以在宏中使用。

原始生命周期类似于普通生命周期，但其标识符以 r# 为前缀。（请注意，r# 前缀不作为实际生命周期的一部分。）

与普通生命周期不同，原始生命周期可以是任何严格或保留关键字，除了上面为 RAW_LIFETIME 列出的那些。

使用 RESERVED_RAW_LIFETIME 词法单元是错误的。

标点符号

标点符号词法单元用作运算符、分隔符和语法的其他部分。

分隔符

括号标点符号用于语法的各个部分。左括号必须始终与右括号配对。括号和其中的词法单元在宏中被称为“词法单元树“。三种类型的括号是：

保留词法单元

几种词法单元形式被保留供将来使用或为了避免混淆。源输入匹配这些形式之一是错误的。

保留前缀

一些被称为_保留前缀_的词法形式被保留供将来使用。

如果源输入在词法上被解释为非原始标识符（或关键字）并且紧接着 #、' 或 " 字符（没有中间空白），则被识别为保留前缀。

请注意，原始标识符、原始字符串字面量和原始字节字符串字面量可能包含 # 字符，但不被解释为包含保留前缀。

类似地，原始字符串字面量、字节字面量、字节字符串字面量、原始字节字符串字面量、C 字符串字面量和原始 C 字符串字面量中使用的 r、b、br、c 和 cr 前缀不被解释为保留前缀。

如果源输入在词法上被解释为非原始生命周期（或关键字）并且紧接着 # 字符（没有中间空白），则被识别为保留生命周期前缀。

保留守卫

保留守卫是为将来使用保留的语法，如果使用将生成编译错误。

保留守卫字符串字面量是一个或多个 U+0023（#）后紧跟 STRING_LITERAL 的词法单元。

保留井号是两个或多个 U+0023（#）的词法单元。

1. 同一字面量两侧的 # 数量必须相等。 ↩

2. 所有数字字面量都允许 _ 作为可视分隔符：1_234.0E+18f64 ↩

3. 参见 lex.token.literal.char-escape.unicode。 ↩

宏

Rust 的功能和语法可以通过称为宏（Macro）的自定义定义来扩展。它们被赋予名称，并通过一致的语法调用：some_extension!(...)。

有两种定义新宏的方式：

• 通过示例定义的宏 以更高级别的声明方式定义新语法。
• 过程宏 使用操作输入词法单元的函数来定义函数式宏、自定义派生和自定义属性。

宏调用

宏调用在编译时展开宏，并用宏的结果替换调用。宏可以在以下情况下调用：

• 表达式 和 语句

• 模式

• 类型

• 项 包括 关联项

• macro_rules 转录器

• 外部块

当用作项或语句时，使用 MacroInvocationSemi 形式，当不使用花括号时，末尾需要分号。可见性限定符 永远不允许在宏调用或 macro_rules 定义之前。

#![allow(unused)]
fn main() {
// Used as an expression.
let x = vec![1,2,3];

// Used as a statement.
println!("Hello!");

// Used in a pattern.
macro_rules! pat {
    ($i:ident) => (Some($i))
}

if let pat!(x) = Some(1) {
    assert_eq!(x, 1);
}

// Used in a type.
macro_rules! Tuple {
    { $A:ty, $B:ty } => { ($A, $B) };
}

type N2 = Tuple!(i32, i32);

// Used as an item.
use std::cell::RefCell;
thread_local!(static FOO: RefCell<u32> = RefCell::new(1));

// Used as an associated item.
macro_rules! const_maker {
    ($t:ty, $v:tt) => { const CONST: $t = $v; };
}
trait T {
    const_maker!{i32, 7}
}

// Macro calls within macros.
macro_rules! example {
    () => { println!("Macro call in a macro!") };
}
// Outer macro `example` is expanded, then inner macro `println` is expanded.
example!();
}

宏调用可以通过两种作用域进行解析：

• 文本作用域
  • 文本作用域 macro_rules
• 基于路径的作用域
  • 基于路径的作用域 macro_rules
  • 过程宏

通过示例定义的宏（Macros by Example）