Struct heapless::Vec

pub struct Vec<T, const N: usize> { /* fields omitted */ }

A fixed capacity Vec

Examples

use heapless::Vec;


// A vector with a fixed capacity of 8 elements allocated on the stack
let mut vec = Vec::<_, 8>::new();
vec.push(1);
vec.push(2);

assert_eq!(vec.len(), 2);
assert_eq!(vec[0], 1);

assert_eq!(vec.pop(), Some(2));
assert_eq!(vec.len(), 1);

vec[0] = 7;
assert_eq!(vec[0], 7);

vec.extend([1, 2, 3].iter().cloned());

for x in &vec {
    println!("{}", x);
}
assert_eq!(*vec, [7, 1, 2, 3]);

Implementations

impl<T, const N: usize> Vec<T, N>

pub const fn new() -> Self

Constructs a new, empty vector with a fixed capacity of N

Examples

use heapless::Vec;

// allocate the vector on the stack
let mut x: Vec<u8, 16> = Vec::new();

// allocate the vector in a static variable
static mut X: Vec<u8, 16> = Vec::new();

Vec const constructor; wrap the returned value in Vec

pub fn from_slice(other: &[T]) -> Result<Self, ()> where
    T: Clone, 

Constructs a new vector with a fixed capacity of N and fills it with the provided slice.

This is equivalent to the following code:

use heapless::Vec;

let mut v: Vec<u8, 16> = Vec::new();
v.extend_from_slice(&[1, 2, 3]).unwrap();

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

Extracts a slice containing the entire vector.

Equivalent to &s[..].

Examples

use heapless::Vec;
let buffer: Vec<u8, 5> = Vec::from_slice(&[1, 2, 3, 5, 8]).unwrap();
assert_eq!(buffer.as_slice(), &[1, 2, 3, 5, 8]);

pub const fn capacity(&self) -> usize

Returns the maximum number of elements the vector can hold.

pub fn clear(&mut self)

Clears the vector, removing all values.

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

Extends the vec from an iterator.

Panic

Panics if the vec cannot hold all elements of the iterator.

pub fn extend_from_slice(&mut self, other: &[T]) -> Result<(), ()> where
    T: Clone, 

Clones and appends all elements in a slice to the Vec.

Iterates over the slice other, clones each element, and then appends it to this Vec. The other vector is traversed in-order.

Examples

use heapless::Vec;

let mut vec = Vec::<u8, 8>::new();
vec.push(1).unwrap();
vec.extend_from_slice(&[2, 3, 4]).unwrap();
assert_eq!(*vec, [1, 2, 3, 4]);

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

Removes the last element from a vector and returns it, or None if it’s empty

pub fn push(&mut self, item: T) -> Result<(), T>

Appends an item to the back of the collection

Returns back the item if the vector is full

pub unsafe fn push_unchecked(&mut self, item: T)

Appends an item to the back of the collection

Safety

This assumes the vec is not full.

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

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

pub fn resize(&mut self, new_len: usize, value: T) -> Result<(), ()> where
    T: Clone, 

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with value. If new_len is less than len, the Vec is simply truncated.

See also resize_default.

pub fn resize_default(&mut self, new_len: usize) -> Result<(), ()> where
    T: Clone + Default, 

Resizes the Vec in-place so that len is equal to new_len.

If new_len is greater than len, the Vec is extended by the difference, with each additional slot filled with Default::default(). If new_len is less than len, the Vec is simply truncated.

See also resize.

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

Forces the length of the vector to new_len.

This is a low-level operation that maintains none of the normal invariants of the type. Normally changing the length of a vector is done using one of the safe operations instead, such as truncate, resize, extend, or clear.

Safety

• new_len must be less than or equal to capacity().
• The elements at old_len..new_len must be initialized.

Examples

This method can be useful for situations in which the vector is serving as a buffer for other code, particularly over FFI:

use heapless::Vec;

pub fn get_dictionary(&self) -> Option<Vec<u8, 32768>> {
    // Per the FFI method's docs, "32768 bytes is always enough".
    let mut dict = Vec::new();
    let mut dict_length = 0;
    // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
    // 1. `dict_length` elements were initialized.
    // 2. `dict_length` <= the capacity (32_768)
    // which makes `set_len` safe to call.
    unsafe {
        // Make the FFI call...
        let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
        if r == Z_OK {
            // ...and update the length to what was initialized.
            dict.set_len(dict_length);
            Some(dict)
        } else {
            None
        }
    }
}

While the following example is sound, there is a memory leak since the inner vectors were not freed prior to the set_len call:

use core::iter::FromIterator;
use heapless::Vec;

let mut vec = Vec::<Vec<u8, 3>, 3>::from_iter(
    [
        Vec::from_iter([1, 0, 0].iter().cloned()),
        Vec::from_iter([0, 1, 0].iter().cloned()),
        Vec::from_iter([0, 0, 1].iter().cloned()),
    ]
    .iter()
    .cloned()
);
// SAFETY:
// 1. `old_len..0` is empty so no elements need to be initialized.
// 2. `0 <= capacity` always holds whatever `capacity` is.
unsafe {
    vec.set_len(0);
}

