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; `[` _ArrayElements_<sup>?</sup> `]`
   8 >
   9 > _ArrayElements_ :\
  10 > &nbsp;&nbsp; &nbsp;&nbsp; [_Expression_] ( `,` [_Expression_] )<sup>\*</sup> `,`<sup>?</sup>\
  11 > &nbsp;&nbsp; | [_Expression_] `;` [_Expression_]
  12
  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.
  18 This produces an array containing each of these values in the order they are written.
  19
  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].
  24 An array expression of this form creates an array with the length of the value of the legnth operand with each element a copy of the repeat operand.
  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.
  27
  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.
  31
  32 <div class="warning">
  33
  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.
  35 See [issue #74836](https://github.com/rust-lang/rust/issues/74836).
  36
  37 </div>
  38
  39 ```rust
  40 [1, 2, 3, 4];
  41 ["a", "b", "c", "d"];
  42 [0; 128];              // array with 128 zeros
  43 [0u8, 0u8, 0u8, 0u8,];
  44 [[1, 0, 0], [0, 1, 0], [0, 0, 1]]; // 2D array
  45 const EMPTY: Vec<i32> = Vec::new();
  46 [EMPTY; 2];
  47 ```
  48
  49 ## Array and slice indexing expressions
  50
  51 > **<sup>Syntax</sup>**\
  52 > _IndexExpression_ :\
  53 > &nbsp;&nbsp; [_Expression_] `[` [_Expression_] `]`
  54
  55 [Array] and [slice]-typed values can be indexed by writing a square-bracket-enclosed expression of type `usize` (the index) after them.
  56 When the array is mutable, the resulting [memory location] can be assigned to.
  57
  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.
  60
  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.
  64
  65 ```rust,should_panic
  66 // lint is deny by default.
  67 #![warn(unconditional_panic)]
  68
  69 ([1, 2, 3, 4])[2];        // Evaluates to 3
  70
  71 let b = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
  72 b[1][2];                  // multidimensional array indexing
  73
  74 let x = (["a", "b"])[10]; // warning: index out of bounds
  75
  76 let n = 10;
  77 let y = (["a", "b"])[n];  // panics
  78
  79 let arr = ["a", "b"];
  80 arr[10];                  // warning: index out of bounds
  81 ```
  82
  83 The array index expression can be implemented for types other than arrays and slices by implementing the [Index] and [IndexMut] traits.
  84
  85 [`Copy`]: ../special-types-and-traits.md#copy
  86 [IndexMut]: ../../std/ops/trait.IndexMut.html
  87 [Index]: ../../std/ops/trait.Index.html
  88 [_Expression_]: ../expressions.md
  89 [array]: ../types/array.md
  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 [path]: path-expr.md
  95 [slice]: ../types/slice.md