[rustc.git] / src / doc / reference / src / expressions / literal-expr.md

# Literal expressions

> **<sup>Syntax</sup>**\
> _LiteralExpression_ :\
> &nbsp;&nbsp; &nbsp;&nbsp; [CHAR_LITERAL]\
> &nbsp;&nbsp; | [STRING_LITERAL]\
> &nbsp;&nbsp; | [RAW_STRING_LITERAL]\
> &nbsp;&nbsp; | [BYTE_LITERAL]\
> &nbsp;&nbsp; | [BYTE_STRING_LITERAL]\
> &nbsp;&nbsp; | [RAW_BYTE_STRING_LITERAL]\
> &nbsp;&nbsp; | [INTEGER_LITERAL][^out-of-range]\
> &nbsp;&nbsp; | [FLOAT_LITERAL]\
> &nbsp;&nbsp; | `true` | `false`
>
> [^out-of-range]: A value ≥ 2<sup>128</sup> is not allowed.

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][literal tokens] forms described earlier can make up a literal expression, as can the keywords `true` and `false`.

```rust
"hello";   // string type
'5';       // character type
5;         // integer type
```

## Character literal expressions

A character literal expression consists of a single [CHAR_LITERAL] token.

> **Note**: This section is incomplete.

## String literal expressions

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

> **Note**: This section is incomplete.

## Byte literal expressions

A byte literal expression consists of a single [BYTE_LITERAL] token.

> **Note**: This section is incomplete.

## Byte string literal expressions

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

> **Note**: This section is incomplete.

## Integer literal expressions

An integer literal expression consists of a single [INTEGER_LITERAL] token.

