Primitive Type array

1.0.0 ·

Expand description

A fixed-size array, denoted [T; N], for the element type, T, and the non-negative compile-time constant size, N.

There are two syntactic forms for creating an array:

A list with each element, i.e., [x, y, z].
A repeat expression [expr; N] where N is how many times to repeat expr in the array. expr must either be:
- A value of a type implementing the Copy trait
- A const value

Note that [expr; 0] is allowed, and produces an empty array. This will still evaluate expr, however, and immediately drop the resulting value, so be mindful of side effects.

Arrays of any size implement the following traits if the element type allows it:

Copy
Clone
Debug
IntoIterator (implemented for [T; N], &[T; N] and &mut [T; N])
PartialEq, PartialOrd, Eq, Ord
Hash
AsRef, AsMut
Borrow, BorrowMut

Arrays of sizes from 0 to 32 (inclusive) implement the Default trait if the element type allows it. As a stopgap, trait implementations are statically generated up to size 32.

Arrays of sizes from 1 to 12 (inclusive) implement From<Tuple>, where Tuple is a homogenous tuple of appropriate length.

Arrays coerce to slices ([T]), so a slice method may be called on an array. Indeed, this provides most of the API for working with arrays.

Slices have a dynamic size and do not coerce to arrays. Instead, use slice.try_into().unwrap() or <ArrayType>::try_from(slice).unwrap().

Array’s try_from(slice) implementations (and the corresponding slice.try_into() array implementations) succeed if the input slice length is the same as the result array length. They optimize especially well when the optimizer can easily determine the slice length, e.g. <[u8; 4]>::try_from(&slice[4..8]).unwrap(). Array implements TryFrom returning:

[T; N] copies from the slice’s elements
&[T; N] references the original slice’s elements
&mut [T; N] references the original slice’s elements

You can move elements out of an array with a slice pattern. If you want one element, see mem::replace.

Examples

let mut array: [i32; 3] = [0; 3];

array[1] = 1;
array[2] = 2;

assert_eq!([1, 2], &array[1..]);

// This loop prints: 0 1 2
for x in array {
    print!("{x} ");
}

Run

You can also iterate over reference to the array’s elements:

let array: [i32; 3] = [0; 3];

for x in &array { }

Run

You can use <ArrayType>::try_from(slice) or slice.try_into() to get an array from a slice:

let bytes: [u8; 3] = [1, 0, 2];
assert_eq!(1, u16::from_le_bytes(<[u8; 2]>::try_from(&bytes[0..2]).unwrap()));
assert_eq!(512, u16::from_le_bytes(bytes[1..3].try_into().unwrap()));

Run

You can use a slice pattern to move elements out of an array:

fn move_away(_: String) { /* Do interesting things. */ }

let [john, roa] = ["John".to_string(), "Roa".to_string()];
move_away(john);
move_away(roa);

Run

Arrays can be created from homogenous tuples of appropriate length:

let tuple: (u32, u32, u32) = (1, 2, 3);
let array: [u32; 3] = tuple.into();

Run

Editions

Prior to Rust 1.53, arrays did not implement IntoIterator by value, so the method call array.into_iter() auto-referenced into a slice iterator. Right now, the old behavior is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring IntoIterator by value. In the future, the behavior on the 2015 and 2018 edition might be made consistent to the behavior of later editions.

// Rust 2015 and 2018:

let array: [i32; 3] = [0; 3];

// This creates a slice iterator, producing references to each value.
for item in array.into_iter().enumerate() {
    let (i, x): (usize, &i32) = item;
    println!("array[{i}] = {x}");
}

// The `array_into_iter` lint suggests this change for future compatibility:
for item in array.iter().enumerate() {
    let (i, x): (usize, &i32) = item;
    println!("array[{i}] = {x}");
}

// You can explicitly iterate an array by value using `IntoIterator::into_iter`
for item in IntoIterator::into_iter(array).enumerate() {
    let (i, x): (usize, i32) = item;
    println!("array[{i}] = {x}");
}

Run

Starting in the 2021 edition, array.into_iter() uses IntoIterator normally to iterate by value, and iter() should be used to iterate by reference like previous editions.

// Rust 2021:

let array: [i32; 3] = [0; 3];

// This iterates by reference:
for item in array.iter().enumerate() {
    let (i, x): (usize, &i32) = item;
    println!("array[{i}] = {x}");
}

// This iterates by value:
for item in array.into_iter().enumerate() {
    let (i, x): (usize, i32) = item;
    println!("array[{i}] = {x}");
}

Run

Future language versions might start treating the array.into_iter() syntax on editions 2015 and 2018 the same as on edition 2021. So code using those older editions should still be written with this change in mind, to prevent breakage in the future. The safest way to accomplish this is to avoid the into_iter syntax on those editions. If an edition update is not viable/desired, there are multiple alternatives:

