.RS File Format – Lexical structure

Raw identifiers

Writing r# before a name lets it be any strict or reserved keyword. The r# is not part of the name, so r#match and an identifier named match in another crate’s edition are the same. This lets code use names that became keywords in a later edition. The five exceptions are r#_, r#crate, r#self, r#Self and r#super, which are errors.

fn r#match(needle: &str, haystack: &str) -> bool {
    haystack.contains(needle)
}

let r#async = 1;    // async is a keyword from edition 2018
let r#gen = 2;      // gen is reserved from edition 2024

Strict keywords

These cannot be used as names of items, variables, parameters, fields, variants, type or lifetime parameters, labels, macros, attributes, macro placeholders or crates.

Reserved keywords

These have the same restrictions as strict keywords but are not used yet.

Weak keywords

These have a special meaning only in certain places and can otherwise be used as names.

In edition 2015, dyn is weak: it is a keyword only in a type position where it is followed by a path that does not start with :: or <, a lifetime, a question mark, a for keyword or an opening parenthesis. From edition 2018 it is a strict keyword.

Escapes

Unlike C, there are no \a, \b, \f or \v escapes and no octal escapes. Use \x08 or \u{8} for a backspace.

Character literals

One Unicode scalar value, or one quote, ASCII or Unicode escape, in single quotes. A literal may not contain an unescaped ', \, line feed, carriage return or tab. A char always holds a whole scalar value, so '😀' is valid.

String literals

Any sequence of Unicode characters between double quotes. A line feed inside the literal is part of the string. A carriage return is not allowed. An unescaped " or \ is not allowed, except for a backslash used as a string continuation.

let a = "one
two";                          // "one\ntwo"
let b = "one \
         two";                 // "one two"; the continuation removes the line feed and leading spaces
let c = "A\x41\u{41}";         // "AAA"

Raw string literals

A raw string starts with r, then zero to 255 # characters, then ". It ends at a " followed by the same number of # characters. Nothing inside is an escape. A carriage return is not allowed.

r"C:\Temp";             // C:\Temp
r#"She said "hi""#;     // She said "hi"
r##"a "# in it"##;      // a "# in it

Byte and byte string literals

A byte literal is one ASCII character (U+0000 to U+007F) or one byte escape between b' and ', and has type u8. A byte string holds ASCII characters and byte escapes between b" and ". Its type is a reference to an array of bytes. Line feeds and string continuations are allowed; carriage returns and non-ASCII characters are not.

A raw byte string starts with br and is delimited like a raw string. Only ASCII is allowed in it.

b'R';       b"\x52";    br"R";       // the byte 82, or strings holding it
b"\\x52";   br"\x52";                // the four bytes \ x 5 2
b"foo #\"# bar";  br##"foo #"# bar"##;

C string literals

A C string literal (edition 2021 and later) holds any Unicode characters except ", \, carriage return and NUL, plus byte and Unicode escapes other than an escape with the value zero. The value is a &'static CStr with a null byte added at the end; no other null byte is allowed. Non-ASCII characters are stored as their UTF-8 bytes, and the literal has no defined encoding beyond that, so c"æ", c"\u{00E6}" and c"\xC3\xA6" are the same.

A raw C string starts with cr and is delimited like a raw string; it takes any Unicode character except NUL and carriage return, and has no escapes. Before edition 2021, c"" reads as the identifier c followed by "".

Integer literals

• _ may appear anywhere after the first digit, or after the radix prefix if at least one digit follows: 0b________1 is valid.
• A leading zero does not mean octal: 010 is the decimal number 10.
• An integer has no sign. -1i8 is two tokens, a - and 1i8.
• A literal too big for its type is rejected by a lint that is deny by default, not by the grammar. 256_u8 is a valid token.
• The token is rejected when a digit is out of range for the radix (0b0102, 0o1279), when a radix prefix has no digit (0b), and for an unsuffixed binary, octal or hexadecimal number directly followed by . and a digit (0x80.0). In these cases it is an error, not two tokens.

Floating-point literals

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

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

• 1.0, 12E+99_f64, 0.1f32 and 2. are floating-point literals.
• 2.f64 is a method call on the integer 2, and 1..2 is a range, so a literal may end in a point only when no ., _ or letter follows.
• An integer literal with an f32 or f64 suffix is accepted as a float expression: 5f32 has type f32.
• A number with no digits after the exponent (2e) is a lexical error.
• A float literal has no sign. -1.0 is two tokens.

Suffixes

A suffix is an identifier written directly after a literal, with no white space. At expression or pattern level, only these are accepted; any other suffix, or any suffix on a non-numeric literal, is rejected:

With no suffix, the type comes from type inference. If nothing constrains it, integer literals default to i32 and floats to f64. A literal’s suffix may not begin with e or E unless it is an exponent; 2em is an error.

Tuple indexes

The number after the dot in t.0 is a tuple index. It uses the same lexical form as a decimal integer but it is compared as the literal token: no leading zeros, no underscores, no suffix and no other radix. t.01, t.0usize and t.0b10 do not refer to a field.