Struct StackVec 

pub struct StackVec<'mem, T> { /* private fields */ }

A Vec-like implementation on a fixed-size buffer that grows upwards.

StackVec provides a familiar Vec-like interface for managing a contiguous array, but it operates on a pre-allocated slice of memory instead of the heap. It is a LIFO stack that grows from a low memory address towards a higher one.

This is useful for creating dynamic-length collections in environments where heap allocation is not available or desirable.

Layout (high address at the top):

  base (low addr)
    │
    ▼
  [ item1, item2, ... itemN, ... free space ... ]
                            ▲
                            └─ len points here (one-past-end)

Example

use frame_mem_utils::stack::{StackVec, make_storage};
use core::mem::MaybeUninit;

let mut buffer: [MaybeUninit<u8>; 16] = make_storage();
let mut vec = StackVec::from_slice(&mut buffer);

vec.push(10u8).unwrap();
vec.push_slice(&[20, 30]).unwrap();

assert_eq!(vec.len(), 3);
assert_eq!(vec.peek_all(), &[10, 20, 30]);
assert_eq!(vec.pop(), Some(30));

Implementations

impl<'mem, T> StackVec<'mem, T>

pub const fn from_slice(buf: &'mem mut [MaybeUninit<T>]) -> Self

Creates an empty StackVec from a given slice of MaybeUninit<T>.

The vector will use this slice as its backing storage.

pub const fn new_full(buf: &'mem mut [T]) -> Self

where T: Copy,

Creates a StackVec from a slice of already initialized data.

The vector will be full and all elements will be considered live.

pub fn to_slice(self) -> &'mem mut [MaybeUninit<T>]

Converts the StackVec back into the backing slice.

pub fn set_other<'b>(&self, other: &mut StackVec<'b, T>) -> Result<(), usize>

where T: Clone,

Clones the content of this vector to another StackVec.

The other vector will be cleared before the copy.

impl<T> StackVec<'_, T>

pub fn len(&self) -> usize

Returns the number of elements in the vector.

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

this is a weird mix of alloc and free it is mainly used for checkpoints

Safety

1. the length must be in bounds
2. if elements are alloced same as alloc

pub fn capacity(&self) -> usize

pub fn get_base(&self) -> *mut T

Returns a raw pointer to the base of the vector’s buffer.

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements.

pub fn room_left(&self) -> usize

Returns the number of additional elements the vector can hold.

impl<'me, T> StackVec<'me, T>

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

Appends an element to the end of the vector.

Returns Err(v) if the vector is full.

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

Removes the last element from the vector and returns it.

Returns None if the vector is empty.

pub fn push_n<const N: usize>(&mut self, arr: [T; N]) -> Result<(), [T; N]>

Appends an array of N elements to the end of the vector.

Returns Err(arr) if there is not enough room.

pub fn pop_n<const N: usize>(&mut self) -> Option<[T; N]>

Pops an array of N elements from the end of the vector.

Returns None if there are not enough elements.

pub fn pop_many<'b>(&'b mut self, n: usize) -> Option<RefBox<'b, [T]>>

Pops n elements from the vector and returns them as a RefBox<[T]>.

Returns None if there are not enough elements.

pub fn push_slice(&mut self, src: &[T]) -> Option<()>

where T: Clone,

Appends a slice of elements to the end of the vector.

Returns None if there is not enough room.

pub unsafe fn alloc(&mut self, len: usize) -> Option<()>

reserves len uninitialised slots (UB to read them).

Safety

1. the elements must eventually be inilized before a drop
2. no pops or peeks of these slots may happen

pub fn flush(&mut self, len: usize) -> Option<()>

Drops len values from the top (destructors run).

pub fn free(&mut self, len: usize) -> Option<()>

Discards len values from the top (no destructors).

pub fn peek(&self) -> Option<&T>

Returns a reference to the last element of the vector.

pub fn peek_many(&self, n: usize) -> Option<&[T]>

Returns a slice of the last n elements of the vector.

pub fn peek_all<'b>(&'b self) -> &'b [T]

Returns a slice containing all elements in the vector.

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

Returns a mutable reference to the last element of the vector.

pub fn peek_many_mut(&mut self, n: usize) -> Option<&mut [T]>

Returns a mutable slice of the last n elements of the vector.

pub fn peek_all_mut<'b>(&'b mut self) -> &'b mut [T]

Returns a mutable slice of all elements in the vector.

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

Raw pointer to the current top (no lifetime).

pub fn spot(&mut self, n: usize) -> Option<&mut T>

Mutable ref to the n-th value below the top (0 == top).

pub fn spot_raw(&self, n: usize) -> Option<*mut T>

Raw pointer variant (no lifetime).

pub fn get(&self, id: usize) -> Option<&T>

Mutable ref to the n-th value from the start (start==0).

pub fn get_mut(&mut self, id: usize) -> Option<&mut T>

Mutable ref to the n-th value from the start (start==0).

pub fn get_raw(&self, id: usize) -> Option<*mut T>

Pointer to the n-th value from the start (start==0).

pub fn split<'b>(&'b mut self) -> (&'b mut [T], StackVec<'b, T>)

Splits the vector into a slice of its elements and an empty StackVec. (live slice on the left, empty StackVec on the right)

pub fn split_consume(self) -> (&'me mut [T], StackVec<'me, T>)

Consumes the vector and returns a slice of its elements and an empty StackVec.

pub fn split_raw<'b>(&'b mut self) -> (*mut T, StackVec<'b, T>)

Raw pointer to live slice + empty right-hand StackVec (no borrow).

Trait Implementations

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

fn drop(&mut self)

Executes the destructor for this type.

impl<T> Index<usize> for StackVec<'_, T>

type Output = T

The returned type after indexing.

fn index(&self, id: usize) -> &T

Performs the indexing (container[index]) operation.

impl<T> IndexMut<usize> for StackVec<'_, T>

fn index_mut(&mut self, id: usize) -> &mut T

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

impl Write for StackVec<'_, u8>

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

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<'m, T: Send> Send for StackVec<'m, T>

impl<'m, T: Sync> Sync for StackVec<'m, T>