Struct generational_arena::Arena

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

The Arena allows inserting and removing elements that are referred to by Index.

See the module-level documentation for example usage and motivation.

Methods

impl<T> Arena<T>

pub fn new() -> Arena<T>

Constructs a new, empty Arena.

Examples

use generational_arena::Arena;

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

pub fn with_capacity(n: usize) -> Arena<T>

Constructs a new, empty Arena<T> with the specified capacity.

The Arena<T> will be able to hold n elements without further allocation.

Examples

use generational_arena::Arena;

let mut arena = Arena::with_capacity(10);

// These insertions will not require further allocation.
for i in 0..10 {
    assert!(arena.try_insert(i).is_ok());
}

// But now we are at capacity, and there is no more room.
assert!(arena.try_insert(99).is_err());

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

Attempts to insert value into the arena using existing capacity.

This method will never allocate new capacity in the arena.

If insertion succeeds, then the value's index is returned. If insertion fails, then Err(value) is returned to give ownership of value back to the caller.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();

match arena.try_insert(42) {
    Ok(idx) => {
        // Insertion succeeded.
        assert_eq!(arena[idx], 42);
    }
    Err(x) => {
        // Insertion failed.
        assert_eq!(x, 42);
    }
};

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

Insert value into the arena, allocating more capacity if necessary.

The value's associated index in the arena is returned.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();

let idx = arena.insert(42);
assert_eq!(arena[idx], 42);

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

Remove the element at index i from the arena.

If the element at index i is still in the arena, then it is returned. If it is not in the arena, then None is returned.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx = arena.insert(42);

assert_eq!(arena.remove(idx), Some(42));
assert_eq!(arena.remove(idx), None);

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

Is the element at index i in the arena?

Returns true if the element at i is in the arena, false otherwise.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx = arena.insert(42);

assert!(arena.contains(idx));
arena.remove(idx);
assert!(!arena.contains(idx));

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

Get a shared reference to the element at index i if it is in the arena.

If the element at index i is not in the arena, then None is returned.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx = arena.insert(42);

assert_eq!(arena.get(idx), Some(&42));
arena.remove(idx);
assert!(arena.get(idx).is_none());

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

Get an exclusive reference to the element at index i if it is in the arena.

If the element at index i is not in the arena, then None is returned.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx = arena.insert(42);

*arena.get_mut(idx).unwrap() += 1;
assert_eq!(arena.remove(idx), Some(43));
assert!(arena.get_mut(idx).is_none());

pub fn capacity(&self) -> usize

Get the capacity of this arena.

The capacity is the maximum number of elements the arena can hold without further allocation, including however many it currently contains.

Examples

use generational_arena::Arena;

let mut arena = Arena::with_capacity(10);
assert_eq!(arena.capacity(), 10);

// `try_insert` does not allocate new capacity.
for i in 0..10 {
    assert!(arena.try_insert(1).is_ok());
    assert_eq!(arena.capacity(), 10);
}

// But `insert` will if the arena is already at capacity.
arena.insert(0);
assert!(arena.capacity() > 10);

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

Allocate space for additional_capacity more elements in the arena.

Panics

Panics if this causes the capacity to overflow.

Examples

use generational_arena::Arena;

let mut arena = Arena::with_capacity(10);
arena.reserve(5);
assert_eq!(arena.capacity(), 15);

Important traits for Iter<'a, T>

impl<'a, T> Iterator for Iter<'a, T> type Item = (Index, &'a T);

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

Iterate over shared references to the elements in this arena.

Yields pairs of (Index, &T) items.

Order of iteration is not defined.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
for i in 0..10 {
    arena.insert(i * i);
}

for (idx, value) in arena.iter() {
    println!("{} is at index {:?}", value, idx);
}

Important traits for IterMut<'a, T>

impl<'a, T> Iterator for IterMut<'a, T> type Item = (Index, &'a mut T);

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

Iterate over exclusive references to the elements in this arena.

Yields pairs of (Index, &mut T) items.

Order of iteration is not defined.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
for i in 0..10 {
    arena.insert(i * i);
}

for (_idx, value) in arena.iter_mut() {
    *value += 5;
}

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> IntoIterator for Arena<T>

type Item = 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.

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> Extend<T> for Arena<T>

fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

impl<T> FromIterator<T> for Arena<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

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.