Struct slotmap::SlotMap

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

Slot map, storage with stable unique keys.

See crate documentation for more details.

Methods

impl<T> SlotMap<T>

pub fn new() -> Self

Construct a new, empty SlotMap.

The slot map will not allocate until values are inserted.

Examples

let mut sm: SlotMap<i32> = SlotMap::new();

pub fn with_capacity(capacity: usize) -> SlotMap<T>

Creates an empty SlotMap with the given capacity.

The slot map will not reallocate until it holds at least capacity elements. If capacity is 0, the slot map will not allocate.

Examples

let mut sm: SlotMap<i32> = SlotMap::with_capacity(10);

pub fn len(&self) -> usize

Returns the number of elements in the slot map.

Examples

let mut sm = SlotMap::with_capacity(10);
sm.insert("len() counts actual elements, not capacity");
let key = sm.insert("removed elements don't count either");
sm.remove(key);
assert_eq!(sm.len(), 1);

pub fn is_empty(&self) -> bool

Returns if the slot map is empty.

Examples

let mut sm = SlotMap::new();
let key = sm.insert("dummy");
assert_eq!(sm.is_empty(), false);
sm.remove(key);
assert_eq!(sm.is_empty(), true);

pub fn capacity(&self) -> usize

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

Examples

let sm: SlotMap<f64> = SlotMap::with_capacity(10);
assert_eq!(sm.capacity(), 10);

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

Reserves capacity for at least additional more elements to be inserted in the SlotMap. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new allocation size overflows usize.

Examples

let mut sm = SlotMap::new();
sm.insert("foo");
sm.reserve(32);
assert!(sm.capacity() >= 33);

pub fn contains_key(&self, key: Key) -> bool

Returns true if the slot map contains key.

Examples

let mut sm = SlotMap::new();
let key = sm.insert(42);
assert_eq!(sm.contains_key(key), true);
sm.remove(key);
assert_eq!(sm.contains_key(key), false);

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

Inserts a value into the slot map. Returns a unique Key that can be used to access this value.

Panics

Panics if the number of elements in the slot map overflows a u32.

Examples

let mut sm = SlotMap::new();
let key = sm.insert(42);
assert_eq!(sm[key], 42);

pub fn insert_with_key<F>(&mut self, f: F) -> Key where     F: FnOnce(Key) -> T,

Inserts a value given by f into the slot map. The Key where the value will be stored is passed into f. This is useful to store values that contain their own key.

Panics

Panics if the number of elements in the slot map overflows a u32.

Examples

let mut sm = SlotMap::new();
let key = sm.insert_with_key(|k| (k, 20));
assert_eq!(sm[key], (key, 20));

pub fn remove(&mut self, key: Key) -> Option<T>

Removes a key from the slot map, returning the value at the key if the key was not previously removed.

Examples

let mut sm = SlotMap::new();
let key = sm.insert(42);
assert_eq!(sm.remove(key), Some(42));
assert_eq!(sm.remove(key), None);

pub fn retain<F>(&mut self, f: F) where     F: FnMut(Key, &mut T) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all key-value pairs (k, v) such that f(k, &mut v) returns false. This method operates in place and invalidates any removed keys.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();

let k1 = sm.insert(0);
let k2 = sm.insert(1);
let k3 = sm.insert(2);

sm.retain(|key, val| key == k1 || *val == 1);

assert!(sm.contains_key(k1));
assert!(sm.contains_key(k2));
assert!(!sm.contains_key(k3));

assert_eq!(2, sm.len());

pub fn clear(&mut self)

Clears the slotmap. Keeps the allocated memory for reuse.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
for i in 0..10 {
    sm.insert(i);
}
assert_eq!(sm.len(), 10);
sm.clear();
assert_eq!(sm.len(), 0);

Important traits for Drain<'a, T>

impl<'a, T> Iterator for Drain<'a, T> type Item = (Key, T);

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

Clears the slotmap, returning all key-value pairs as an iterator. Keeps the allocated memory for reuse.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
let k = sm.insert(0);
let v: Vec<_> = sm.drain().collect();
assert_eq!(sm.len(), 0);
assert_eq!(v, vec![(k, 0)]);

pub fn get(&self, key: Key) -> Option<&T>

Returns a reference to the value corresponding to the key.

Examples

let mut sm = SlotMap::new();
let key = sm.insert("bar");
assert_eq!(sm.get(key), Some(&"bar"));
sm.remove(key);
assert_eq!(sm.get(key), None);

