Literal expressions

Syntax
LiteralExpression :
      CHAR_LITERAL
   | STRING_LITERAL
   | RAW_STRING_LITERAL
   | BYTE_LITERAL
   | BYTE_STRING_LITERAL
   | RAW_BYTE_STRING_LITERAL
   | C_STRING_LITERAL
   | RAW_C_STRING_LITERAL
   | INTEGER_LITERAL
   | FLOAT_LITERAL
   | true | false

A literal expression is an expression consisting of a single token, rather than a sequence of tokens, that immediately and directly denotes the value it evaluates to, rather than referring to it by name or some other evaluation rule.

A literal is a form of constant expression, so is evaluated (primarily) at compile time.

Each of the lexical literal forms described earlier can make up a literal expression, as can the keywords true and false.

#![allow(unused)]
fn main() {
"hello";   // string type
'5';       // character type
5;         // integer type
}

In the descriptions below, the string representation of a token is the sequence of characters from the input which matched the token’s production in a Lexer grammar snippet.

Note: this string representation never includes a character U+000D (CR) immediately followed by U+000A (LF): this pair would have been previously transformed into a single U+000A (LF).

Escapes

The descriptions of textual literal expressions below make use of several forms of escape.

Each form of escape is characterised by:

  • an escape sequence: a sequence of characters, which always begins with U+005C (\)
  • an escaped value: either a single character or an empty sequence of characters

In the definitions of escapes below:

  • An octal digit is any of the characters in the range [0-7].
  • A hexadecimal digit is any of the characters in the ranges [0-9], [a-f], or [A-F].

Simple escapes

Each sequence of characters occurring in the first column of the following table is an escape sequence.

In each case, the escaped value is the character given in the corresponding entry in the second column.

Escape sequenceEscaped value
\0U+0000 (NUL)
\tU+0009 (HT)
\nU+000A (LF)
\rU+000D (CR)
\"U+0022 (QUOTATION MARK)
\'U+0027 (APOSTROPHE)
\\U+005C (REVERSE SOLIDUS)

8-bit escapes

The escape sequence consists of \x followed by two hexadecimal digits.

The escaped value is the character whose Unicode scalar value is the result of interpreting the final two characters in the escape sequence as a hexadecimal integer, as if by u8::from_str_radix with radix 16.

Note: the escaped value therefore has a Unicode scalar value in the range of u8.

7-bit escapes

The escape sequence consists of \x followed by an octal digit then a hexadecimal digit.

The escaped value is the character whose Unicode scalar value is the result of interpreting the final two characters in the escape sequence as a hexadecimal integer, as if by u8::from_str_radix with radix 16.

Unicode escapes

The escape sequence consists of \u{, followed by a sequence of characters each of which is a hexadecimal digit or _, followed by }.

The escaped value is the character whose Unicode scalar value is the result of interpreting the hexadecimal digits contained in the escape sequence as a hexadecimal integer, as if by u32::from_str_radix with radix 16.

Note: the permitted forms of a CHAR_LITERAL or STRING_LITERAL token ensure that there is such a character.

String continuation escapes

The escape sequence consists of \ followed immediately by U+000A (LF), and all following whitespace characters before the next non-whitespace character. For this purpose, the whitespace characters are U+0009 (HT), U+000A (LF), U+000D (CR), and U+0020 (SPACE).

The escaped value is an empty sequence of characters.

Note: The effect of this form of escape is that a string continuation skips following whitespace, including additional newlines. Thus a, b and c are equal:

#![allow(unused)]
fn main() {
let a = "foobar";
let b = "foo\
         bar";
let c = "foo\

     bar";

assert_eq!(a, b);
assert_eq!(b, c);
}

Skipping additional newlines (as in example c) is potentially confusing and unexpected. This behavior may be adjusted in the future. Until a decision is made, it is recommended to avoid relying on skipping multiple newlines with line continuations. See this issue for more information.

Character literal expressions

A character literal expression consists of a single CHAR_LITERAL token.

The expression’s type is the primitive char type.

The token must not have a suffix.

The token’s literal content is the sequence of characters following the first U+0027 (') and preceding the last U+0027 (') in the string representation of the token.

The literal expression’s represented character is derived from the literal content as follows:

  • If the literal content is one of the following forms of escape sequence, the represented character is the escape sequence’s escaped value:

  • Otherwise the represented character is the single character that makes up the literal content.

The expression’s value is the char corresponding to the represented character’s Unicode scalar value.

Note: the permitted forms of a CHAR_LITERAL token ensure that these rules always produce a single character.

Examples of character literal expressions:

#![allow(unused)]
fn main() {
'R';                               // R
'\'';                              // '
'\x52';                            // R
'\u{00E6}';                        // LATIN SMALL LETTER AE (U+00E6)
}

String literal expressions

A string literal expression consists of a single STRING_LITERAL or RAW_STRING_LITERAL token.

The expression’s type is a shared reference (with static lifetime) to the primitive str type. That is, the type is &'static str.

The token must not have a suffix.

The token’s literal content is the sequence of characters following the first U+0022 (") and preceding the last U+0022 (") in the string representation of the token.

The literal expression’s represented string is a sequence of characters derived from the literal content as follows:

The expression’s value is a reference to a statically allocated str containing the UTF-8 encoding of the represented string.

Examples of string literal expressions:

#![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 literal expressions

A byte literal expression consists of a single BYTE_LITERAL token.

The expression’s type is the primitive u8 type.

The token must not have a suffix.

The token’s literal content is the sequence of characters following the first U+0027 (') and preceding the last U+0027 (') in the string representation of the token.

