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.

Arrays of sizes from 0 to 32 (inclusive) implement the following traits if the element type allows it:

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

This limitation on the size N exists because Rust does not yet support code that is generic over the size of an array type. [Foo; 3] and [Bar; 3] are instances of same generic type [T; 3], but [Foo; 3] and [Foo; 5] are entirely different types. As a stopgap, trait implementations are statically generated up to size 32.

Arrays of any size are Copy if the element type is Copy and Clone if the element type is Clone. This works because Copy and Clone traits are specially known to the compiler.

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() { }

If the array has 32 or fewer elements (see above), 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);

Trait Implementations

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

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

Formats the value using the given formatter.

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

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

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

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

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

Important traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]

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

Mutably borrows from an owned value.

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

Important traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]

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

Performs the conversion.

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

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

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

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

This method tests for !=.

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

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

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

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

This method tests for !=.

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

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

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

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

This method tests for !=.

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

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

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

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

This method tests for !=.

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

type Error = TryFromSliceError

The type returned in the event of a conversion error.

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

Performs the conversion.

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

type Error = TryFromSliceError

The type returned in the event of a conversion error.

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

Performs the conversion.

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

type Error = TryFromSliceError

The type returned in the event of a conversion error.

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

Performs the conversion.

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

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

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

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

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

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.

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.

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

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

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

fn default() -> [T; 4]

Returns the "default value" for a type.

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

fn default() -> [T; 1]

Returns the "default value" for a type.

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

fn default() -> [T; 29]

Returns the "default value" for a type.

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

fn default() -> [T; 30]

Returns the "default value" for a type.

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

fn default() -> [T; 6]

Returns the "default value" for a type.

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

fn default() -> [T; 11]

Returns the "default value" for a type.

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

fn default() -> [T; 19]

Returns the "default value" for a type.

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

fn default() -> [T; 12]

Returns the "default value" for a type.

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

fn default() -> [T; 9]

Returns the "default value" for a type.

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

fn default() -> [T; 27]

Returns the "default value" for a type.

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

fn default() -> [T; 20]

Returns the "default value" for a type.

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

fn default() -> [T; 24]

Returns the "default value" for a type.

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

fn default() -> [T; 21]

Returns the "default value" for a type.

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

fn default() -> [T; 2]

Returns the "default value" for a type.

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

fn default() -> [T; 26]

Returns the "default value" for a type.

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

fn default() -> [T; 28]

Returns the "default value" for a type.

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

fn default() -> [T; 31]

Returns the "default value" for a type.

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

fn default() -> [T; 8]

Returns the "default value" for a type.

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

fn default() -> [T; 23]

Returns the "default value" for a type.

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

fn default() -> [T; 7]

Returns the "default value" for a type.

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

fn default() -> [T; 17]

Returns the "default value" for a type.

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

fn default() -> [T; 15]

Returns the "default value" for a type.

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

fn default() -> [T; 18]

Returns the "default value" for a type.

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

fn default() -> [T; 25]

Returns the "default value" for a type.

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

fn default() -> [T; 3]

Returns the "default value" for a type.

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

fn default() -> [T; 32]

Returns the "default value" for a type.

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

fn default() -> [T; 13]

Returns the "default value" for a type.

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

fn default() -> [T; 5]

Returns the "default value" for a type.

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

fn default() -> [T; 10]

Returns the "default value" for a type.

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

fn default() -> [T; 16]

Returns the "default value" for a type.

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

fn default() -> [T; 22]

Returns the "default value" for a type.

impl<T> Default for [T; 0]

fn default() -> [T; 0]

Returns the "default value" for a type.

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

fn default() -> [T; 14]

Returns the "default value" for a type.

impl<T> LengthAtMost32 for [T; 1]

impl<T> LengthAtMost32 for [T; 27]

impl<T> LengthAtMost32 for [T; 23]

impl<T> LengthAtMost32 for [T; 8]

impl<T> LengthAtMost32 for [T; 2]

impl<T> LengthAtMost32 for [T; 29]

impl<T> LengthAtMost32 for [T; 20]

impl<T> LengthAtMost32 for [T; 0]

impl<T> LengthAtMost32 for [T; 25]

impl<T> LengthAtMost32 for [T; 5]

impl<T> LengthAtMost32 for [T; 31]

impl<T> LengthAtMost32 for [T; 28]

impl<T> LengthAtMost32 for [T; 9]

impl<T> LengthAtMost32 for [T; 18]

impl<T> LengthAtMost32 for [T; 24]

impl<T> LengthAtMost32 for [T; 32]

impl<T> LengthAtMost32 for [T; 16]

impl<T> LengthAtMost32 for [T; 15]

impl<T> LengthAtMost32 for [T; 11]

impl<T> LengthAtMost32 for [T; 30]

impl<T> LengthAtMost32 for [T; 19]

impl<T> LengthAtMost32 for [T; 10]

impl<T> LengthAtMost32 for [T; 3]

impl<T> LengthAtMost32 for [T; 26]

impl<T> LengthAtMost32 for [T; 13]

impl<T> LengthAtMost32 for [T; 22]

impl<T> LengthAtMost32 for [T; 17]

impl<T> LengthAtMost32 for [T; 12]

impl<T> LengthAtMost32 for [T; 7]

impl<T> LengthAtMost32 for [T; 21]

impl<T> LengthAtMost32 for [T; 6]

impl<T> LengthAtMost32 for [T; 14]

impl<T> LengthAtMost32 for [T; 4]

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

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?

Important traits for IterMut<'a, T>

impl<'a, T> Iterator for IterMut<'a, T> type Item = &'a mut T;

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

Creates an iterator from a value.

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

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?

Important traits for Iter<'a, T>

impl<'a, T> Iterator for Iter<'a, T> type Item = &'a T;

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

Creates an iterator from a value.

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

Important traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]

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

Immutably borrows from an owned value.

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

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp #44095)

Restrict a value to a certain interval.

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

Important traits for &'_ [u8]

impl<'_> Read for &'_ [u8]impl<'_> Write for &'_ mut [u8]

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

Performs the conversion.