Struct Arena

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

Container that can have elements inserted into it and removed from it.

Indices use the Index type, created by inserting values with Arena::insert.

Implementations

impl<T> Arena<T>

pub const fn new() -> Self

Construct an empty arena.

pub fn with_capacity(capacity: usize) -> Self

Construct an empty arena with space to hold exactly capacity elements without reallocating.

pub const fn len(&self) -> usize

Return the number of elements contained in the arena.

pub fn capacity(&self) -> usize

Return the number of elements the arena can hold without allocating, including the elements currently in the arena.

pub const fn is_empty(&self) -> bool

Returns whether the arena is empty.

pub fn insert(&mut self, value: T) -> Index

Insert a new value into the arena, returning an index that can be used to later retrieve the value.

pub fn insert_at(&mut self, index: Index, value: T) -> Option<T>

Insert a new value at a given index, returning the old value if present. The entry’s generation is set to the given index’s generation.

Caveats

This method is capable of “resurrecting” an old Index. This is unavoidable; if we already have an occupied entry (or had) at this index of some generation M, and then insert_at that same slot but with a generation N < M, eventually after some number of insertions and removals it is possible we could end up with an index matching that old index. There are few cases where this is likely to be a problem, but it is still possible.

pub fn insert_at_slot(&mut self, slot: u32, value: T) -> (Index, Option<T>)

Insert a new value at a given slot, returning the old value if present. If the slot is already occupied, this will increment the generation of the slot, and invalidate any previous indices pointing to it.

pub fn contains(&self, index: Index) -> bool

Returns true if the given index is valid for the arena.

pub fn contains_slot(&self, slot: u32) -> Option<Index>

Checks to see whether a slot is occupied in the arena, and if it is, returns Some with the true Index of that slot (slot plus generation.) Otherwise, returns None.

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

Get an immutable reference to a value inside the arena by Index, returning None if the index is not contained in the arena.

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

Get a mutable reference to a value inside the arena by Index, returning None if the index is not contained in the arena.

pub fn get2_mut( &mut self, index1: Index, index2: Index, ) -> (Option<&mut T>, Option<&mut T>)

Get mutable references of two values inside this arena at once by Index, returning None if the corresponding index is not contained in this arena.

Panics

This function panics when the two indices are equal (having the same slot number and generation).

pub fn remove(&mut self, index: Index) -> Option<T>

Remove the value contained at the given index from the arena, returning it if it was present.

pub fn invalidate(&mut self, index: Index) -> Option<Index>

Invalidate the given index and return a new index to the same value. This is roughly equivalent to remove followed by insert, but much faster. If the old index is already invalid, this method returns None.

pub fn get_by_slot(&self, slot: u32) -> Option<(Index, &T)>

Attempt to look up the given slot in the arena, disregarding any generational information, and retrieve an immutable reference to it. Returns None if the slot is empty.

pub fn get_by_slot_mut(&mut self, slot: u32) -> Option<(Index, &mut T)>

Attempt to look up the given slot in the arena, disregarding any generational information, and retrieve a mutable reference to it. Returns None if the slot is empty.

pub fn remove_by_slot(&mut self, slot: u32) -> Option<(Index, T)>

Remove an entry in the arena by its slot, disregarding any generational info. Returns None if the slot was already empty.

pub fn clear(&mut self)

Clear the arena and drop all elements.

pub fn iter(&self) -> Iter<'_, T>

Iterate over all of the indexes and values contained in the arena.

Iteration order is not defined.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

Iterate over all of the indexes and values contained in the arena, with mutable access to each value.

Iteration order is not defined.

pub fn drain(&mut self) -> Drain<'_, T>

Returns an iterator that removes each element from the arena.

Iteration order is not defined.

If the iterator is dropped before it is fully consumed, any uniterated items will be dropped from the arena, and the arena will be empty. The arena’s capacity will not be changed.

pub fn retain<F: FnMut(Index, &mut T) -> bool>(&mut self, f: F)

Remove all entries in the Arena which don’t satisfy the provided predicate.

Trait Implementations

impl<T: Clone> Clone for Arena<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Arena<T>

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

Formats the value using the given formatter.

impl<T> Default for Arena<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Index<Index> for Arena<T>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Index> for Arena<T>

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

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

impl<'a, T> IntoIterator for &'a Arena<T>

type Item = (Index, &'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> IntoIterator for &'a mut Arena<T>

type Item = (Index, &'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> IntoIterator for Arena<T>

type Item = (Index, T)

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.