Struct generational_arena::Arena

source ·

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

Expand description

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

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

Implementations§

source §

impl<T> Arena<T>

source

pub fn new() -> Arena<T>

Constructs a new, empty Arena.

Examples

use generational_arena::Arena;

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

source

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());

source

pub fn clear(&mut self)

Clear all the items inside the arena, but keep its allocation.

Examples

use generational_arena::Arena;

let mut arena = Arena::with_capacity(1);
arena.insert(42);
arena.insert(43);

arena.clear();

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

source

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);
    }
};

source

pub fn try_insert_with<F: FnOnce(Index) -> T>( &mut self, create: F ) -> Result<Index, F>

Attempts to insert the value returned by create into the arena using existing capacity. create is called with the new value’s associated index, allowing values that know their own index.

This method will never allocate new capacity in the arena.

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

Examples

use generational_arena::{Arena, Index};

let mut arena = Arena::new();

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

source

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);

source

pub fn insert_with(&mut self, create: impl FnOnce(Index) -> T) -> Index

Insert the value returned by create into the arena, allocating more capacity if necessary. create is called with the new value’s associated index, allowing values that know their own index.

The new value’s associated index in the arena is returned.

Examples

use generational_arena::{Arena, Index};

let mut arena = Arena::new();

let idx = arena.insert_with(|idx| (42, idx));
assert_eq!(arena[idx].0, 42);
assert_eq!(arena[idx].1, idx);

source

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);

source

pub fn retain(&mut self, predicate: impl FnMut(Index, &mut T) -> bool)

Retains only the elements specified by the predicate.

In other words, remove all indices such that predicate(index, &value) returns false.

Examples

use generational_arena::Arena;

let mut crew = Arena::new();
crew.extend(&["Jim Hawkins", "John Silver", "Alexander Smollett", "Israel Hands"]);
let pirates = ["John Silver", "Israel Hands"]; // too dangerous to keep them around
crew.retain(|_index, member| !pirates.contains(member));
let mut crew_members = crew.iter().map(|(_, member)| **member);
assert_eq!(crew_members.next(), Some("Jim Hawkins"));
assert_eq!(crew_members.next(), Some("Alexander Smollett"));
assert!(crew_members.next().is_none());

source

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));

source

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());

source

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());

source

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

Get a pair of exclusive references to the elements at index i1 and i2 if it is in the arena.

If the element at index i1 or i2 is not in the arena, then None is returned for this element.

Panics

Panics if i1 and i2 are pointing to the same item of the arena.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx1 = arena.insert(0);
let idx2 = arena.insert(1);

{
    let (item1, item2) = arena.get2_mut(idx1, idx2);

    *item1.unwrap() = 3;
    *item2.unwrap() = 4;
}

assert_eq!(arena[idx1], 3);
assert_eq!(arena[idx2], 4);

source

pub fn len(&self) -> usize

Get the length of this arena.

The length is the number of elements the arena holds.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
assert_eq!(arena.len(), 0);

let idx = arena.insert(42);
assert_eq!(arena.len(), 1);

let _ = arena.insert(0);
assert_eq!(arena.len(), 2);

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

source

pub fn is_empty(&self) -> bool

Returns true if the arena contains no elements

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
assert!(arena.is_empty());

let idx = arena.insert(42);
assert!(!arena.is_empty());

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

source

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);

source

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);

source

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);
}

source

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;
}

source

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

Iterate over elements of the arena and remove them.

Yields pairs of (Index, T) items.

Order of iteration is not defined.

Note: All elements are removed even if the iterator is only partially consumed or not consumed at all.

Examples

use generational_arena::Arena;

let mut arena = Arena::new();
let idx_1 = arena.insert("hello");
let idx_2 = arena.insert("world");

assert!(arena.get(idx_1).is_some());
assert!(arena.get(idx_2).is_some());
for (idx, value) in arena.drain() {
    assert!((idx == idx_1 && value == "hello") || (idx == idx_2 && value == "world"));
}
assert!(arena.get(idx_1).is_none());
assert!(arena.get(idx_2).is_none());