Struct indextree::Arena

source ·

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

Expand description

An Arena structure containing certain Nodes.

Implementations§

source §

impl<T> Arena<T>

source

pub fn new() -> Arena<T>

Creates a new empty Arena.

source

pub fn with_capacity(n: usize) -> Self

Creates a new empty Arena with enough capacity to store n nodes.

source

pub fn capacity(&self) -> usize

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

source

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

Reserves capacity for additional more nodes to be inserted.

The arena may reserve more space to avoid frequent reallocations.

§Panics

Panics if the new capacity exceeds isize::MAX bytes.

source

pub fn get_node_id(&self, node: &Node<T>) -> Option<NodeId>

Retrieves the NodeId corresponding to a Node in the Arena.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");
let node = arena.get(foo).unwrap();

let node_id = arena.get_node_id(node).unwrap();
assert_eq!(*arena[node_id].get(), "foo");

source

pub fn get_node_id_at(&self, index: NonZeroUsize) -> Option<NodeId>

Retrieves the NodeId corresponding to the Node at index in the Arena, if it exists.

Note: We use 1 based indexing, so the first element is at 1 and not 0.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");
let node = arena.get(foo).unwrap();
let index: NonZeroUsize = foo.into();

let new_foo = arena.get_node_id_at(index).unwrap();
assert_eq!(foo, new_foo);

foo.remove(&mut arena);
let new_foo = arena.get_node_id_at(index);
assert!(new_foo.is_none(), "must be none if the node at the index doesn't exist");

source

pub fn new_node(&mut self, data: T) -> NodeId

Creates a new node from its associated data.

§Panics

Panics if the arena already has usize::max_value() nodes.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");

assert_eq!(*arena[foo].get(), "foo");

source

pub fn count(&self) -> usize

Counts the number of nodes in arena and returns it.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");
let _bar = arena.new_node("bar");
assert_eq!(arena.count(), 2);

foo.remove(&mut arena);
assert_eq!(arena.count(), 2);

source

pub fn is_empty(&self) -> bool

Returns true if arena has no nodes, false otherwise.

§Examples

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

let foo = arena.new_node("foo");
assert!(!arena.is_empty());

foo.remove(&mut arena);
assert!(!arena.is_empty());

source

pub fn get(&self, id: NodeId) -> Option<&Node<T>>

Returns a reference to the node with the given id if in the arena.

Returns None if not available.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");
assert_eq!(arena.get(foo).map(|node| *node.get()), Some("foo"));

Note that this does not check whether the given node ID is created by the arena.

let mut arena = Arena::new();
let foo = arena.new_node("foo");
let bar = arena.new_node("bar");
assert_eq!(arena.get(foo).map(|node| *node.get()), Some("foo"));

let mut another_arena = Arena::new();
let _ = another_arena.new_node("Another arena");
assert_eq!(another_arena.get(foo).map(|node| *node.get()), Some("Another arena"));
assert!(another_arena.get(bar).is_none());

source

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

Returns a mutable reference to the node with the given id if in the arena.

Returns None if not available.

§Examples

let mut arena = Arena::new();
let foo = arena.new_node("foo");
assert_eq!(arena.get(foo).map(|node| *node.get()), Some("foo"));

*arena.get_mut(foo).expect("The `foo` node exists").get_mut() = "FOO!";
assert_eq!(arena.get(foo).map(|node| *node.get()), Some("FOO!"));

source

pub fn iter(&self) -> impl Iterator<Item = &Node<T>>

Returns an iterator of all nodes in the arena in storage-order.

Note that this iterator returns also removed elements, which can be tested with the is_removed() method on the node.

§Examples

let mut arena = Arena::new();
let _foo = arena.new_node("foo");
let _bar = arena.new_node("bar");

let mut iter = arena.iter();
assert_eq!(iter.next().map(|node| *node.get()), Some("foo"));
assert_eq!(iter.next().map(|node| *node.get()), Some("bar"));
assert_eq!(iter.next().map(|node| *node.get()), None);

let mut arena = Arena::new();
let _foo = arena.new_node("foo");
let bar = arena.new_node("bar");
bar.remove(&mut arena);

let mut iter = arena.iter();
assert_eq!(iter.next().map(|node| (*node.get(), node.is_removed())), Some(("foo", false)));
assert_eq!(iter.next().map_or(false, |node| node.is_removed()), true);
assert_eq!(iter.next().map(|node| (*node.get(), node.is_removed())), None);

source

pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Node<T>>

Returns a mutable iterator of all nodes in the arena in storage-order.

Note that this iterator returns also removed elements, which can be tested with the is_removed() method on the node.

§Example

let arena: &mut Arena<i64> = &mut Arena::new();
let a = arena.new_node(1);
let b = arena.new_node(2);
assert!(a.checked_append(b, arena).is_ok());

for node in arena.iter_mut() {
    let data = node.get_mut();
    *data = data.wrapping_add(4);
}

let node_refs = arena.iter().map(|i| i.get().clone()).collect::<Vec<_>>();
assert_eq!(node_refs, vec![5, 6]);

source

pub fn clear(&mut self)

Clears all the nodes in the arena, but retains its allocated capacity.

Note that this does not marks all nodes as removed, but completely removes them from the arena storage, thus invalidating all the node ids that were previously created.

Any attempt to call the is_removed() method on the node id will result in panic behavior.