use iter, equivalent to the old behavior, creating references
use IntoIterator::into_iter, equivalent to the post-2021 behavior (Rust 1.53+)
replace for ... in array.into_iter() { with for ... in array {, equivalent to the post-2021 behavior (Rust 1.53+)

// Rust 2015 and 2018:

let array: [i32; 3] = [0; 3];

// This iterates by reference:
for item in array.iter() {
    let x: &i32 = item;
    println!("{x}");
}

// This iterates by value:
for item in IntoIterator::into_iter(array) {
    let x: i32 = item;
    println!("{x}");
}

// This iterates by value:
for item in array {
    let x: i32 = item;
    println!("{x}");
}

// IntoIter can also start a chain.
// This iterates by value:
for item in IntoIterator::into_iter(array).enumerate() {
    let (i, x): (usize, i32) = item;
    println!("array[{i}] = {x}");
}

Primitive Type array

Implementations§

impl<T, const N: usize> [MaybeUninit<T>; N]

pub const fn transpose(self) -> MaybeUninit<[T; N]>

impl<const N: usize> [u8; N]

pub const fn as_ascii(&self) -> Option<&[AsciiChar; N]>

pub const unsafe fn as_ascii_unchecked(&self) -> &[AsciiChar; N]

impl<T, const N: usize> [T; N]

pub fn map<F, U>(self, f: F) -> [U; N]where F: FnMut(T) -> U,

pub fn try_map<F, R>( self, f: F ) -> <<R as Try>::Residual as Residual<[<R as Try>::Output; N]>>::TryTypewhere F: FnMut(T) -> R, R: Try, <R as Try>::Residual: Residual<[<R as Try>::Output; N]>,

pub fn zip<U>(self, rhs: [U; N]) -> [(T, U); N]

pub const fn as_slice(&self) -> &[T]

pub fn as_mut_slice(&mut self) -> &mut [T]

pub fn each_ref(&self) -> [&T; N]

pub fn each_mut(&mut self) -> [&mut T; N]

pub fn split_array_ref<const M: usize>(&self) -> (&[T; M], &[T])

pub fn split_array_mut<const M: usize>(&mut self) -> (&mut [T; M], &mut [T])

pub fn rsplit_array_ref<const M: usize>(&self) -> (&[T], &[T; M])

pub fn rsplit_array_mut<const M: usize>(&mut self) -> (&mut [T], &mut [T; M])

Trait Implementations§

impl<T, const N: usize> AsMut<[T]> for [T; N]

fn as_mut(&mut self) -> &mut [T]

impl<T, const N: usize> AsMut<[T; N]> for Simd<T, N>where LaneCount<N>: SupportedLaneCount, T: SimdElement,

fn as_mut(&mut self) -> &mut [T; N]

impl<T, const N: usize> AsRef<[T]> for [T; N]

fn as_ref(&self) -> &[T]

impl<T, const N: usize> AsRef<[T; N]> for Simd<T, N>where LaneCount<N>: SupportedLaneCount, T: SimdElement,

fn as_ref(&self) -> &[T; N]

impl<T, const N: usize> Borrow<[T]> for [T; N]

fn borrow(&self) -> &[T]

impl<T, const N: usize> BorrowMut<[T]> for [T; N]

fn borrow_mut(&mut self) -> &mut [T]

impl<T, const N: usize> Clone for [T; N]where T: Clone,

fn clone(&self) -> [T; N]

fn clone_from(&mut self, other: &[T; N])

impl<T, const N: usize> Debug for [T; N]where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

impl<T> Default for [T; 0]

fn default() -> [T; 0]

impl<T> Default for [T; 1]where T: Default,

fn default() -> [T; 1]

impl<T> Default for [T; 10]where T: Default,

fn default() -> [T; 10]

impl<T> Default for [T; 11]where T: Default,

fn default() -> [T; 11]

impl<T> Default for [T; 12]where T: Default,

fn default() -> [T; 12]

impl<T> Default for [T; 13]where T: Default,

fn default() -> [T; 13]

impl<T> Default for [T; 14]where T: Default,

fn default() -> [T; 14]

impl<T> Default for [T; 15]where T: Default,

fn default() -> [T; 15]

impl<T> Default for [T; 16]where T: Default,

fn default() -> [T; 16]

impl<T> Default for [T; 17]where T: Default,

fn default() -> [T; 17]

impl<T> Default for [T; 18]where T: Default,

fn default() -> [T; 18]

impl<T> Default for [T; 19]where T: Default,

fn default() -> [T; 19]

impl<T> Default for [T; 2]where T: Default,

fn default() -> [T; 2]

impl<T> Default for [T; 20]where T: Default,

fn default() -> [T; 20]

impl<T> Default for [T; 21]where T: Default,

fn default() -> [T; 21]

impl<T> Default for [T; 22]where T: Default,

fn default() -> [T; 22]

impl<T> Default for [T; 23]where T: Default,

fn default() -> [T; 23]

impl<T> Default for [T; 24]where T: Default,

fn default() -> [T; 24]

impl<T> Default for [T; 25]where T: Default,

fn default() -> [T; 25]

impl<T> Default for [T; 26]where T: Default,

fn default() -> [T; 26]

impl<T> Default for [T; 27]where T: Default,

fn default() -> [T; 27]

impl<T> Default for [T; 28]where T: Default,