Struct tinyvec::ArrayVec

#[repr(C)]
pub struct ArrayVec<A> { /* fields omitted */ }

An array-backed, vector-like data structure.

• ArrayVec has a fixed capacity, equal to the array size.
• ArrayVec has a variable length, as you add and remove elements. Attempts to fill the vec beyond its capacity will cause a panic.
• All of the vec’s array slots are always initialized in terms of Rust’s memory model. When you remove a element from a location, the old value at that location is replaced with the type’s default value.

The overall API of this type is intended to, as much as possible, emulate the API of the Vec type.

Construction

You can use the array_vec! macro similarly to how you might use the vec! macro. Specify the array type, then optionally give all the initial values you want to have.

let some_ints = array_vec!([i32; 4] => 1, 2, 3);
assert_eq!(some_ints.len(), 3);

The default for an ArrayVec is to have a default array with length 0. The new method is the same as calling default

let some_ints = ArrayVec::<[i32; 7]>::default();
assert_eq!(some_ints.len(), 0);

let more_ints = ArrayVec::<[i32; 7]>::new();
assert_eq!(some_ints, more_ints);

If you have an array and want the whole thing so count as being “in” the new ArrayVec you can use one of the from implementations. If you want part of the array then you can use from_array_len:

let some_ints = ArrayVec::from([5, 6, 7, 8]);
assert_eq!(some_ints.len(), 4);

let more_ints = ArrayVec::from_array_len([5, 6, 7, 8], 2);
assert_eq!(more_ints.len(), 2);

let no_ints: ArrayVec<[u8; 5]> = ArrayVec::from_array_empty([1, 2, 3, 4, 5]);
assert_eq!(no_ints.len(), 0);

Implementations

impl<A: Array> ArrayVec<A>

pub fn append(&mut self, other: &mut Self)

Move all values from other into this vec.

Panics

• If the vec overflows its capacity

Example

let mut av = array_vec!([i32; 10] => 1, 2, 3);
let mut av2 = array_vec!([i32; 10] => 4, 5, 6);
av.append(&mut av2);
assert_eq!(av, &[1, 2, 3, 4, 5, 6][..]);
assert_eq!(av2, &[][..]);

pub fn try_append<'other>(
    &mut self,
    other: &'other mut Self
) -> Option<&'other mut Self>

Move all values from other into this vec. If appending would overflow the capacity, Some(other) is returned.

Example

let mut av = array_vec!([i32; 7] => 1, 2, 3);
let mut av2 = array_vec!([i32; 7] => 4, 5, 6);
av.append(&mut av2);
assert_eq!(av, &[1, 2, 3, 4, 5, 6][..]);
assert_eq!(av2, &[][..]);

let mut av3 = array_vec!([i32; 7] => 7, 8, 9);
assert!(av.try_append(&mut av3).is_some());
assert_eq!(av, &[1, 2, 3, 4, 5, 6][..]);
assert_eq!(av3, &[7, 8, 9][..]);

pub fn as_mut_ptr(&mut self) -> *mut A::Item

A *mut pointer to the backing array.

Safety

This pointer has provenance over the entire backing array.

pub fn as_mut_slice(&mut self) -> &mut [A::Item]

Performs a deref_mut, into unique slice form.

pub fn as_ptr(&self) -> *const A::Item

A *const pointer to the backing array.

Safety

This pointer has provenance over the entire backing array.

pub fn as_slice(&self) -> &[A::Item]

Performs a deref, into shared slice form.

pub fn capacity(&self) -> usize

The capacity of the ArrayVec.

This is fixed based on the array type, but can’t yet be made a const fn on Stable Rust.

pub fn clear(&mut self)

Truncates the ArrayVec down to length 0.

pub fn drain<R>(&mut self, range: R) -> ArrayVecDrain<'_, A::Item> where
    R: RangeBounds<usize>, 

Creates a draining iterator that removes the specified range in the vector and yields the removed items.

Panics

• If the start is greater than the end
• If the end is past the edge of the vec.

Example

let mut av = array_vec!([i32; 4] => 1, 2, 3);
let av2: ArrayVec<[i32; 4]> = av.drain(1..).collect();
assert_eq!(av.as_slice(), &[1][..]);
assert_eq!(av2.as_slice(), &[2, 3][..]);

