Struct `ArrayVec`

struct ArrayVec<T, CAP: usize> { ... }

A vector with a fixed capacity.

The ArrayVec is a vector backed by a fixed size array. It keeps track of the number of initialized elements. The ArrayVec<T, CAP> is parameterized by T for the element type and CAP for the maximum capacity.

CAP is of type usize but is range limited to u32::MAX; attempting to create larger arrayvecs with larger capacity will panic.

The vector is a contiguous value (storing the elements inline) that you can store directly on the stack if needed.

It offers a simple API but also dereferences to a slice, so that the full slice API is available. The ArrayVec can be converted into a by value iterator.

Implementations

`impl<T, CAP: usize> ArrayVec<T, CAP>`

fn new() -> ArrayVec<T, CAP>

Create a new empty ArrayVec.

The maximum capacity is given by the generic parameter CAP.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 16>::new();
array.push(1);
array.push(2);
assert_eq!(&array[..], &[1, 2]);
assert_eq!(array.capacity(), 16);

const fn new_const() -> ArrayVec<T, CAP>

Create a new empty ArrayVec (const fn).

The maximum capacity is given by the generic parameter CAP.

use arrayvec::ArrayVec;

static ARRAY: ArrayVec<u8, 1024> = ArrayVec::new_const();

const fn len(self: &Self) -> usize

Return the number of elements in the ArrayVec.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);
array.pop();
assert_eq!(array.len(), 2);

const fn is_empty(self: &Self) -> bool

Returns whether the ArrayVec is empty.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1]);
array.pop();
assert_eq!(array.is_empty(), true);

const fn capacity(self: &Self) -> usize

Return the capacity of the ArrayVec.

use arrayvec::ArrayVec;

let array = ArrayVec::from([1, 2, 3]);
assert_eq!(array.capacity(), 3);

const fn is_full(self: &Self) -> bool

Return true if the ArrayVec is completely filled to its capacity, false otherwise.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 1>::new();
assert!(!array.is_full());
array.push(1);
assert!(array.is_full());

const fn remaining_capacity(self: &Self) -> usize

Returns the capacity left in the ArrayVec.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);
array.pop();
assert_eq!(array.remaining_capacity(), 1);

fn push(self: &mut Self, element: T)

Push element to the end of the vector.

Panics if the vector is already full.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

array.push(1);
array.push(2);

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

fn try_push(self: &mut Self, element: T) -> Result<(), CapacityError<T>>

Push element to the end of the vector.

Return Ok if the push succeeds, or return an error if the vector is already full.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

let push1 = array.try_push(1);
let push2 = array.try_push(2);

assert!(push1.is_ok());
assert!(push2.is_ok());

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

let overflow = array.try_push(3);

assert!(overflow.is_err());

unsafe fn push_unchecked(self: &mut Self, element: T)

Push element to the end of the vector without checking the capacity.

It is up to the caller to ensure the capacity of the vector is sufficiently large.

This method uses debug assertions to check that the arrayvec is not full.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

if array.len() + 2 <= array.capacity() {
    unsafe {
        array.push_unchecked(1);
        array.push_unchecked(2);
    }
}

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

fn truncate(self: &mut Self, new_len: usize)

Shortens the vector, keeping the first len elements and dropping the rest.

If len is greater than the vector’s current length this has no effect.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3, 4, 5]);
array.truncate(3);
assert_eq!(&array[..], &[1, 2, 3]);
array.truncate(4);
assert_eq!(&array[..], &[1, 2, 3]);

fn clear(self: &mut Self)

Remove all elements in the vector.

fn insert(self: &mut Self, index: usize, element: T)

Insert element at position index.

Shift up all elements after index.

It is an error if the index is greater than the length or if the arrayvec is full.

Panics if the array is full or the index is out of bounds. See try_insert for fallible version.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

array.insert(0, "x");
array.insert(0, "y");
assert_eq!(&array[..], &["y", "x"]);

fn try_insert(self: &mut Self, index: usize, element: T) -> Result<(), CapacityError<T>>

Insert element at position index.

Shift up all elements after index; the index must be less than or equal to the length.

Returns an error if vector is already at full capacity.

Panics index is out of bounds.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

assert!(array.try_insert(0, "x").is_ok());
assert!(array.try_insert(0, "y").is_ok());
assert!(array.try_insert(0, "z").is_err());
assert_eq!(&array[..], &["y", "x"]);