If the token has a [suffix], the suffix will be the name of one of the [primitive integer types][numeric 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:

```rust
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 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`, the expression is rejected by the parser.

* 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 consists of a single [FLOAT_LITERAL] token.

If the token has a [suffix], the suffix will be the name of one of the [primitive floating-point types][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:

```rust
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 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`


[boolean type]: ../types/boolean.md
[constant expression]: ../const_eval.md#constant-expressions
[floating-point types]: ../types/numeric.md#floating-point-types
[lint check]: ../attributes/diagnostics.md#lint-check-attributes
[literal tokens]: ../tokens.md#literals
[numeric cast]: operator-expr.md#numeric-cast
[numeric types]: ../types/numeric.md
[suffix]: ../tokens.md#suffixes
[negation operator]: operator-expr.md#negation-operators
[overflow]: operator-expr.md#overflow
[`f32::from_str`]: ../../core/primitive.f32.md#method.from_str
[`f32::INFINITY`]: ../../core/primitive.f32.md#associatedconstant.INFINITY
[`f32::NAN`]: ../../core/primitive.f32.md#associatedconstant.NAN
[`f64::from_str`]: ../../core/primitive.f64.md#method.from_str
[`f64::INFINITY`]: ../../core/primitive.f64.md#associatedconstant.INFINITY
[`f64::NAN`]: ../../core/primitive.f64.md#associatedconstant.NAN
[`u128::from_str_radix`]: ../../core/primitive.u128.md#method.from_str_radix
[CHAR_LITERAL]: ../tokens.md#character-literals
[STRING_LITERAL]: ../tokens.md#string-literals
[RAW_STRING_LITERAL]: ../tokens.md#raw-string-literals
[BYTE_LITERAL]: ../tokens.md#byte-literals
[BYTE_STRING_LITERAL]: ../tokens.md#byte-string-literals
[RAW_BYTE_STRING_LITERAL]: ../tokens.md#raw-byte-string-literals
[INTEGER_LITERAL]: ../tokens.md#integer-literals
[FLOAT_LITERAL]: ../tokens.md#floating-point-literals
Commit	Line	Data
ea8adc8c XL	1	# Literal expressions
ea8adc8c XL	2
8faf50e0 XL	3	> <sup>Syntax</sup>\
	4	> _LiteralExpression_ :\
	5	>       [CHAR_LITERAL]\
	6	>    \| [STRING_LITERAL]\
	7	>    \| [RAW_STRING_LITERAL]\
	8	>    \| [BYTE_LITERAL]\
	9	>    \| [BYTE_STRING_LITERAL]\
	10	>    \| [RAW_BYTE_STRING_LITERAL]\
04454e1e	11	>    \| [INTEGER_LITERAL][^out-of-range]\
8faf50e0	12	>    \| [FLOAT_LITERAL]\
04454e1e FG	13	>    \| `true` \| `false`
	14	>
	15	> [^out-of-range]: A value ≥ 2<sup>128</sup> is not allowed.
abe05a73	16
04454e1e FG	17	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.
	18
	19	A literal is a form of [constant expression], so is evaluated (primarily) at compile time.
	20
	21	Each of the lexical [literal][literal tokens] forms described earlier can make up a literal expression, as can the keywords `true` and `false`.
ea8adc8c XL	22
	23	```rust
	24	"hello"; // string type
	25	'5'; // character type
	26	5; // integer type
	27	```
abe05a73	28
04454e1e FG	29	## Character literal expressions
	30
	31	A character literal expression consists of a single [CHAR_LITERAL] token.
	32
	33	> Note: This section is incomplete.
	34
	35	## String literal expressions
	36
	37	A string literal expression consists of a single [STRING_LITERAL] or [RAW_STRING_LITERAL] token.
	38
	39	> Note: This section is incomplete.
	40
	41	## Byte literal expressions
	42
	43	A byte literal expression consists of a single [BYTE_LITERAL] token.
	44
	45	> Note: This section is incomplete.
	46
	47	## Byte string literal expressions
	48
	49	A string literal expression consists of a single [BYTE_STRING_LITERAL] or [RAW_BYTE_STRING_LITERAL] token.
	50
	51	> Note: This section is incomplete.
	52
	53	## Integer literal expressions
	54
	55	An integer literal expression consists of a single [INTEGER_LITERAL] token.
	56
	57	If the token has a [suffix], the suffix will be the name of one of the [primitive integer types][numeric types]: `u8`, `i8`, `u16`, `i16`, `u32`, `i32`, `u64`, `i64`, `u128`, `i128`, `usize`, or `isize`, and the expression has that type.
	58
	59	If the token has no suffix, the expression's type is determined by type inference:
	60
	61	* If an integer type can be _uniquely_ determined from the surrounding program context, the expression has that type.
	62
	63	* If the program context under-constrains the type, it defaults to the signed 32-bit integer `i32`.
	64
	65	* If the program context over-constrains the type, it is considered a static type error.
	66
	67	Examples of integer literal expressions:
	68
	69	```rust
	70	123; // type i32
	71	123i32; // type i32
	72	123u32; // type u32
	73	123_u32; // type u32
	74	let a: u64 = 123; // type u64
	75
	76	0xff; // type i32
	77	0xff_u8; // type u8
	78
	79	0o70; // type i32
	80	0o70_i16; // type i16
	81
	82	0b1111_1111_1001_0000; // type i32
	83	0b1111_1111_1001_0000i64; // type i64
	84
	85	0usize; // type usize
	86	```
	87
	88	The value of the expression is determined from the string representation of the token as follows:
	89
	90	* An integer radix is chosen by inspecting the first two characters of the string, as follows:
	91
	92	* `0b` indicates radix 2
93	* `0o` indicates radix 8
94	* `0x` indicates radix 16
95	* otherwise the radix is 10.
96
97	* If the radix is not 10, the first two characters are removed from the string.
98
99	* Any underscores are removed from the string.
100
101	* The string is converted to a `u128` value as if by [`u128::from_str_radix`] with the chosen radix.
102	If the value does not fit in `u128`, the expression is rejected by the parser.
103
104	* The `u128` value is converted to the expression's type via a [numeric cast].
105
106	> Note: The final cast will truncate the value of the literal if it does not fit in the expression's type.
107	> `rustc` includes a [lint check] named `overflowing_literals`, defaulting to `deny`, which rejects expressions where this occurs.
108
109	> Note: `-1i8`, for example, is an application of the [negation operator] to the literal expression `1i8`, not a single integer literal expression.
110	> See [Overflow] for notes on representing the most negative value for a signed type.
111
112	## Floating-point literal expressions
113
114	A floating-point literal expression consists of a single [FLOAT_LITERAL] token.
115
116	If the token has a [suffix], the suffix will be the name of one of the [primitive floating-point types][floating-point types]: `f32` or `f64`, and the expression has that type.
117
118	If the token has no suffix, the expression's type is determined by type inference:
119
120	* If a floating-point type can be _uniquely_ determined from the surrounding program context, the expression has that type.
121
122	* If the program context under-constrains the type, it defaults to `f64`.
123
124	* If the program context over-constrains the type, it is considered a static type error.
125
126	Examples of floating-point literal expressions:
127
128	```rust
129	123.0f64; // type f64
130	0.1f64; // type f64
131	0.1f32; // type f32
132	12E+99_f64; // type f64
133	5f32; // type f32
134	let x: f64 = 2.; // type f64
135	```
136
137	The value of the expression is determined from the string representation of the token as follows:
138
139	* Any underscores are removed from the string.
140
141	* The string is converted to the expression's type as if by [`f32::from_str`] or [`f64::from_str`].
142
143	> 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.
144
145	> Note: `inf` and `NaN` are not literal tokens.
146	> The [`f32::INFINITY`], [`f64::INFINITY`], [`f32::NAN`], and [`f64::NAN`] constants can be used instead of literal expressions.
147	> In `rustc`, a literal large enough to be evaluated as infinite will trigger the `overflowing_literals` lint check.
148
149	## Boolean literal expressions
150
151	A boolean literal expression consists of one of the keywords `true` or `false`.
152
153	The expression's type is the primitive [boolean type], and its value is:
154	* true if the keyword is `true`
155	* false if the keyword is `false`
156
157
158	[boolean type]: ../types/boolean.md
159	[constant expression]: ../const_eval.md#constant-expressions
160	[floating-point types]: ../types/numeric.md#floating-point-types
161	[lint check]: ../attributes/diagnostics.md#lint-check-attributes
162	[literal tokens]: ../tokens.md#literals
163	[numeric cast]: operator-expr.md#numeric-cast
164	[numeric types]: ../types/numeric.md
165	[suffix]: ../tokens.md#suffixes
166	[negation operator]: operator-expr.md#negation-operators
167	[overflow]: operator-expr.md#overflow
168	[`f32::from_str`]: ../../core/primitive.f32.md#method.from_str
169	[`f32::INFINITY`]: ../../core/primitive.f32.md#associatedconstant.INFINITY
170	[`f32::NAN`]: ../../core/primitive.f32.md#associatedconstant.NAN
171	[`f64::from_str`]: ../../core/primitive.f64.md#method.from_str
172	[`f64::INFINITY`]: ../../core/primitive.f64.md#associatedconstant.INFINITY
173	[`f64::NAN`]: ../../core/primitive.f64.md#associatedconstant.NAN
174	[`u128::from_str_radix`]: ../../core/primitive.u128.md#method.from_str_radix
416331ca XL	175	[CHAR_LITERAL]: ../tokens.md#character-literals
	176	[STRING_LITERAL]: ../tokens.md#string-literals
	177	[RAW_STRING_LITERAL]: ../tokens.md#raw-string-literals
	178	[BYTE_LITERAL]: ../tokens.md#byte-literals
	179	[BYTE_STRING_LITERAL]: ../tokens.md#byte-string-literals
	180	[RAW_BYTE_STRING_LITERAL]: ../tokens.md#raw-byte-string-literals
	181	[INTEGER_LITERAL]: ../tokens.md#integer-literals
	182	[FLOAT_LITERAL]: ../tokens.md#floating-point-literals