av.drain(..);
assert_eq!(av.as_slice(), &[]);

pub fn into_inner(self) -> A

Returns the inner array of the ArrayVec.

This returns the full array, even if the ArrayVec length is currently less than that.

Example

let mut favorite_numbers = array_vec!([i32; 5] => 87, 48, 33, 9, 26);
assert_eq!(favorite_numbers.clone().into_inner(), [87, 48, 33, 9, 26]);

favorite_numbers.pop();
assert_eq!(favorite_numbers.into_inner(), [87, 48, 33, 9, 0]);

A use for this function is to build an array from an iterator by first collecting it into an ArrayVec.

let arr_vec: ArrayVec<[i32; 10]> = (1..=3).cycle().take(10).collect();
let inner = arr_vec.into_inner();
assert_eq!(inner, [1, 2, 3, 1, 2, 3, 1, 2, 3, 1]);

pub fn extend_from_slice(&mut self, sli: &[A::Item]) where
    A::Item: Clone, 

Clone each element of the slice into this ArrayVec.

Panics

• If the ArrayVec would overflow, this will panic.

pub fn fill<I: IntoIterator<Item = A::Item>>(&mut self, iter: I) -> I::IntoIter

Fill the vector until its capacity has been reached.

Successively fills unused space in the spare slice of the vector with elements from the iterator. It then returns the remaining iterator without exhausting it. This also allows appending the head of an infinite iterator.

This is an alternative to Extend::extend method for cases where the length of the iterator can not be checked. Since this vector can not reallocate to increase its capacity, it is unclear what to do with remaining elements in the iterator and the iterator itself. The interface also provides no way to communicate this to the caller.

Panics

• If the next method of the provided iterator panics.

Example

let mut av = array_vec!([i32; 4]);
let mut to_inf = av.fill(0..);
assert_eq!(&av[..], [0, 1, 2, 3]);
assert_eq!(to_inf.next(), Some(4));

pub fn from_array_len(data: A, len: usize) -> Self

Wraps up an array and uses the given length as the initial length.

If you want to simply use the full array, use from instead.

Panics

• The length specified must be less than or equal to the capacity of the array.

pub fn insert(&mut self, index: usize, item: A::Item)

Inserts an item at the position given, moving all following elements +1 index.

Panics

• If index > len
• If the capacity is exhausted

Example

use tinyvec::*;
let mut av = array_vec!([i32; 10] => 1, 2, 3);
av.insert(1, 4);
assert_eq!(av.as_slice(), &[1, 4, 2, 3]);
av.insert(4, 5);
assert_eq!(av.as_slice(), &[1, 4, 2, 3, 5]);

pub fn try_insert(&mut self, index: usize, item: A::Item) -> Option<A::Item>

Tries to insert an item at the position given, moving all following elements +1 index. Returns back the element if the capacity is exhausted, otherwise returns None.

Panics

• If index > len

Example

