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>
impl<T> Arena<T>
sourcepub fn new() -> Arena<T>
pub fn new() -> Arena<T>
Constructs a new, empty Arena
.
Examples
use generational_arena::Arena;
let mut arena = Arena::<usize>::new();
sourcepub fn with_capacity(n: usize) -> Arena<T>
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());
sourcepub fn clear(&mut self)
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);
sourcepub fn try_insert(&mut self, value: T) -> Result<Index, T>
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);
}
};
sourcepub fn try_insert_with<F: FnOnce(Index) -> T>(
&mut self,
create: F
) -> Result<Index, F>
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.
}
};
sourcepub fn insert(&mut self, value: T) -> Index
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);
sourcepub fn insert_with(&mut self, create: impl FnOnce(Index) -> T) -> Index
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);
sourcepub fn remove(&mut self, i: Index) -> Option<T>
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);
sourcepub fn retain(&mut self, predicate: impl FnMut(Index, &mut T) -> bool)
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());
sourcepub fn contains(&self, i: Index) -> bool
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));
sourcepub fn get(&self, i: Index) -> Option<&T>
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());
sourcepub fn get_mut(&mut self, i: Index) -> Option<&mut T>
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());
sourcepub fn get2_mut(
&mut self,
i1: Index,
i2: Index
) -> (Option<&mut T>, Option<&mut T>)
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);
sourcepub fn len(&self) -> usize
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);
sourcepub fn is_empty(&self) -> bool
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());
sourcepub fn capacity(&self) -> usize
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);
sourcepub fn iter(&self) -> Iter<'_, 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);
}
sourcepub fn iter_mut(&mut self) -> IterMut<'_, 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;
}
sourcepub fn drain(&mut self) -> Drain<'_, T> ⓘ
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());
sourcepub fn get_unknown_gen(&self, i: usize) -> Option<(&T, Index)>
pub fn get_unknown_gen(&self, i: usize) -> Option<(&T, Index)>
Given an i of usize
without a generation, get a shared reference
to the element and the matching Index
of the entry behind i
.
This method is useful when you know there might be an element at the position i, but don’t know its generation or precise Index.
Use cases include using indexing such as Hierarchical BitMap Indexing or other kinds of bit-efficient indexing.
You should use the get
method instead most of the time.
sourcepub fn get_unknown_gen_mut(&mut self, i: usize) -> Option<(&mut T, Index)>
pub fn get_unknown_gen_mut(&mut self, i: usize) -> Option<(&mut T, Index)>
Given an i of usize
without a generation, get an exclusive reference
to the element and the matching Index
of the entry behind i
.
This method is useful when you know there might be an element at the position i, but don’t know its generation or precise Index.
Use cases include using indexing such as Hierarchical BitMap Indexing or other kinds of bit-efficient indexing.
You should use the get_mut
method instead most of the time.
Trait Implementations§
source§impl<T> Extend<T> for Arena<T>
impl<T> Extend<T> for Arena<T>
source§fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)
fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I)
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)