fn pop(self: &mut Self) -> Option<T>

Remove the last element in the vector and return it.

Return Some( element ) if the vector is non-empty, else None.

use arrayvec::ArrayVec;

let mut array = ArrayVec::<_, 2>::new();

array.push(1);

assert_eq!(array.pop(), Some(1));
assert_eq!(array.pop(), None);

fn swap_remove(self: &mut Self, index: usize) -> T

Remove the element at index and swap the last element into its place.

This operation is O(1).

Return the element if the index is in bounds, else panic.

Panics if the index is out of bounds.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);

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

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

fn swap_pop(self: &mut Self, index: usize) -> Option<T>

Remove the element at index and swap the last element into its place.

This is a checked version of .swap_remove.
This operation is O(1).

Return Some( element ) if the index is in bounds, else None.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);

assert_eq!(array.swap_pop(0), Some(1));
assert_eq!(&array[..], &[3, 2]);

assert_eq!(array.swap_pop(10), None);

fn remove(self: &mut Self, index: usize) -> T

Remove the element at index and shift down the following elements.

The index must be strictly less than the length of the vector.

Panics if the index is out of bounds.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);

let removed_elt = array.remove(0);
assert_eq!(removed_elt, 1);
assert_eq!(&array[..], &[2, 3]);

fn pop_at(self: &mut Self, index: usize) -> Option<T>

Remove the element at index and shift down the following elements.

This is a checked version of .remove(index). Returns None if there is no element at index. Otherwise, return the element inside Some.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3]);

assert!(array.pop_at(0).is_some());
assert_eq!(&array[..], &[2, 3]);

assert!(array.pop_at(2).is_none());
assert!(array.pop_at(10).is_none());

fn retain<F>(self: &mut Self, f: F) where F: FnMut(&mut T) -> bool

Retains only the elements specified by the predicate.

In other words, remove all elements e such that f(&mut e) returns false. This method operates in place and preserves the order of the retained elements.

use arrayvec::ArrayVec;

let mut array = ArrayVec::from([1, 2, 3, 4]);
array.retain(|x| *x & 1 != 0 );
assert_eq!(&array[..], &[1, 3]);

unsafe fn set_len(self: &mut Self, length: usize)

Set the vector’s length without dropping or moving out elements

This method is unsafe because it changes the notion of the number of “valid” elements in the vector. Use with care.

This method uses debug assertions to check that length is not greater than the capacity.

fn try_extend_from_slice(self: &mut Self, other: &[T]) -> Result<(), CapacityError> where T: Copy

Copy all elements from the slice and append to the ArrayVec.

use arrayvec::ArrayVec;

let mut vec: ArrayVec<usize, 10> = ArrayVec::new();
vec.push(1);
vec.try_extend_from_slice(&[2, 3]).unwrap();
assert_eq!(&vec[..], &[1, 2, 3]);

Errors

This method will return an error if the capacity left (see remaining_capacity) is smaller then the length of the provided slice.

fn drain<R>(self: &mut Self, range: R) -> Drain<'_, T, CAP> where R: RangeBounds<usize>

Create a draining iterator that removes the specified range in the vector and yields the removed items from start to end. The element range is removed even if the iterator is not consumed until the end.

Note: It is unspecified how many elements are removed from the vector, if the Drain value is leaked.

Panics if the starting point is greater than the end point or if the end point is greater than the length of the vector.

use arrayvec::ArrayVec;

let mut v1 = ArrayVec::from([1, 2, 3]);
let v2: ArrayVec<_, 3> = v1.drain(0..2).collect();
assert_eq!(&v1[..], &[3]);
assert_eq!(&v2[..], &[1, 2]);

fn into_inner(self: Self) -> Result<[T; CAP], Self>

Return the inner fixed size array, if it is full to its capacity.

Return an Ok value with the array if length equals capacity, return an Err with self otherwise.

unsafe fn into_inner_unchecked(self: Self) -> [T; CAP]

Return the inner fixed size array.

Safety: This operation is safe if and only if length equals capacity.

fn take(self: &mut Self) -> Self

Returns the ArrayVec, replacing the original with a new empty ArrayVec.

use arrayvec::ArrayVec;

let mut v = ArrayVec::from([0, 1, 2, 3]);
assert_eq!([0, 1, 2, 3], v.take().into_inner().unwrap());
assert!(v.is_empty());