use tinyvec::*;
let mut av = array_vec!([&'static str; 4] => "one", "two", "three");
av.insert(1, "four");
assert_eq!(av.as_slice(), &["one", "four", "two", "three"]);
assert_eq!(av.try_insert(4, "five"), Some("five"));

pub fn is_empty(&self) -> bool

Checks if the length is 0.

pub fn len(&self) -> usize

The length of the ArrayVec (in elements).

pub fn new() -> Self

Makes a new, empty ArrayVec.

pub fn pop(&mut self) -> Option<A::Item>

Remove and return the last element of the vec, if there is one.

Failure

• If the vec is empty you get None.

Example

let mut av = array_vec!([i32; 10] => 1, 2);
assert_eq!(av.pop(), Some(2));
assert_eq!(av.pop(), Some(1));
assert_eq!(av.pop(), None);

pub fn push(&mut self, val: A::Item)

Place an element onto the end of the vec.

Panics

• If the length of the vec would overflow the capacity.

Example

let mut av = array_vec!([i32; 2]);
assert_eq!(&av[..], []);
av.push(1);
assert_eq!(&av[..], [1]);
av.push(2);
assert_eq!(&av[..], [1, 2]);
// av.push(3); this would overflow the ArrayVec and panic!

pub fn try_push(&mut self, val: A::Item) -> Option<A::Item>

Tries to place an element onto the end of the vec.
Returns back the element if the capacity is exhausted, otherwise returns None.

let mut av = array_vec!([i32; 2]);
assert_eq!(av.as_slice(), []);
assert_eq!(av.try_push(1), None);
assert_eq!(&av[..], [1]);
assert_eq!(av.try_push(2), None);
assert_eq!(&av[..], [1, 2]);
assert_eq!(av.try_push(3), Some(3));

pub fn remove(&mut self, index: usize) -> A::Item

Removes the item at index, shifting all others down by one index.

Returns the removed element.

Panics

• If the index is out of bounds.

Example

let mut av = array_vec!([i32; 4] => 1, 2, 3);
assert_eq!(av.remove(1), 2);
assert_eq!(&av[..], [1, 3]);

pub fn resize(&mut self, new_len: usize, new_val: A::Item) where
    A::Item: Clone, 

As resize_with and it clones the value as the closure.

Example

let mut av = array_vec!([&str; 10] => "hello");
av.resize(3, "world");
assert_eq!(&av[..], ["hello", "world", "world"]);

let mut av = array_vec!([i32; 10] => 1, 2, 3, 4);
av.resize(2, 0);
assert_eq!(&av[..], [1, 2]);

pub fn resize_with<F: FnMut() -> A::Item>(&mut self, new_len: usize, f: F)

Resize the vec to the new length.

If it needs to be longer, it’s filled with repeated calls to the provided function. If it needs to be shorter, it’s truncated.

Example

let mut av = array_vec!([i32; 10] => 1, 2, 3);
av.resize_with(5, Default::default);
assert_eq!(&av[..], [1, 2, 3, 0, 0]);

let mut av = array_vec!([i32; 10]);
let mut p = 1;
av.resize_with(4, || {
  p *= 2;
  p
});
assert_eq!(&av[..], [2, 4, 8, 16]);

pub fn retain<F: FnMut(&A::Item) -> bool>(&mut self, acceptable: F)

Walk the vec and keep only the elements that pass the predicate given.

Example

let mut av = array_vec!([i32; 10] => 1, 1, 2, 3, 3, 4);
av.retain(|&x| x % 2 == 0);
assert_eq!(&av[..], [2, 4]);

pub fn set_len(&mut self, new_len: usize)

Forces the length of the vector to new_len.

Panics

• If new_len is greater than the vec’s capacity.

Safety

• This is a fully safe operation! The inactive memory already counts as “initialized” by Rust’s rules.
• Other than “the memory is initialized” there are no other guarantees regarding what you find in the inactive portion of the vec.

pub fn split_off(&mut self, at: usize) -> Self

Splits the collection at the point given.

• [0, at) stays in this vec
• [at, len) ends up in the new vec.

Panics

• if at > len

Example

let mut av = array_vec!([i32; 4] => 1, 2, 3);
let av2 = av.split_off(1);
assert_eq!(&av[..], [1]);
assert_eq!(&av2[..], [2, 3]);

pub fn splice<R, I>(
    &mut self,
    range: R,
    replacement: I
) -> ArrayVecSplice<'_, A, Fuse<I::IntoIter>> where
    R: RangeBounds<usize>,
    I: IntoIterator<Item = A::Item>, 

Creates a splicing iterator that removes the specified range in the vector, yields the removed items, and replaces them with elements from the provided iterator.

splice fuses the provided iterator, so elements after the first None are ignored.

Panics

• If the start is greater than the end.
• If the end is past the edge of the vec.
• If the provided iterator panics.
• If the new length would overflow the capacity of the array. Because ArrayVecSplice adds elements to this vec in its destructor when necessary, this panic would occur when it is dropped.

Example

use tinyvec::*;
let mut av = array_vec!([i32; 4] => 1, 2, 3);
let av2: ArrayVec<[i32; 4]> = av.splice(1.., 4..=6).collect();
assert_eq!(av.as_slice(), &[1, 4, 5, 6][..]);
assert_eq!(av2.as_slice(), &[2, 3][..]);

av.splice(.., None);
assert_eq!(av.as_slice(), &[]);

pub fn swap_remove(&mut self, index: usize) -> A::Item

Remove an element, swapping the end of the vec into its place.

Panics

• If the index is out of bounds.

Example

let mut av = array_vec!([&str; 4] => "foo", "bar", "quack", "zap");

assert_eq!(av.swap_remove(1), "bar");
assert_eq!(&av[..], ["foo", "zap", "quack"]);

assert_eq!(av.swap_remove(0), "foo");
assert_eq!(&av[..], ["quack", "zap"]);

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

Reduces the vec’s length to the given value.

If the vec is already shorter than the input, nothing happens.

pub fn try_from_array_len(data: A, len: usize) -> Result<Self, A>

Wraps an array, using the given length as the starting length.

If you want to use the whole length of the array, you can just use the From impl.

Failure

If the given length is greater than the capacity of the array this will error, and you’ll get the array back in the Err.

impl<A> ArrayVec<A>

pub const fn from_array_empty(data: A) -> Self

Wraps up an array as a new empty ArrayVec.

If you want to simply use the full array, use from instead.

Examples

This method in particular allows to create values for statics:

static DATA: ArrayVec<[u8; 5]> = ArrayVec::from_array_empty([0; 5]);
assert_eq!(DATA.len(), 0);

But of course it is just an normal empty ArrayVec:

let mut data = ArrayVec::from_array_empty([1, 2, 3, 4]);
assert_eq!(&data[..], &[]);
data.push(42);
assert_eq!(&data[..], &[42]);

impl<A: Array> ArrayVec<A>

pub fn grab_spare_slice(&self) -> &[A::Item]

Obtain the shared slice of the array after the active memory.

Example

let mut av = array_vec!([i32; 4]);
assert_eq!(av.grab_spare_slice().len(), 4);
av.push(10);
av.push(11);
av.push(12);
av.push(13);
assert_eq!(av.grab_spare_slice().len(), 0);

pub fn grab_spare_slice_mut(&mut self) -> &mut [A::Item]

Obtain the mutable slice of the array after the active memory.

Example

let mut av = array_vec!([i32; 4]);
assert_eq!(av.grab_spare_slice_mut().len(), 4);
av.push(10);
av.push(11);
assert_eq!(av.grab_spare_slice_mut().len(), 2);

impl<A: Array> ArrayVec<A>

pub fn drain_to_vec_and_reserve(&mut self, n: usize) -> Vec<A::Item>

Drains all elements to a Vec, but reserves additional space

let mut av = array_vec!([i32; 7] => 1, 2, 3);
let v = av.drain_to_vec_and_reserve(10);
assert_eq!(v, &[1, 2, 3]);
assert_eq!(v.capacity(), 13);

pub fn drain_to_vec(&mut self) -> Vec<A::Item>

Drains all elements to a Vec

let mut av = array_vec!([i32; 7] => 1, 2, 3);
let v = av.drain_to_vec();
assert_eq!(v, &[1, 2, 3]);
assert_eq!(v.capacity(), 3);

Trait Implementations

impl<A: Array> AsMut<[<A as Array>::Item]> for ArrayVec<A>

fn as_mut(&mut self) -> &mut [A::Item]

Performs the conversion.

impl<A: Array> AsRef<[<A as Array>::Item]> for ArrayVec<A>

fn as_ref(&self) -> &[A::Item]

Performs the conversion.

impl<A: Array> Binary for ArrayVec<A> where
    A::Item: Binary, 

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

Formats the value using the given formatter.

impl<A: Array> Borrow<[<A as Array>::Item]> for ArrayVec<A>

fn borrow(&self) -> &[A::Item]

Immutably borrows from an owned value.

impl<A: Array> BorrowMut<[<A as Array>::Item]> for ArrayVec<A>

fn borrow_mut(&mut self) -> &mut [A::Item]

Mutably borrows from an owned value.

impl<A> Clone for ArrayVec<A> where
    A: Array + Clone,
    A::Item: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, o: &Self)

Performs copy-assignment from source.

impl<A: Array> Debug for ArrayVec<A> where
    A::Item: Debug, 

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

Formats the value using the given formatter.

impl<A: Array> Default for ArrayVec<A>

fn default() -> Self

Returns the “default value” for a type.

impl<A: Array> Deref for ArrayVec<A>

type Target = [A::Item]

The resulting type after dereferencing.

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

Dereferences the value.

impl<A: Array> DerefMut for ArrayVec<A>

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

Mutably dereferences the value.

impl<'de, A: Array> Deserialize<'de> for ArrayVec<A> where
    A::Item: Deserialize<'de>, 

This is supported on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<A: Array> Display for ArrayVec<A> where
    A::Item: Display, 

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

Formats the value using the given formatter.

impl<A: Array> Extend<<A as Array>::Item> for ArrayVec<A>

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

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<A: Array> From<A> for ArrayVec<A>

fn from(data: A) -> Self

The output has a length equal to the full array.

If you want to select a length, use from_array_len

impl<A: Array> From<ArrayVec<A>> for TinyVec<A>

fn from(arr: ArrayVec<A>) -> Self

Performs the conversion.

impl<A: Array> FromIterator<<A as Array>::Item> for ArrayVec<A>

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

Creates a value from an iterator.

impl<A: Array> Hash for ArrayVec<A> where
    A::Item: Hash, 

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

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<A: Array, I: SliceIndex<[A::Item]>> Index<I> for ArrayVec<A>

type Output = <I as SliceIndex<[A::Item]>>::Output

The returned type after indexing.

fn index(&self, index: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<A: Array, I: SliceIndex<[A::Item]>> IndexMut<I> for ArrayVec<A>

fn index_mut(&mut self, index: I) -> &mut Self::Output

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

impl<A: Array> IntoIterator for ArrayVec<A>

type Item = A::Item

The type of the elements being iterated over.

type IntoIter = ArrayVecIterator<A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, A: Array> IntoIterator for &'a mut ArrayVec<A>

type Item = &'a mut A::Item

The type of the elements being iterated over.

type IntoIter = IterMut<'a, A::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, A: Array> IntoIterator for &'a ArrayVec<A>

type Item = &'a A::Item

The type of the elements being iterated over.

type IntoIter = Iter<'a, A::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<A: Array> LowerExp for ArrayVec<A> where
    A::Item: LowerExp, 

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

Formats the value using the given formatter.

impl<A: Array> LowerHex for ArrayVec<A> where
    A::Item: LowerHex, 

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

Formats the value using the given formatter.

impl<A: Array> Octal for ArrayVec<A> where
    A::Item: Octal, 

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

Formats the value using the given formatter.

impl<A: Array> Ord for ArrayVec<A> where
    A::Item: Ord, 

fn cmp(&self, other: &Self) -> 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

Restrict a value to a certain interval.

impl<A: Array> PartialEq<&'_ [<A as Array>::Item]> for ArrayVec<A> where
    A::Item: PartialEq, 

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array> PartialEq<&'_ A> for ArrayVec<A> where
    A::Item: PartialEq, 

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array> PartialEq<ArrayVec<A>> for ArrayVec<A> where
    A::Item: PartialEq, 

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A: Array> PartialOrd<ArrayVec<A>> for ArrayVec<A> where
    A::Item: PartialOrd, 

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl<A: Array> Pointer for ArrayVec<A> where
    A::Item: Pointer, 

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

Formats the value using the given formatter.

impl<A: Array> Serialize for ArrayVec<A> where
    A::Item: Serialize, 

This is supported on crate feature serde only.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<T, A> TryFrom<&'_ [T]> for ArrayVec<A> where
    T: Clone + Default,
    A: Array<Item = T>, 

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

The output has a length equal to that of the slice, with the same capacity as A.

type Error = TryFromSliceError

The type returned in the event of a conversion error.

impl<A: Array> UpperExp for ArrayVec<A> where
    A::Item: UpperExp, 

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

Formats the value using the given formatter.

impl<A: Array> UpperHex for ArrayVec<A> where
    A::Item: UpperHex, 

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

Formats the value using the given formatter.

impl<A> Copy for ArrayVec<A> where
    A: Array + Copy,
    A::Item: Copy, 

impl<A: Array> Eq for ArrayVec<A> where
    A::Item: Eq,