Introduction

This book is the primary reference for the Rust programming language. It provides three kinds of material:

• Chapters that informally describe each language construct and their use.
• Chapters that informally describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities.
• Appendix chapters providing rationale and references to languages that influenced the design.

Rust releases

Rust has a new language release every six weeks. The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. Tools (rustc, cargo, etc.) and documentation (Standard library, this book, etc.) are released with the language release.

The latest release of this book, matching the latest Rust version, can always be found at https://doc.rust-lang.org/reference/. Prior versions can be found by adding the Rust version before the “reference” directory. For example, the Reference for Rust 1.49.0 is located at https://doc.rust-lang.org/1.49.0/reference/.

What The Reference is not

This book does not serve as an introduction to the language. Background familiarity with the language is assumed. A separate book is available to help acquire such background familiarity.

This book also does not serve as a reference to the standard library included in the language distribution. Those libraries are documented separately by extracting documentation attributes from their source code. Many of the features that one might expect to be language features are library features in Rust, so what you’re looking for may be there, not here.

Similarly, this book does not usually document the specifics of rustc as a tool or of Cargo. rustc has its own book. Cargo has a book that contains a reference. There are a few pages such as linkage that still describe how rustc works.

This book also only serves as a reference to what is available in stable Rust. For unstable features being worked on, see the Unstable Book.

Rust compilers, including rustc, will perform optimizations. The reference does not specify what optimizations are allowed or disallowed. Instead, think of the compiled program as a black box. You can only probe by running it, feeding it input and observing its output. Everything that happens that way must conform to what the reference says.

Finally, this book is not normative. It may include details that are specific to rustc itself, and should not be taken as a specification for the Rust language. We intend to produce such a book someday, and until then, the reference is the closest thing we have to one.

How to use this book

This book does not assume you are reading this book sequentially. Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss.

There are two main ways to read this document.

The first is to answer a specific question. If you know which chapter answers that question, you can jump to that chapter in the table of contents. Otherwise, you can press s or click the magnifying glass on the top bar to search for keywords related to your question. For example, say you wanted to know when a temporary value created in a let statement is dropped. If you didn’t already know that the lifetime of temporaries is defined in the expressions chapter, you could search “temporary let” and the first search result will take you to that section.

The second is to generally improve your knowledge of a facet of the language. In that case, just browse the table of contents until you see something you want to know more about, and just start reading. If a link looks interesting, click it, and read about that section.

That said, there is no wrong way to read this book. Read it however you feel helps you best.

Conventions

Like all technical books, this book has certain conventions in how it displays information. These conventions are documented here.

• Statements that define a term contain that term in italics. Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition.

  An example term is an example of a term being defined.

• Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words “Edition differences:” in bold.

  Edition differences: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition.

• Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word “Note:” in bold.

  Note: This is an example note.

• Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box.

  Warning: This is an example warning.

• Code snippets inline in the text are inside <code> tags.

  Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner.

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

  All examples are written for the latest edition unless otherwise stated.

• The grammar and lexical structure is in blockquotes with either “Lexer” or “Syntax” in ^{bold superscript} as the first line.

  ^Syntax
  ExampleGrammar:
        ~ Expression
     | box Expression

  See Notation for more detail.

• Rule identifiers appear before each language rule enclosed in square brackets. These identifiers provide a way to refer to a specific rule in the language. The rule identifier uses periods to separate sections from most general to most specific (destructors.scope.nesting.function-body for example).

  The rule name can be clicked to link to that rule.

Contributing

We welcome contributions of all kinds.

You can contribute to this book by opening an issue or sending a pull request to the Rust Reference repository. If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to file an issue or ask about it in the t-lang/doc stream on Zulip. Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. We also want the reference to be as normative as possible, so if you see anything that is wrong or is non-normative but not specifically called out, please also file an issue.

Notation

Grammar

The following notations are used by the Lexer and Syntax grammar snippets:

String table productions

Some rules in the grammar — notably unary operators, binary operators, and keywords — are given in a simplified form: as a listing of printable strings. These cases form a subset of the rules regarding the token rule, and are assumed to be the result of a lexical-analysis phase feeding the parser, driven by a DFA, operating over the disjunction of all such string table entries.

When such a string in monospace font occurs inside the grammar, it is an implicit reference to a single member of such a string table production. See tokens for more information.

Lexical structure

Input format

This chapter describes how a source file is interpreted as a sequence of tokens.

See Crates and source files for a description of how programs are organised into files.

Source encoding

Each source file is interpreted as a sequence of Unicode characters encoded in UTF-8.

It is an error if the file is not valid UTF-8.

Byte order mark removal

If the first character in the sequence is U+FEFF (BYTE ORDER MARK), it is removed.

CRLF normalization

Each pair of characters U+000D (CR) immediately followed by U+000A (LF) is replaced by a single U+000A (LF).

Other occurrences of the character U+000D (CR) are left in place (they are treated as whitespace).

Shebang removal

If the remaining sequence begins with the characters #!, the characters up to and including the first U+000A (LF) are removed from the sequence.

For example, the first line of the following file would be ignored:

#!/usr/bin/env rustx

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

As an exception, if the #! characters are followed (ignoring intervening comments or whitespace) by a [ token, nothing is removed. This prevents an inner attribute at the start of a source file being removed.

Note: The standard library include! macro applies byte order mark removal, CRLF normalization, and shebang removal to the file it reads. The include_str! and include_bytes! macros do not.

Tokenization

The resulting sequence of characters is then converted into tokens as described in the remainder of this chapter.

Keywords

Rust divides keywords into three categories:

• strict
• reserved
• weak

Strict keywords

These keywords can only be used in their correct contexts. They cannot be used as the names of:

• Items
• Variables and function parameters
• Fields and variants
• Type parameters
• Lifetime parameters or loop labels
• Macros or attributes
• Macro placeholders
• Crates

^Lexer:
KW_AS : as
KW_BREAK : break
KW_CONST : const
KW_CONTINUE : continue
KW_CRATE : crate
KW_ELSE : else
KW_ENUM : enum
KW_EXTERN : extern
KW_FALSE : false
KW_FN : fn
KW_FOR : for
KW_IF : if
KW_IMPL : impl
KW_IN : in
KW_LET : let
KW_LOOP : loop
KW_MATCH : match
KW_MOD : mod
KW_MOVE : move
KW_MUT : mut
KW_PUB : pub
KW_REF : ref
KW_RETURN : return
KW_SELFVALUE : self
KW_SELFTYPE : Self
KW_STATIC : static
KW_STRUCT : struct
KW_SUPER : super
KW_TRAIT : trait
KW_TRUE : true
KW_TYPE : type
KW_UNSAFE : unsafe
KW_USE : use
KW_WHERE : where
KW_WHILE : while

The following keywords were added beginning in the 2018 edition.

^{Lexer 2018+}
KW_ASYNC : async
KW_AWAIT : await
KW_DYN : dyn

Reserved keywords

These keywords aren’t used yet, but they are reserved for future use. They have the same restrictions as strict keywords. The reasoning behind this is to make current programs forward compatible with future versions of Rust by forbidding them to use these keywords.

^Lexer
KW_ABSTRACT : abstract
KW_BECOME : become
KW_BOX : box
KW_DO : do
KW_FINAL : final
KW_MACRO : macro
KW_OVERRIDE : override
KW_PRIV : priv
KW_TYPEOF : typeof
KW_UNSIZED : unsized
KW_VIRTUAL : virtual
KW_YIELD : yield

The following keywords are reserved beginning in the 2018 edition.

^{Lexer 2018+}
KW_TRY : try

Weak keywords

These keywords have special meaning only in certain contexts. For example, it is possible to declare a variable or method with the name union.

• macro_rules is used to create custom macros.

• union is used to declare a union and is only a keyword when used in a union declaration.

• 'static is used for the static lifetime and cannot be used as a generic lifetime parameter or loop label

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

• In the 2015 edition, dyn is a keyword when used in a type position followed by a path that does not start with :: or <, a lifetime, a question mark, a for keyword or an opening parenthesis.

  Beginning in the 2018 edition, dyn has been promoted to a strict keyword.

^Lexer
KW_MACRO_RULES : macro_rules
KW_UNION : union
KW_STATICLIFETIME : 'static

^{Lexer 2015}
KW_DYN : dyn

• safe is used for functions and statics, which has meaning in external blocks.

Identifiers

^Lexer:
IDENTIFIER_OR_KEYWORD :
      XID_Start XID_Continue^*
   | _ XID_Continue⁺

RAW_IDENTIFIER : r# IDENTIFIER_OR_KEYWORD _{Except crate, self, super, Self}

NON_KEYWORD_IDENTIFIER : IDENTIFIER_OR_KEYWORD _{Except a strict or reserved keyword}

IDENTIFIER :
NON_KEYWORD_IDENTIFIER | RAW_IDENTIFIER

Identifiers follow the specification in Unicode Standard Annex #31 for Unicode version 15.0, with the additions described below. Some examples of identifiers:

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

The profile used from UAX #31 is:

• Start := XID_Start, plus the underscore character (U+005F)
• Continue := XID_Continue
• Medial := empty

with the additional constraint that a single underscore character is not an identifier.

Note: Identifiers starting with an underscore are typically used to indicate an identifier that is intentionally unused, and will silence the unused warning in rustc.

Identifiers may not be a strict or reserved keyword without the r# prefix described below in raw identifiers.

Zero width non-joiner (ZWNJ U+200C) and zero width joiner (ZWJ U+200D) characters are not allowed in identifiers.

Identifiers are restricted to the ASCII subset of XID_Start and XID_Continue in the following situations:

• extern crate declarations
• External crate names referenced in a path
• Module names loaded from the filesystem without a path attribute
• no_mangle attributed items
• Item names in external blocks

Normalization

Identifiers are normalized using Normalization Form C (NFC) as defined in Unicode Standard Annex #15. Two identifiers are equal if their NFC forms are equal.

Procedural and declarative macros receive normalized identifiers in their input.

Raw identifiers

A raw identifier is like a normal identifier, but prefixed by r#. (Note that the r# prefix is not included as part of the actual identifier.)

Unlike a normal identifier, a raw identifier may be any strict or reserved keyword except the ones listed above for RAW_IDENTIFIER.

Comments

^Lexer
LINE_COMMENT :
      // (~[/ ! \n] | //) ~\n^*
   | //

BLOCK_COMMENT :
      /* (~[* !] | ** | BlockCommentOrDoc) (BlockCommentOrDoc | ~*/)^* */
   | /**/
   | /***/

INNER_LINE_DOC :
   //! ~[\n IsolatedCR]^*

INNER_BLOCK_DOC :
   /*! ( BlockCommentOrDoc | ~[*/ IsolatedCR] )^* */

OUTER_LINE_DOC :
   /// (~/ ~[\n IsolatedCR]^*)^?

OUTER_BLOCK_DOC :
   /** (~* | BlockCommentOrDoc ) (BlockCommentOrDoc | ~[*/ IsolatedCR])^* */

BlockCommentOrDoc :
      BLOCK_COMMENT
   | OUTER_BLOCK_DOC
   | INNER_BLOCK_DOC

IsolatedCR :
   \r

Non-doc comments

Comments follow the general C++ style of line (//) and block (/* ... */) comment forms. Nested block comments are supported.

Non-doc comments are interpreted as a form of whitespace.

Doc comments

Line doc comments beginning with exactly three slashes (///), and block doc comments (/** ... */), both outer doc comments, are interpreted as a special syntax for doc attributes.

That is, they are equivalent to writing #[doc="..."] around the body of the comment, i.e., /// Foo turns into #[doc="Foo"] and /** Bar */ turns into #[doc="Bar"]. They must therefore appear before something that accepts an outer attribute.

Line comments beginning with //! and block comments /*! ... */ are doc comments that apply to the parent of the comment, rather than the item that follows.

That is, they are equivalent to writing #![doc="..."] around the body of the comment. //! comments are usually used to document modules that occupy a source file.

The character U+000D (CR) is not allowed in doc comments.

Note: It is conventional for doc comments to contain Markdown, as expected by rustdoc. However, the comment syntax does not respect any internal Markdown. /** `glob = "*/*.rs";` */ terminates the comment at the first */, and the remaining code would cause a syntax error. This slightly limits the content of block doc comments compared to line doc comments.

Note: The sequence U+000D (CR) immediately followed by U+000A (LF) would have been previously transformed into a single U+000A (LF).

Examples

#![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 {}
}
}

Whitespace

Whitespace is any non-empty string containing only characters that have the Pattern_White_Space Unicode property, namely:

• U+0009 (horizontal tab, '\t')
• U+000A (line feed, '\n')
• U+000B (vertical tab)
• U+000C (form feed)
• U+000D (carriage return, '\r')
• U+0020 (space, ' ')
• U+0085 (next line)
• U+200E (left-to-right mark)
• U+200F (right-to-left mark)
• U+2028 (line separator)
• U+2029 (paragraph separator)

Rust is a “free-form” language, meaning that all forms of whitespace serve only to separate tokens in the grammar, and have no semantic significance.

A Rust program has identical meaning if each whitespace element is replaced with any other legal whitespace element, such as a single space character.

Tokens

Tokens are primitive productions in the grammar defined by regular (non-recursive) languages. Rust source input can be broken down into the following kinds of tokens:

• Keywords
• Identifiers
• Literals
• Lifetimes
• Punctuation
• Delimiters

Within this documentation’s grammar, “simple” tokens are given in string table production form, and appear in monospace font.

Literals

Literals are tokens used in literal expressions.

Examples

Characters and strings

Note: Character and string literal tokens never include the sequence of U+000D (CR) immediately followed by U+000A (LF): this pair would have been previously transformed into a single U+000A (LF).

ASCII escapes

Byte escapes

Unicode escapes

Quote escapes

Numbers

Suffixes

A suffix is a sequence of characters following the primary part of a literal (without intervening whitespace), of the same form as a non-raw identifier or keyword.

^Lexer
SUFFIX : IDENTIFIER_OR_KEYWORD
SUFFIX_NO_E : SUFFIX _{not beginning with e or E}

Any kind of literal (string, integer, etc) with any suffix is valid as a token.

A literal token with any suffix can be passed to a macro without producing an error. The macro itself will decide how to interpret such a token and whether to produce an error or not. In particular, the literal fragment specifier for by-example macros matches literal tokens with arbitrary suffixes.

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

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

However, suffixes on literal tokens which are interpreted as literal expressions or patterns are restricted. Any suffixes are rejected on non-numeric literal tokens, and numeric literal tokens are accepted only with suffixes from the list below.

Character and string literals

Character literals

^Lexer
CHAR_LITERAL :
   ' ( ~[' \ \n \r \t] | QUOTE_ESCAPE | ASCII_ESCAPE | UNICODE_ESCAPE ) ' SUFFIX^?

QUOTE_ESCAPE :
   \' | \"

ASCII_ESCAPE :
      \x OCT_DIGIT HEX_DIGIT
   | \n | \r | \t | \\ | \0

UNICODE_ESCAPE :
   \u{ ( HEX_DIGIT _^* )^1..6 }

A character literal is a single Unicode character enclosed within two U+0027 (single-quote) characters, with the exception of U+0027 itself, which must be escaped by a preceding U+005C character (\).

String literals

^Lexer
STRING_LITERAL :
   " (
      ~[" \ IsolatedCR]
      | QUOTE_ESCAPE
      | ASCII_ESCAPE
      | UNICODE_ESCAPE
      | STRING_CONTINUE
   )^* " SUFFIX^?

STRING_CONTINUE :
   \ followed by \n

A string literal is a sequence of any Unicode characters enclosed within two U+0022 (double-quote) characters, with the exception of U+0022 itself, which must be escaped by a preceding U+005C character (\).

Line-breaks, represented by the character U+000A (LF), are allowed in string literals. When an unescaped U+005C character (\) occurs immediately before a line break, the line break does not appear in the string represented by the token. See String continuation escapes for details. The character U+000D (CR) may not appear in a string literal other than as part of such a string continuation escape.

Character escapes

Some additional escapes are available in either character or non-raw string literals. An escape starts with a U+005C (\) and continues with one of the following forms:

• A 7-bit code point escape starts with U+0078 (x) and is followed by exactly two hex digits with value up to 0x7F. It denotes the ASCII character with value equal to the provided hex value. Higher values are not permitted because it is ambiguous whether they mean Unicode code points or byte values.

• A 24-bit code point escape starts with U+0075 (u) and is followed by up to six hex digits surrounded by braces U+007B ({) and U+007D (}). It denotes the Unicode code point equal to the provided hex value.

• A whitespace escape is one of the characters U+006E (n), U+0072 (r), or U+0074 (t), denoting the Unicode values U+000A (LF), U+000D (CR) or U+0009 (HT) respectively.

• The null escape is the character U+0030 (0) and denotes the Unicode value U+0000 (NUL).

• The backslash escape is the character U+005C (\) which must be escaped in order to denote itself.

Raw string literals

^Lexer
RAW_STRING_LITERAL :
   r RAW_STRING_CONTENT SUFFIX^?

RAW_STRING_CONTENT :
      " ( ~ IsolatedCR )^{* (non-greedy)} "
   | # RAW_STRING_CONTENT #

