Struct StableVec 

pub struct StableVec<T> { /* private fields */ }

A Vec<T>-like collection that maintains stable indices for its elements.

Unlike with a standard Vec<T>, removing elements from a StableVec<T> is O(1), and it does not move other elements or invalidate their indices. This is achieved by internally storing each element as an Option<T>, and reusing freed slots for new elements.

Overiew of Important Methods

• push adds a new element and returns its stable index (O(1)).
• remove removes an element at a given index and returns it (O(1)).
• try_remove attempts to remove an element at a given index, returning None if it doesn’t exist (O(1)).
• get and get_mut provide access to elements by index (O(1)).
• clear removes all elements without deallocating memory (O(1)).

Implementations

impl<T> StableVec<T>

pub const fn new() -> Self

Creates a new empty StableVec.

pub fn with_capacity(capacity: usize) -> Self

Creates a new StableVec with the given initial capacity.

This is useful for preallocating space to avoid reallocations.

pub fn push(&mut self, element: T) -> usize

Pushes a new element to the first available slot, returning its index.

This may reuse a previously freed slot.

Time Complexity

O(1)

pub fn next_push_index(&self) -> usize

Returns the next index that will be used for a push.

This index may reuse a previously freed slot.

Time Complexity

O(1)

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

Removes the element at the given index, returning it.

Time Complexity

O(1)

Panics

Panics if there is no element at the given index.

pub fn try_remove(&mut self, index: usize) -> Option<T>

Tries to remove the element at the given index, returning it if it existed.

Time Complexity

O(1)

pub fn clear(&mut self)

Removes all elements from the StableVec.

No memory is deallocated, so the capacity remains the same.

Time Complexity

O(1)

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

Returns a reference to the element at the given index, if it exists.

Time Complexity

O(1)

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

Returns a mutable reference to the element at the given index, if it exists.

Time Complexity

O(1)

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

Returns a reference to the element at the given index without bounds checking.

Time Complexity

O(1)

Safety

The caller must ensure that the index is in bounds and that there is an element at that index.

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

Returns a mutable reference to the element at the given index without bounds checking.

Time Complexity

O(1)

Safety

The caller must ensure that the index is in bounds and that there is an element at that index.

pub fn get_disjoint_mut2( &mut self, index1: usize, index2: usize, ) -> Option<[&mut T; 2]>

Returns mutable references to two disjoint elements at the given indices, if they exist.

If the indices are the same, or if either index is out of bounds or has no element, None is returned.

Time Complexity

O(1)

pub unsafe fn get_disjoint_mut_unchecked( &mut self, index1: usize, index2: usize, ) -> [&mut T; 2]

Returns mutable references to two disjoint elements at the given indices without bounds checking.

If the indices are the same, or if either index has no element, the behavior is undefined.

Time Complexity

O(1)

Safety

The caller must ensure that the indices are disjoint and that there are elements at both indices.

pub fn len(&self) -> usize

Returns the number of elements in the StableVec.

Time Complexity

O(1)

pub fn is_empty(&self) -> bool

Returns true if the StableVec is empty.

Time Complexity

O(1)

pub fn capacity(&self) -> usize

Returns the capacity of the StableVec.

Time Complexity

O(1)

pub fn iter(&self) -> impl Iterator<Item = (usize, &T)>

Returns an iterator over the elements and indices of the StableVec.

pub fn iter_mut(&mut self) -> impl Iterator<Item = (usize, &mut T)>

Returns a mutable iterator over the elements and indices of the StableVec.

Trait Implementations

impl<T: Clone> Clone for StableVec<T>

fn clone(&self) -> StableVec<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for StableVec<T>

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

Formats the value using the given formatter.

impl<T> Default for StableVec<T>

fn default() -> Self

Creates a new empty StableVec.

impl<T> Index<usize> for StableVec<T>

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

Returns a reference to the element at the given index.

Time Complexity

O(1)

Panics

Panics if there is no element at the given index.

type Output = T

The returned type after indexing.

impl<T> IndexMut<usize> for StableVec<T>

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

Returns a mutable reference to the element at the given index.

Time Complexity

O(1)

Panics

Panics if there is no element at the given index.

impl<T> IntoIterator for StableVec<T>

type Item = T

The type of the elements being iterated over.

type IntoIter = StableVecIntoIterator<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.