]>
Commit | Line | Data |
---|---|---|
ea8adc8c XL |
1 | # Array and array index expressions |
2 | ||
3 | ## Array expressions | |
4 | ||
8faf50e0 XL |
5 | > **<sup>Syntax</sup>**\ |
6 | > _ArrayExpression_ :\ | |
136023e0 | 7 | > `[` _ArrayElements_<sup>?</sup> `]` |
13cf67c4 XL |
8 | > |
9 | > _ArrayElements_ :\ | |
10 | > [_Expression_] ( `,` [_Expression_] )<sup>\*</sup> `,`<sup>?</sup>\ | |
11 | > | [_Expression_] `;` [_Expression_] | |
ff7c6d11 | 12 | |
cdc7bbd5 XL |
13 | *Array expressions* construct [arrays][array]. |
14 | Array expressions come in two forms. | |
15 | ||
16 | The first form lists out every value in the array. | |
17 | The syntax for this form is a comma-separated list of expressions of uniform type enclosed in square brackets. | |
6a06907d | 18 | This produces an array containing each of these values in the order they are written. |
ea8adc8c | 19 | |
cdc7bbd5 XL |
20 | The syntax for the second form is two expressions separated by a semicolon (`;`) enclosed in square brackets. |
21 | The expression before the `;` is called the *repeat operand*. | |
22 | The expression after the `;` is called the *length operand*. | |
23 | It must have type `usize` and be a [constant expression], such as a [literal] or a [constant item]. | |
94222f64 | 24 | An array expression of this form creates an array with the length of the value of the length operand with each element being a copy of the repeat operand. |
cdc7bbd5 XL |
25 | That is, `[a; b]` creates an array containing `b` copies of the value of `a`. |
26 | If the length operand has a value greater than 1 then this requires that the type of the repeat operand is [`Copy`] or that it must be a [path] to a constant item. | |
5869c6ff | 27 | |
cdc7bbd5 XL |
28 | When the repeat operand is a constant item, it is evaluated the length operand's value times. |
29 | If that value is `0`, then the constant item is not evaluated at all. | |
30 | For expressions that are not a constant item, it is evaluated exactly once, and then the result is copied the length operand's value times. | |
5869c6ff XL |
31 | |
32 | <div class="warning"> | |
33 | ||
cdc7bbd5 | 34 | Warning: In the case where the length operand is 0, and the repeat operand is a non-constant item, there is currently a bug in `rustc` where the value `a` is evaluated but not dropped, thus causing a leak. |
6a06907d | 35 | See [issue #74836](https://github.com/rust-lang/rust/issues/74836). |
5869c6ff XL |
36 | |
37 | </div> | |
ea8adc8c XL |
38 | |
39 | ```rust | |
40 | [1, 2, 3, 4]; | |
41 | ["a", "b", "c", "d"]; | |
42 | [0; 128]; // array with 128 zeros | |
ff7c6d11 XL |
43 | [0u8, 0u8, 0u8, 0u8,]; |
44 | [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; // 2D array | |
5869c6ff XL |
45 | const EMPTY: Vec<i32> = Vec::new(); |
46 | [EMPTY; 2]; | |
ea8adc8c XL |
47 | ``` |
48 | ||
49 | ## Array and slice indexing expressions | |
50 | ||
8faf50e0 XL |
51 | > **<sup>Syntax</sup>**\ |
52 | > _IndexExpression_ :\ | |
ff7c6d11 XL |
53 | > [_Expression_] `[` [_Expression_] `]` |
54 | ||
cdc7bbd5 | 55 | [Array] and [slice]-typed values can be indexed by writing a square-bracket-enclosed expression of type `usize` (the index) after them. |
5869c6ff | 56 | When the array is mutable, the resulting [memory location] can be assigned to. |
94b46f34 | 57 | |
6a06907d XL |
58 | For other types an index expression `a[b]` is equivalent to `*std::ops::Index::index(&a, b)`, or `*std::ops::IndexMut::index_mut(&mut a, b)` in a mutable place expression context. |
59 | Just as with methods, Rust will also insert dereference operations on `a` repeatedly to find an implementation. | |
ea8adc8c | 60 | |
6a06907d XL |
61 | Indices are zero-based for arrays and slices. |
62 | Array access is a [constant expression], so bounds can be checked at compile-time with a constant index value. | |
63 | Otherwise a check will be performed at run-time that will put the thread in a _panicked state_ if it fails. | |
ea8adc8c XL |
64 | |
65 | ```rust,should_panic | |
94b46f34 | 66 | // lint is deny by default. |
74b04a01 | 67 | #![warn(unconditional_panic)] |
94b46f34 | 68 | |
ea8adc8c XL |
69 | ([1, 2, 3, 4])[2]; // Evaluates to 3 |
70 | ||
ff7c6d11 XL |
71 | let b = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; |
72 | b[1][2]; // multidimensional array indexing | |
73 | ||
94b46f34 | 74 | let x = (["a", "b"])[10]; // warning: index out of bounds |
ea8adc8c XL |
75 | |
76 | let n = 10; | |
77 | let y = (["a", "b"])[n]; // panics | |
78 | ||
79 | let arr = ["a", "b"]; | |
94b46f34 | 80 | arr[10]; // warning: index out of bounds |
ea8adc8c | 81 | ``` |
ff7c6d11 | 82 | |
6a06907d | 83 | The array index expression can be implemented for types other than arrays and slices by implementing the [Index] and [IndexMut] traits. |
ff7c6d11 | 84 | |
5869c6ff | 85 | [`Copy`]: ../special-types-and-traits.md#copy |
416331ca XL |
86 | [IndexMut]: ../../std/ops/trait.IndexMut.html |
87 | [Index]: ../../std/ops/trait.Index.html | |
416331ca | 88 | [_Expression_]: ../expressions.md |
5869c6ff | 89 | [array]: ../types/array.md |
416331ca | 90 | [constant expression]: ../const_eval.md#constant-expressions |
5869c6ff XL |
91 | [constant item]: ../items/constant-items.md |
92 | [literal]: ../tokens.md#literals | |
416331ca | 93 | [memory location]: ../expressions.md#place-expressions-and-value-expressions |
cdc7bbd5 | 94 | [path]: path-expr.md |
5869c6ff | 95 | [slice]: ../types/slice.md |