Struct Arena

pub struct Arena<T, A = DefaultArenaBehavior<T>> { /* private fields */ }

An arena of objects of type T.

use id_arena::Arena;

let mut arena = Arena::<&str>::new();

let a = arena.alloc("Albert");
assert_eq!(arena[a], "Albert");

arena[a] = "Alice";
assert_eq!(arena[a], "Alice");

Implementations

impl<T, A> Arena<T, A>

where A: ArenaBehavior,

pub fn new() -> Arena<T, A>

Construct a new, empty Arena.

use id_arena::Arena;

let mut arena = Arena::<usize>::new();
arena.alloc(42);

pub fn with_capacity(capacity: usize) -> Arena<T, A>

Construct a new, empty Arena with capacity for the given number of elements.

use id_arena::Arena;

let mut arena = Arena::<usize>::with_capacity(100);
for x in 0..100 {
    arena.alloc(x * x);
}

pub fn alloc(&mut self, item: T) -> A::Id

Allocate item within this arena and return its id.

use id_arena::Arena;

let mut arena = Arena::<usize>::new();
let _id = arena.alloc(42);

Panics

Panics if the number of elements in the arena overflows a usize or Id’s index storage representation.

pub fn alloc_with_id(&mut self, f: impl FnOnce(A::Id) -> T) -> A::Id

Allocate an item with the id that it will be assigned.

This is useful for structures that want to store their id as their own member.

use id_arena::{Arena, Id};

struct Cat {
    id: Id<Cat>,
}

let mut arena = Arena::<Cat>::new();

let kitty = arena.alloc_with_id(|id| Cat { id });
assert_eq!(arena[kitty].id, kitty);

pub fn next_id(&self) -> A::Id

Get the id that will be used for the next item allocated into this arena.

If you are allocating a struct that wants to have its id as a member of itself, prefer the less error-prone Arena::alloc_with_id method.

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

Get a shared reference to the object associated with the given id if it exists.

If there is no object associated with id (for example, it might reference an object allocated within a different arena) then return None.

use id_arena::Arena;

let mut arena = Arena::<usize>::new();
let id = arena.alloc(42);
assert!(arena.get(id).is_some());

let other_arena = Arena::<usize>::new();
assert!(other_arena.get(id).is_none());

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

Get an exclusive reference to the object associated with the given id if it exists.

If there is no object associated with id (for example, it might reference an object allocated within a different arena) then return None.

use id_arena::Arena;

let mut arena = Arena::<usize>::new();
let id = arena.alloc(42);
assert!(arena.get_mut(id).is_some());

let mut other_arena = Arena::<usize>::new();
assert!(other_arena.get_mut(id).is_none());

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

Iterate over this arena’s items and their ids.

use id_arena::Arena;

let mut arena = Arena::<&str>::new();

arena.alloc("hello");
arena.alloc("hi");
arena.alloc("yo");

for (id, s) in arena.iter() {
    assert_eq!(arena.get(id).unwrap(), s);
    println!("{:?} -> {}", id, s);
}

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

Iterate over this arena’s items and their ids, allowing mutation of each item.

pub fn len(&self) -> usize

Get the number of objects allocated in this arena.

use id_arena::Arena;

let mut arena = Arena::<&str>::new();

arena.alloc("hello");
arena.alloc("hi");

assert_eq!(arena.len(), 2);

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<T, A> Default for Arena<T, A>

where A: ArenaBehavior,

fn default() -> Arena<T, A>

Returns the “default value” for a type.

impl<T, A> Index<<A as ArenaBehavior>::Id> for Arena<T, A>

where A: ArenaBehavior,

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T, A> IndexMut<<A as ArenaBehavior>::Id> for Arena<T, A>

where A: ArenaBehavior,

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

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

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

where A: ArenaBehavior,

type Item = (<A as ArenaBehavior>::Id, &'a T)

The type of the elements being iterated over.

type IntoIter = Iter<'a, T, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, T, A>

Creates an iterator from a value.

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

where A: ArenaBehavior,

type Item = (<A as ArenaBehavior>::Id, &'a mut T)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IterMut<'a, T, A>

Creates an iterator from a value.

impl<T, A> IntoIterator for Arena<T, A>

where A: ArenaBehavior,

type Item = (<A as ArenaBehavior>::Id, T)

The type of the elements being iterated over.

type IntoIter = IntoIter<T, A>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<T, A>

Creates an iterator from a value.

impl<T: PartialEq, A: PartialEq> PartialEq for Arena<T, A>

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: Eq, A: Eq> Eq for Arena<T, A>

impl<T, A> StructuralPartialEq for Arena<T, A>