Struct Arena 

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

A collection-type with constant insert and remove operations.

After inserting elements into the Arena, you can use the returned Index to refer to the newly inserted element in get or remove operations.

Example

use pulz_arena::Arena;

let mut arena = Arena::new();
let index = arena.insert("test");
assert_eq!(1, arena.len());

Implementations

impl<T> Arena<T>

pub const fn new() -> Self

Constructs a new, empty Arena<T>.

The internal vector will not allocate until elements are inserted into it.

Example

use pulz_arena::Arena;

let arena = Arena::<u32>::new();
assert!(arena.is_empty());

pub fn with_capacity(capacity: usize) -> Self

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

The arena will be able to hold at exactly capacity elements without reallocating.

It is important to note that although the returned arena has the capacity specified, the arena will have a zero length.

Example

use pulz_arena::Arena;

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

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

assert!(arena.try_insert(16).is_err());
assert_eq!(15, arena.capacity());

pub fn capacity(&self) -> usize

Returns the number of elements the arena can hold without reallocating.

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

Reserved capacity for at least additional more elements to be inserted into this arena.

The internal vector may reserve more space to avoid frequent reallocations. Does nothing, if the capacity is already sufficient.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.capacity());
arena.insert(1);
arena.reserve(15);
assert!(arena.capacity() >= 16);
assert_eq!(1, arena.len());

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

Reserves the minimum capacity for exactly additional more elements to be inserted into this arena.

Does nothing, if the capacity is already sufficient.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.capacity());
arena.insert(1);
arena.reserve_exact(15);
assert_eq!(16, arena.capacity());
assert_eq!(1, arena.len());

pub fn clear(&mut self)

Clears the arena by removing all values.

Note this method has no effect on the allocated capacity of the arena.

Example

let mut arena = Arena::new();
arena.insert("test");
arena.insert("foo");
arena.insert("bar");
assert!(!arena.is_empty());
arena.clear();
assert!(arena.is_empty());

pub const fn len(&self) -> usize

Returns the number of elements in this arena.

Also referred to as its ‘length’ or ‘size’.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.len());
let index0 = arena.insert("test");
assert_eq!(1, arena.len());
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert_eq!(Some("test"), arena.remove(index0));
assert_eq!(1, arena.len());

pub const fn is_empty(&self) -> bool

Returns true if the arena contains no elements.

Example

let mut arena = Arena::new();
assert!(arena.is_empty());
let index0 = arena.insert("test");
assert!(!arena.is_empty());
let index1 = arena.insert("test2");
assert!(!arena.is_empty());
arena.remove(index0);
assert!(!arena.is_empty());
arena.remove(index1);
assert!(arena.is_empty());

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

Attempts to insert value into the arena at a free spot.

If there is a free spot, the provided value is inserted into this spot and the method returns the Index pointing to this spot.

Errors

If there is no free spot, it will not try to allocate new capacity. In this case, it returns Err(value) with the provided value, to give back ownership to the caller.

Example

let mut arena = Arena::new();
arena.reserve_exact(15);

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

assert!(arena.try_insert(16).is_err());
assert_eq!(15, arena.capacity());

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

where F: FnOnce(Index) -> T,

Attempts to insert a new value returned by create into the arena at a free spot.

If there is a free spot, the created value is inserted into this spot and the method returns the Index pointing to this spot.

The create method is called with the Index of the spot, where the created value will be inserted. This allows the value to be aware of it’s own index.

Errors

If there is no free spot, it will not try to allocate new capacity. In this case, it returns Err(create) with the provided create function, to give back ownership to the caller.

Example

struct Element {
    index: Index,
    value: usize,
}
let mut arena = Arena::new();
arena.reserve_exact(3);

assert_eq!(0, arena.len());
let index0 = arena.try_insert_with(|i| Element{ index: i, value: 42 }).ok().unwrap();
let index1 = arena.try_insert_with(|i| Element{ index: i, value: 666 }).ok().unwrap();
let index2 = arena.try_insert_with(|i| Element{ index: i, value: 42 }).ok().unwrap();
assert_eq!(3, arena.len());

assert!(arena.try_insert_with(|i| Element{ index: i, value: 99 }).is_err());
assert_eq!(3, arena.capacity());

assert_eq!(index0, arena[index0].index);
assert_eq!(index1, arena[index1].index);
assert_eq!(index2, arena[index2].index);

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

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

The provided value is inserted into a free spot or into a newly allocated spot and the method returns the Index pointing to this spot.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.len());
let index0 = arena.insert("test");
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert_eq!("test", arena[index0]);
assert_eq!("foo", arena[index1]);

pub fn insert_with<F>(&mut self, create: F) -> Index

where F: FnOnce(Index) -> T,

