Struct static_alloc::fixed_vec::FixedVec

pub struct FixedVec<'a, T> { /* fields omitted */ }

A Vec-like structure that does not manage its allocation.

This vector type will never (re-)allocate but it can also not free underused memory. As opposed to other similar crates, it does require and additional bounds on its type parameter as it truly manages uninitialized memory to store instances.

Basic Usage

Advanaced Usage

One focus of the library is composability. It should not be surprising that FixedVec interacts with the Slab allocator, which implements a specialized interface providing the Uninit type instead of a raw *const u8. Hence, the FixedVec can use this instead of its own local stack variables.

let alloc: Slab<[u8; 1 << 12]> = Slab::uninit();
let some_usize = alloc.leak(0_usize).unwrap();

let mut vec: FixedVec<&usize> = FixedVec::from_available(
    alloc.get_layout(Layout::new::<[&usize; 1]>()).unwrap().uninit);
// Push the reference to the other allocation.
vec.push(some_usize);

// … do something else

// Ensure lifetimes work out.
drop(vec);

Methods

impl<'_, T> FixedVec<'_, T>

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

Shorten the vector to a maximum length.

If the length is not larger than len this has no effect.

The tail of the vector is dropped starting from the last element. This is opposite to ([WIP] interface does not yet exist) .drain(len..).for_each(drop).

Example

let mut memory: MaybeUninit<[usize; 4]> = MaybeUninit::uninit();
let uninit = Uninit::from(&mut memory).cast_slice().unwrap();
let mut vec = FixedVec::new(uninit);

vec.push(0usize);
vec.push(1usize);
vec.push(2usize);

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

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

Extracts a slice containing the entire vector.

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

Extracts the mutable slice containing the entire vector.

pub fn clear(&mut self)

Remove all elements.

This is an alias for truncate(0).

pub fn len(&self) -> usize

Returns the number of elements in the vector.

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

Set the raw length.

Safety

• new_len must be smaller or equal self.capacity()
• The caller must ensure that all newly referenced elements are properly initialized.

pub fn capacity(&self) -> usize

Returns the number of elements the vector can hold.

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

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

Appends an element to the back of a collection.

Return Err(val) if it is not possible to append the element.

use static_alloc::{FixedVec, Uninit};
use core::mem::MaybeUninit;

// Only enough storage for one element.
let mut allocation: MaybeUninit<[u32; 1]> = MaybeUninit::uninit();
let uninit = Uninit::from_maybe_uninit(&mut allocation);
let mut vec = FixedVec::from_available(uninit);

// First push succeeds.
assert_eq!(vec.push(1), Ok(()));

// The second push fails.
assert_eq!(vec.push(2), Err(2));

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

Removes the last element from a vector and returns it, or None if it is empty.

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

Split the capacity of the collection into two at a given index.

In contrast to Vec::split_off calling this method reduces the capacity of self to at.

Panics

This method panics if at > self.capacity().

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

Extend the vector with as many elements as fit.

Returns the iterator with all elements that were not pushed into the vector.

impl<'a, T> FixedVec<'a, T>

pub fn new(uninit: Uninit<'a, [T]>) -> Self

Create a FixedVec in a pre-allocated region.

The capacity will be that of the underlying allocation.

pub fn from_available<U>(generic: Uninit<'a, U>) -> Self

Create a FixedVec with as large of a capacity as available.

When no aligned slice can be create within the provided memory then the constructor will fallback to an empty dangling slice.

This is only a utility function.

pub fn shrink_to_fit(&mut self) -> Uninit<'a, ()>

Return trailing bytes that can not be used by the FixedVec.

This operation is idempotent.

Trait Implementations

impl<'_, T> DerefMut for FixedVec<'_, T>

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

Mutably dereferences the value.

impl<'_, T> Deref for FixedVec<'_, T>

type Target = [T]

The resulting type after dereferencing.

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

Dereferences the value.

impl<'a, 'b, T: PartialEq> PartialEq<FixedVec<'b, T>> for FixedVec<'a, T>

fn eq(&self, other: &FixedVec<T>) -> bool

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

fn ne(&self, other: &FixedVec<T>) -> bool

This method tests for !=.

impl<'_, T: Eq> Eq for FixedVec<'_, T>

impl<'_, T: Ord> Ord for FixedVec<'_, T>

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

Restrict a value to a certain interval.

impl<'a, 'b, T: PartialOrd> PartialOrd<FixedVec<'b, T>> for FixedVec<'a, T>

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

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

fn lt(&self, other: &FixedVec<T>) -> bool

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

fn le(&self, other: &FixedVec<T>) -> bool

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

fn ge(&self, other: &FixedVec<T>) -> bool

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

fn gt(&self, other: &FixedVec<T>) -> bool

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

impl<'_, T> Drop for FixedVec<'_, T>

fn drop(&mut self)

Executes the destructor for this type.

impl<'_, T, I> Index<I> for FixedVec<'_, T> where
    I: SliceIndex<[T]>, 

type Output = I::Output

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'_, T, I> IndexMut<I> for FixedVec<'_, T> where
    I: SliceIndex<[T]>, 

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

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

impl<'_, T: Hash> Hash for FixedVec<'_, T>

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> AsRef<[T]> for FixedVec<'_, T>

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

Performs the conversion.

impl<'_, T> AsMut<[T]> for FixedVec<'_, T>

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

Performs the conversion.

impl<'_, T> Borrow<[T]> for FixedVec<'_, T>

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

Immutably borrows from an owned value.

impl<'_, T> BorrowMut<[T]> for FixedVec<'_, T>

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

Mutably borrows from an owned value.