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 [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 homogeneous 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} ");
}

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

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

for x in &array { }

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

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

Arrays can be created from homogeneous tuples of appropriate length:

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

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

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

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

Implementations

source

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

1.55.0source

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

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

If you don’t necessarily need a new fixed-size array, consider using Iterator::map instead.

Note on performance and stack usage

Unfortunately, usages of this method are currently not always optimized as well as they could be. This mainly concerns large arrays, as mapping over small arrays seem to be optimized just fine. Also note that in debug mode (i.e. without any optimizations), this method can use a lot of stack space (a few times the size of the array or more).

Therefore, in performance-critical code, try to avoid using this method on large arrays or check the emitted code. Also try to avoid chained maps (e.g. arr.map(...).map(...)).

In many cases, you can instead use Iterator::map by calling .iter() or .into_iter() on your array. [T; N]::map is only necessary if you really need a new array of the same size as the result. Rust’s lazy iterators tend to get optimized very well.

Examples

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

source

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

🔬This is a nightly-only experimental API. (array_try_map #79711)

A fallible function f applied to each element on array self in order to return an array the same size as self or the first error encountered.

The return type of this function depends on the return type of the closure. If you return Result<T, E> from the closure, you’ll get a Result<[T; N], E>. If you return Option<T> from the closure, you’ll get an Option<[T; N]>.

Examples

#![feature(array_try_map)]
let a = ["1", "2", "3"];
let b = a.try_map(|v| v.parse::<u32>()).unwrap().map(|v| v + 1);
assert_eq!(b, [2, 3, 4]);

let a = ["1", "2a", "3"];
let b = a.try_map(|v| v.parse::<u32>());
assert!(b.is_err());

use std::num::NonZeroU32;
let z = [1, 2, 0, 3, 4];
assert_eq!(z.try_map(NonZeroU32::new), None);
let a = [1, 2, 3];
let b = a.try_map(NonZeroU32::new);
let c = b.map(|x| x.map(NonZeroU32::get));
assert_eq!(c, Some(a));

1.57.0 (const: 1.57.0)source

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

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

1.57.0source

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

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

source

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 avoid moving the original array if its elements are not Copy.

#![feature(array_methods)]

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

source

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

source

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

🔬This is a nightly-only experimental API. (split_array #90091)

Divides one array reference into two at an index.

The first will contain all indices from [0, M) (excluding the index M itself) and the second will contain all indices from [M, N) (excluding the index N itself).

Panics

Panics if M > N.

Examples

#![feature(split_array)]

let v = [1, 2, 3, 4, 5, 6];

{
   let (left, right) = v.split_array_ref::<0>();
   assert_eq!(left, &[]);
   assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<2>();
    assert_eq!(left, &[1, 2]);
    assert_eq!(right, &[3, 4, 5, 6]);
}

{
    let (left, right) = v.split_array_ref::<6>();
    assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
    assert_eq!(right, &[]);
}

source

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

🔬This is a nightly-only experimental API. (split_array #90091)

Divides one mutable array reference into two at an index.

The first will contain all indices from [0, M) (excluding the index M itself) and the second will contain all indices from [M, N) (excluding the index N itself).

Panics

Panics if M > N.

Examples

#![feature(split_array)]

let mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.split_array_mut::<2>();
assert_eq!(left, &mut [1, 0][..]);
assert_eq!(right, &mut [3, 0, 5, 6]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);

source

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

🔬This is a nightly-only experimental API. (split_array #90091)

Divides one array reference into two at an index from the end.

The first will contain all indices from [0, N - M) (excluding the index N - M itself) and the second will contain all indices from [N - M, N) (excluding the index N itself).

Panics

Panics if M > N.

Examples

#![feature(split_array)]

let v = [1, 2, 3, 4, 5, 6];

{
   let (left, right) = v.rsplit_array_ref::<0>();
   assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
   assert_eq!(right, &[]);
}

{
    let (left, right) = v.rsplit_array_ref::<2>();
    assert_eq!(left, &[1, 2, 3, 4]);
    assert_eq!(right, &[5, 6]);
}

{
    let (left, right) = v.rsplit_array_ref::<6>();
    assert_eq!(left, &[]);
    assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
}

source

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

🔬This is a nightly-only experimental API. (split_array #90091)

Divides one mutable array reference into two at an index from the end.

The first will contain all indices from [0, N - M) (excluding the index N - M itself) and the second will contain all indices from [N - M, N) (excluding the index N itself).

Panics

Panics if M > N.

Examples

#![feature(split_array)]

let mut v = [1, 0, 3, 0, 5, 6];
let (left, right) = v.rsplit_array_mut::<4>();
assert_eq!(left, &mut [1, 0]);
assert_eq!(right, &mut [3, 0, 5, 6][..]);
left[1] = 2;
right[1] = 4;
assert_eq!(v, [1, 2, 3, 4, 5, 6]);

source

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

source

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

🔬This is a nightly-only experimental API. (ascii_char #110998)

Converts this array of bytes into a array of ASCII characters, or returns None if any of the characters is non-ASCII.

Examples

#![feature(ascii_char)]
#![feature(const_option)]

const HEX_DIGITS: [std::ascii::Char; 16] =
    *b"0123456789abcdef".as_ascii().unwrap();

assert_eq!(HEX_DIGITS[1].as_str(), "1");
assert_eq!(HEX_DIGITS[10].as_str(), "a");

source

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

🔬This is a nightly-only experimental API. (ascii_char #110998)

Converts this array of bytes into a array of ASCII characters, without checking whether they’re valid.

Safety

Every byte in the array must be in 0..=127, or else this is UB.

source

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

source

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

🔬This is a nightly-only experimental API. (maybe_uninit_uninit_array_transpose #96097)

Transposes a [MaybeUninit<T>; N] into a MaybeUninit<[T; N]>.

Examples

#![feature(maybe_uninit_uninit_array_transpose)]

let data = [MaybeUninit::<u8>::uninit(); 1000];
let data: MaybeUninit<[u8; 1000]> = data.transpose();

Trait Implementations

source

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

source

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

Converts this type into a mutable reference of the (usually inferred) input type.

source

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

source

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

Converts this type into a mutable reference of the (usually inferred) input type.

source

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

source

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

Converts this type into a shared reference of the (usually inferred) input type.

source

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

source

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

Converts this type into a shared reference of the (usually inferred) input type.

1.4.0source

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

source

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

Immutably borrows from an owned value. Read more

1.4.0source

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

source

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

Mutably borrows from an owned value. Read more

1.58.0source

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

source

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

Returns a copy of the value. Read more

source

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

Performs copy-assignment from source. Read more

source

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

source

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

Formats the value using the given formatter. Read more

1.4.0source

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

source

fn default() -> [T; 32]