Inserts a new value returned by create into the arena , allocating more capacity if necessary.

The provided value is inserted into a free spot or into a newly allocated spot and the method returns the Index pointing to this spot.

The create method is called with the Index of the spot, where the created value will be inserted. This allows the value to be aware of it’s own index.

Example

struct Element {
    index: Index,
    value: usize,
}
let mut arena = Arena::new();
assert_eq!(0, arena.len());
let index0 = arena.insert_with(|i| Element{ index: i, value: 42 });
let index1 = arena.insert_with(|i| Element{ index: i, value: 666 });
assert_eq!(2, arena.len());
assert_eq!(index0, arena[index0].index);
assert_eq!(index1, arena[index1].index);

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

Removes the element at the given index from this arena.

The method returns the old value, if it is still in the arena. If it is not in the arena, then None is returned.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.len());
let index0 = arena.insert("test");
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert_eq!(Some("test"), arena.remove(index0));
assert_eq!(1, arena.len());
// removing it a second time returns `None`
assert_eq!(None, arena.remove(index0));
assert_eq!(1, arena.len());

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

Checks, if the element at the given index is still in the arena.

Returns true if there is a element for the given index.

Example

let mut arena = Arena::new();
assert_eq!(0, arena.len());
let index0 = arena.insert("test");
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert!(arena.contains(index0));
assert!(arena.contains(index1));
assert_eq!(Some("test"), arena.remove(index0));
assert_eq!(1, arena.len());
assert!(!arena.contains(index0)); // element not in the arena
assert!(arena.contains(index1));

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

Get a shared reference to the element at the given index.

If there is no element at the given index, None is returned.

Example

let mut arena = Arena::new();
let index0 = arena.insert("test");
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert_eq!(Some(&"test"), arena.get(index0));
assert_eq!(Some(&"foo"), arena.get(index1));
assert_eq!(2, arena.len());
assert_eq!(Some("test"), arena.remove(index0));
assert_eq!(1, arena.len());
assert_eq!(None, arena.get(index0));

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

Get a exclusive reference to the element at the given index.

If there is no element at the given index, None is returned.

Example

let mut arena = Arena::new();
let index0 = arena.insert("test");
let index1 = arena.insert("foo");
assert_eq!(2, arena.len());
assert_eq!("test", arena[index0]);
let element = arena.get_mut(index0).unwrap();
*element = "bar";
assert_eq!("bar", arena[index0]);

pub fn get_by_offset(&self, offset: u32) -> Option<&T>

Get a shared reference to the element at the given offset (the offset into the arena).

If there is no element at the given offset, None is returned.

pub fn get_mut_by_offset(&mut self, offset: u32) -> Option<&mut T>

Get a exclusive reference to the element at the given offset (the offset into the arena).

If there is no element at the given offset, None is returned.

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

Creates a draining iterator that removes all elements from this arena and yields the removed items.

When the iterator is dropped, all the remaining elements are removed and dropped!

Example

let mut arena = Arena::new();
let indices = [
    arena.insert(0),
    arena.insert(1),
    arena.insert(2),
];
assert_eq!(3, arena.len());
for (i, (index, element)) in arena.drain().enumerate() {
   assert_eq!(indices[i], index);
   assert_eq!(i, element);
}
assert!(arena.is_empty());

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

Creates an shared iterator over the elements of this arena.

Example

let mut arena = Arena::new();
let indices = [
    arena.insert(0),
    arena.insert(1),
    arena.insert(2),
];
assert_eq!(3, arena.len());
for (i, (index, element)) in arena.iter().enumerate() {
   assert_eq!(indices[i], index);
   assert_eq!(i, *element);
}
assert_eq!(3, arena.len());

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

Creates an exclusive iterator over the elements of this arena.

Example

let mut arena = Arena::new();
let indices = [
    arena.insert(0),
    arena.insert(1),
    arena.insert(2),
];
assert_eq!(3, arena.len());
for (i, (index, element)) in arena.iter_mut().enumerate() {
   assert_eq!(indices[i], index);
   *element *= 3;
}
assert_eq!(3, arena.len());
assert_eq!(0, arena[indices[0]]);
assert_eq!(3, arena[indices[1]]);
assert_eq!(6, arena[indices[2]]);

Trait Implementations

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

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Default for Arena<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Drop for Arena<T>

fn drop(&mut self)

Executes the destructor for this type.

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.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

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) -> &T

Performs the indexing (container[index]) operation.

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

type Output = T

The returned type after indexing.

fn index(&self, index: u32) -> &T

Performs the indexing (container[index]) operation.

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

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

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

impl<T> IndexMut<u32> for Arena<T>

fn index_mut(&mut self, index: u32) -> &mut T

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