引言

本书是 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 语句中创建的临时值何时被丢弃。 如果您不知道 临时值的生命周期 定义在 表达式章节 中，您可以搜索“临时 let”，第一个搜索结果将带您到该部分。

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

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

约定

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

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

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

• 主要文本描述最新的稳定版本。与以前版本的差异在版本块中分离：

  2018 版次差异

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

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

  注意

  这是一个示例注释。

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

  例子

  这是一个代码示例。

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

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

  警告

  这是一个示例警告。

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

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

  // 这是一行隐藏行。
  fn main() {
      println!("这是一个代码示例");
  }

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

• 语法和词法产生式在 符号 章节中描述。

• 规则标识符出现在每个语言规则之前，用方括号括起来。这些标识符提供了一种引用和链接到语言中特定规则的方法（例如，示例规则）。规则标识符使用句点将部分从最一般到最具体地分开（例如，解构器.作用域.嵌套.函数体）。在窄屏幕上，规则名称将折叠显示 [*]。

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

  警告

  规则的组织目前处于变动中。暂时而言，这些标识符名称在不同版本之间不稳定，如果它们发生更改，指向这些规则的链接可能会失效。我们打算在组织稳定后将其稳定化，以便指向规则名称的链接在不同版本之间不会中断。

• 具有相关测试的规则将在其下方包含一个“测试”链接（在窄屏幕上，该链接为 [T]）。单击该链接将弹出一个测试列表，可以单击以查看测试。例如，请参见 输入.编码.utf8。

  将规则链接到测试是一项持续进行的工作。有关概述，请参阅 测试摘要 章节。

贡献

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

您可以通过在 Rust语言参考仓库 中提出问题或发送拉取请求来为本书做出贡献。 如果本书没有回答您的问题，并且您认为它的答案属于其范围，请不要犹豫 提交问题 或在 Zulip 上的 t-lang/doc 流中提问。 了解人们最常使用本书做什么有助于我们将注意力集中在使这些部分尽善尽美上。 当然，如果您发现任何错误或非规范性但未明确指出的内容，也请 提交问题。

记法

语法

以下记法用于词法分析器和语法格式文法片段：

序列的优先级高于|选项。

字符串表产生式

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

当语法中出现等宽字体的字符串时，它隐式引用了此类字符串表产生式的一个成员。有关更多信息，请参阅词法单元。

语法可视化

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

词法结构

输入格式

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

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

源文件编码

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

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

字节序标记移除

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

CRLF规范化

每对紧跟着U+000A (LF) 的U+000D (CR) 字符会被单个U+000A (LF) 替换。此操作只执行一次，不会重复，因此在规范化之后，输入中仍然可能存在紧跟着U+000A (LF) 的U+000D (CR)（例如，如果原始输入包含 “CR CR LF LF”）。

字符U+000D (CR) 的其他出现位置则保留不变（它们被视为空白符）。

Shebang移除

如果剩余序列以字符#!开头，则从序列中移除直到（并包括）第一个U+000A (LF) 的所有字符。

例如，以下文件的第一行将被忽略：

#!/usr/bin/env rustx

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

作为例外，如果#!字符后面紧跟着（忽略中间的注释或空白符）一个[词法单元，则不进行任何移除。这可以防止源文件开头的内部属性被移除。

词法单元化

然后，所得的字符序列将转换为词法单元，具体描述见本章的其余部分。

关键字

Rust 将关键字分为三类：

• 严格关键字
• 保留关键字
• 弱关键字

严格关键字

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

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

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

• _
• 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 16.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属性的项
• 外部块中的项名

规范化

标识符使用规范化形式 C (NFC) 进行规范化，如Unicode标准附件#15中所定义。两个标识符在它们的 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() {
//! 适用于此crate的隐式匿名模块的文档注释

pub mod outer_module {

    //!  - 内部行级文档注释
    //!! - 仍然是内部行级文档注释（但开头带感叹号）

    /*!  - 内部块级文档注释 */
    /*!! - 仍然是内部块级文档注释（但开头带感叹号） */

    //   - 仅是普通注释
    ///  - 外部行级文档注释（恰好三个斜杠）
    //// - 仅是普通注释

    /*   - 仅是普通注释 */
    /**  - 外部块级文档注释（恰好两个星号） */
    /*** - 仅是普通注释 */

    pub mod inner_module {}