Normally, here, one would use clear instead to correctly drop the contents and thus not leak memory.

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

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Panics

Panics if index is out of bounds.

Examples

use heapless::Vec;

let mut v: Vec<_, 8> = Vec::new();
v.push("foo").unwrap();
v.push("bar").unwrap();
v.push("baz").unwrap();
v.push("qux").unwrap();

assert_eq!(v.swap_remove(1), "bar");
assert_eq!(&*v, ["foo", "qux", "baz"]);

assert_eq!(v.swap_remove(0), "foo");
assert_eq!(&*v, ["baz", "qux"]);

pub unsafe fn swap_remove_unchecked(&mut self, index: usize) -> T

Removes an element from the vector and returns it.

The removed element is replaced by the last element of the vector.

This does not preserve ordering, but is O(1).

Safety

Assumes index within bounds.

Examples

use heapless::Vec;

let mut v: Vec<_, 8> = Vec::new();
v.push("foo").unwrap();
v.push("bar").unwrap();
v.push("baz").unwrap();
v.push("qux").unwrap();

assert_eq!(unsafe { v.swap_remove_unchecked(1) }, "bar");
assert_eq!(&*v, ["foo", "qux", "baz"]);

assert_eq!(unsafe { v.swap_remove_unchecked(0) }, "foo");
assert_eq!(&*v, ["baz", "qux"]);

pub fn is_full(&self) -> bool

Returns true if the vec is full

pub fn starts_with(&self, needle: &[T]) -> bool where
    T: PartialEq, 

Returns true if needle is a prefix of the Vec.

Always returns true if needle is an empty slice.

Examples

use heapless::Vec;

let v: Vec<_, 8> = Vec::from_slice(b"abc").unwrap();
assert_eq!(v.starts_with(b""), true);
assert_eq!(v.starts_with(b"ab"), true);
assert_eq!(v.starts_with(b"bc"), false);

pub fn ends_with(&self, needle: &[T]) -> bool where
    T: PartialEq, 

Returns true if needle is a suffix of the Vec.

Always returns true if needle is an empty slice.

Examples

use heapless::Vec;

let v: Vec<_, 8> = Vec::from_slice(b"abc").unwrap();
assert_eq!(v.ends_with(b""), true);
assert_eq!(v.ends_with(b"ab"), false);
assert_eq!(v.ends_with(b"bc"), true);

Trait Implementations

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

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

Performs the conversion.

impl<T, const N: usize> AsMut<Vec<T, N>> for Vec<T, N>

fn as_mut(&mut self) -> &mut Self

Performs the conversion.

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

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

Performs the conversion.

impl<T, const N: usize> AsRef<Vec<T, N>> for Vec<T, N>

fn as_ref(&self) -> &Self

Performs the conversion.

impl<T, const N: usize> Clone for Vec<T, N> where
    T: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, const N: usize> Debug for Vec<T, N> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T, const N: usize> Default for Vec<T, N>

fn default() -> Self

Returns the “default value” for a type.

impl<T, const N: usize> Deref for Vec<T, N>

type Target = [T]

The resulting type after dereferencing.

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

Dereferences the value.

impl<T, const N: usize> DerefMut for Vec<T, N>

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

Mutably dereferences the value.

impl<T, const N: usize> Drop for Vec<T, N>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, const N: usize> Extend<&'a T> for Vec<T, N> where
    T: 'a + Copy, 

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = &'a 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<T, const N: usize> Extend<T> for Vec<T, N>

fn extend<I>(&mut self, iter: I) where
    I: IntoIterator<Item = 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<T, const N: usize> FromIterator<T> for Vec<T, N>

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

Creates a value from an iterator.

impl<T, const N: usize> Hash for Vec<T, N> where
    T: 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<T, const N: usize> Hash for Vec<T, N> where
    T: 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, T, const N: usize> IntoIterator for &'a Vec<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?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, const N: usize> IntoIterator for &'a mut Vec<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?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize> IntoIterator for Vec<T, N>

type Item = T

The type of the elements being iterated over.

type IntoIter = IntoIter<T, N>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

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

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

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

#[must_use]

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

This method tests for !=.

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

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

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

#[must_use]

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

This method tests for !=.

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

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

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

#[must_use]

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

This method tests for !=.

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

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

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

#[must_use]

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

This method tests for !=.

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

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

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

#[must_use]

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

This method tests for !=.

impl<A, B, const N1: usize, const N2: usize> PartialEq<Vec<B, N2>> for Vec<A, N1> where
    A: PartialEq<B>, 

fn eq(&self, other: &Vec<B, N2>) -> bool

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

#[must_use]

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

This method tests for !=.

impl<const N: usize> Write for Vec<u8, N>

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a char into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the write! macro with implementors of this trait.

impl<T, const N: usize> Eq for Vec<T, N> where
    T: Eq,