pub unsafe fn get_unchecked(&self, key: Key) -> &T

Returns a reference to the value corresponding to the key without version or bounds checking.

Safety

This should only be used if contains_key(key) is true. Otherwise it is potentially unsafe.

Examples

let mut sm = SlotMap::new();
let key = sm.insert("bar");
assert_eq!(unsafe { sm.get_unchecked(key) }, &"bar");
sm.remove(key);
// sm.get_unchecked(key) is now dangerous!

pub fn get_mut(&mut self, key: Key) -> Option<&mut T>

Returns a mutable reference to the value corresponding to the key.

Examples

let mut sm = SlotMap::new();
let key = sm.insert(3.5);
if let Some(x) = sm.get_mut(key) {
    *x += 3.0;
}
assert_eq!(sm[key], 6.5);

pub unsafe fn get_unchecked_mut(&mut self, key: Key) -> &mut T

Returns a mutable reference to the value corresponding to the key without version or bounds checking.

Safety

This should only be used if contains_key(key) is true. Otherwise it is potentially unsafe.

Examples

let mut sm = SlotMap::new();
let key = sm.insert("foo");
unsafe { *sm.get_unchecked_mut(key) = "bar" };
assert_eq!(sm[key], "bar");
sm.remove(key);
// sm.get_unchecked_mut(key) is now dangerous!

Important traits for Iter<'a, T>

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

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

An iterator visiting all key-value pairs in arbitrary order. The iterator element type is (Key, &'a T).

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
let k0 = sm.insert(0);
let k1 = sm.insert(1);
let k2 = sm.insert(2);

let mut it = sm.iter();
assert_eq!(it.next(), Some((k0, &0)));
assert_eq!(it.len(), 2);
assert_eq!(it.next(), Some((k1, &1)));
assert_eq!(it.next(), Some((k2, &2)));
assert_eq!(it.next(), None);

Important traits for IterMut<'a, T>

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

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

An iterator visiting all key-value pairs in arbitrary order, with mutable references to the values. The iterator element type is (Key, &'a mut T).

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
let k0 = sm.insert(10);
let k1 = sm.insert(20);
let k2 = sm.insert(30);

for (k, v) in sm.iter_mut() {
    if k != k1 {
        *v *= -1;
    }
}

assert_eq!(sm.values().collect::<Vec<_>>(), vec![&-10, &20, &-30]);

Important traits for Keys<'a, T>

impl<'a, T> Iterator for Keys<'a, T> type Item = Key;

pub fn keys(&self) -> Keys<T>

An iterator visiting all keys in arbitrary order. The iterator element type is Key.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
let k0 = sm.insert(10);
let k1 = sm.insert(20);
let k2 = sm.insert(30);
let v: Vec<_> = sm.keys().collect();
assert_eq!(v, vec![k0, k1, k2]);

Important traits for Values<'a, T>

impl<'a, T> Iterator for Values<'a, T> type Item = &'a T;

pub fn values(&self) -> Values<T>

An iterator visiting all values in arbitrary order. The iterator element type is &'a T.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
sm.insert(10);
sm.insert(20);
sm.insert(30);
let v: Vec<_> = sm.values().collect();
assert_eq!(v, vec![&10, &20, &30]);

Important traits for ValuesMut<'a, T>

impl<'a, T> Iterator for ValuesMut<'a, T> type Item = &'a mut T;

pub fn values_mut(&mut self) -> ValuesMut<T>

An iterator visiting all values mutably in arbitrary order. The iterator element type is &'a mut T.

This function must iterate over all slots, empty or not. In the face of many deleted elements it can be inefficient.

Examples

let mut sm = SlotMap::new();
sm.insert(10);
sm.insert(20);
sm.insert(30);
sm.values_mut().for_each(|n| { *n *= 3 });
let v: Vec<_> = sm.into_iter().map(|(_k, v)| v).collect();
assert_eq!(v, vec![30, 60, 90]);

Trait Implementations

impl<T: Debug> Debug for SlotMap<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Clone> Clone for SlotMap<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Default for SlotMap<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> Index<Key> for SlotMap<T>

type Output = T

The returned type after indexing.

fn index(&self, key: Key) -> &T

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Key> for SlotMap<T>

fn index_mut(&mut self, key: Key) -> &mut T

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

impl<'a, T> IntoIterator for &'a SlotMap<T>

type Item = (Key, &'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 SlotMap<T>

type Item = (Key, &'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> IntoIterator for SlotMap<T>

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