Struct Arena 

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

Generational arena. See the module-level docs.

Examples

use arena_lib::Arena;

let mut arena = Arena::new();
let a = arena.insert("alpha");
let b = arena.insert("bravo");

assert_eq!(arena.len(), 2);
assert_eq!(arena.get(a), Some(&"alpha"));

let removed = arena.remove(a);
assert_eq!(removed, Some("alpha"));
assert!(arena.get(a).is_none()); // stale handle
assert_eq!(arena.get(b), Some(&"bravo"));

Implementations

impl<T> Arena<T>

pub const fn new() -> Self

Creates an empty arena that performs no allocation until first insert.

pub fn with_capacity(capacity: usize) -> Self

Creates an empty arena with space pre-reserved for capacity elements.

The arena will still grow on demand; this is a hint, not a hard cap.

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements.

pub const fn len(&self) -> usize

Number of live elements currently in the arena.

pub const fn is_empty(&self) -> bool

Returns true when the arena holds no live elements.

pub fn capacity(&self) -> usize

Returns the number of slots the arena can hold before reallocating.

This counts both occupied and vacant slots.

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

Returns true if the index refers to a live element.

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

Returns a shared reference to the element behind idx, or None if the handle is stale.

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

Returns a unique reference to the element behind idx, or None if the handle is stale.

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

Inserts value and returns a fresh Index.

Panics on the catastrophic case where the slot counter would overflow u32::MAX. Use Arena::try_insert for an explicit fallible variant.

pub fn try_insert(&mut self, value: T) -> Result<Index>

Inserts value, returning an Index on success or Error::CounterOverflow if the arena cannot represent more slots.

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

Removes the element behind idx and returns it, or None if the handle is stale.

The slot’s generation counter advances so the consumed handle — and any other handle previously issued for the same slot — never resolves again, even if the slot is reused by a later insert.

Examples

use arena_lib::Arena;

let mut arena = Arena::new();
let h = arena.insert("payload");

assert_eq!(arena.remove(h), Some("payload"));
assert_eq!(arena.remove(h), None); // stale on every subsequent call

pub fn clear(&mut self)

Removes every element and resets the free list.

Underlying capacity is retained. Generation counters are preserved, so handles issued before the clear remain stale afterwards.

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

Returns an iterator over (Index, &T) for every live element.

Vacant slots are skipped; iteration order follows slot indices, which is not the insertion order if any removals have happened.

Examples

use arena_lib::Arena;

let mut arena = Arena::new();
let _a = arena.insert("alpha");
let killed = arena.insert("dead");
let _b = arena.insert("bravo");
arena.remove(killed);

let live: Vec<&&str> = arena.iter().map(|(_idx, value)| value).collect();
assert_eq!(live, vec![&"alpha", &"bravo"]);

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

Returns an iterator over (Index, &mut T) for every live element.

Trait Implementations

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.