src/doc/reference/src/expressions/array-expr.md

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