]>
Commit | Line | Data |
---|---|---|
ea8adc8c XL |
1 | # Array and array index expressions |
2 | ||
3 | ## Array expressions | |
4 | ||
8faf50e0 XL |
5 | > **<sup>Syntax</sup>**\ |
6 | > _ArrayExpression_ :\ | |
13cf67c4 XL |
7 | > `[` [_InnerAttribute_]<sup>\*</sup> _ArrayElements_<sup>?</sup> `]` |
8 | > | |
9 | > _ArrayElements_ :\ | |
10 | > [_Expression_] ( `,` [_Expression_] )<sup>\*</sup> `,`<sup>?</sup>\ | |
11 | > | [_Expression_] `;` [_Expression_] | |
ff7c6d11 | 12 | |
416331ca | 13 | An _[array](../types/array.md) expression_ can be written by |
ea8adc8c | 14 | enclosing zero or more comma-separated expressions of uniform type in square |
60c5eb7d | 15 | brackets. This produces an array containing each of these values in the |
ea8adc8c XL |
16 | order they are written. |
17 | ||
18 | Alternatively there can be exactly two expressions inside the brackets, | |
19 | separated by a semi-colon. The expression after the `;` must be a have type | |
0bf4aa26 | 20 | `usize` and be a [constant expression], |
416331ca XL |
21 | such as a [literal](../tokens.md#literals) or a [constant |
22 | item](../items/constant-items.md). `[a; b]` creates an array containing `b` | |
ea8adc8c XL |
23 | copies of the value of `a`. If the expression after the semi-colon has a value |
24 | greater than 1 then this requires that the type of `a` is | |
416331ca | 25 | [`Copy`](../special-types-and-traits.md#copy). |
ea8adc8c XL |
26 | |
27 | ```rust | |
28 | [1, 2, 3, 4]; | |
29 | ["a", "b", "c", "d"]; | |
30 | [0; 128]; // array with 128 zeros | |
ff7c6d11 XL |
31 | [0u8, 0u8, 0u8, 0u8,]; |
32 | [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; // 2D array | |
ea8adc8c XL |
33 | ``` |
34 | ||
13cf67c4 XL |
35 | ### Array expression attributes |
36 | ||
37 | [Inner attributes] are allowed directly after the opening bracket of an array | |
38 | expression in the same expression contexts as [attributes on block | |
39 | expressions]. | |
40 | ||
ea8adc8c XL |
41 | ## Array and slice indexing expressions |
42 | ||
8faf50e0 XL |
43 | > **<sup>Syntax</sup>**\ |
44 | > _IndexExpression_ :\ | |
ff7c6d11 XL |
45 | > [_Expression_] `[` [_Expression_] `]` |
46 | ||
416331ca | 47 | [Array](../types/array.md) and [slice](../types/slice.md)-typed expressions can be |
94b46f34 XL |
48 | indexed by writing a square-bracket-enclosed expression of type `usize` (the |
49 | index) after them. When the array is mutable, the resulting [memory location] | |
50 | can be assigned to. | |
51 | ||
ea8adc8c | 52 | For other types an index expression `a[b]` is equivalent to |
94b46f34 XL |
53 | `*std::ops::Index::index(&a, b)`, or |
54 | `*std::ops::IndexMut::index_mut(&mut a, b)` in a mutable place expression | |
55 | context. Just as with methods, Rust will also insert dereference operations on | |
56 | `a` repeatedly to find an implementation. | |
ea8adc8c | 57 | |
94b46f34 XL |
58 | Indices are zero-based for arrays and slices. Array access is a [constant |
59 | expression], so bounds can be checked at compile-time with a constant index | |
ff7c6d11 XL |
60 | value. Otherwise a check will be performed at run-time that will put the thread |
61 | in a _panicked state_ if it fails. | |
ea8adc8c XL |
62 | |
63 | ```rust,should_panic | |
94b46f34 XL |
64 | // lint is deny by default. |
65 | #![warn(const_err)] | |
66 | ||
ea8adc8c XL |
67 | ([1, 2, 3, 4])[2]; // Evaluates to 3 |
68 | ||
ff7c6d11 XL |
69 | let b = [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; |
70 | b[1][2]; // multidimensional array indexing | |
71 | ||
94b46f34 | 72 | let x = (["a", "b"])[10]; // warning: index out of bounds |
ea8adc8c XL |
73 | |
74 | let n = 10; | |
75 | let y = (["a", "b"])[n]; // panics | |
76 | ||
77 | let arr = ["a", "b"]; | |
94b46f34 | 78 | arr[10]; // warning: index out of bounds |
ea8adc8c | 79 | ``` |
ff7c6d11 XL |
80 | |
81 | The array index expression can be implemented for types other than arrays and slices | |
82 | by implementing the [Index] and [IndexMut] traits. | |
83 | ||
416331ca XL |
84 | [IndexMut]: ../../std/ops/trait.IndexMut.html |
85 | [Index]: ../../std/ops/trait.Index.html | |
86 | [Inner attributes]: ../attributes.md | |
87 | [_Expression_]: ../expressions.md | |
88 | [_InnerAttribute_]: ../attributes.md | |
89 | [attributes on block expressions]: block-expr.md#attributes-on-block-expressions | |
90 | [constant expression]: ../const_eval.md#constant-expressions | |
91 | [memory location]: ../expressions.md#place-expressions-and-value-expressions |