fn as_slice(self: &Self) -> &[T]

Return a slice containing all elements of the vector.

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

Return a mutable slice containing all elements of the vector.

fn as_ptr(self: &Self) -> *const T

Return a raw pointer to the vector's buffer.

fn as_mut_ptr(self: &mut Self) -> *mut T

Return a raw mutable pointer to the vector's buffer.

`impl<CAP: usize> Write for ArrayVec<u8, CAP>`

fn write(self: &mut Self, data: &[u8]) -> Result<usize>
fn flush(self: &mut Self) -> Result<()>

`impl<P, T> Receiver for ArrayVec<T, CAP>`

`impl<T> Any for ArrayVec<T, CAP>`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for ArrayVec<T, CAP>`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for ArrayVec<T, CAP>`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for ArrayVec<T, CAP>`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for ArrayVec<T, CAP>`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T> ToOwned for ArrayVec<T, CAP>`

fn to_owned(self: &Self) -> T
fn clone_into(self: &Self, target: &mut T)

`impl<T, CAP: usize> AsMut for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> AsRef for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> Borrow for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> BorrowMut for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> Clone for ArrayVec<T, CAP>`

fn clone(self: &Self) -> Self
fn clone_from(self: &mut Self, rhs: &Self)

`impl<T, CAP: usize> Debug for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> Default for ArrayVec<T, CAP>`

fn default() -> ArrayVec<T, CAP>: Return an empty array

`impl<T, CAP: usize> Deref for ArrayVec<T, CAP>`

fn deref(self: &Self) -> &<Self as >::Target

`impl<T, CAP: usize> DerefMut for ArrayVec<T, CAP>`

fn deref_mut(self: &mut Self) -> &mut <Self as >::Target

`impl<T, CAP: usize> Drop for ArrayVec<T, CAP>`

fn drop(self: &mut Self)

`impl<T, CAP: usize> Eq for ArrayVec<T, CAP>`

`impl<T, CAP: usize> Extend for ArrayVec<T, CAP>`

fn extend<I: IntoIterator<Item = T>>(self: &mut Self, iter: I)

Extend the ArrayVec with an iterator.

Panics if extending the vector exceeds its capacity.

`impl<T, CAP: usize> Freeze for ArrayVec<T, CAP>`

`impl<T, CAP: usize> From for ArrayVec<T, CAP>`

fn from(array: [T; CAP]) -> Self

`impl<T, CAP: usize> FromIterator for ArrayVec<T, CAP>`

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Create an ArrayVec from an iterator.

Panics if the number of elements in the iterator exceeds the arrayvec's capacity.

`impl<T, CAP: usize> Hash for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> IntoIterator for ArrayVec<T, CAP>`

fn into_iter(self: Self) -> IntoIter<T, CAP>

`impl<T, CAP: usize> Ord for ArrayVec<T, CAP>`

fn cmp(self: &Self, other: &Self) -> Ordering

`impl<T, CAP: usize> PartialEq for ArrayVec<T, CAP>`

fn eq(self: &Self, other: &Self) -> bool

`impl<T, CAP: usize> PartialEq for ArrayVec<T, CAP>`

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

`impl<T, CAP: usize> PartialOrd for ArrayVec<T, CAP>`

fn partial_cmp(self: &Self, other: &Self) -> Option<Ordering>
fn lt(self: &Self, other: &Self) -> bool
fn le(self: &Self, other: &Self) -> bool
fn ge(self: &Self, other: &Self) -> bool
fn gt(self: &Self, other: &Self) -> bool

`impl<T, CAP: usize> RefUnwindSafe for ArrayVec<T, CAP>`

`impl<T, CAP: usize> Send for ArrayVec<T, CAP>`

`impl<T, CAP: usize> Sync for ArrayVec<T, CAP>`

`impl<T, CAP: usize> TryFrom for ArrayVec<T, CAP>`

fn try_from(slice: &[T]) -> Result<Self, <Self as >::Error>

`impl<T, CAP: usize> Unpin for ArrayVec<T, CAP>`

`impl<T, CAP: usize> UnsafeUnpin for ArrayVec<T, CAP>`

`impl<T, CAP: usize> UnwindSafe for ArrayVec<T, CAP>`

`impl<T, U> Into for ArrayVec<T, CAP>`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for ArrayVec<T, CAP>`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for ArrayVec<T, CAP>`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>