    pub mod nested_comments {
        /* 在 Rust 中 /* 我们可以 /* 嵌套注释 */ */ */

        // 所有三种块级注释都可以包含或嵌套在
        // 任何其他类型的注释中：

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

    pub mod degenerate_cases {
        // 空的内部行级文档注释
        //!

        // 空的内部块级文档注释
        /*!*/

        // 空的行级注释
        //

        // 空的外部行级文档注释
        ///

        // 空的块级注释
        /**/

        pub mod dummy_item {}

        // 空的两个星号的块注释不是文档块，它是普通的块注释
        /***/

    }

    /* 下一个是不允许的，因为外部文档注释
       需要一个接收文档的条目 */

    /// 我的条目在哪里？
  mod boo {}
}
}

空白字符

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

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

如果Rust程序中的每个空白字符元素被任何其他合法的空白字符元素（例如一个空格字符）替换，其含义保持不变。

词法单元

词法单元是语法格式中由正则（非递归）语言定义的原始生成式。Rust源输入可以分解为以下几种词法单元：

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

在此文档的语法中，“简单”词法单元以字符串表生成式形式给出，并以等宽字体显示。

字面量

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

示例

字符和字符串

ASCII转义

字节转义

Unicode转义

引号转义

数字

后缀

后缀是紧跟在字面量主要部分（无中间空白）后面的一串字符，其形式与非原始标识符或关键字相同。

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

带有任何后缀的字面量词法单元可以传递给宏而不会产生错误。宏本身将决定如何解释此类词法单元以及是否产生错误。特别是，声明宏的literal fragment specifier匹配带有任意后缀的字面量词法单元。

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

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

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

字符和字符串字面量

字符字面量

字符字面量是单个Unicode字符，用两个U+0027（单引号）字符括起来，但U+0027本身除外，它必须通过前面加一个U+005C字符（\）进行转义。

字符串字面量

字符串字面量是任何Unicode字符序列，用两个U+0022（双引号）字符括起来，但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（双引号）（除非后面紧跟的U+0023（#）字符数量与用于开始原始C字符串字面量的字符数量相同或更多）或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;
}
}

元组项索引

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

元组项索引与字面量词法单元直接比较。元组项索引从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;
}
}

类似于数字字面量的保留形式

以下类似于数字字面量的词法形式是_保留形式_。由于可能存在的歧义，词法分析器会拒绝这些形式，而不是将其解释为单独的词法单元。

• 未加后缀的二进制或八进制字面量，紧接着（无中间空白）一个超出其基数范围的十进制数字。

• 未加后缀的二进制、八进制或十六进制字面量，紧接着（无中间空白）一个句点字符（对句点后面的内容有与浮点数字面量相同的限制）。

• 未加后缀的二进制或八进制字面量，紧接着（无中间空白）字符e或E。

• 以基数前缀之一开头但不是有效的二进制、八进制或十六进制字面量（因为它不包含任何数字）的输入。

• 具有浮点数字面量形式，但指数中没有数字的输入。

保留形式的示例：

#![allow(unused)]
fn main() {
0b0102;  // 这不是`0b010`后跟`2`
0o1279;  // 这不是`0o127`后跟`9`
0x80.0;  // 这不是`0x80`后跟`.`和`0`
0b101e;  // 这不是一个带后缀的字面量，也不是`0b101`后跟`e`
0b;      // 这不是一个整数字面量，也不是`0`后跟`b`
0b_;     // 这不是一个整数字面量，也不是`0`后跟`b_`
2e;      // 这不是一个浮点数字面量，也不是`2`后跟`e`
2.0e;    // 这不是一个浮点数字面量，也不是`2.0`后跟`e`
2em;     // 这不是一个带后缀的字面量，也不是`2`后跟`em`
2.0em;   // 这不是一个带后缀的字面量，也不是`2.0`后跟`em`
}

生命周期和循环标签

生命周期参数和循环标签使用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的功能和语法可以通过称为宏的自定义定义进行扩展。它们被赋予名称，并通过一致的语法some_extension!(...)来调用。

有两种方法可以定义新宏：

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

宏调用

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

• 表达式和语句

• 模式

• 类型

• 项包括关联项

• macro_rules转录器

• 外部块

当用作项或语句时，使用MacroInvocationSemi形式，如果未使用大括号，则末尾需要分号。可见性限定符绝不允许出现在宏调用或macro_rules定义之前。

