Primitive Type array

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 [x; N], which produces an array with N copies of x. The type of x must be Copy.

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] 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 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.

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);
}

An array itself is not iterable:

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

for x in array { }
// error: the trait bound `[i32; 3]: std::iter::Iterator` is not satisfied

The solution is to coerce the array to a slice by calling a slice method:

for x in array.iter() { }

You can also use the array reference's IntoIterator implementation:

for x in &array { }

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);

Implementations

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

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

🔬 This is a nightly-only experimental API. (array_map #75243)

Returns an array of the same size as self, with function f applied to each element in order.

Examples

#![feature(array_map)]
let x = [1, 2, 3];
let y = x.map(|v| v + 1);
assert_eq!(y, [2, 3, 4]);

let x = [1, 2, 3];
let mut temp = 0;
let y = x.map(|v| { temp += 1; v * temp });
assert_eq!(y, [1, 4, 9]);

let x = ["Ferris", "Bueller's", "Day", "Off"];
let y = x.map(|v| v.len());
assert_eq!(y, [6, 9, 3, 3]);

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

🔬 This is a nightly-only experimental API. (array_zip #80094)

'Zips up' two arrays into a single array of pairs.

zip() returns a new array where every element is a tuple where the first element comes from the first array, and the second element comes from the second array. In other words, it zips two arrays together, into a single one.

Examples

#![feature(array_zip)]
let x = [1, 2, 3];
let y = [4, 5, 6];
let z = x.zip(y);
assert_eq!(z, [(1, 4), (2, 5), (3, 6)]);

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

🔬 This is a nightly-only experimental API. (array_methods #76118)

Returns a slice containing the entire array. Equivalent to &s[..].

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

🔬 This is a nightly-only experimental API. (array_methods #76118)

Returns a mutable slice containing the entire array. Equivalent to &mut s[..].

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

🔬 This is a nightly-only experimental API. (array_methods #76118)

Borrows each element and returns an array of references with the same size as self.

Example

#![feature(array_methods)]

let floats = [3.1, 2.7, -1.0];
let float_refs: [&f64; 3] = floats.each_ref();
assert_eq!(float_refs, [&3.1, &2.7, &-1.0]);

This method is particularly useful if combined with other methods, like map. This way, you can can avoid moving the original array if its elements are not Copy.

#![feature(array_methods, array_map)]

let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
let is_ascii = strings.each_ref().map(|s| s.is_ascii());
assert_eq!(is_ascii, [true, false, true]);

// We can still access the original array: it has not been moved.
assert_eq!(strings.len(), 3);

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

🔬 This is a nightly-only experimental API. (array_methods #76118)

Borrows each element mutably and returns an array of mutable references with the same size as self.

Example

#![feature(array_methods)]

let mut floats = [3.1, 2.7, -1.0];
let float_refs: [&mut f64; 3] = floats.each_mut();
*float_refs[0] = 0.0;
assert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]);
assert_eq!(floats, [0.0, 2.7, -1.0]);

Trait Implementations

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

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Immutably borrows from an owned value.

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

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

Mutably borrows from an owned value.

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

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

Formats the value using the given formatter.

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

pub fn default() -> [T; 20]

Returns the "default value" for a type.

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

pub fn default() -> [T; 28]

Returns the "default value" for a type.

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

pub fn default() -> [T; 8]

Returns the "default value" for a type.

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

pub fn default() -> [T; 19]

Returns the "default value" for a type.

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

pub fn default() -> [T; 24]

Returns the "default value" for a type.

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

pub fn default() -> [T; 23]

Returns the "default value" for a type.

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

pub fn default() -> [T; 16]

Returns the "default value" for a type.

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

pub fn default() -> [T; 25]

Returns the "default value" for a type.

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

pub fn default() -> [T; 14]

Returns the "default value" for a type.

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

pub fn default() -> [T; 18]

Returns the "default value" for a type.

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

pub fn default() -> [T; 10]

Returns the "default value" for a type.

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

pub fn default() -> [T; 2]

Returns the "default value" for a type.

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

pub fn default() -> [T; 12]

Returns the "default value" for a type.

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

pub fn default() -> [T; 7]

Returns the "default value" for a type.

impl<T> Default for [T; 0]

pub fn default() -> [T; 0]

Returns the "default value" for a type.

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

pub fn default() -> [T; 15]

Returns the "default value" for a type.

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

pub fn default() -> [T; 6]

Returns the "default value" for a type.

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

pub fn default() -> [T; 3]

Returns the "default value" for a type.

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

pub fn default() -> [T; 17]

Returns the "default value" for a type.

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

pub fn default() -> [T; 32]

Returns the "default value" for a type.

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

pub fn default() -> [T; 21]

Returns the "default value" for a type.

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

pub fn default() -> [T; 26]

Returns the "default value" for a type.

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

pub fn default() -> [T; 1]

Returns the "default value" for a type.

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

pub fn default() -> [T; 13]

Returns the "default value" for a type.

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

pub fn default() -> [T; 4]

Returns the "default value" for a type.

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

pub fn default() -> [T; 27]

Returns the "default value" for a type.

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

pub fn default() -> [T; 9]

Returns the "default value" for a type.

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

pub fn default() -> [T; 30]

Returns the "default value" for a type.

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

pub fn default() -> [T; 22]

Returns the "default value" for a type.

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

pub fn default() -> [T; 31]

Returns the "default value" for a type.

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

pub fn default() -> [T; 29]

Returns the "default value" for a type.

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

pub fn default() -> [T; 11]

Returns the "default value" for a type.

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

pub fn default() -> [T; 5]

Returns the "default value" for a type.

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

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

pub fn hash<H>(&self, state: &mut H) where
    H: Hasher, 

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

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

type Output = <[T] as Index<I>>::Output

The returned type after indexing.

pub fn index(&self, index: I) -> &<[T; N] as Index<I>>::Output

Performs the indexing (container[index]) operation.

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

pub fn index_mut(&mut self, index: I) -> &mut <[T; N] as Index<I>>::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T, const N: usize> IntoIterator for &'a [T; N]

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T>

Which kind of iterator are we turning this into?

pub fn into_iter(self) -> Iter<'a, T>

Creates an iterator from a value.

impl<'a, T, const N: usize> IntoIterator for &'a mut [T; N]

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T>

Which kind of iterator are we turning this into?

pub fn into_iter(self) -> IterMut<'a, T>

Creates an iterator from a value.

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

Implements comparison of arrays lexicographically.

pub fn cmp(&self, other: &[T; N]) -> Ordering

This method returns an Ordering between self and other.

#[must_use]pub fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]pub fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]pub fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<'_, A, B, const N: usize> PartialEq<&'_ [B]> for [A; N] where
    A: PartialEq<B>, 

pub fn eq(&self, other: &&[B]) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &&[B]) -> bool

This method tests for !=.

impl<'_, A, B, const N: usize> PartialEq<&'_ mut [B]> for [A; N] where
    A: PartialEq<B>, 

pub fn eq(&self, other: &&mut [B]) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &&mut [B]) -> bool

This method tests for !=.

impl<A, B, const N: usize> PartialEq<[B; N]> for [A; N] where
    A: PartialEq<B>, 

pub fn eq(&self, other: &[B; N]) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &[B; N]) -> bool

This method tests for !=.

impl<A, B, const N: usize> PartialEq<[B]> for [A; N] where
    A: PartialEq<B>, 

pub fn eq(&self, other: &[B]) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &[B]) -> bool