Raw string literals do not process any escapes. They start with the character U+0072 (r), followed by fewer than 256 of the character U+0023 (#) and a U+0022 (double-quote) character.

The raw string body can contain any sequence of Unicode characters other than U+000D (CR). It is terminated only by another U+0022 (double-quote) character, followed by the same number of U+0023 (#) characters that preceded the opening U+0022 (double-quote) character.

All Unicode characters contained in the raw string body represent themselves, the characters U+0022 (double-quote) (except when followed by at least as many U+0023 (#) characters as were used to start the raw string literal) or U+005C (\) do not have any special meaning.

Examples for string literals:

#![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
}

Byte and byte string literals

Byte literals

^Lexer
BYTE_LITERAL :
   b' ( ASCII_FOR_CHAR | BYTE_ESCAPE ) ' SUFFIX^?

ASCII_FOR_CHAR :
   any ASCII (i.e. 0x00 to 0x7F), except ', \, \n, \r or \t

BYTE_ESCAPE :
      \x HEX_DIGIT HEX_DIGIT
   | \n | \r | \t | \\ | \0 | \' | \"

A byte literal is a single ASCII character (in the U+0000 to U+007F range) or a single escape preceded by the characters U+0062 (b) and U+0027 (single-quote), and followed by the character U+0027. If the character U+0027 is present within the literal, it must be escaped by a preceding U+005C (\) character. It is equivalent to a u8 unsigned 8-bit integer number literal.

Byte string literals

^Lexer
BYTE_STRING_LITERAL :
   b" ( ASCII_FOR_STRING | BYTE_ESCAPE | STRING_CONTINUE )^* " SUFFIX^?

ASCII_FOR_STRING :
   any ASCII (i.e 0x00 to 0x7F), except ", \ and IsolatedCR

A non-raw byte string literal is a sequence of ASCII characters and escapes, preceded by the characters U+0062 (b) and U+0022 (double-quote), and followed by the character U+0022. If the character U+0022 is present within the literal, it must be escaped by a preceding U+005C (\) character. Alternatively, a byte string literal can be a raw byte string literal, defined below.

Line-breaks, represented by the character U+000A (LF), are allowed in byte string literals. When an unescaped U+005C character (\) occurs immediately before a line break, the line break does not appear in the string represented by the token. See String continuation escapes for details. The character U+000D (CR) may not appear in a byte string literal other than as part of such a string continuation escape.

Some additional escapes are available in either byte or non-raw byte string literals. An escape starts with a U+005C (\) and continues with one of the following forms:

• A byte escape escape starts with U+0078 (x) and is followed by exactly two hex digits. It denotes the byte equal to the provided hex value.

• A whitespace escape is one of the characters U+006E (n), U+0072 (r), or U+0074 (t), denoting the bytes values 0x0A (ASCII LF), 0x0D (ASCII CR) or 0x09 (ASCII HT) respectively.

• The null escape is the character U+0030 (0) and denotes the byte value 0x00 (ASCII NUL).

• The backslash escape is the character U+005C (\) which must be escaped in order to denote its ASCII encoding 0x5C.

Raw byte string literals

^Lexer
RAW_BYTE_STRING_LITERAL :
   br RAW_BYTE_STRING_CONTENT SUFFIX^?

RAW_BYTE_STRING_CONTENT :
      " ASCII_FOR_RAW^{* (non-greedy)} "
   | # RAW_BYTE_STRING_CONTENT #

ASCII_FOR_RAW :
   any ASCII (i.e. 0x00 to 0x7F) except IsolatedCR

Raw byte string literals do not process any escapes. They start with the character U+0062 (b), followed by U+0072 (r), followed by fewer than 256 of the character U+0023 (#), and a U+0022 (double-quote) character.

The raw string body can contain any sequence of ASCII characters other than U+000D (CR). It is terminated only by another U+0022 (double-quote) character, followed by the same number of U+0023 (#) characters that preceded the opening U+0022 (double-quote) character. A raw byte string literal can not contain any non-ASCII byte.

All characters contained in the raw string body represent their ASCII encoding, the characters U+0022 (double-quote) (except when followed by at least as many U+0023 (#) characters as were used to start the raw string literal) or U+005C (\) do not have any special meaning.

Examples for byte string literals:

#![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 string and raw C string literals

C string literals

^Lexer
C_STRING_LITERAL :
   c" (
      ~[" \ IsolatedCR NUL]
      | BYTE_ESCAPE except \0 or \x00
      | UNICODE_ESCAPE except \u{0}, \u{00}, …, \u{000000}
      | STRING_CONTINUE
   )^* " SUFFIX^?

A C string literal is a sequence of Unicode characters and escapes, preceded by the characters U+0063 (c) and U+0022 (double-quote), and followed by the character U+0022. If the character U+0022 is present within the literal, it must be escaped by a preceding U+005C (\) character. Alternatively, a C string literal can be a raw C string literal, defined below.

C strings are implicitly terminated by byte 0x00, so the C string literal c"" is equivalent to manually constructing a &CStr from the byte string literal b"\x00". Other than the implicit terminator, byte 0x00 is not permitted within a C string.

Line-breaks, represented by the character U+000A (LF), are allowed in C string literals. When an unescaped U+005C character (\) occurs immediately before a line break, the line break does not appear in the string represented by the token. See String continuation escapes for details. The character U+000D (CR) may not appear in a C string literal other than as part of such a string continuation escape.

Some additional escapes are available in non-raw C string literals. An escape starts with a U+005C (\) and continues with one of the following forms:

• A byte escape escape starts with U+0078 (x) and is followed by exactly two hex digits. It denotes the byte equal to the provided hex value.

• A 24-bit code point escape starts with U+0075 (u) and is followed by up to six hex digits surrounded by braces U+007B ({) and U+007D (}). It denotes the Unicode code point equal to the provided hex value, encoded as UTF-8.

• A whitespace escape is one of the characters U+006E (n), U+0072 (r), or U+0074 (t), denoting the bytes values 0x0A (ASCII LF), 0x0D (ASCII CR) or 0x09 (ASCII HT) respectively.

• The backslash escape is the character U+005C (\) which must be escaped in order to denote its ASCII encoding 0x5C.

A C string represents bytes with no defined encoding, but a C string literal may contain Unicode characters above U+007F. Such characters will be replaced with the bytes of that character’s UTF-8 representation.

The following C string literals are equivalent:

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

Edition differences: C string literals are accepted in the 2021 edition or later. In earlier additions the token c"" is lexed as c "".

Raw C string literals

^Lexer
RAW_C_STRING_LITERAL :
   cr RAW_C_STRING_CONTENT SUFFIX^?

RAW_C_STRING_CONTENT :
      " ( ~ IsolatedCR NUL )^{* (non-greedy)} "
   | # RAW_C_STRING_CONTENT #

Raw C string literals do not process any escapes. They start with the character U+0063 (c), followed by U+0072 (r), followed by fewer than 256 of the character U+0023 (#), and a U+0022 (double-quote) character.

The raw C string body can contain any sequence of Unicode characters other than U+0000 (NUL) and U+000D (CR). It is terminated only by another U+0022 (double-quote) character, followed by the same number of U+0023 (#) characters that preceded the opening U+0022 (double-quote) character.

All characters contained in the raw C string body represent themselves in UTF-8 encoding. The characters U+0022 (double-quote) (except when followed by at least as many U+0023 (#) characters as were used to start the raw C string literal) or U+005C (\) do not have any special meaning.

Edition differences: Raw C string literals are accepted in the 2021 edition or later. In earlier additions the token cr"" is lexed as cr "", and cr#""# is lexed as cr #""# (which is non-grammatical).

Examples for C string and raw C string literals

#![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
}

Number literals

A number literal is either an integer literal or a floating-point literal. The grammar for recognizing the two kinds of literals is mixed.

Integer literals

^Lexer
INTEGER_LITERAL :
   ( DEC_LITERAL | BIN_LITERAL | OCT_LITERAL | HEX_LITERAL ) SUFFIX_NO_E^?

DEC_LITERAL :
   DEC_DIGIT (DEC_DIGIT|_)^*

BIN_LITERAL :
   0b (BIN_DIGIT|_)^* BIN_DIGIT (BIN_DIGIT|_)^*

OCT_LITERAL :
   0o (OCT_DIGIT|_)^* OCT_DIGIT (OCT_DIGIT|_)^*

HEX_LITERAL :
   0x (HEX_DIGIT|_)^* HEX_DIGIT (HEX_DIGIT|_)^*

BIN_DIGIT : [0-1]

OCT_DIGIT : [0-7]

DEC_DIGIT : [0-9]

HEX_DIGIT : [0-9 a-f A-F]

An integer literal has one of four forms:

• A decimal literal starts with a decimal digit and continues with any mixture of decimal digits and underscores.

• A hex literal starts with the character sequence U+0030 U+0078 (0x) and continues as any mixture (with at least one digit) of hex digits and underscores.

• An octal literal starts with the character sequence U+0030 U+006F (0o) and continues as any mixture (with at least one digit) of octal digits and underscores.

• A binary literal starts with the character sequence U+0030 U+0062 (0b) and continues as any mixture (with at least one digit) of binary digits and underscores.

Like any literal, an integer literal may be followed (immediately, without any spaces) by a suffix as described above. The suffix may not begin with e or E, as that would be interpreted as the exponent of a floating-point literal. See Integer literal expressions for the effect of these suffixes.

Examples of integer literals which are accepted as literal expressions:

#![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;
}

Note that -1i8, for example, is analyzed as two tokens: - followed by 1i8.

Examples of integer literals which are not accepted as literal expressions:

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

Tuple index

^Lexer
TUPLE_INDEX:
   INTEGER_LITERAL

A tuple index is used to refer to the fields of tuples, tuple structs, and tuple variants.

Tuple indices are compared with the literal token directly. Tuple indices start with 0 and each successive index increments the value by 1 as a decimal value. Thus, only decimal values will match, and the value must not have any extra 0 prefix characters.

#![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`
}

Note: Tuple indices may include certain suffixes, but this is not intended to be valid, and may be removed in a future version. See https://github.com/rust-lang/rust/issues/60210 for more information.

Floating-point literals

^Lexer
FLOAT_LITERAL :
      DEC_LITERAL . (not immediately followed by ., _ or an XID_Start character)
   | DEC_LITERAL . DEC_LITERAL SUFFIX_NO_E^?
   | DEC_LITERAL (. DEC_LITERAL)^? FLOAT_EXPONENT SUFFIX^?

FLOAT_EXPONENT :
   (e|E) (+|-)^? (DEC_DIGIT|_)^* DEC_DIGIT (DEC_DIGIT|_)^*

A floating-point literal has one of two forms:

• A decimal literal followed by a period character U+002E (.). This is optionally followed by another decimal literal, with an optional exponent.
• A single decimal literal followed by an exponent.

Like integer literals, a floating-point literal may be followed by a suffix, so long as the pre-suffix part does not end with U+002E (.). The suffix may not begin with e or E if the literal does not include an exponent. See Floating-point literal expressions for the effect of these suffixes.

Examples of floating-point literals which are accepted as literal expressions:

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

This last example is different because it is not possible to use the suffix syntax with a floating point literal end.token.ing in a period. 2.f64 would attempt to call a method named f64 on 2.

Note that -1.0, for example, is analyzed as two tokens: - followed by 1.0.

Examples of floating-point literals which are not accepted as literal expressions:

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

Reserved forms similar to number literals

^Lexer
RESERVED_NUMBER :
      BIN_LITERAL [2-9​]
   | OCT_LITERAL [8-9​]
   | ( BIN_LITERAL | OCT_LITERAL | HEX_LITERAL ) .
         (not immediately followed by ., _ or an XID_Start character)
   | ( BIN_LITERAL | OCT_LITERAL ) (e|E)
   | 0b _^* end of input or not BIN_DIGIT
   | 0o _^* end of input or not OCT_DIGIT
   | 0x _^* end of input or not HEX_DIGIT
   | DEC_LITERAL ( . DEC_LITERAL)^? (e|E) (+|-)^? end of input or not DEC_DIGIT

The following lexical forms similar to number literals are reserved forms. Due to the possible ambiguity these raise, they are rejected by the tokenizer instead of being interpreted as separate tokens.

• An unsuffixed binary or octal literal followed, without intervening whitespace, by a decimal digit out of the range for its radix.

• An unsuffixed binary, octal, or hexadecimal literal followed, without intervening whitespace, by a period character (with the same restrictions on what follows the period as for floating-point literals).

• An unsuffixed binary or octal literal followed, without intervening whitespace, by the character e or E.

• Input which begins with one of the radix prefixes but is not a valid binary, octal, or hexadecimal literal (because it contains no digits).

• Input which has the form of a floating-point literal with no digits in the exponent.

Examples of reserved forms:

#![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_`
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`
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`
}

Lifetimes and loop labels

^Lexer
LIFETIME_TOKEN :
      ' IDENTIFIER_OR_KEYWORD (not immediately followed by ')
   | '_ (not immediately followed by ')

LIFETIME_OR_LABEL :
      ' NON_KEYWORD_IDENTIFIER (not immediately followed by ')

Lifetime parameters and loop labels use LIFETIME_OR_LABEL tokens. Any LIFETIME_TOKEN will be accepted by the lexer, and for example, can be used in macros.

Punctuation

Punctuation symbol tokens are listed here for completeness. Their individual usages and meanings are defined in the linked pages.

Delimiters

Bracket punctuation is used in various parts of the grammar. An open bracket must always be paired with a close bracket. Brackets and the tokens within them are referred to as “token trees” in macros. The three types of brackets are:

Reserved prefixes

^{Lexer 2021+}
RESERVED_TOKEN_DOUBLE_QUOTE : ( IDENTIFIER_OR_KEYWORD _{Except b or c or r or br or cr} | _ ) "
RESERVED_TOKEN_SINGLE_QUOTE : ( IDENTIFIER_OR_KEYWORD _{Except b} | _ ) '
RESERVED_TOKEN_POUND : ( IDENTIFIER_OR_KEYWORD _{Except r or br or cr} | _ ) #

Some lexical forms known as reserved prefixes are reserved for future use.

Source input which would otherwise be lexically interpreted as a non-raw identifier (or a keyword or _) which is immediately followed by a #, ', or " character (without intervening whitespace) is identified as a reserved prefix.

Note that raw identifiers, raw string literals, and raw byte string literals may contain a # character but are not interpreted as containing a reserved prefix.

Similarly the r, b, br, c, and cr prefixes used in raw string literals, byte literals, byte string literals, raw byte string literals, C string literals, and raw C string literals are not interpreted as reserved prefixes.

Edition differences: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros).

Before the 2021 edition, reserved prefixes are accepted by the lexer and interpreted as multiple tokens (for example, one token for the identifier or keyword, followed by a # token).

Examples accepted in all editions:

#![allow(unused)]
fn main() {
macro_rules! lexes {($($_:tt)*) => {}}
lexes!{a #foo}
lexes!{continue 'foo}
lexes!{match "..." {}}
lexes!{r#let#foo}         // three tokens: r#let # foo
}

Examples accepted before the 2021 edition but rejected later:

#![allow(unused)]
fn main() {
macro_rules! lexes {($($_:tt)*) => {}}
lexes!{a#foo}
lexes!{continue'foo}
lexes!{match"..." {}}
}

Macros

The functionality and syntax of Rust can be extended with custom definitions called macros. They are given names, and invoked through a consistent syntax: some_extension!(...).

There are two ways to define new macros:

• Macros by Example define new syntax in a higher-level, declarative way.
• Procedural Macros define function-like macros, custom derives, and custom attributes using functions that operate on input tokens.

Macro Invocation

^Syntax
MacroInvocation :
   SimplePath ! DelimTokenTree

DelimTokenTree :
      ( TokenTree^* )
   | [ TokenTree^* ]
   | { TokenTree^* }

TokenTree :
   Token_{except delimiters} | DelimTokenTree

MacroInvocationSemi :
      SimplePath ! ( TokenTree^* ) ;
   | SimplePath ! [ TokenTree^* ] ;
   | SimplePath ! { TokenTree^* }

A macro invocation expands a macro at compile time and replaces the invocation with the result of the macro. Macros may be invoked in the following situations:

• Expressions and statements
• Patterns
• Types
• Items including associated items
• macro_rules transcribers
• External blocks

When used as an item or a statement, the MacroInvocationSemi form is used where a semicolon is required at the end when not using curly braces. Visibility qualifiers are never allowed before a macro invocation or macro_rules definition.

#![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!();
}

Macros By Example

^Syntax
MacroRulesDefinition :
   macro_rules ! IDENTIFIER MacroRulesDef

MacroRulesDef :
      ( MacroRules ) ;
   | [ MacroRules ] ;
   | { MacroRules }

MacroRules :
   MacroRule ( ; MacroRule )^* ;^?

MacroRule :
   MacroMatcher => MacroTranscriber

MacroMatcher :
      ( MacroMatch^* )
   | [ MacroMatch^* ]
   | { MacroMatch^* }

MacroMatch :
      Token_{except $ and delimiters}
   | MacroMatcher
   | $ ( IDENTIFIER_OR_KEYWORD _{except crate} | RAW_IDENTIFIER | _ ) : MacroFragSpec
   | $ ( MacroMatch⁺ ) MacroRepSep^? MacroRepOp

MacroFragSpec :
      block | expr | expr_2021 | ident | item | lifetime | literal
   | meta | pat | pat_param | path | stmt | tt | ty | vis

MacroRepSep :
   Token_{except delimiters and MacroRepOp}

MacroRepOp :
   * | + | ?

MacroTranscriber :
   DelimTokenTree

macro_rules allows users to define syntax extension in a declarative way. We call such extensions “macros by example” or simply “macros”.

Each macro by example has a name, and one or more rules. Each rule has two parts: a matcher, describing the syntax that it matches, and a transcriber, describing the syntax that will replace a successfully matched invocation. Both the matcher and the transcriber must be surrounded by delimiters. Macros can expand to expressions, statements, items (including traits, impls, and foreign items), types, or patterns.

Transcribing

When a macro is invoked, the macro expander looks up macro invocations by name, and tries each macro rule in turn. It transcribes the first successful match; if this results in an error, then future matches are not tried.

When matching, no lookahead is performed; if the compiler cannot unambiguously determine how to parse the macro invocation one token at a time, then it is an error. In the following example, the compiler does not look ahead past the identifier to see if the following token is a ), even though that would allow it to parse the invocation unambiguously:

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

ambiguity!(error); // Error: local ambiguity
}

In both the matcher and the transcriber, the $ token is used to invoke special behaviours from the macro engine (described below in Metavariables and Repetitions). Tokens that aren’t part of such an invocation are matched and transcribed literally, with one exception. The exception is that the outer delimiters for the matcher will match any pair of delimiters. Thus, for instance, the matcher (()) will match {()} but not {{}}. The character $ cannot be matched or transcribed literally.

Forwarding a matched fragment

When forwarding a matched fragment to another macro-by-example, matchers in the second macro will see an opaque AST of the fragment type. The second macro can’t use literal tokens to match the fragments in the matcher, only a fragment specifier of the same type. The ident, lifetime, and tt fragment types are an exception, and can be matched by literal tokens. The following illustrates this restriction:

#![allow(unused)]
fn main() {
macro_rules! foo {
    ($l:expr) => { bar!($l); }
// ERROR:               ^^ no rules expected this token in macro call
}

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

foo!(3);
}

The following illustrates how tokens can be directly matched after matching a tt fragment:

#![allow(unused)]
fn main() {
// compiles OK
macro_rules! foo {
    ($l:tt) => { bar!($l); }
}

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

foo!(3);
}

Metavariables

In the matcher, $ name : fragment-specifier matches a Rust syntax fragment of the kind specified and binds it to the metavariable $name.

Valid fragment specifiers are:

• block: a BlockExpression
• expr: an Expression except UnderscoreExpression and ConstBlockExpression (see macro.decl.meta.expr-underscore)
• expr_2021: same as expr (see macro.decl.meta.edition2021)
• ident: an IDENTIFIER_OR_KEYWORD or RAW_IDENTIFIER
• item: an Item
• lifetime: a LIFETIME_TOKEN
• literal: matches -^?LiteralExpression
• meta: an Attr, the contents of an attribute
• pat: a Pattern (see macro.decl.meta.edition2021)
• pat_param: a PatternNoTopAlt
• path: a TypePath style path
• stmt: a Statement without the trailing semicolon (except for item statements that require semicolons)
• tt: a TokenTree (a single token or tokens in matching delimiters (), [], or {})
• ty: a Type
• vis: a possibly empty Visibility qualifier

In the transcriber, metavariables are referred to simply by $name, since the fragment kind is specified in the matcher. Metavariables are replaced with the syntax element that matched them.

The keyword metavariable $crate can be used to refer to the current crate; see Hygiene below. Metavariables can be transcribed more than once or not at all.

For reasons of backwards compatibility, though _ is also an expression, a standalone underscore is not matched by the expr fragment specifier. However, _ is matched by the expr fragment specifier when it appears as a subexpression. For the same reason, a standalone const block is not matched but it is matched when appearing as a subexpression.

Edition differences: Starting with the 2021 edition, pat fragment-specifiers match top-level or-patterns (that is, they accept Pattern).

Before the 2021 edition, they match exactly the same fragments as pat_param (that is, they accept PatternNoTopAlt).

The relevant edition is the one in effect for the macro_rules! definition.

The expr_2021 fragment specifier exists to maintain backwards compatibility with editions before 2024.

Repetitions

In both the matcher and transcriber, repetitions are indicated by placing the tokens to be repeated inside $(…), followed by a repetition operator, optionally with a separator token between.

The separator token can be any token other than a delimiter or one of the repetition operators, but ; and , are the most common. For instance, $( $i:ident ),* represents any number of identifiers separated by commas. Nested repetitions are permitted.

The repetition operators are:

• * — indicates any number of repetitions.
• + — indicates any number but at least one.
• ? — indicates an optional fragment with zero or one occurrence.

Since ? represents at most one occurrence, it cannot be used with a separator.

The repeated fragment both matches and transcribes to the specified number of the fragment, separated by the separator token. Metavariables are matched to every repetition of their corresponding fragment. For instance, the $( $i:ident ),* example above matches $i to all of the identifiers in the list.

During transcription, additional restrictions apply to repetitions so that the compiler knows how to expand them properly:

1. A metavariable must appear in exactly the same number, kind, and nesting order of repetitions in the transcriber as it did in the matcher. So for the matcher $( $i:ident ),*, the transcribers => { $i }, => { $( $( $i)* )* }, and => { $( $i )+ } are all illegal, but => { $( $i );* } is correct and replaces a comma-separated list of identifiers with a semicolon-separated list.
2. Each repetition in the transcriber must contain at least one metavariable to decide how many times to expand it. If multiple metavariables appear in the same repetition, they must be bound to the same number of fragments. For instance, ( $( $i:ident ),* ; $( $j:ident ),* ) => (( $( ($i,$j) ),* )) must bind the same number of $i fragments as $j fragments. This means that invoking the macro with (a, b, c; d, e, f) is legal and expands to ((a,d), (b,e), (c,f)), but (a, b, c; d, e) is illegal because it does not have the same number. This requirement applies to every layer of nested repetitions.

Scoping, Exporting, and Importing

For historical reasons, the scoping of macros by example does not work entirely like items. Macros have two forms of scope: textual scope, and path-based scope. Textual scope is based on the order that things appear in source files, or even across multiple files, and is the default scoping. It is explained further below. Path-based scope works exactly the same way that item scoping does. The scoping, exporting, and importing of macros is controlled largely by attributes.

When a macro is invoked by an unqualified identifier (not part of a multi-part path), it is first looked up in textual scoping. If this does not yield any results, then it is looked up in path-based scoping. If the macro’s name is qualified with a path, then it is only looked up in path-based scoping.

use lazy_static::lazy_static; // Path-based import.

macro_rules! lazy_static { // Textual definition.
    (lazy) => {};
}

lazy_static!{lazy} // Textual lookup finds our macro first.
self::lazy_static!{} // Path-based lookup ignores our macro, finds imported one.

Textual Scope

Textual scope is based largely on the order that things appear in source files, and works similarly to the scope of local variables declared with let except it also applies at the module level. When macro_rules! is used to define a macro, the macro enters the scope after the definition (note that it can still be used recursively, since names are looked up from the invocation site), up until its surrounding scope, typically a module, is closed. This can enter child modules and even span across multiple files:

//// src/lib.rs
mod has_macro {
    // m!{} // Error: m is not in scope.

    macro_rules! m {
        () => {};
    }
    m!{} // OK: appears after declaration of m.

    mod uses_macro;
}

// m!{} // Error: m is not in scope.

//// src/has_macro/uses_macro.rs

m!{} // OK: appears after declaration of m in src/lib.rs

It is not an error to define a macro multiple times; the most recent declaration will shadow the previous one unless it has gone out of scope.

#![allow(unused)]
fn main() {
macro_rules! m {
    (1) => {};
}

m!(1);

mod inner {
    m!(1);

    macro_rules! m {
        (2) => {};
    }
    // m!(1); // Error: no rule matches '1'
    m!(2);

    macro_rules! m {
        (3) => {};
    }
    m!(3);
}

m!(1);
}

Macros can be declared and used locally inside functions as well, and work similarly:

#![allow(unused)]
fn main() {
fn foo() {
    // m!(); // Error: m is not in scope.
    macro_rules! m {
        () => {};
    }
    m!();
}

// m!(); // Error: m is not in scope.
}

The macro_use attribute

The macro_use attribute has two purposes. First, it can be used to make a module’s macro scope not end when the module is closed, by applying it to a module:

#![allow(unused)]
fn main() {
#[macro_use]
mod inner {
    macro_rules! m {
        () => {};
    }
}

m!();
}

Second, it can be used to import macros from another crate, by attaching it to an extern crate declaration appearing in the crate’s root module. Macros imported this way are imported into the macro_use prelude, not textually, which means that they can be shadowed by any other name. While macros imported by #[macro_use] can be used before the import statement, in case of a conflict, the last macro imported wins. Optionally, a list of macros to import can be specified using the MetaListIdents syntax; this is not supported when #[macro_use] is applied to a module.

#[macro_use(lazy_static)] // Or #[macro_use] to import all macros.
extern crate lazy_static;

lazy_static!{}
// self::lazy_static!{} // Error: lazy_static is not defined in `self`

Macros to be imported with #[macro_use] must be exported with #[macro_export], which is described below.

Path-Based Scope

By default, a macro has no path-based scope. However, if it has the #[macro_export] attribute, then it is declared in the crate root scope and can be referred to normally as such:

#![allow(unused)]
fn main() {
self::m!();
m!(); // OK: Path-based lookup finds m in the current module.

mod inner {
    super::m!();
    crate::m!();
}

mod mac {
    #[macro_export]
    macro_rules! m {
        () => {};
    }
}
}

Macros labeled with #[macro_export] are always pub and can be referred to by other crates, either by path or by #[macro_use] as described above.

Hygiene

Macros by example have mixed-site hygiene. This means that loop labels, block labels, and local variables are looked up at the macro definition site while other symbols are looked up at the macro invocation site. For example:

#![allow(unused)]
fn main() {
let x = 1;
fn func() {
    unreachable!("this is never called")
}

macro_rules! check {
    () => {
        assert_eq!(x, 1); // Uses `x` from the definition site.
        func();           // Uses `func` from the invocation site.
    };
}

{
    let x = 2;
    fn func() { /* does not panic */ }
    check!();
}
}

Labels and local variables defined in macro expansion are not shared between invocations, so this code doesn’t compile:

#![allow(unused)]
fn main() {
macro_rules! m {
    (define) => {
        let x = 1;
    };
    (refer) => {
        dbg!(x);
    };
}

m!(define);
m!(refer);
}

A special case is the $crate metavariable. It refers to the crate defining the macro, and can be used at the start of the path to look up items or macros which are not in scope at the invocation site.

//// Definitions in the `helper_macro` crate.
#[macro_export]
macro_rules! helped {
    // () => { helper!() } // This might lead to an error due to 'helper' not being in scope.
    () => { $crate::helper!() }
}

#[macro_export]
macro_rules! helper {
    () => { () }
}

//// Usage in another crate.
// Note that `helper_macro::helper` is not imported!
use helper_macro::helped;

fn unit() {
    helped!();
}

Note that, because $crate refers to the current crate, it must be used with a fully qualified module path when referring to non-macro items:

#![allow(unused)]
fn main() {
pub mod inner {
    #[macro_export]
    macro_rules! call_foo {
        () => { $crate::inner::foo() };
    }

    pub fn foo() {}
}
}

Additionally, even though $crate allows a macro to refer to items within its own crate when expanding, its use has no effect on visibility. An item or macro referred to must still be visible from the invocation site. In the following example, any attempt to invoke call_foo!() from outside its crate will fail because foo() is not public.

#![allow(unused)]
fn main() {
#[macro_export]
macro_rules! call_foo {
    () => { $crate::foo() };
}

fn foo() {}
}

Version & Edition differences: Prior to Rust 1.30, $crate and local_inner_macros (below) were unsupported. They were added alongside path-based imports of macros (described above), to ensure that helper macros did not need to be manually imported by users of a macro-exporting crate. Crates written for earlier versions of Rust that use helper macros need to be modified to use $crate or local_inner_macros to work well with path-based imports.

When a macro is exported, the #[macro_export] attribute can have the local_inner_macros keyword added to automatically prefix all contained macro invocations with $crate::. This is intended primarily as a tool to migrate code written before $crate was added to the language to work with Rust 2018’s path-based imports of macros. Its use is discouraged in new code.

#![allow(unused)]
fn main() {
#[macro_export(local_inner_macros)]
macro_rules! helped {
    () => { helper!() } // Automatically converted to $crate::helper!().
}

#[macro_export]
macro_rules! helper {
    () => { () }
}
}

Follow-set Ambiguity Restrictions

The parser used by the macro system is reasonably powerful, but it is limited in order to prevent ambiguity in current or future versions of the language.

In particular, in addition to the rule about ambiguous expansions, a nonterminal matched by a metavariable must be followed by a token which has been decided can be safely used after that kind of match.

As an example, a macro matcher like $i:expr [ , ] could in theory be accepted in Rust today, since [,] cannot be part of a legal expression and therefore the parse would always be unambiguous. However, because [ can start trailing expressions, [ is not a character which can safely be ruled out as coming after an expression. If [,] were accepted in a later version of Rust, this matcher would become ambiguous or would misparse, breaking working code. Matchers like $i:expr, or $i:expr; would be legal, however, because , and ; are legal expression separators. The specific rules are:

• expr and stmt may only be followed by one of: =>, ,, or ;.

• pat_param may only be followed by one of: =>, ,, =, |, if, or in.

• pat may only be followed by one of: =>, ,, =, if, or in.

• path and ty may only be followed by one of: =>, ,, =, |, ;, :, >, >>, [, {, as, where, or a macro variable of block fragment specifier.

• vis may only be followed by one of: ,, an identifier other than a non-raw priv, any token that can begin a type, or a metavariable with a ident, ty, or path fragment specifier.

• All other fragment specifiers have no restrictions.

Edition differences: Before the 2021 edition, pat may also be followed by |.

When repetitions are involved, then the rules apply to every possible number of expansions, taking separators into account. This means:

• If the repetition includes a separator, that separator must be able to follow the contents of the repetition.
• If the repetition can repeat multiple times (* or +), then the contents must be able to follow themselves.
• The contents of the repetition must be able to follow whatever comes before, and whatever comes after must be able to follow the contents of the repetition.
• If the repetition can match zero times (* or ?), then whatever comes after must be able to follow whatever comes before.

For more detail, see the formal specification.

Procedural Macros

Procedural macros allow creating syntax extensions as execution of a function. Procedural macros come in one of three flavors:

• Function-like macros - custom!(...)
• Derive macros - #[derive(CustomDerive)]
• Attribute macros - #[CustomAttribute]

Procedural macros allow you to run code at compile time that operates over Rust syntax, both consuming and producing Rust syntax. You can sort of think of procedural macros as functions from an AST to another AST.

Procedural macros must be defined in the root of a crate with the crate type of proc-macro. The macros may not be used from the crate where they are defined, and can only be used when imported in another crate.

Note: When using Cargo, Procedural macro crates are defined with the proc-macro key in your manifest:

[lib]
proc-macro = true

As functions, they must either return syntax, panic, or loop endlessly. Returned syntax either replaces or adds the syntax depending on the kind of procedural macro. Panics are caught by the compiler and are turned into a compiler error. Endless loops are not caught by the compiler which hangs the compiler.

Procedural macros run during compilation, and thus have the same resources that the compiler has. For example, standard input, error, and output are the same that the compiler has access to. Similarly, file access is the same. Because of this, procedural macros have the same security concerns that Cargo’s build scripts have.

Procedural macros have two ways of reporting errors. The first is to panic. The second is to emit a compile_error macro invocation.

The proc_macro crate

Procedural macro crates almost always will link to the compiler-provided proc_macro crate. The proc_macro crate provides types required for writing procedural macros and facilities to make it easier.

This crate primarily contains a TokenStream type. Procedural macros operate over token streams instead of AST nodes, which is a far more stable interface over time for both the compiler and for procedural macros to target. A token stream is roughly equivalent to Vec<TokenTree> where a TokenTree can roughly be thought of as lexical token. For example foo is an Ident token, . is a Punct token, and 1.2 is a Literal token. The TokenStream type, unlike Vec<TokenTree>, is cheap to clone.

All tokens have an associated Span. A Span is an opaque value that cannot be modified but can be manufactured. Spans represent an extent of source code within a program and are primarily used for error reporting. While you cannot modify a Span itself, you can always change the Span associated with any token, such as through getting a Span from another token.

Procedural macro hygiene

Procedural macros are unhygienic. This means they behave as if the output token stream was simply written inline to the code it’s next to. This means that it’s affected by external items and also affects external imports.

Macro authors need to be careful to ensure their macros work in as many contexts as possible given this limitation. This often includes using absolute paths to items in libraries (for example, ::std::option::Option instead of Option) or by ensuring that generated functions have names that are unlikely to clash with other functions (like __internal_foo instead of foo).

Function-like procedural macros

Function-like procedural macros are procedural macros that are invoked using the macro invocation operator (!).

These macros are defined by a public function with the proc_macro attribute and a signature of (TokenStream) -> TokenStream. The input TokenStream is what is inside the delimiters of the macro invocation and the output TokenStream replaces the entire macro invocation.

The proc_macro attribute defines the macro in the macro namespace in the root of the crate.

For example, the following macro definition ignores its input and outputs a function answer into its scope.

#![crate_type = "proc-macro"]
extern crate proc_macro;
use proc_macro::TokenStream;

#[proc_macro]
pub fn make_answer(_item: TokenStream) -> TokenStream {
    "fn answer() -> u32 { 42 }".parse().unwrap()
}

And then we use it in a binary crate to print “42” to standard output.

extern crate proc_macro_examples;
use proc_macro_examples::make_answer;

make_answer!();

fn main() {
    println!("{}", answer());
}

Function-like procedural macros may be invoked in any macro invocation position, which includes statements, expressions, patterns, type expressions, item positions, including items in extern blocks, inherent and trait implementations, and trait definitions.

Derive macros

Derive macros define new inputs for the derive attribute. These macros can create new items given the token stream of a struct, enum, or union. They can also define derive macro helper attributes.

Custom derive macros are defined by a public function with the proc_macro_derive attribute and a signature of (TokenStream) -> TokenStream.

The proc_macro_derive attribute defines the custom derive in the macro namespace in the root of the crate.

The input TokenStream is the token stream of the item that has the derive attribute on it. The output TokenStream must be a set of items that are then appended to the module or block that the item from the input TokenStream is in.

The following is an example of a derive macro. Instead of doing anything useful with its input, it just appends a function answer.

#![crate_type = "proc-macro"]
extern crate proc_macro;
use proc_macro::TokenStream;

#[proc_macro_derive(AnswerFn)]
pub fn derive_answer_fn(_item: TokenStream) -> TokenStream {
    "fn answer() -> u32 { 42 }".parse().unwrap()
}

And then using said derive macro:

extern crate proc_macro_examples;
use proc_macro_examples::AnswerFn;

#[derive(AnswerFn)]
struct Struct;

fn main() {
    assert_eq!(42, answer());
}

Derive macro helper attributes

Derive macros can add additional attributes into the scope of the item they are on. Said attributes are called derive macro helper attributes. These attributes are inert, and their only purpose is to be fed into the derive macro that defined them. That said, they can be seen by all macros.

The way to define helper attributes is to put an attributes key in the proc_macro_derive macro with a comma separated list of identifiers that are the names of the helper attributes.

For example, the following derive macro defines a helper attribute helper, but ultimately doesn’t do anything with it.

#![crate_type="proc-macro"]
extern crate proc_macro;
use proc_macro::TokenStream;

#[proc_macro_derive(HelperAttr, attributes(helper))]
pub fn derive_helper_attr(_item: TokenStream) -> TokenStream {
    TokenStream::new()
}

And then usage on the derive macro on a struct:

#[derive(HelperAttr)]
struct Struct {
    #[helper] field: ()
}

Attribute macros

Attribute macros define new outer attributes which can be attached to items, including items in extern blocks, inherent and trait implementations, and trait definitions.

Attribute macros are defined by a public function with the proc_macro_attribute attribute that has a signature of (TokenStream, TokenStream) -> TokenStream. The first TokenStream is the delimited token tree following the attribute’s name, not including the outer delimiters. If the attribute is written as a bare attribute name, the attribute TokenStream is empty. The second TokenStream is the rest of the item including other attributes on the item. The returned TokenStream replaces the item with an arbitrary number of items.

The proc_macro_attribute attribute defines the attribute in the macro namespace in the root of the crate.

For example, this attribute macro takes the input stream and returns it as is, effectively being the no-op of attributes.

#![crate_type = "proc-macro"]
extern crate proc_macro;
use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn return_as_is(_attr: TokenStream, item: TokenStream) -> TokenStream {
    item
}

This following example shows the stringified TokenStreams that the attribute macros see. The output will show in the output of the compiler. The output is shown in the comments after the function prefixed with “out:”.

// my-macro/src/lib.rs
extern crate proc_macro;
use proc_macro::TokenStream;

#[proc_macro_attribute]
pub fn show_streams(attr: TokenStream, item: TokenStream) -> TokenStream {
    println!("attr: \"{attr}\"");
    println!("item: \"{item}\"");
    item
}

// src/lib.rs
extern crate my_macro;

use my_macro::show_streams;

// Example: Basic function
#[show_streams]
fn invoke1() {}
// out: attr: ""
// out: item: "fn invoke1() {}"

// Example: Attribute with input
#[show_streams(bar)]
fn invoke2() {}
// out: attr: "bar"
// out: item: "fn invoke2() {}"

// Example: Multiple tokens in the input
#[show_streams(multiple => tokens)]
fn invoke3() {}
// out: attr: "multiple => tokens"
// out: item: "fn invoke3() {}"

// Example:
#[show_streams { delimiters }]
fn invoke4() {}
// out: attr: "delimiters"
// out: item: "fn invoke4() {}"

Declarative macro tokens and procedural macro tokens

Declarative macro_rules macros and procedural macros use similar, but different definitions for tokens (or rather TokenTrees.)

Token trees in macro_rules (corresponding to tt matchers) are defined as

• Delimited groups ((...), {...}, etc)
• All operators supported by the language, both single-character and multi-character ones (+, +=).
  • Note that this set doesn’t include the single quote '.
• Literals ("string", 1, etc)
  • Note that negation (e.g. -1) is never a part of such literal tokens, but a separate operator token.
• Identifiers, including keywords (ident, r#ident, fn)
• Lifetimes ('ident)
• Metavariable substitutions in macro_rules (e.g. $my_expr in macro_rules! mac { ($my_expr: expr) => { $my_expr } } after the mac’s expansion, which will be considered a single token tree regardless of the passed expression)

Token trees in procedural macros are defined as

• Delimited groups ((...), {...}, etc)
• All punctuation characters used in operators supported by the language (+, but not +=), and also the single quote ' character (typically used in lifetimes, see below for lifetime splitting and joining behavior)
• Literals ("string", 1, etc)
  • Negation (e.g. -1) is supported as a part of integer and floating point literals.
• Identifiers, including keywords (ident, r#ident, fn)

Mismatches between these two definitions are accounted for when token streams are passed to and from procedural macros.
Note that the conversions below may happen lazily, so they might not happen if the tokens are not actually inspected.

When passed to a proc-macro

• All multi-character operators are broken into single characters.
• Lifetimes are broken into a ' character and an identifier.
• All metavariable substitutions are represented as their underlying token streams.
  • Such token streams may be wrapped into delimited groups (Group) with implicit delimiters (Delimiter::None) when it’s necessary for preserving parsing priorities.
  • tt and ident substitutions are never wrapped into such groups and always represented as their underlying token trees.

When emitted from a proc macro

• Punctuation characters are glued into multi-character operators when applicable.
• Single quotes ' joined with identifiers are glued into lifetimes.
• Negative literals are converted into two tokens (the - and the literal) possibly wrapped into a delimited group (Group) with implicit delimiters (Delimiter::None) when it’s necessary for preserving parsing priorities.

Note that neither declarative nor procedural macros support doc comment tokens (e.g. /// Doc), so they are always converted to token streams representing their equivalent #[doc = r"str"] attributes when passed to macros.

Crates and source files

^Syntax
Crate :
   InnerAttribute^*
   Item^*

Note: Although Rust, like any other language, can be implemented by an interpreter as well as a compiler, the only existing implementation is a compiler, and the language has always been designed to be compiled. For these reasons, this section assumes a compiler.

Rust’s semantics obey a phase distinction between compile-time and run-time.¹ Semantic rules that have a static interpretation govern the success or failure of compilation, while semantic rules that have a dynamic interpretation govern the behavior of the program at run-time.

The compilation model centers on artifacts called crates. Each compilation processes a single crate in source form, and if successful, produces a single crate in binary form: either an executable or some sort of library.²

A crate is a unit of compilation and linking, as well as versioning, distribution, and runtime loading. A crate contains a tree of nested module scopes. The top level of this tree is a module that is anonymous (from the point of view of paths within the module) and any item within a crate has a canonical module path denoting its location within the crate’s module tree.

The Rust compiler is always invoked with a single source file as input, and always produces a single output crate. The processing of that source file may result in other source files being loaded as modules. Source files have the extension .rs.

A Rust source file describes a module, the name and location of which — in the module tree of the current crate — are defined from outside the source file: either by an explicit Module item in a referencing source file, or by the name of the crate itself.

Every source file is a module, but not every module needs its own source file: module definitions can be nested within one file.

Each source file contains a sequence of zero or more Item definitions, and may optionally begin with any number of attributes that apply to the containing module, most of which influence the behavior of the compiler.

The anonymous crate module can have additional attributes that apply to the crate as a whole.

Note: The file’s contents may be preceded by a shebang.

#![allow(unused)]
fn main() {
// Specify the crate name.
#![crate_name = "projx"]

// Specify the type of output artifact.
#![crate_type = "lib"]

// Turn on a warning.
// This can be done in any module, not just the anonymous crate module.
#![warn(non_camel_case_types)]
}

Main Functions

A crate that contains a main function can be compiled to an executable.

If a main function is present, it must take no arguments, must not declare any trait or lifetime bounds, must not have any where clauses, and its return type must implement the Termination trait.

fn main() {}

fn main() -> ! {
    std::process::exit(0);
}

fn main() -> impl std::process::Termination {
    std::process::ExitCode::SUCCESS
}

The main function may be an import, e.g. from an external crate or from the current one.

#![allow(unused)]
fn main() {
mod foo {
    pub fn bar() {
        println!("Hello, world!");
    }
}
use foo::bar as main;
}

Note: Types with implementations of Termination in the standard library include:

• ()
• !
• Infallible
• ExitCode
• Result<T, E> where T: Termination, E: Debug

The no_main attribute

The no_main attribute may be applied at the crate level to disable emitting the main symbol for an executable binary. This is useful when some other object being linked to defines main.

The crate_name attribute

The crate_name attribute may be applied at the crate level to specify the name of the crate with the MetaNameValueStr syntax.

#![allow(unused)]
#![crate_name = "mycrate"]
fn main() {
}

The crate name must not be empty, and must only contain Unicode alphanumeric or _ (U+005F) characters.

Conditional compilation

^Syntax
ConfigurationPredicate :
      ConfigurationOption
   | ConfigurationAll
   | ConfigurationAny
   | ConfigurationNot

ConfigurationOption :
   IDENTIFIER (= (STRING_LITERAL | RAW_STRING_LITERAL))^?

ConfigurationAll
   all ( ConfigurationPredicateList^? )

ConfigurationAny
   any ( ConfigurationPredicateList^? )

ConfigurationNot
   not ( ConfigurationPredicate )

ConfigurationPredicateList
   ConfigurationPredicate (, ConfigurationPredicate)^* ,^?

Conditionally compiled source code is source code that is compiled only under certain conditions.

Source code can be made conditionally compiled using the cfg and cfg_attr attributes and the built-in cfg macro.

Whether to compile can depend on the target architecture of the compiled crate, arbitrary values passed to the compiler, and other things further described below.

Each form of conditional compilation takes a configuration predicate that evaluates to true or false. The predicate is one of the following:

• A configuration option. The predicate is true if the option is set, and false if it is unset.

• all() with a comma-separated list of configuration predicates. It is true if all of the given predicates are true, or if the list is empty.

• any() with a comma-separated list of configuration predicates. It is true if at least one of the given predicates is true. If there are no predicates, it is false.

• not() with a configuration predicate. It is true if its predicate is false and false if its predicate is true.

Configuration options are either names or key-value pairs, and are either set or unset.

Names are written as a single identifier, such as unix.

Key-value pairs are written as an identifier, =, and then a string, such as target_arch = "x86_64".

Note: Whitespace around the = is ignored, so foo="bar" and foo = "bar" are equivalent.

Keys do not need to be unique. For example, both feature = "std" and feature = "serde" can be set at the same time.

Set Configuration Options

Which configuration options are set is determined statically during the compilation of the crate.

Some options are compiler-set based on data about the compilation.

Other options are arbitrarily-set based on input passed to the compiler outside of the code.

It is not possible to set a configuration option from within the source code of the crate being compiled.

Note: For rustc, arbitrary-set configuration options are set using the --cfg flag. Configuration values for a specified target can be displayed with rustc --print cfg --target $TARGET.

Note: Configuration options with the key feature are a convention used by Cargo for specifying compile-time options and optional dependencies.

target_arch

Key-value option set once with the target’s CPU architecture. The value is similar to the first element of the platform’s target triple, but not identical.

Example values:

• "x86"
• "x86_64"
• "mips"
• "powerpc"
• "powerpc64"
• "arm"
• "aarch64"

target_feature

Key-value option set for each platform feature available for the current compilation target.

Example values:

• "avx"
• "avx2"
• "crt-static"
• "rdrand"
• "sse"
• "sse2"
• "sse4.1"

See the target_feature attribute for more details on the available features.

An additional feature of crt-static is available to the target_feature option to indicate that a static C runtime is available.

target_os

Key-value option set once with the target’s operating system. This value is similar to the second and third element of the platform’s target triple.

Example values:

• "windows"
• "macos"
• "ios"
• "linux"
• "android"
• "freebsd"
• "dragonfly"
• "openbsd"
• "netbsd"
• "none" (typical for embedded targets)

target_family

Key-value option providing a more generic description of a target, such as the family of the operating systems or architectures that the target generally falls into. Any number of target_family key-value pairs can be set.

Example values:

• "unix"
• "windows"
• "wasm"
• Both "unix" and "wasm"

unix and windows

unix is set if target_family = "unix" is set.

windows is set if target_family = "windows" is set.

target_env

Key-value option set with further disambiguating information about the target platform with information about the ABI or libc used. For historical reasons, this value is only defined as not the empty-string when actually needed for disambiguation. Thus, for example, on many GNU platforms, this value will be empty. This value is similar to the fourth element of the platform’s target triple. One difference is that embedded ABIs such as gnueabihf will simply define target_env as "gnu".

Example values:

• ""
• "gnu"
• "msvc"
• "musl"
• "sgx"

target_abi

Key-value option set to further disambiguate the target_env with information about the target ABI.

For historical reasons, this value is only defined as not the empty-string when actually needed for disambiguation. Thus, for example, on many GNU platforms, this value will be empty.

Example values:

• ""
• "llvm"
• "eabihf"
• "abi64"
• "sim"
• "macabi"

target_endian

Key-value option set once with either a value of “little” or “big” depending on the endianness of the target’s CPU.

target_pointer_width

Key-value option set once with the target’s pointer width in bits.

Example values:

• "16"
• "32"
• "64"

target_vendor

Key-value option set once with the vendor of the target.

Example values:

• "apple"
• "fortanix"
• "pc"
• "unknown"

target_has_atomic

Key-value option set for each bit width that the target supports atomic loads, stores, and compare-and-swap operations.

When this cfg is present, all of the stable core::sync::atomic APIs are available for the relevant atomic width.

Possible values:

• "8"
• "16"
• "32"
• "64"
• "128"
• "ptr"

test

Enabled when compiling the test harness. Done with rustc by using the --test flag. See Testing for more on testing support.

debug_assertions

Enabled by default when compiling without optimizations. This can be used to enable extra debugging code in development but not in production. For example, it controls the behavior of the standard library’s debug_assert! macro.

proc_macro

Set when the crate being compiled is being compiled with the proc_macro crate type.

panic

Key-value option set depending on the panic strategy. Note that more values may be added in the future.

Example values:

• "abort"
• "unwind"

Forms of conditional compilation

The cfg attribute

^Syntax
CfgAttrAttribute :
   cfg ( ConfigurationPredicate )

The cfg attribute conditionally includes the thing it is attached to based on a configuration predicate.

It is written as cfg, (, a configuration predicate, and finally ).

If the predicate is true, the thing is rewritten to not have the cfg attribute on it. If the predicate is false, the thing is removed from the source code.

When a crate-level cfg has a false predicate, the behavior is slightly different: any crate attributes preceding the cfg are kept, and any crate attributes following the cfg are removed. This allows #![no_std] and #![no_core] crates to avoid linking std/core even if a #![cfg(...)] has removed the entire crate.

Some examples on functions:

#![allow(unused)]
fn main() {
// The function is only included in the build when compiling for macOS
#[cfg(target_os = "macos")]
fn macos_only() {
  // ...
}

// This function is only included when either foo or bar is defined
#[cfg(any(foo, bar))]
fn needs_foo_or_bar() {
  // ...
}

// This function is only included when compiling for a unixish OS with a 32-bit
// architecture
#[cfg(all(unix, target_pointer_width = "32"))]
fn on_32bit_unix() {
  // ...
}

// This function is only included when foo is not defined
#[cfg(not(foo))]
fn needs_not_foo() {
  // ...
}

// This function is only included when the panic strategy is set to unwind
#[cfg(panic = "unwind")]
fn when_unwinding() {
  // ...
}

}

The cfg attribute is allowed anywhere attributes are allowed.

The cfg_attr attribute

^Syntax
CfgAttrAttribute :
   cfg_attr ( ConfigurationPredicate , CfgAttrs^? )

CfgAttrs :
   Attr (, Attr)^* ,^?

The cfg_attr attribute conditionally includes attributes based on a configuration predicate.

When the configuration predicate is true, this attribute expands out to the attributes listed after the predicate. For example, the following module will either be found at linux.rs or windows.rs based on the target.

#[cfg_attr(target_os = "linux", path = "linux.rs")]
#[cfg_attr(windows, path = "windows.rs")]
mod os;

Zero, one, or more attributes may be listed. Multiple attributes will each be expanded into separate attributes. For example:

#[cfg_attr(feature = "magic", sparkles, crackles)]
fn bewitched() {}

// When the `magic` feature flag is enabled, the above will expand to:
#[sparkles]
#[crackles]
fn bewitched() {}

Note: The cfg_attr can expand to another cfg_attr. For example, #[cfg_attr(target_os = "linux", cfg_attr(feature = "multithreaded", some_other_attribute))] is valid. This example would be equivalent to #[cfg_attr(all(target_os = "linux", feature ="multithreaded"), some_other_attribute)].

The cfg_attr attribute is allowed anywhere attributes are allowed.

The crate_type and crate_name attributes cannot be used with cfg_attr.

The cfg macro

The built-in cfg macro takes in a single configuration predicate and evaluates to the true literal when the predicate is true and the false literal when it is false.

For example:

#![allow(unused)]
fn main() {
let machine_kind = if cfg!(unix) {
  "unix"
} else if cfg!(windows) {
  "windows"
} else {
  "unknown"
};

println!("I'm running on a {} machine!", machine_kind);
}

Items

^Syntax:
Item:
   OuterAttribute^*
      VisItem
   | MacroItem

VisItem:
   Visibility^?
   (
         Module
      | ExternCrate
      | UseDeclaration
      | Function
      | TypeAlias
      | Struct
      | Enumeration
      | Union
      | ConstantItem
      | StaticItem
      | Trait
      | Implementation
      | ExternBlock
   )

MacroItem:
      MacroInvocationSemi
   | MacroRulesDefinition

An item is a component of a crate. Items are organized within a crate by a nested set of modules. Every crate has a single “outermost” anonymous module; all further items within the crate have paths within the module tree of the crate.

Items are entirely determined at compile-time, generally remain fixed during execution, and may reside in read-only memory.

There are several kinds of items:

• modules
• extern crate declarations
• use declarations
• function definitions
• type definitions
• struct definitions
• enumeration definitions
• union definitions
• constant items
• static items
• trait definitions
• implementations
• extern blocks

Items may be declared in the root of the crate, a module, or a block expression.

A subset of items, called associated items, may be declared in traits and implementations.

A subset of items, called external items, may be declared in extern blocks.

Items may be defined in any order, with the exception of macro_rules which has its own scoping behavior.

Name resolution of item names allows items to be defined before or after where the item is referred to in the module or block.

See item scopes for information on the scoping rules of items.

Modules

^Syntax:
Module :
      unsafe^? mod IDENTIFIER ;
   | unsafe^? mod IDENTIFIER {
        InnerAttribute^*
        Item^*
      }

A module is a container for zero or more items.

A module item is a module, surrounded in braces, named, and prefixed with the keyword mod. A module item introduces a new, named module into the tree of modules making up a crate\1

Modules can nest arbitrarily.

An example of a module:

#![allow(unused)]
fn main() {
mod math {
    type Complex = (f64, f64);
    fn sin(f: f64) -> f64 {
        /* ... */
      unimplemented!();
    }
    fn cos(f: f64) -> f64 {
        /* ... */
      unimplemented!();
    }
    fn tan(f: f64) -> f64 {
        /* ... */
      unimplemented!();
    }
}
}

Modules are defined in the type namespace of the module or block where they are located.

It is an error to define multiple items with the same name in the same namespace within a module. See the scopes chapter for more details on restrictions and shadowing behavior.

The unsafe keyword is syntactically allowed to appear before the mod keyword, but it is rejected at a semantic level. This allows macros to consume the syntax and make use of the unsafe keyword, before removing it from the token stream.

Module Source Filenames

A module without a body is loaded from an external file. When the module does not have a path attribute, the path to the file mirrors the logical module path.

Ancestor module path components are directories, and the module’s contents are in a file with the name of the module plus the .rs extension. For example, the following module structure can have this corresponding filesystem structure:

Module filenames may also be the name of the module as a directory with the contents in a file named mod.rs within that directory. The above example can alternately be expressed with crate::util’s contents in a file named util/mod.rs. It is not allowed to have both util.rs and util/mod.rs.

Note: Prior to rustc 1.30, using mod.rs files was the way to load a module with nested children. It is encouraged to use the new naming convention as it is more consistent, and avoids having many files named mod.rs within a project.

The path attribute

The directories and files used for loading external file modules can be influenced with the path attribute.

For path attributes on modules not inside inline module blocks, the file path is relative to the directory the source file is located. For example, the following code snippet would use the paths shown based on where it is located:

#[path = "foo.rs"]
mod c;

For path attributes inside inline module blocks, the relative location of the file path depends on the kind of source file the path attribute is located in. “mod-rs” source files are root modules (such as lib.rs or main.rs) and modules with files named mod.rs. “non-mod-rs” source files are all other module files. Paths for path attributes inside inline module blocks in a mod-rs file are relative to the directory of the mod-rs file including the inline module components as directories. For non-mod-rs files, it is the same except the path starts with a directory with the name of the non-mod-rs module. For example, the following code snippet would use the paths shown based on where it is located:

mod inline {
    #[path = "other.rs"]
    mod inner;
}

An example of combining the above rules of path attributes on inline modules and nested modules within (applies to both mod-rs and non-mod-rs files):

#[path = "thread_files"]
mod thread {
    // Load the `local_data` module from `thread_files/tls.rs` relative to
    // this source file's directory.
    #[path = "tls.rs"]
    mod local_data;
}

Attributes on Modules

Modules, like all items, accept outer attributes. They also accept inner attributes: either after { for a module with a body, or at the beginning of the source file, after the optional BOM and shebang.

The built-in attributes that have meaning on a module are cfg, deprecated, doc, the lint check attributes, path, and no_implicit_prelude. Modules also accept macro attributes.

Extern crate declarations

^Syntax:
ExternCrate :
   extern crate CrateRef AsClause^? ;

CrateRef :
   IDENTIFIER | self

AsClause :
   as ( IDENTIFIER | _ )

An extern crate declaration specifies a dependency on an external crate.

The external crate is then bound into the declaring scope as the given identifier in the type namespace.

Additionally, if the extern crate appears in the crate root, then the crate name is also added to the extern prelude, making it automatically in scope in all modules.

The as clause can be used to bind the imported crate to a different name.

The external crate is resolved to a specific soname at compile time, and a runtime linkage requirement to that soname is passed to the linker for loading at runtime. The soname is resolved at compile time by scanning the compiler’s library path and matching the optional crate_name provided against the crate_name attributes that were declared on the external crate when it was compiled. If no crate_name is provided, a default name attribute is assumed, equal to the identifier given in the extern crate declaration.

The self crate may be imported which creates a binding to the current crate. In this case the as clause must be used to specify the name to bind it to.

Three examples of extern crate declarations:

extern crate pcre;

extern crate std; // equivalent to: extern crate std as std;

extern crate std as ruststd; // linking to 'std' under another name

When naming Rust crates, hyphens are disallowed. However, Cargo packages may make use of them. In such case, when Cargo.toml doesn’t specify a crate name, Cargo will transparently replace - with _ (Refer to RFC 940 for more details).

Here is an example:

// Importing the Cargo package hello-world
extern crate hello_world; // hyphen replaced with an underscore

Underscore Imports

An external crate dependency can be declared without binding its name in scope by using an underscore with the form extern crate foo as _. This may be useful for crates that only need to be linked, but are never referenced, and will avoid being reported as unused.

The macro_use attribute works as usual and imports the macro names into the macro_use prelude.

The no_link attribute

The no_link attribute may be specified on an extern crate item to prevent linking the crate into the output. This is commonly used to load a crate to access only its macros.

Use declarations

^Syntax:
UseDeclaration :
   use UseTree ;

UseTree :
      (SimplePath^? ::)^? *
   | (SimplePath^? ::)^? { (UseTree ( , UseTree )^* ,^?)^? }
   | SimplePath ( as ( IDENTIFIER | _ ) )^?

A use declaration creates one or more local name bindings synonymous with some other path. Usually a use declaration is used to shorten the path required to refer to a module item. These declarations may appear in modules and blocks, usually at the top. A use declaration is also sometimes called an import, or, if it is public, a re-export.

Use declarations support a number of convenient shortcuts:

• Simultaneously binding a list of paths with a common prefix, using the brace syntax use a::b::{c, d, e::f, g::h::i};

• Simultaneously binding a list of paths with a common prefix and their common parent module, using the self keyword, such as use a::b::{self, c, d::e};

• Rebinding the target name as a new local name, using the syntax use p::q::r as x;. This can also be used with the last two features: use a::b::{self as ab, c as abc}.

• Binding all paths matching a given prefix, using the asterisk wildcard syntax use a::b::*;.

• Nesting groups of the previous features multiple times, such as use a::b::{self as ab, c, d::{*, e::f}};

An example of use declarations:

use std::collections::hash_map::{self, HashMap};

fn foo<T>(_: T){}
fn bar(map1: HashMap<String, usize>, map2: hash_map::HashMap<String, usize>){}

fn main() {
    // use declarations can also exist inside of functions
    use std::option::Option::{Some, None};

    // Equivalent to 'foo(vec![std::option::Option::Some(1.0f64),
    // std::option::Option::None]);'
    foo(vec![Some(1.0f64), None]);

    // Both `hash_map` and `HashMap` are in scope.
    let map1 = HashMap::new();
    let map2 = hash_map::HashMap::new();
    bar(map1, map2);
}

use Visibility

Like items, use declarations are private to the containing module, by default. Also like items, a use declaration can be public, if qualified by the pub keyword. Such a use declaration serves to re-export a name. A public use declaration can therefore redirect some public name to a different target definition: even a definition with a private canonical path, inside a different module.

If a sequence of such redirections form a cycle or cannot be resolved unambiguously, they represent a compile-time error.

An example of re-exporting:

mod quux {
    pub use self::foo::{bar, baz};
    pub mod foo {
        pub fn bar() {}
        pub fn baz() {}
    }
}

fn main() {
    quux::bar();
    quux::baz();
}

In this example, the module quux re-exports two public names defined in foo.

use Paths

The paths that are allowed in a use item follow the SimplePath grammar and are similar to the paths that may be used in an expression. They may create bindings for:

• Nameable items
• Enum variants
• Built-in types
• Attributes
• Derive macros

They cannot import associated items, generic parameters, local variables, paths with Self, or tool attributes. More restrictions are described below.

use will create bindings for all namespaces from the imported entities, with the exception that a self import will only import from the type namespace (as described below). For example, the following illustrates creating bindings for the same name in two namespaces:

#![allow(unused)]
fn main() {
mod stuff {
    pub struct Foo(pub i32);
}

// Imports the `Foo` type and the `Foo` constructor.
use stuff::Foo;

fn example() {
    let ctor = Foo; // Uses `Foo` from the value namespace.
    let x: Foo = ctor(123); // Uses `Foo` From the type namespace.
}
}

Edition differences: In the 2015 edition, use paths are relative to the crate root. For example:

mod foo {
    pub mod example { pub mod iter {} }
    pub mod baz { pub fn foobaz() {} }
}
mod bar {
    // Resolves `foo` from the crate root.
    use foo::example::iter;
    // The `::` prefix explicitly resolves `foo`
    // from the crate root.
    use ::foo::baz::foobaz;
}

fn main() {}

The 2015 edition does not allow use declarations to reference the extern prelude. Thus, extern crate declarations are still required in 2015 to reference an external crate in a use declaration. Beginning with the 2018 edition, use declarations can specify an external crate dependency the same way extern crate can.

as renames

The as keyword can be used to change the name of an imported entity. For example:

#![allow(unused)]
fn main() {
// Creates a non-public alias `bar` for the function `foo`.
use inner::foo as bar;

mod inner {
    pub fn foo() {}
}
}

Brace syntax

Braces can be used in the last segment of the path to import multiple entities from the previous segment, or, if there are no previous segments, from the current scope. Braces can be nested, creating a tree of paths, where each grouping of segments is logically combined with its parent to create a full path.

#![allow(unused)]
fn main() {
// Creates bindings to:
// - `std::collections::BTreeSet`
// - `std::collections::hash_map`
// - `std::collections::hash_map::HashMap`
use std::collections::{BTreeSet, hash_map::{self, HashMap}};
}

An empty brace does not import anything, though the leading path is validated that it is accessible.

Edition differences: In the 2015 edition, paths are relative to the crate root, so an import such as use {foo, bar}; will import the names foo and bar from the crate root, whereas starting in 2018, those names are relative to the current scope.

self imports

The keyword self may be used within brace syntax to create a binding of the parent entity under its own name.

mod stuff {
    pub fn foo() {}
    pub fn bar() {}
}
mod example {
    // Creates a binding for `stuff` and `foo`.
    use crate::stuff::{self, foo};
    pub fn baz() {
        foo();
        stuff::bar();
    }
}
fn main() {}

self only creates a binding from the type namespace of the parent entity. For example, in the following, only the foo mod is imported:

mod bar {
    pub mod foo {}
    pub fn foo() {}
}

// This only imports the module `foo`. The function `foo` lives in
// the value namespace and is not imported.
use bar::foo::{self};

fn main() {
    foo(); //~ ERROR `foo` is a module
}

Note: self may also be used as the first segment of a path. The usage of self as the first segment and inside a use brace is logically the same; it means the current module of the parent segment, or the current module if there is no parent segment. See self in the paths chapter for more information on the meaning of a leading self.

Glob imports

The * character may be used as the last segment of a use path to import all importable entities from the entity of the preceding segment. For example:

#![allow(unused)]
fn main() {
// Creates a non-public alias to `bar`.
use foo::*;

mod foo {
    fn i_am_private() {}
    enum Example {
        V1,
        V2,
    }
    pub fn bar() {
        // Creates local aliases to `V1` and `V2`
        // of the `Example` enum.
        use Example::*;
        let x = V1;
    }
}
}

Items and named imports are allowed to shadow names from glob imports in the same namespace. That is, if there is a name already defined by another item in the same namespace, the glob import will be shadowed. For example:

#![allow(unused)]
fn main() {
// This creates a binding to the `clashing::Foo` tuple struct
// constructor, but does not import its type because that would
// conflict with the `Foo` struct defined here.
//
// Note that the order of definition here is unimportant.
use clashing::*;
struct Foo {
    field: f32,
}

fn do_stuff() {
    // Uses the constructor from `clashing::Foo`.
    let f1 = Foo(123);
    // The struct expression uses the type from
    // the `Foo` struct defined above.
    let f2 = Foo { field: 1.0 };
    // `Bar` is also in scope due to the glob import.
    let z = Bar {};
}

mod clashing {
    pub struct Foo(pub i32);
    pub struct Bar {}
}
}

* cannot be used as the first or intermediate segments.

* cannot be used to import a module’s contents into itself (such as use self::*;).

Edition differences: In the 2015 edition, paths are relative to the crate root, so an import such as use *; is valid, and it means to import everything from the crate root. This cannot be used in the crate root itself.

Underscore Imports

Items can be imported without binding to a name by using an underscore with the form use path as _. This is particularly useful to import a trait so that its methods may be used without importing the trait’s symbol, for example if the trait’s symbol may conflict with another symbol. Another example is to link an external crate without importing its name.

Asterisk glob imports will import items imported with _ in their unnameable form.

mod foo {
    pub trait Zoo {
        fn zoo(&self) {}
    }

    impl<T> Zoo for T {}
}

use self::foo::Zoo as _;
struct Zoo;  // Underscore import avoids name conflict with this item.

fn main() {
    let z = Zoo;
    z.zoo();
}

The unique, unnameable symbols are created after macro expansion so that macros may safely emit multiple references to _ imports. For example, the following should not produce an error:

#![allow(unused)]
fn main() {
macro_rules! m {
    ($item: item) => { $item $item }
}

m!(use std as _;);
// This expands to:
// use std as _;
// use std as _;
}

Restrictions

The following are restrictions for valid use declarations:

• use crate; must use as to define the name to which to bind the crate root.

• use {self}; is an error; there must be a leading segment when using self.

• As with any item definition, use imports cannot create duplicate bindings of the same name in the same namespace in a module or block.

• use paths with $crate are not allowed in a macro_rules expansion.

• use paths cannot refer to enum variants through a type alias. For example:

  #![allow(unused)]
  fn main() {
  enum MyEnum {
      MyVariant
  }
  type TypeAlias = MyEnum;
  
  use MyEnum::MyVariant; //~ OK
  use TypeAlias::MyVariant; //~ ERROR
  }

Ambiguities

Note: This section is incomplete.

Some situations are an error when there is an ambiguity as to which name a use declaration refers. This happens when there are two name candidates that do not resolve to the same entity.

Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used. For example:

mod foo {
    pub struct Qux;
}

mod bar {
    pub struct Qux;
}

use foo::*;
use bar::*; //~ OK, no name conflict.

fn main() {
    // This would be an error, due to the ambiguity.
    //let x = Qux;
}

Multiple glob imports are allowed to import the same name, and that name is allowed to be used, if the imports are of the same item (following re-exports). The visibility of the name is the maximum visibility of the imports. For example:

mod foo {
    pub struct Qux;
}

mod bar {
    pub use super::foo::Qux;
}

// These both import the same `Qux`. The visibility of `Qux`
// is `pub` because that is the maximum visibility between
// these two `use` declarations.
pub use bar::*;
use foo::*;

fn main() {
    let _: Qux = Qux;
}

Functions

^Syntax
Function :
   FunctionQualifiers fn IDENTIFIER GenericParams^?
      ( FunctionParameters^? )
      FunctionReturnType^? WhereClause^?
      ( BlockExpression | ; )

FunctionQualifiers :
   const^? async^1? ItemSafety^? (extern Abi^?)^?

ItemSafety :
   safe² | unsafe

Abi :
   STRING_LITERAL | RAW_STRING_LITERAL

FunctionParameters :
      SelfParam ,^?
   | (SelfParam ,)^? FunctionParam (, FunctionParam)^* ,^?

SelfParam :
   OuterAttribute^* ( ShorthandSelf | TypedSelf )

ShorthandSelf :
   (& | & Lifetime)^? mut^? self

TypedSelf :
   mut^? self : Type

FunctionParam :
   OuterAttribute^* ( FunctionParamPattern | ... | Type ³ )

FunctionParamPattern :
   PatternNoTopAlt : ( Type | ... )

FunctionReturnType :
   -> Type

¹

The async qualifier is not allowed in the 2015 edition.

²

The safe function qualifier is only allowed semantically within extern blocks.

³

Function parameters with only a type are only allowed in an associated function of a trait item in the 2015 edition.

A function consists of a block (that’s the body of the function), along with a name, a set of parameters, and an output type. Other than a name, all these are optional.

Functions are declared with the keyword fn which defines the given name in the value namespace of the module or block where it is located.

Functions may declare a set of input variables as parameters, through which the caller passes arguments into the function, and the output type of the value the function will return to its caller on completion.

If the output type is not explicitly stated, it is the unit type.

When referred to, a function yields a first-class value of the corresponding zero-sized function item type, which when called evaluates to a direct call to the function.

For example, this is a simple function:

#![allow(unused)]
fn main() {
fn answer_to_life_the_universe_and_everything() -> i32 {
    return 42;
}
}

The safe function is semantically only allowed when used in an extern block.

Function parameters

Function parameters are irrefutable patterns, so any pattern that is valid in an else-less let binding is also valid as a parameter:

#![allow(unused)]
fn main() {
fn first((value, _): (i32, i32)) -> i32 { value }
}

If the first parameter is a SelfParam, this indicates that the function is a method.

Functions with a self parameter may only appear as an associated function in a trait or implementation.

A parameter with the ... token indicates a variadic function, and may only be used as the last parameter of an external block function. The variadic parameter may have an optional identifier, such as args: ....

Function body

The body block of a function is conceptually wrapped in another block that first binds the argument patterns and then returns the value of the function’s body. This means that the tail expression of the block, if evaluated, ends up being returned to the caller. As usual, an explicit return expression within the body of the function will short-cut that implicit return, if reached.

For example, the function above behaves as if it was written as:

// argument_0 is the actual first argument passed from the caller
let (value, _) = argument_0;
return {
    value
};

Functions without a body block are terminated with a semicolon. This form may only appear in a trait or external block.

Generic functions

A generic function allows one or more parameterized types to appear in its signature. Each type parameter must be explicitly declared in an angle-bracket-enclosed and comma-separated list, following the function name.

#![allow(unused)]
fn main() {
// foo is generic over A and B

fn foo<A, B>(x: A, y: B) {
}
}

Inside the function signature and body, the name of the type parameter can be used as a type name.

Trait bounds can be specified for type parameters to allow methods with that trait to be called on values of that type. This is specified using the where syntax:

#![allow(unused)]
fn main() {
use std::fmt::Debug;
fn foo<T>(x: T) where T: Debug {
}
}

When a generic function is referenced, its type is instantiated based on the context of the reference. For example, calling the foo function here:

#![allow(unused)]
fn main() {
use std::fmt::Debug;

fn foo<T>(x: &[T]) where T: Debug {
    // details elided
}

foo(&[1, 2]);
}

will instantiate type parameter T with i32.

The type parameters can also be explicitly supplied in a trailing path component after the function name. This might be necessary if there is not sufficient context to determine the type parameters. For example, mem::size_of::<u32>() == 4.

Extern function qualifier

The extern function qualifier allows providing function definitions that can be called with a particular ABI:

extern "ABI" fn foo() { /* ... */ }

These are often used in combination with external block items which provide function declarations that can be used to call functions without providing their definition:

unsafe extern "ABI" {
  unsafe fn foo(); /* no body */
  safe fn bar(); /* no body */
}
unsafe { foo() };
bar();

When "extern" Abi?* is omitted from FunctionQualifiers in function items, the ABI "Rust" is assigned. For example:

#![allow(unused)]
fn main() {
fn foo() {}
}

is equivalent to:

#![allow(unused)]
fn main() {
extern "Rust" fn foo() {}
}

Functions can be called by foreign code, and using an ABI that differs from Rust allows, for example, to provide functions that can be called from other programming languages like C:

#![allow(unused)]
fn main() {
// Declares a function with the "C" ABI
extern "C" fn new_i32() -> i32 { 0 }

// Declares a function with the "stdcall" ABI
#[cfg(any(windows, target_arch = "x86"))]
extern "stdcall" fn new_i32_stdcall() -> i32 { 0 }
}

Just as with external block, when the extern keyword is used and the "ABI" is omitted, the ABI used defaults to "C". That is, this:

#![allow(unused)]
fn main() {
extern fn new_i32() -> i32 { 0 }
let fptr: extern fn() -> i32 = new_i32;
}

is equivalent to:

#![allow(unused)]
fn main() {
extern "C" fn new_i32() -> i32 { 0 }
let fptr: extern "C" fn() -> i32 = new_i32;
}

Functions with an ABI that differs from "Rust" do not support unwinding in the exact same way that Rust does. Therefore, unwinding past the end of functions with such ABIs causes the process to abort.

Note: The LLVM backend of the rustc implementation aborts the process by executing an illegal instruction.

Const functions

Functions qualified with the const keyword are const functions, as are tuple struct and tuple variant constructors. Const functions can be called from within const contexts.

Const functions may use the extern function qualifier.

Const functions are not allowed to be async.

Async functions

Functions may be qualified as async, and this can also be combined with the unsafe qualifier:

#![allow(unused)]
fn main() {
async fn regular_example() { }
async unsafe fn unsafe_example() { }
}

Async functions do no work when called: instead, they capture their arguments into a future. When polled, that future will execute the function’s body.

An async function is roughly equivalent to a function that returns impl Future and with an async move block as its body:

#![allow(unused)]
fn main() {
// Source
async fn example(x: &str) -> usize {
    x.len()
}
}

is roughly equivalent to:

#![allow(unused)]
fn main() {
use std::future::Future;
// Desugared
fn example<'a>(x: &'a str) -> impl Future<Output = usize> + 'a {
    async move { x.len() }
}
}

The actual desugaring is more complex:

• The return type in the desugaring is assumed to capture all lifetime parameters from the async fn declaration. This can be seen in the desugared example above, which explicitly outlives, and hence captures, 'a.

• The async move block in the body captures all function parameters, including those that are unused or bound to a _ pattern. This ensures that function parameters are dropped in the same order as they would be if the function were not async, except that the drop occurs when the returned future has been fully awaited.

For more information on the effect of async, see async blocks.

Edition differences: Async functions are only available beginning with Rust 2018.

Combining async and unsafe

It is legal to declare a function that is both async and unsafe. The resulting function is unsafe to call and (like any async function) returns a future. This future is just an ordinary future and thus an unsafe context is not required to “await” it:

#![allow(unused)]
fn main() {
// Returns a future that, when awaited, dereferences `x`.
//
// Soundness condition: `x` must be safe to dereference until
// the resulting future is complete.
async unsafe fn unsafe_example(x: *const i32) -> i32 {
  *x
}

async fn safe_example() {
    // An `unsafe` block is required to invoke the function initially:
    let p = 22;
    let future = unsafe { unsafe_example(&p) };

    // But no `unsafe` block required here. This will
    // read the value of `p`:
    let q = future.await;
}
}

Note that this behavior is a consequence of the desugaring to a function that returns an impl Future – in this case, the function we desugar to is an unsafe function, but the return value remains the same.

Unsafe is used on an async function in precisely the same way that it is used on other functions: it indicates that the function imposes some additional obligations on its caller to ensure soundness. As in any other unsafe function, these conditions may extend beyond the initial call itself – in the snippet above, for example, the unsafe_example function took a pointer x as argument, and then (when awaited) dereferenced that pointer. This implies that x would have to be valid until the future is finished executing, and it is the caller’s responsibility to ensure that.

Attributes on functions

Outer attributes are allowed on functions. Inner attributes are allowed directly after the { inside its body block.

This example shows an inner attribute on a function. The function is documented with just the word “Example”.

#![allow(unused)]
fn main() {
fn documented() {
    #![doc = "Example"]
}
}

Note: Except for lints, it is idiomatic to only use outer attributes on function items.

The attributes that have meaning on a function are cfg, cfg_attr, deprecated, doc, export_name, link_section, no_mangle, the lint check attributes, must_use, the procedural macro attributes, the testing attributes, and the optimization hint attributes. Functions also accept attributes macros.

Attributes on function parameters

Outer attributes are allowed on function parameters and the permitted built-in attributes are restricted to cfg, cfg_attr, allow, warn, deny, and forbid.

#![allow(unused)]
fn main() {
fn len(
    #[cfg(windows)] slice: &[u16],
    #[cfg(not(windows))] slice: &[u8],
) -> usize {
    slice.len()
}
}

Inert helper attributes used by procedural macro attributes applied to items are also allowed but be careful to not include these inert attributes in your final TokenStream.

For example, the following code defines an inert some_inert_attribute attribute that is not formally defined anywhere and the some_proc_macro_attribute procedural macro is responsible for detecting its presence and removing it from the output token stream.

#[some_proc_macro_attribute]
fn foo_oof(#[some_inert_attribute] arg: u8) {
}

Type aliases

^Syntax
TypeAlias :
   type IDENTIFIER GenericParams^? ( : TypeParamBounds )^? WhereClause^? ( = Type WhereClause^?)^? ;

A type alias defines a new name for an existing type in the type namespace of the module or block where it is located. Type aliases are declared with the keyword type. Every value has a single, specific type, but may implement several different traits, and may be compatible with several different type constraints.

For example, the following defines the type Point as a synonym for the type (u8, u8), the type of pairs of unsigned 8 bit integers:

#![allow(unused)]
fn main() {
type Point = (u8, u8);
let p: Point = (41, 68);
}

A type alias to a tuple-struct or unit-struct cannot be used to qualify that type’s constructor:

#![allow(unused)]
fn main() {
struct MyStruct(u32);

use MyStruct as UseAlias;
type TypeAlias = MyStruct;

let _ = UseAlias(5); // OK
let _ = TypeAlias(5); // Doesn't work
}

A type alias, when not used as an associated type, must include a Type and may not include TypeParamBounds.

A type alias, when used as an associated type in a trait, must not include a Type specification but may include TypeParamBounds.

A type alias, when used as an associated type in a trait impl, must include a Type specification and may not include TypeParamBounds.

Where clauses before the equals sign on a type alias in a trait impl (like type TypeAlias<T> where T: Foo = Bar<T>) are deprecated. Where clauses after the equals sign (like type TypeAlias<T> = Bar<T> where T: Foo) are preferred.

Structs

^Syntax
Struct :
      StructStruct
   | TupleStruct

StructStruct :
   struct IDENTIFIER  GenericParams^? WhereClause^? ( { StructFields^? } | ; )

TupleStruct :
   struct IDENTIFIER  GenericParams^? ( TupleFields^? ) WhereClause^? ;

StructFields :
   StructField (, StructField)^* ,^?

StructField :
   OuterAttribute^*
   Visibility^?
   IDENTIFIER : Type

TupleFields :
   TupleField (, TupleField)^* ,^?

TupleField :
   OuterAttribute^*
   Visibility^?
   Type

A struct is a nominal struct type defined with the keyword struct.

A struct declaration defines the given name in the type namespace of the module or block where it is located.

An example of a struct item and its use:

#![allow(unused)]
fn main() {
struct Point {x: i32, y: i32}
let p = Point {x: 10, y: 11};
let px: i32 = p.x;
}

A tuple struct is a nominal tuple type, and is also defined with the keyword struct. In addition to defining a type, it also defines a constructor of the same name in the value namespace. The constructor is a function which can be called to create a new instance of the struct. For example:

#![allow(unused)]
fn main() {
struct Point(i32, i32);
let p = Point(10, 11);
let px: i32 = match p { Point(x, _) => x };
}

A unit-like struct is a struct without any fields, defined by leaving off the list of fields entirely. Such a struct implicitly defines a constant of its type with the same name. For example:

#![allow(unused)]
fn main() {
struct Cookie;
let c = [Cookie, Cookie {}, Cookie, Cookie {}];
}

is equivalent to

#![allow(unused)]
fn main() {
struct Cookie {}
const Cookie: Cookie = Cookie {};
let c = [Cookie, Cookie {}, Cookie, Cookie {}];
}

The precise memory layout of a struct is not specified. One can specify a particular layout using the repr attribute.

Enumerations

^Syntax
Enumeration :
   enum IDENTIFIER  GenericParams^? WhereClause^? { EnumItems^? }

EnumItems :
   EnumItem ( , EnumItem )^* ,^?

EnumItem :
   OuterAttribute^* Visibility^?
   IDENTIFIER ( EnumItemTuple | EnumItemStruct )^? EnumItemDiscriminant^?

EnumItemTuple :
   ( TupleFields^? )

EnumItemStruct :
   { StructFields^? }

EnumItemDiscriminant :
   = Expression

An enumeration, also referred to as an enum, is a simultaneous definition of a nominal enumerated type as well as a set of constructors, that can be used to create or pattern-match values of the corresponding enumerated type.

Enumerations are declared with the keyword enum.

The enum declaration defines the enumeration type in the type namespace of the module or block where it is located.

An example of an enum item and its use:

#![allow(unused)]
fn main() {
enum Animal {
    Dog,
    Cat,
}

let mut a: Animal = Animal::Dog;
a = Animal::Cat;
}

Enum constructors can have either named or unnamed fields:

#![allow(unused)]
fn main() {
enum Animal {
    Dog(String, f64),
    Cat { name: String, weight: f64 },
}

let mut a: Animal = Animal::Dog("Cocoa".to_string(), 37.2);
a = Animal::Cat { name: "Spotty".to_string(), weight: 2.7 };
}

In this example, Cat is a struct-like enum variant, whereas Dog is simply called an enum variant.

An enum where no constructors contain fields are called a field-less enum. For example, this is a fieldless enum:

#![allow(unused)]
fn main() {
enum Fieldless {
    Tuple(),
    Struct{},
    Unit,
}
}

If a field-less enum only contains unit variants, the enum is called an unit-only enum. For example:

#![allow(unused)]
fn main() {
enum Enum {
    Foo = 3,
    Bar = 2,
    Baz = 1,
}
}

Variant constructors are similar to struct definitions, and can be referenced by a path from the enumeration name, including in use declarations.

Each variant defines its type in the type namespace, though that type cannot be used as a type specifier. Tuple-like and unit-like variants also define a constructor in the value namespace.

A struct-like variant can be instantiated with a struct expression.

A tuple-like variant can be instantiated with a call expression or a struct expression.

A unit-like variant can be instantiated with a path expression or a struct expression. For example:

#![allow(unused)]
fn main() {
enum Examples {
    UnitLike,
    TupleLike(i32),
    StructLike { value: i32 },
}

use Examples::*; // Creates aliases to all variants.
let x = UnitLike; // Path expression of the const item.
let x = UnitLike {}; // Struct expression.
let y = TupleLike(123); // Call expression.
let y = TupleLike { 0: 123 }; // Struct expression using integer field names.
let z = StructLike { value: 123 }; // Struct expression.
}

Discriminants

Each enum instance has a discriminant: an integer logically associated to it that is used to determine which variant it holds.

Under the Rust representation, the discriminant is interpreted as an isize value. However, the compiler is allowed to use a smaller type (or another means of distinguishing variants) in its actual memory layout.

Assigning discriminant values

Explicit discriminants

In two circumstances, the discriminant of a variant may be explicitly set by following the variant name with = and a constant expression:

1. if the enumeration is “unit-only”.

2. if a primitive representation is used. For example:

   #![allow(unused)]
   fn main() {
   #[repr(u8)]
   enum Enum {
       Unit = 3,
       Tuple(u16),
       Struct {
           a: u8,
           b: u16,
       } = 1,
   }
   }

Implicit discriminants

If a discriminant for a variant is not specified, then it is set to one higher than the discriminant of the previous variant in the declaration. If the discriminant of the first variant in the declaration is unspecified, then it is set to zero.

#![allow(unused)]
fn main() {
enum Foo {
    Bar,            // 0
    Baz = 123,      // 123
    Quux,           // 124
}

let baz_discriminant = Foo::Baz as u32;
assert_eq!(baz_discriminant, 123);
}

Restrictions

It is an error when two variants share the same discriminant.

#![allow(unused)]
fn main() {
enum SharedDiscriminantError {
    SharedA = 1,
    SharedB = 1
}

enum SharedDiscriminantError2 {
    Zero,       // 0
    One,        // 1
    OneToo = 1  // 1 (collision with previous!)
}
}

It is also an error to have an unspecified discriminant where the previous discriminant is the maximum value for the size of the discriminant.

#![allow(unused)]
fn main() {
#[repr(u8)]
enum OverflowingDiscriminantError {
    Max = 255,
    MaxPlusOne // Would be 256, but that overflows the enum.
}

#[repr(u8)]
enum OverflowingDiscriminantError2 {
    MaxMinusOne = 254, // 254
    Max,               // 255
    MaxPlusOne         // Would be 256, but that overflows the enum.
}
}

Accessing discriminant

Via mem::discriminant

std::mem::discriminant returns an opaque reference to the discriminant of an enum value which can be compared. This cannot be used to get the value of the discriminant.

Casting

If an enumeration is unit-only (with no tuple and struct variants), then its discriminant can be directly accessed with a numeric cast; e.g.:

#![allow(unused)]
fn main() {
enum Enum {
    Foo,
    Bar,
    Baz,
}

assert_eq!(0, Enum::Foo as isize);
assert_eq!(1, Enum::Bar as isize);
assert_eq!(2, Enum::Baz as isize);
}

Field-less enums can be casted if they do not have explicit discriminants, or where only unit variants are explicit.

#![allow(unused)]
fn main() {
enum Fieldless {
    Tuple(),
    Struct{},
    Unit,
}

assert_eq!(0, Fieldless::Tuple() as isize);
assert_eq!(1, Fieldless::Struct{} as isize);
assert_eq!(2, Fieldless::Unit as isize);

#[repr(u8)]
enum FieldlessWithDiscrimants {
    First = 10,
    Tuple(),
    Second = 20,
    Struct{},
    Unit,
}

assert_eq!(10, FieldlessWithDiscrimants::First as u8);
assert_eq!(11, FieldlessWithDiscrimants::Tuple() as u8);
assert_eq!(20, FieldlessWithDiscrimants::Second as u8);
assert_eq!(21, FieldlessWithDiscrimants::Struct{} as u8);
assert_eq!(22, FieldlessWithDiscrimants::Unit as u8);
}

Pointer casting

If the enumeration specifies a primitive representation, then the discriminant may be reliably accessed via unsafe pointer casting:

#![allow(unused)]
fn main() {
#[repr(u8)]
enum Enum {
    Unit,
    Tuple(bool),
    Struct{a: bool},
}

impl Enum {
    fn discriminant(&self) -> u8 {
        unsafe { *(self as *const Self as *const u8) }
    }
}

let unit_like = Enum::Unit;
let tuple_like = Enum::Tuple(true);
let struct_like = Enum::Struct{a: false};

assert_eq!(0, unit_like.discriminant());
assert_eq!(1, tuple_like.discriminant());
assert_eq!(2, struct_like.discriminant());
}

Zero-variant enums

Enums with zero variants are known as zero-variant enums. As they have no valid values, they cannot be instantiated.

#![allow(unused)]
fn main() {
enum ZeroVariants {}
}

Zero-variant enums are equivalent to the never type, but they cannot be coerced into other types.

#![allow(unused)]
fn main() {
enum ZeroVariants {}
let x: ZeroVariants = panic!();
let y: u32 = x; // mismatched type error
}

Variant visibility

Enum variants syntactically allow a Visibility annotation, but this is rejected when the enum is validated. This allows items to be parsed with a unified syntax across different contexts where they are used.

#![allow(unused)]
fn main() {
macro_rules! mac_variant {
    ($vis:vis $name:ident) => {
        enum $name {
            $vis Unit,

            $vis Tuple(u8, u16),

            $vis Struct { f: u8 },
        }
    }
}

// Empty `vis` is allowed.
mac_variant! { E }

// This is allowed, since it is removed before being validated.
#[cfg(FALSE)]
enum E {
    pub U,
    pub(crate) T(u8),
    pub(super) T { f: String }
}
}

Unions

^Syntax
Union :
   union IDENTIFIER GenericParams^? WhereClause^? {StructFields^? }

A union declaration uses the same syntax as a struct declaration, except with union in place of struct.

A union declaration defines the given name in the type namespace of the module or block where it is located.

#![allow(unused)]
fn main() {
#[repr(C)]
union MyUnion {
    f1: u32,
    f2: f32,
}
}

The key property of unions is that all fields of a union share common storage. As a result, writes to one field of a union can overwrite its other fields, and size of a union is determined by the size of its largest field.

Union field types are restricted to the following subset of types:

• Copy types

• References (&T and &mut T for arbitrary T)

• ManuallyDrop<T> (for arbitrary T)

• Tuples and arrays containing only allowed union field types

This restriction ensures, in particular, that union fields never need to be dropped. Like for structs and enums, it is possible to impl Drop for a union to manually define what happens when it gets dropped.

Unions without any fields are not accepted by the compiler, but can be accepted by macros.

Initialization of a union

A value of a union type can be created using the same syntax that is used for struct types, except that it must specify exactly one field:

#![allow(unused)]
fn main() {
union MyUnion { f1: u32, f2: f32 }

let u = MyUnion { f1: 1 };
}

The expression above creates a value of type MyUnion and initializes the storage using field f1. The union can be accessed using the same syntax as struct fields:

#![allow(unused)]
fn main() {
union MyUnion { f1: u32, f2: f32 }

let u = MyUnion { f1: 1 };
let f = unsafe { u.f1 };
}

Reading and writing union fields

Unions have no notion of an “active field”. Instead, every union access just interprets the storage as the type of the field used for the access.

Reading a union field reads the bits of the union at the field’s type.

Fields might have a non-zero offset (except when the C representation is used); in that case the bits starting at the offset of the fields are read

It is the programmer’s responsibility to make sure that the data is valid at the field’s type. Failing to do so results in undefined behavior. For example, reading the value 3 from a field of the boolean type is undefined behavior. Effectively, writing to and then reading from a union with the C representation is analogous to a transmute from the type used for writing to the type used for reading.

Consequently, all reads of union fields have to be placed in unsafe blocks:

#![allow(unused)]
fn main() {
union MyUnion { f1: u32, f2: f32 }
let u = MyUnion { f1: 1 };

unsafe {
    let f = u.f1;
}
}

Commonly, code using unions will provide safe wrappers around unsafe union field accesses.

In contrast, writes to union fields are safe, since they just overwrite arbitrary data, but cannot cause undefined behavior. (Note that union field types can never have drop glue, so a union field write will never implicitly drop anything.)

Pattern matching on unions

Another way to access union fields is to use pattern matching.

Pattern matching on union fields uses the same syntax as struct patterns, except that the pattern must specify exactly one field.

Since pattern matching is like reading the union with a particular field, it has to be placed in unsafe blocks as well.

#![allow(unused)]
fn main() {
union MyUnion { f1: u32, f2: f32 }

fn f(u: MyUnion) {
    unsafe {
        match u {
            MyUnion { f1: 10 } => { println!("ten"); }
            MyUnion { f2 } => { println!("{}", f2); }
        }
    }
}
}

Pattern matching may match a union as a field of a larger structure. In particular, when using a Rust union to implement a C tagged union via FFI, this allows matching on the tag and the corresponding field simultaneously:

#![allow(unused)]
fn main() {
#[repr(u32)]
enum Tag { I, F }

#[repr(C)]
union U {
    i: i32,
    f: f32,
}

#[repr(C)]
struct Value {
    tag: Tag,
    u: U,
}

fn is_zero(v: Value) -> bool {
    unsafe {
        match v {
            Value { tag: Tag::I, u: U { i: 0 } } => true,
            Value { tag: Tag::F, u: U { f: num } } if num == 0.0 => true,
            _ => false,
        }
    }
}
}

References to union fields

Since union fields share common storage, gaining write access to one field of a union can give write access to all its remaining fields.

Borrow checking rules have to be adjusted to account for this fact. As a result, if one field of a union is borrowed, all its remaining fields are borrowed as well for the same lifetime.

#![allow(unused)]
fn main() {
union MyUnion { f1: u32, f2: f32 }
// ERROR: cannot borrow `u` (via `u.f2`) as mutable more than once at a time
fn test() {
    let mut u = MyUnion { f1: 1 };
    unsafe {
        let b1 = &mut u.f1;
//                    ---- first mutable borrow occurs here (via `u.f1`)
        let b2 = &mut u.f2;
//                    ^^^^ second mutable borrow occurs here (via `u.f2`)
        *b1 = 5;
    }
//  - first borrow ends here
    assert_eq!(unsafe { u.f1 }, 5);
}
}

As you could see, in many aspects (except for layouts, safety, and ownership) unions behave exactly like structs, largely as a consequence of inheriting their syntactic shape from structs. This is also true for many unmentioned aspects of Rust language (such as privacy, name resolution, type inference, generics, trait implementations, inherent implementations, coherence, pattern checking, etc etc etc).

Constant items

^Syntax
ConstantItem :
   const ( IDENTIFIER | _ ) : Type ( = Expression )^? ;

A constant item is an optionally named constant value which is not associated with a specific memory location in the program.

Constants are essentially inlined wherever they are used, meaning that they are copied directly into the relevant context when used. This includes usage of constants from external crates, and non-Copy types. References to the same constant are not necessarily guaranteed to refer to the same memory address.

The constant declaration defines the constant value in the value namespace of the module or block where it is located.

Constants must be explicitly typed. The type must have a 'static lifetime: any references in the initializer must have 'static lifetimes. References in the type of a constant default to 'static lifetime; see static lifetime elision.

A reference to a constant will have 'static lifetime if the constant value is eligible for promotion; otherwise, a temporary will be created.

#![allow(unused)]
fn main() {
const BIT1: u32 = 1 << 0;
const BIT2: u32 = 1 << 1;

const BITS: [u32; 2] = [BIT1, BIT2];
const STRING: &'static str = "bitstring";

struct BitsNStrings<'a> {
    mybits: [u32; 2],
    mystring: &'a str,
}

const BITS_N_STRINGS: BitsNStrings<'static> = BitsNStrings {
    mybits: BITS,
    mystring: STRING,
};
}

The constant expression may only be omitted in a trait definition.

Constants with Destructors

Constants can contain destructors. Destructors are run when the value goes out of scope.

#![allow(unused)]
fn main() {
struct TypeWithDestructor(i32);

impl Drop for TypeWithDestructor {
    fn drop(&mut self) {
        println!("Dropped. Held {}.", self.0);
    }
}

const ZERO_WITH_DESTRUCTOR: TypeWithDestructor = TypeWithDestructor(0);

fn create_and_drop_zero_with_destructor() {
    let x = ZERO_WITH_DESTRUCTOR;
    // x gets dropped at end of function, calling drop.
    // prints "Dropped. Held 0.".
}
}

Unnamed constant

Unlike an associated constant, a free constant may be unnamed by using an underscore instead of the name. For example:

#![allow(unused)]
fn main() {
const _: () =  { struct _SameNameTwice; };

// OK although it is the same name as above:
const _: () =  { struct _SameNameTwice; };
}

As with underscore imports, macros may safely emit the same unnamed constant in the same scope more than once. For example, the following should not produce an error:

#![allow(unused)]
fn main() {
macro_rules! m {
    ($item: item) => { $item $item }
}

m!(const _: () = (););
// This expands to:
// const _: () = ();
// const _: () = ();
}

Evaluation

Free constants are always evaluated at compile-time to surface panics. This happens even within an unused function:

#![allow(unused)]
fn main() {
// Compile-time panic
const PANIC: () = std::unimplemented!();

fn unused_generic_function<T>() {
    // A failing compile-time assertion
    const _: () = assert!(usize::BITS == 0);
}
}

Static items

^Syntax
StaticItem :
   ItemSafety^?1 static mut^? IDENTIFIER : Type ( = Expression )^? ;

¹

The safe and unsafe function qualifiers are only allowed semantically within extern blocks.

A static item is similar to a constant, except that it represents a precise memory location in the program. All references to the static refer to the same memory location.

Static items have the static lifetime, which outlives all other lifetimes in a Rust program. Static items do not call drop at the end of the program.

The static declaration defines a static value in the value namespace of the module or block where it is located.

The static initializer is a constant expression evaluated at compile time. Static initializers may refer to other statics.

Non-mut static items that contain a type that is not interior mutable may be placed in read-only memory.

All access to a static is safe, but there are a number of restrictions on statics:

• The type must have the Sync trait bound to allow thread-safe access.

• Constants cannot refer to statics.

The initializer expression must be omitted in an external block, and must be provided for free static items.

The safe and unsafe qualifiers are semantically only allowed when used in an external block.

Statics & generics

A static item defined in a generic scope (for example in a blanket or default implementation) will result in exactly one static item being defined, as if the static definition was pulled out of the current scope into the module. There will not be one item per monomorphization.

This code:

use std::sync::atomic::{AtomicUsize, Ordering};

trait Tr {
    fn default_impl() {
        static COUNTER: AtomicUsize = AtomicUsize::new(0);
        println!("default_impl: counter was {}", COUNTER.fetch_add(1, Ordering::Relaxed));
    }

    fn blanket_impl();
}

struct Ty1 {}
struct Ty2 {}

impl<T> Tr for T {
    fn blanket_impl() {
        static COUNTER: AtomicUsize = AtomicUsize::new(0);
        println!("blanket_impl: counter was {}", COUNTER.fetch_add(1, Ordering::Relaxed));
    }
}

fn main() {
    <Ty1 as Tr>::default_impl();
    <Ty2 as Tr>::default_impl();
    <Ty1 as Tr>::blanket_impl();
    <Ty2 as Tr>::blanket_impl();
}

prints

default_impl: counter was 0
default_impl: counter was 1
blanket_impl: counter was 0
blanket_impl: counter was 1

Mutable statics

If a static item is declared with the mut keyword, then it is allowed to be modified by the program. One of Rust’s goals is to make concurrency bugs hard to run into, and this is obviously a very large source of race conditions or other bugs

For this reason, an unsafe block is required when either reading or writing a mutable static variable. Care should be taken to ensure that modifications to a mutable static are safe with respect to other threads running in the same process.

Mutable statics are still very useful, however. They can be used with C libraries and can also be bound from C libraries in an extern block.

#![allow(unused)]
fn main() {
fn atomic_add(_: *mut u32, _: u32) -> u32 { 2 }

static mut LEVELS: u32 = 0;

// This violates the idea of no shared state, and this doesn't internally
// protect against races, so this function is `unsafe`
unsafe fn bump_levels_unsafe() -> u32 {
    unsafe {
        let ret = LEVELS;
        LEVELS += 1;
        return ret;
    }
}

// As an alternative to `bump_levels_unsafe`, this function is safe, assuming
// that we have an atomic_add function which returns the old value. This
// function is safe only if no other code accesses the static in a non-atomic
// fashion. If such accesses are possible (such as in `bump_levels_unsafe`),
// then this would need to be `unsafe` to indicate to the caller that they
// must still guard against concurrent access.
fn bump_levels_safe() -> u32 {
    unsafe {
        return atomic_add(&raw mut LEVELS, 1);
    }
}
}

Mutable statics have the same restrictions as normal statics, except that the type does not have to implement the Sync trait.

Using Statics or Consts

It can be confusing whether or not you should use a constant item or a static item. Constants should, in general, be preferred over statics unless one of the following are true:

• Large amounts of data are being stored
• The single-address property of statics is required.
• Interior mutability is required.

Traits

^Syntax
Trait :
   unsafe^? trait IDENTIFIER  GenericParams^? ( : TypeParamBounds^? )^? WhereClause^? {
     InnerAttribute^*
     AssociatedItem^*
   }

A trait describes an abstract interface that types can implement. This interface consists of associated items, which come in three varieties:

• functions
• types
• constants

The trait declaration defines a trait in the type namespace of the module or block where it is located.

Associated items are defined as members of the trait within their respective namespaces. Associated types are defined in the type namespace. Associated constants and associated functions are defined in the value namespace.

All traits define an implicit type parameter Self that refers to “the type that is implementing this interface”. Traits may also contain additional type parameters. These type parameters, including Self, may be constrained by other traits and so forth as usual.

Traits are implemented for specific types through separate implementations.

Trait functions may omit the function body by replacing it with a semicolon. This indicates that the implementation must define the function. If the trait function defines a body, this definition acts as a default for any implementation which does not override it. Similarly, associated constants may omit the equals sign and expression to indicate implementations must define the constant value. Associated types must never define the type, the type may only be specified in an implementation.

#![allow(unused)]
fn main() {
// Examples of associated trait items with and without definitions.
trait Example {
    const CONST_NO_DEFAULT: i32;
    const CONST_WITH_DEFAULT: i32 = 99;
    type TypeNoDefault;
    fn method_without_default(&self);
    fn method_with_default(&self) {}
}
}

Trait functions are not allowed to be const.

Trait bounds

Generic items may use traits as bounds on their type parameters.

Generic traits

Type parameters can be specified for a trait to make it generic. These appear after the trait name, using the same syntax used in generic functions.

#![allow(unused)]
fn main() {
trait Seq<T> {
    fn len(&self) -> u32;
    fn elt_at(&self, n: u32) -> T;
    fn iter<F>(&self, f: F) where F: Fn(T);
}
}

Dyn compatibility

A dyn-compatible trait can be the base trait of a trait object. A trait is dyn compatible if it has the following qualities:

• All supertraits must also be dyn compatible.

• Sized must not be a supertrait. In other words, it must not require Self: Sized.

• It must not have any associated constants.

• It must not have any associated types with generics.

• All associated functions must either be dispatchable from a trait object or be explicitly non-dispatchable:
  • Dispatchable functions must:
    • Not have any type parameters (although lifetime parameters are allowed).
    • Be a method that does not use Self except in the type of the receiver.
    • Have a receiver with one of the following types:
      • &Self (i.e. &self)
      • &mut Self (i.e &mut self)
      • Box<Self>
      • Rc<Self>
      • Arc<Self>
      • Pin<P> where P is one of the types above
    • Not have an opaque return type; that is,
      • Not be an async fn (which has a hidden Future type).
      • Not have a return position impl Trait type (fn example(&self) -> impl Trait).
    • Not have a where Self: Sized bound (receiver type of Self (i.e. self) implies this).
  • Explicitly non-dispatchable functions require:
    • Have a where Self: Sized bound (receiver type of Self (i.e. self) implies this).

Note: This concept was formerly known as object safety.

#![allow(unused)]
fn main() {
use std::rc::Rc;
use std::sync::Arc;
use std::pin::Pin;
// Examples of dyn compatible methods.
trait TraitMethods {
    fn by_ref(self: &Self) {}
    fn by_ref_mut(self: &mut Self) {}
    fn by_box(self: Box<Self>) {}
    fn by_rc(self: Rc<Self>) {}
    fn by_arc(self: Arc<Self>) {}
    fn by_pin(self: Pin<&Self>) {}
    fn with_lifetime<'a>(self: &'a Self) {}
    fn nested_pin(self: Pin<Arc<Self>>) {}
}
struct S;
impl TraitMethods for S {}
let t: Box<dyn TraitMethods> = Box::new(S);
}

#![allow(unused)]
fn main() {
// This trait is dyn compatible, but these methods cannot be dispatched on a trait object.
trait NonDispatchable {
    // Non-methods cannot be dispatched.
    fn foo() where Self: Sized {}
    // Self type isn't known until runtime.
    fn returns(&self) -> Self where Self: Sized;
    // `other` may be a different concrete type of the receiver.
    fn param(&self, other: Self) where Self: Sized {}
    // Generics are not compatible with vtables.
    fn typed<T>(&self, x: T) where Self: Sized {}
}

struct S;
impl NonDispatchable for S {
    fn returns(&self) -> Self where Self: Sized { S }
}
let obj: Box<dyn NonDispatchable> = Box::new(S);
obj.returns(); // ERROR: cannot call with Self return
obj.param(S);  // ERROR: cannot call with Self parameter
obj.typed(1);  // ERROR: cannot call with generic type
}

#![allow(unused)]
fn main() {
use std::rc::Rc;
// Examples of dyn-incompatible traits.
trait DynIncompatible {
    const CONST: i32 = 1;  // ERROR: cannot have associated const

    fn foo() {}  // ERROR: associated function without Sized
    fn returns(&self) -> Self; // ERROR: Self in return type
    fn typed<T>(&self, x: T) {} // ERROR: has generic type parameters
    fn nested(self: Rc<Box<Self>>) {} // ERROR: nested receiver not yet supported
}

struct S;
impl DynIncompatible for S {
    fn returns(&self) -> Self { S }
}
let obj: Box<dyn DynIncompatible> = Box::new(S); // ERROR
}

#![allow(unused)]
fn main() {
// `Self: Sized` traits are dyn-incompatible.
trait TraitWithSize where Self: Sized {}

struct S;
impl TraitWithSize for S {}
let obj: Box<dyn TraitWithSize> = Box::new(S); // ERROR
}

#![allow(unused)]
fn main() {
// Dyn-incompatible if `Self` is a type argument.
trait Super<A> {}
trait WithSelf: Super<Self> where Self: Sized {}

struct S;
impl<A> Super<A> for S {}
impl WithSelf for S {}
let obj: Box<dyn WithSelf> = Box::new(S); // ERROR: cannot use `Self` type parameter
}

Supertraits

Supertraits are traits that are required to be implemented for a type to implement a specific trait. Furthermore, anywhere a generic or trait object is bounded by a trait, it has access to the associated items of its supertraits.

Supertraits are declared by trait bounds on the Self type of a trait and transitively the supertraits of the traits declared in those trait bounds. It is an error for a trait to be its own supertrait.

The trait with a supertrait is called a subtrait of its supertrait.

The following is an example of declaring Shape to be a supertrait of Circle.

#![allow(unused)]
fn main() {
trait Shape { fn area(&self) -> f64; }
trait Circle : Shape { fn radius(&self) -> f64; }
}

And the following is the same example, except using where clauses.

#![allow(unused)]
fn main() {
trait Shape { fn area(&self) -> f64; }
trait Circle where Self: Shape { fn radius(&self) -> f64; }
}

This next example gives radius a default implementation using the area function from Shape.

#![allow(unused)]
fn main() {
trait Shape { fn area(&self) -> f64; }
trait Circle where Self: Shape {
    fn radius(&self) -> f64 {
        // A = pi * r^2
        // so algebraically,
        // r = sqrt(A / pi)
        (self.area() /std::f64::consts::PI).sqrt()
    }
}
}

This next example calls a supertrait method on a generic parameter.

#![allow(unused)]
fn main() {
trait Shape { fn area(&self) -> f64; }
trait Circle : Shape { fn radius(&self) -> f64; }
fn print_area_and_radius<C: Circle>(c: C) {
    // Here we call the area method from the supertrait `Shape` of `Circle`.
    println!("Area: {}", c.area());
    println!("Radius: {}", c.radius());
}
}

Similarly, here is an example of calling supertrait methods on trait objects.

#![allow(unused)]
fn main() {
trait Shape { fn area(&self) -> f64; }
trait Circle : Shape { fn radius(&self) -> f64; }
struct UnitCircle;
impl Shape for UnitCircle { fn area(&self) -> f64 { std::f64::consts::PI } }
impl Circle for UnitCircle { fn radius(&self) -> f64 { 1.0 } }
let circle = UnitCircle;
let circle = Box::new(circle) as Box<dyn Circle>;
let nonsense = circle.radius() * circle.area();
}

Unsafe traits

Traits items that begin with the unsafe keyword indicate that implementing the trait may be unsafe. It is safe to use a correctly implemented unsafe trait. The trait implementation must also begin with the unsafe keyword.

Sync and Send are examples of unsafe traits.

Parameter patterns

Function or method declarations without a body only allow IDENTIFIER or _ wild card patterns. mut IDENTIFIER is currently allowed, but it is deprecated and will become a hard error in the future.

In the 2015 edition, the pattern for a trait function or method parameter is optional:

#![allow(unused)]
fn main() {
// 2015 Edition
trait T {
    fn f(i32);  // Parameter identifiers are not required.
}
}

The kinds of patterns for parameters is limited to one of the following:

• IDENTIFIER
• mut IDENTIFIER
• _
• & IDENTIFIER
• && IDENTIFIER

Beginning in the 2018 edition, function or method parameter patterns are no longer optional. Also, all irrefutable patterns are allowed as long as there is a body. Without a body, the limitations listed above are still in effect.

#![allow(unused)]
fn main() {
trait T {
    fn f1((a, b): (i32, i32)) {}
    fn f2(_: (i32, i32));  // Cannot use tuple pattern without a body.
}
}

Item visibility

Trait items syntactically allow a Visibility annotation, but this is rejected when the trait is validated. This allows items to be parsed with a unified syntax across different contexts where they are used. As an example, an empty vis macro fragment specifier can be used for trait items, where the macro rule may be used in other situations where visibility is allowed.

macro_rules! create_method {
    ($vis:vis $name:ident) => {
        $vis fn $name(&self) {}
    };
}

trait T1 {
    // Empty `vis` is allowed.
    create_method! { method_of_t1 }
}

struct S;

impl S {
    // Visibility is allowed here.
    create_method! { pub method_of_s }
}

impl T1 for S {}

fn main() {
    let s = S;
    s.method_of_t1();
    s.method_of_s();
}

Implementations

^Syntax
Implementation :
   InherentImpl | TraitImpl

InherentImpl :
   impl GenericParams^? Type WhereClause^? {
      InnerAttribute^*
      AssociatedItem^*
   }

TraitImpl :
   unsafe^? impl GenericParams^? !^? TypePath for Type
   WhereClause^?
   {
      InnerAttribute^*
      AssociatedItem^*
   }

An implementation is an item that associates items with an implementing type. Implementations are defined with the keyword impl and contain functions that belong to an instance of the type that is being implemented or to the type statically.

There are two types of implementations:

• inherent implementations
• trait implementations

Inherent Implementations

An inherent implementation is defined as the sequence of the impl keyword, generic type declarations, a path to a nominal type, a where clause, and a bracketed set of associable items.

The nominal type is called the implementing type and the associable items are the associated items to the implementing type.

Inherent implementations associate the contained items to the implementing type.

Inherent implementations can contain associated functions (including methods) and associated constants.

They cannot contain associated type aliases.

The path to an associated item is any path to the implementing type, followed by the associated item’s identifier as the final path component.

A type can also have multiple inherent implementations. An implementing type must be defined within the same crate as the original type definition.

pub mod color {
    pub struct Color(pub u8, pub u8, pub u8);

    impl Color {
        pub const WHITE: Color = Color(255, 255, 255);
    }
}

mod values {
    use super::color::Color;
    impl Color {
        pub fn red() -> Color {
            Color(255, 0, 0)
        }
    }
}

pub use self::color::Color;
fn main() {
    // Actual path to the implementing type and impl in the same module.
    color::Color::WHITE;

    // Impl blocks in different modules are still accessed through a path to the type.
    color::Color::red();

    // Re-exported paths to the implementing type also work.
    Color::red();

    // Does not work, because use in `values` is not pub.
    // values::Color::red();
}

Trait Implementations

A trait implementation is defined like an inherent implementation except that the optional generic type declarations are followed by a trait, followed by the keyword for, followed by a path to a nominal type.

The trait is known as the implemented trait. The implementing type implements the implemented trait.

A trait implementation must define all non-default associated items declared by the implemented trait, may redefine default associated items defined by the implemented trait, and cannot define any other items.

The path to the associated items is < followed by a path to the implementing type followed by as followed by a path to the trait followed by > as a path component followed by the associated item’s path component.

Unsafe traits require the trait implementation to begin with the unsafe keyword.

#![allow(unused)]
fn main() {
#[derive(Copy, Clone)]
struct Point {x: f64, y: f64};
type Surface = i32;
struct BoundingBox {x: f64, y: f64, width: f64, height: f64};
trait Shape { fn draw(&self, s: Surface); fn bounding_box(&self) -> BoundingBox; }
fn do_draw_circle(s: Surface, c: Circle) { }
struct Circle {
    radius: f64,
    center: Point,
}

impl Copy for Circle {}

impl Clone for Circle {
    fn clone(&self) -> Circle { *self }
}

impl Shape for Circle {
    fn draw(&self, s: Surface) { do_draw_circle(s, *self); }
    fn bounding_box(&self) -> BoundingBox {
        let r = self.radius;
        BoundingBox {
            x: self.center.x - r,
            y: self.center.y - r,
            width: 2.0 * r,
            height: 2.0 * r,
        }
    }
}
}

Trait Implementation Coherence

A trait implementation is considered incoherent if either the orphan rules check fails or there are overlapping implementation instances.

Two trait implementations overlap when there is a non-empty intersection of the traits the implementation is for, the implementations can be instantiated with the same type.

Orphan rules

Given impl<P1..=Pn> Trait<T1..=Tn> for T0, an impl is valid only if at least one of the following is true:

• Trait is a local trait
• All of
  • At least one of the types T0..=Tn must be a local type. Let Ti be the first such type.
  • No uncovered type parameters P1..=Pn may appear in T0..Ti (excluding Ti)

Only the appearance of uncovered type parameters is restricted.

Note that for the purposes of coherence, fundamental types are special. The T in Box<T> is not considered covered, and Box<LocalType> is considered local.

Generic Implementations

An implementation can take generic parameters, which can be used in the rest of the implementation. Implementation parameters are written directly after the impl keyword.

#![allow(unused)]
fn main() {
trait Seq<T> { fn dummy(&self, _: T) { } }
impl<T> Seq<T> for Vec<T> {
    /* ... */
}
impl Seq<bool> for u32 {
    /* Treat the integer as a sequence of bits */
}
}

Generic parameters constrain an implementation if the parameter appears at least once in one of:

• The implemented trait, if it has one
• The implementing type
• As an associated type in the bounds of a type that contains another parameter that constrains the implementation

Type and const parameters must always constrain the implementation. Lifetimes must constrain the implementation if the lifetime is used in an associated type.

Examples of constraining situations:

#![allow(unused)]
fn main() {
trait Trait{}
trait GenericTrait<T> {}
trait HasAssocType { type Ty; }
struct Struct;
struct GenericStruct<T>(T);
struct ConstGenericStruct<const N: usize>([(); N]);
// T constrains by being an argument to GenericTrait.
impl<T> GenericTrait<T> for i32 { /* ... */ }

// T constrains by being an argument to GenericStruct
impl<T> Trait for GenericStruct<T> { /* ... */ }

// Likewise, N constrains by being an argument to ConstGenericStruct
impl<const N: usize> Trait for ConstGenericStruct<N> { /* ... */ }

// T constrains by being in an associated type in a bound for type `U` which is
// itself a generic parameter constraining the trait.
impl<T, U> GenericTrait<U> for u32 where U: HasAssocType<Ty = T> { /* ... */ }

// Like previous, except the type is `(U, isize)`. `U` appears inside the type
// that includes `T`, and is not the type itself.
impl<T, U> GenericStruct<U> where (U, isize): HasAssocType<Ty = T> { /* ... */ }
}

Examples of non-constraining situations:

#![allow(unused)]
fn main() {
// The rest of these are errors, since they have type or const parameters that
// do not constrain.

// T does not constrain since it does not appear at all.
impl<T> Struct { /* ... */ }

// N does not constrain for the same reason.
impl<const N: usize> Struct { /* ... */ }

// Usage of T inside the implementation does not constrain the impl.
impl<T> Struct {
    fn uses_t(t: &T) { /* ... */ }
}

// T is used as an associated type in the bounds for U, but U does not constrain.
impl<T, U> Struct where U: HasAssocType<Ty = T> { /* ... */ }

// T is used in the bounds, but not as an associated type, so it does not constrain.
impl<T, U> GenericTrait<U> for u32 where U: GenericTrait<T> {}
}

Example of an allowed unconstraining lifetime parameter:

#![allow(unused)]
fn main() {
struct Struct;
impl<'a> Struct {}
}

Example of a disallowed unconstraining lifetime parameter:

#![allow(unused)]
fn main() {
struct Struct;
trait HasAssocType { type Ty; }
impl<'a> HasAssocType for Struct {
    type Ty = &'a Struct;
}
}

Attributes on Implementations

Implementations may contain outer attributes before the impl keyword and inner attributes inside the brackets that contain the associated items. Inner attributes must come before any associated items. The attributes that have meaning here are cfg, deprecated, doc, and the lint check attributes.

External blocks

^Syntax
ExternBlock :
   unsafe^? extern Abi^? {
      InnerAttribute^*
      ExternalItem^*
   }

ExternalItem :
   OuterAttribute^* (
         MacroInvocationSemi
      | ( Visibility^? ( StaticItem | Function ) )
   )

External blocks provide declarations of items that are not defined in the current crate and are the basis of Rust’s foreign function interface. These are akin to unchecked imports.

Two kinds of item declarations are allowed in external blocks: functions and statics.

Calling functions or accessing statics that are declared in external blocks is only allowed in an unsafe context.

The external block defines its functions and statics in the value namespace of the module or block where it is located.

Functions

Functions within external blocks are declared in the same way as other Rust functions, with the exception that they must not have a body and are instead terminated by a semicolon.

Patterns are not allowed in parameters, only IDENTIFIER or _ may be used.

The safe and unsafe function qualifiers are allowed, but other function qualifiers (e.g. const, async, extern) are not.

Functions within external blocks may be called by Rust code, just like functions defined in Rust. The Rust compiler automatically translates between the Rust ABI and the foreign ABI.

A function declared in an extern block is implicitly unsafe unless the safe function qualifier is present.

When coerced to a function pointer, a function declared in an extern block has type extern "abi" for<'l1, ..., 'lm> fn(A1, ..., An) -> R, where 'l1, … 'lm are its lifetime parameters, A1, …, An are the declared types of its parameters, R is the declared return type.

Statics

Statics within external blocks are declared in the same way as statics outside of external blocks, except that they do not have an expression initializing their value.

Unless a static item declared in an extern block is qualified as safe, it is unsafe to access that item, whether or not it’s mutable, because there is nothing guaranteeing that the bit pattern at the static’s memory is valid for the type it is declared with, since some arbitrary (e.g. C) code is in charge of initializing the static.

Extern statics can be either immutable or mutable just like statics outside of external blocks.

An immutable static must be initialized before any Rust code is executed. It is not enough for the static to be initialized before Rust code reads from it. Once Rust code runs, mutating an immutable static (from inside or outside Rust) is UB, except if the mutation happens to bytes inside of an UnsafeCell.

ABI

By default external blocks assume that the library they are calling uses the standard C ABI on the specific platform. Other ABIs may be specified using an abi string, as shown here:

#![allow(unused)]
fn main() {
#[cfg(any(windows, target_arch = "x86"))]
// Interface to the Windows API
unsafe extern "stdcall" { }
}

There are three ABI strings which are cross-platform, and which all compilers are guaranteed to support:

• unsafe extern "Rust" – The default ABI when you write a normal fn foo() in any Rust code.

• unsafe extern "C" – This is the same as extern fn foo(); whatever the default your C compiler supports.

• unsafe extern "system" – Usually the same as extern "C", except on Win32, in which case it’s "stdcall", or what you should use to link to the Windows API itself

There are also some platform-specific ABI strings:

• unsafe extern "cdecl" – The default for x86_32 C code.

• unsafe extern "stdcall" – The default for the Win32 API on x86_32.

• unsafe extern "win64" – The default for C code on x86_64 Windows.

• unsafe extern "sysv64" – The default for C code on non-Windows x86_64.

• unsafe extern "aapcs" – The default for ARM.

• unsafe extern "fastcall" – The fastcall ABI – corresponds to MSVC’s __fastcall and GCC and clang’s __attribute__((fastcall))

• unsafe extern "vectorcall" – The vectorcall ABI – corresponds to MSVC’s __vectorcall and clang’s __attribute__((vectorcall))

• unsafe extern "thiscall" – The default for C++ member functions on MSVC – corresponds to MSVC’s __thiscall and GCC and clang’s __attribute__((thiscall))

• unsafe extern "efiapi" – The ABI used for UEFI functions.

Variadic functions

Functions within external blocks may be variadic by specifying ... as the last argument. The variadic parameter may optionally be specified with an identifier.

#![allow(unused)]
fn main() {
unsafe extern "C" {
    safe fn foo(...);
    unsafe fn bar(x: i32, ...);
    unsafe fn with_name(format: *const u8, args: ...);
}
}

Attributes on extern blocks

The following attributes control the behavior of external blocks.

The link attribute

The link attribute specifies the name of a native library that the compiler should link with for the items within an extern block.

It uses the MetaListNameValueStr syntax to specify its inputs. The name key is the name of the native library to link. The kind key is an optional value which specifies the kind of library with the following possible values:

• dylib — Indicates a dynamic library. This is the default if kind is not specified.

• static — Indicates a static library.

• framework — Indicates a macOS framework. This is only valid for macOS targets.

• raw-dylib — Indicates a dynamic library where the compiler will generate an import library to link against (see dylib versus raw-dylib below for details). This is only valid for Windows targets.

The name key must be included if kind is specified.

The optional modifiers argument is a way to specify linking modifiers for the library to link.

Modifiers are specified as a comma-delimited string with each modifier prefixed with either a + or - to indicate that the modifier is enabled or disabled, respectively.

Specifying multiple modifiers arguments in a single link attribute, or multiple identical modifiers in the same modifiers argument is not currently supported.
Example: #[link(name = "mylib", kind = "static", modifiers = "+whole-archive")].

The wasm_import_module key may be used to specify the WebAssembly module name for the items within an extern block when importing symbols from the host environment. The default module name is env if wasm_import_module is not specified.

#[link(name = "crypto")]
unsafe extern {
    // …
}

#[link(name = "CoreFoundation", kind = "framework")]
unsafe extern {
    // …
}

#[link(wasm_import_module = "foo")]
unsafe extern {
    // …
}

It is valid to add the link attribute on an empty extern block. You can use this to satisfy the linking requirements of extern blocks elsewhere in your code (including upstream crates) instead of adding the attribute to each extern block.

Linking modifiers: bundle

This modifier is only compatible with the static linking kind. Using any other kind will result in a compiler error.

When building a rlib or staticlib +bundle means that the native static library will be packed into the rlib or staticlib archive, and then retrieved from there during linking of the final binary.

When building a rlib -bundle means that the native static library is registered as a dependency of that rlib “by name”, and object files from it are included only during linking of the final binary, the file search by that name is also performed during final linking.
When building a staticlib -bundle means that the native static library is simply not included into the archive and some higher level build system will need to add it later during linking of the final binary.

This modifier has no effect when building other targets like executables or dynamic libraries.

The default for this modifier is +bundle.

More implementation details about this modifier can be found in bundle documentation for rustc.

Linking modifiers: whole-archive

This modifier is only compatible with the static linking kind. Using any other kind will result in a compiler error.

+whole-archive means that the static library is linked as a whole archive without throwing any object files away.

The default for this modifier is -whole-archive.

More implementation details about this modifier can be found in whole-archive documentation for rustc.

Linking modifiers: verbatim

This modifier is compatible with all linking kinds.

+verbatim means that rustc itself won’t add any target-specified library prefixes or suffixes (like lib or .a) to the library name, and will try its best to ask for the same thing from the linker.

-verbatim means that rustc will either add a target-specific prefix and suffix to the library name before passing it to linker, or won’t prevent linker from implicitly adding it.

The default for this modifier is -verbatim.

More implementation details about this modifier can be found in verbatim documentation for rustc.

dylib versus raw-dylib

On Windows, linking against a dynamic library requires that an import library is provided to the linker: this is a special static library that declares all of the symbols exported by the dynamic library in such a way that the linker knows that they have to be dynamically loaded at runtime.

Specifying kind = "dylib" instructs the Rust compiler to link an import library based on the name key. The linker will then use its normal library resolution logic to find that import library. Alternatively, specifying kind = "raw-dylib" instructs the compiler to generate an import library during compilation and provide that to the linker instead.

raw-dylib is only supported on Windows. Using it when targeting other platforms will result in a compiler error.

The import_name_type key

On x86 Windows, names of functions are “decorated” (i.e., have a specific prefix and/or suffix added) to indicate their calling convention. For example, a stdcall calling convention function with the name fn1 that has no arguments would be decorated as _fn1@0. However, the PE Format does also permit names to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains use different decorations for the same calling conventions which means, by default, some Win32 functions cannot be called using the raw-dylib link kind via the GNU toolchain.

To allow for these differences, when using the raw-dylib link kind you may also specify the import_name_type key with one of the following values to change how functions are named in the generated import library:

• decorated: The function name will be fully-decorated using the MSVC toolchain format.
• noprefix: The function name will be decorated using the MSVC toolchain format, but skipping the leading ?, @, or optionally _.
• undecorated: The function name will not be decorated.