#![allow(unused)]
fn main() {
// 用作表达式。
let x = vec![1,2,3];

// 用作语句。
println!("Hello!");

// 用在模式中。
macro_rules! pat {
    ($i:ident) => (Some($i))
}

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

// 用在类型中。
macro_rules! Tuple {
    { $A:ty, $B:ty } => { ($A, $B) };
}

type N2 = Tuple!(i32, i32);

// 用作项。
use std::cell::RefCell;
thread_local!(static FOO: RefCell<u32> = RefCell::new(1));

// 用作关联项。
macro_rules! const_maker {
    ($t:ty, $v:tt) => { const CONST: $t = $v; };
}
trait T {
    const_maker!{i32, 7}
}

// 宏内的宏调用。
macro_rules! example {
    () => { println!("Macro call in a macro!") };
}
// 外部宏`example`展开后，内部宏`println`也会展开。
example!();
}

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

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

声明宏

macro_rules 允许用户以声明式的方式定义语法扩展。我们称这种扩展为“声明宏”或简称“宏”。

每个声明宏都有一个名称和一条或多条 规则 。每条规则包含两部分：一个 匹配器 ，描述它匹配的语法；一个 转录器 ，描述成功匹配的调用将替换成的语法。匹配器和转录器都必须由分隔符包围。宏可以展开为表达式、语句、项（包括特型、impl 和外部项）、类型或模式。

转录

当宏被调用时，宏扩展器会按名称查找宏调用，并依次尝试每条宏规则。它转录第一个成功匹配的规则；如果此操作导致错误，则不会尝试后续匹配。

匹配时，不执行前瞻(lookahead)；如果编译器无法逐个词法单元明确地确定如何解析宏调用，则会报错。在下面的示例中，编译器不会在前瞻到标识符之后，去检查后面的词法单元是否是 )，即使那样可以使其明确地解析调用：

#![allow(unused)]
fn main() {
macro_rules! ambiguity {
    ($($i:ident)* $j:ident) => { };
}

ambiguity!(error); // 错误：局部歧义
}

在匹配器和转录器中，$ 词法单元用于调用宏引擎的特殊行为（在下面的元变量和重复中描述）。不属于此类调用的词法单元会被字面匹配和转录，但有一个例外。这个例外是，匹配器的外部分隔符将匹配任意一对分隔符。因此，例如，匹配器 (()) 将匹配 {()} 但不匹配 {{}}。字符 $ 不能被字面匹配或转录。

转发匹配到的片段

当将一个匹配到的片段转发给另一个声明宏时，第二个宏中的匹配器将看到该片段类型的不透明 AST。第二个宏不能使用字面词法单元来匹配匹配器中的片段，只能使用相同类型的片段说明符。ident、lifetime 和 tt 片段类型是一个例外，它们可以通过字面词法单元进行匹配。下面示例说明了此限制：

#![allow(unused)]
fn main() {
macro_rules! foo {
    ($l:expr) => { bar!($l); }
// 错误：               ^^ 宏调用中不期望此词法单元
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

下面示例说明了在匹配 tt 片段后如何直接匹配词法单元：

#![allow(unused)]
fn main() {
// 编译通过
macro_rules! foo {
    ($l:tt) => { bar!($l); }
}

macro_rules! bar {
    (3) => {}
}

foo!(3);
}

元变量

在匹配器中，$ 名称 : 片段说明符 匹配指定种类的Rust语法片段，并将其绑定到元变量 $名称。

有效的片段说明符有：

• block：一个块表达式
• expr：一个表达式
• expr_2021：一个表达式，除了下划线表达式和常量块表达式（参见macro.decl.meta.edition2024）
• ident：一个IDENTIFIER_OR_KEYWORD，除了 _、RAW_IDENTIFIER或$crate
• item：一个项
• lifetime：一个LIFETIME_TOKEN
• literal：匹配 -^?字面量表达式
• meta：一个Attr，一个属性的内容
• pat：一个模式（参见macro.decl.meta.edition2021）
• pat_param：一个PatternNoTopAlt
• path：一个TypePath样式的路径
• stmt：一个语句，不带末尾分号（需要分号的项语句除外）
• tt：一个TokenTree （一个单独的词法单元或匹配分隔符 ()、[] 或 {} 中的词法单元）
• ty：一个类型
• vis：一个可能为空的可见性限定符