The literal expression’s represented character is derived from the literal content as follows:

  • If the literal content is one of the following forms of escape sequence, the represented character is the escape sequence’s escaped value:

  • Otherwise the represented character is the single character that makes up the literal content.

The expression’s value is the represented character’s Unicode scalar value.

Note: the permitted forms of a BYTE_LITERAL token ensure that these rules always produce a single character, whose Unicode scalar value is in the range of u8.

Examples of byte literal expressions:

#![allow(unused)]
fn main() {
b'R';                              // 82
b'\'';                             // 39
b'\x52';                           // 82
b'\xA0';                           // 160
}

Byte string literal expressions

A byte string literal expression consists of a single BYTE_STRING_LITERAL or RAW_BYTE_STRING_LITERAL token.

The expression’s type is a shared reference (with static lifetime) to an array whose element type is u8. That is, the type is &'static [u8; N], where N is the number of bytes in the represented string described below.

The token must not have a suffix.

The token’s literal content is the sequence of characters following the first U+0022 (") and preceding the last U+0022 (") in the string representation of the token.

The literal expression’s represented string is a sequence of characters derived from the literal content as follows:

The expression’s value is a reference to a statically allocated array containing the Unicode scalar values of the characters in the represented string, in the same order.

Note: the permitted forms of BYTE_STRING_LITERAL and RAW_BYTE_STRING_LITERAL tokens ensure that these rules always produce array element values in the range of u8.

Examples of byte string literal expressions:

#![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 literal expressions

A C string literal expression consists of a single C_STRING_LITERAL or RAW_C_STRING_LITERAL token.

The expression’s type is a shared reference (with static lifetime) to the standard library CStr type. That is, the type is &'static core::ffi::CStr.

The token must not have a suffix.

The token’s literal content is the sequence of characters following the first " and preceding the last " in the string representation of the token.

The literal expression’s represented bytes are a sequence of bytes derived from the literal content as follows:

Note: the permitted forms of C_STRING_LITERAL and RAW_C_STRING_LITERAL tokens ensure that the represented bytes never include a null byte.

The expression’s value is a reference to a statically allocated CStr whose array of bytes contains the represented bytes followed by a null byte.

Examples of C string literal expressions:

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

c"æ";                                // LATIN SMALL LETTER AE (U+00E6)
c"\u{00E6}";                         // LATIN SMALL LETTER AE (U+00E6)
c"\xC3\xA6";                         // LATIN SMALL LETTER AE (U+00E6)

c"\xE6".to_bytes();                  // [230]
c"\u{00E6}".to_bytes();              // [195, 166]
}

Integer literal expressions

An integer literal expression consists of a single INTEGER_LITERAL token.

If the token has a suffix, the suffix must be the name of one of the primitive integer types: u8, i8, u16, i16, u32, i32, u64, i64, u128, i128, usize, or isize, and the expression has that type.

If the token has no suffix, the expression’s type is determined by type inference:

  • If an integer type can be uniquely determined from the surrounding program context, the expression has that type.

  • If the program context under-constrains the type, it defaults to the signed 32-bit integer i32.

  • If the program context over-constrains the type, it is considered a static type error.

Examples of integer literal expressions:

#![allow(unused)]
fn main() {
123;                               // type i32
123i32;                            // type i32
123u32;                            // type u32
123_u32;                           // type u32
let a: u64 = 123;                  // type u64

0xff;                              // type i32
0xff_u8;                           // type u8

0o70;                              // type i32
0o70_i16;                          // type i16

0b1111_1111_1001_0000;             // type i32
0b1111_1111_1001_0000i64;          // type i64

0usize;                            // type usize
}

The value of the expression is determined from the string representation of the token as follows:

  • An integer radix is chosen by inspecting the first two characters of the string, as follows:

    • 0b indicates radix 2
    • 0o indicates radix 8
    • 0x indicates radix 16
    • otherwise the radix is 10.

  • If the radix is not 10, the first two characters are removed from the string.

  • Any suffix is removed from the string.

  • Any underscores are removed from the string.

  • The string is converted to a u128 value as if by u128::from_str_radix with the chosen radix. If the value does not fit in u128, it is a compiler error.

  • The u128 value is converted to the expression’s type via a numeric cast.

Note: The final cast will truncate the value of the literal if it does not fit in the expression’s type. rustc includes a lint check named overflowing_literals, defaulting to deny, which rejects expressions where this occurs.

Note: -1i8, for example, is an application of the negation operator to the literal expression 1i8, not a single integer literal expression. See Overflow for notes on representing the most negative value for a signed type.

Floating-point literal expressions

A floating-point literal expression has one of two forms:

If the token has a suffix, the suffix must be the name of one of the primitive floating-point types: f32 or f64, and the expression has that type.

If the token has no suffix, the expression’s type is determined by type inference:

  • If a floating-point type can be uniquely determined from the surrounding program context, the expression has that type.

  • If the program context under-constrains the type, it defaults to f64.

  • If the program context over-constrains the type, it is considered a static type error.

Examples of floating-point literal expressions:

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

The value of the expression is determined from the string representation of the token as follows:

  • Any suffix is removed from the string.

  • Any underscores are removed from the string.

  • The string is converted to the expression’s type as if by f32::from_str or f64::from_str.

Note: -1.0, for example, is an application of the negation operator to the literal expression 1.0, not a single floating-point literal expression.

Note: inf and NaN are not literal tokens. The f32::INFINITY, f64::INFINITY, f32::NAN, and f64::NAN constants can be used instead of literal expressions. In rustc, a literal large enough to be evaluated as infinite will trigger the overflowing_literals lint check.

Boolean literal expressions

A boolean literal expression consists of one of the keywords true or false.

The expression’s type is the primitive boolean type, and its value is:

  • true if the keyword is true
  • false if the keyword is false