This method tests for !=.

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

pub fn partial_cmp(&self, other: &[T; N]) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

pub fn lt(&self, other: &[T; N]) -> bool

This method tests less than (for self and other) and is used by the < operator.

pub fn le(&self, other: &[T; N]) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

pub fn ge(&self, other: &[T; N]) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

pub fn gt(&self, other: &[T; N]) -> bool

This method tests greater than (for self and other) and is used by the > operator.

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

type Item = T

🔬 This is a nightly-only experimental API. (slice_pattern #56345)

stopgap trait for slice patterns

The element type of the slice being matched on.

pub fn as_slice(&self) -> &[<[T; N] as SlicePattern>::Item]

🔬 This is a nightly-only experimental API. (slice_pattern #56345)

stopgap trait for slice patterns

Currently, the consumers of SlicePattern need a slice.

impl<'_, T, const N: usize> TryFrom<&'_ [T]> for [T; N] where
    T: Copy, 

type Error = TryFromSliceError

The type returned in the event of a conversion error.

pub fn try_from(slice: &[T]) -> Result<[T; N], TryFromSliceError>

Performs the conversion.

impl<'a, T, const N: usize> TryFrom<&'a [T]> for &'a [T; N]

type Error = TryFromSliceError

The type returned in the event of a conversion error.

pub fn try_from(slice: &[T]) -> Result<&[T; N], TryFromSliceError>

Performs the conversion.

impl<'a, T, const N: usize> TryFrom<&'a mut [T]> for &'a mut [T; N]

type Error = TryFromSliceError

The type returned in the event of a conversion error.

pub fn try_from(slice: &mut [T]) -> Result<&mut [T; N], TryFromSliceError>

Performs the conversion.

impl<T, A, const N: usize> TryFrom<Vec<T, A>> for [T; N] where
    A: Allocator, 

type Error = Vec<T, A>

The type returned in the event of a conversion error.

pub fn try_from(vec: Vec<T, A>) -> Result<[T; N], Vec<T, A>>

Gets the entire contents of the Vec<T> as an array, if its size exactly matches that of the requested array.

Examples

use std::convert::TryInto;
assert_eq!(vec![1, 2, 3].try_into(), Ok([1, 2, 3]));
assert_eq!(<Vec<i32>>::new().try_into(), Ok([]));

If the length doesn't match, the input comes back in Err:

use std::convert::TryInto;
let r: Result<[i32; 4], _> = (0..10).collect::<Vec<_>>().try_into();
assert_eq!(r, Err(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]));

If you're fine with just getting a prefix of the Vec<T>, you can call .truncate(N) first.

use std::convert::TryInto;
let mut v = String::from("hello world").into_bytes();
v.sort();
v.truncate(2);
let [a, b]: [_; 2] = v.try_into().unwrap();
assert_eq!(a, b' ');
assert_eq!(b, b'd');