Struct slotmap::SecondaryMap [−][src]
pub struct SecondaryMap<K: Key, V> { /* fields omitted */ }
Expand description
Secondary map, associate data with previously stored elements in a slot map.
A SecondaryMap
allows you to efficiently store additional information
for each element in a slot map. You can have multiple secondary maps per
slot map, but not multiple slot maps per secondary map. It is safe but
unspecified behavior if you use keys from multiple different slot maps in
the same SecondaryMap
.
A SecondaryMap
does not leak memory even if you never remove elements.
In return, when you remove a key from the primary slot map, after any insert
the space associated with the removed element may be reclaimed. Don’t expect
the values associated with a removed key to stick around after an insertion
has happened!
Finally a note on memory complexity, the SecondaryMap
can use memory for
each slot in the primary slot map, and has to iterate over every slot during
iteration, regardless of whether you have inserted an associative value at
that key or not. If you have some property that you only expect to set for a
minority of keys, use a SparseSecondaryMap
,
which is backed by a HashMap
.
Example usage:
let mut players = SlotMap::new();
let mut health = SecondaryMap::new();
let mut ammo = SecondaryMap::new();
let alice = players.insert("alice");
let bob = players.insert("bob");
for p in players.keys() {
health.insert(p, 100);
ammo.insert(p, 30);
}
// Alice attacks Bob with all her ammo!
health[bob] -= ammo[alice] * 3;
ammo[alice] = 0;
Implementations
Constructs a new, empty SecondaryMap
.
Examples
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::new();
Creates an empty SecondaryMap
with the given capacity of slots.
The secondary map will not reallocate until it holds at least capacity
slots. Even inserting a single key-value pair might require as many
slots as the slot map the key comes from, so it’s recommended to match
the capacity of a secondary map to its corresponding slot map.
Examples
let mut sm: SlotMap<_, i32> = SlotMap::with_capacity(10);
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::with_capacity(sm.capacity());
Returns the number of elements in the secondary map.
Examples
let mut sm = SlotMap::new();
let k = sm.insert(4);
let mut squared = SecondaryMap::new();
assert_eq!(squared.len(), 0);
squared.insert(k, 16);
assert_eq!(squared.len(), 1);
Returns if the secondary map is empty.
Examples
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::new();
assert!(sec.is_empty());
Returns the number of elements the SecondaryMap
can hold without
reallocating.
Examples
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::with_capacity(10);
assert!(sec.capacity() >= 10);
Sets the capacity of the SecondaryMap
to new_capacity
, if it is
bigger than the current capacity.
It is recommended to set the capacity of a SecondaryMap
to the
capacity of its corresponding slot map before inserting many new
elements to prevent frequent reallocations. The collection may reserve
more space than requested.
Panics
Panics if the new allocation size overflows usize
.
Examples
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::with_capacity(10);
assert!(sec.capacity() >= 10);
sec.set_capacity(1000);
assert!(sec.capacity() >= 1000);
This is supported on crate feature unstable
only.
unstable
only.Tries to set the capacity of the SecondaryMap
to new_capacity
, if it
is bigger than the current capacity.
It is recommended to set the capacity of a SecondaryMap
to the
capacity of its corresponding slot map before inserting many new
elements to prevent frequent reallocations. The collection may reserve
more space than requested.
Examples
let mut sec: SecondaryMap<DefaultKey, i32> = SecondaryMap::with_capacity(10);
assert!(sec.capacity() >= 10);
sec.try_set_capacity(1000).unwrap();
assert!(sec.capacity() >= 1000);
Inserts a value into the secondary map at the given key
. Can silently
fail and return None
if key
was removed from the originating slot
map.
Returns None
if this key was not present in the map, the old value
otherwise.
Examples
let mut sm = SlotMap::new();
let k = sm.insert(4);
let mut squared = SecondaryMap::new();
assert_eq!(squared.insert(k, 0), None);
assert_eq!(squared.insert(k, 4), Some(0));
// You don't have to use insert if the key is already in the secondary map.
squared[k] *= squared[k];
assert_eq!(squared[k], 16);
Removes a key from the secondary map, returning the value at the key if
the key was not previously removed. If key
was removed from the
originating slot map, its corresponding entry in the secondary map may
or may not already be removed.
Examples
let mut sm = SlotMap::new();
let mut squared = SecondaryMap::new();
let k = sm.insert(4);
squared.insert(k, 16);
squared.remove(k);
assert!(!squared.contains_key(k));
// It's not necessary to remove keys deleted from the primary slot map, they
// get deleted automatically when their slots are reused on a subsequent insert.
squared.insert(k, 16);
sm.remove(k); // Remove k from the slot map, making an empty slot.
let new_k = sm.insert(2); // Since sm only has one empty slot, this reuses it.
assert!(!squared.contains_key(new_k)); // Space reuse does not mean equal keys.
assert!(squared.contains_key(k)); // Slot has not been reused in squared yet.
squared.insert(new_k, 4);
assert!(!squared.contains_key(k)); // Old key is no longer available.
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 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 mut sec = SecondaryMap::new();
let k1 = sm.insert(0); sec.insert(k1, 10);
let k2 = sm.insert(1); sec.insert(k2, 11);
let k3 = sm.insert(2); sec.insert(k3, 12);
sec.retain(|key, val| key == k1 || *val == 11);
assert!(sec.contains_key(k1));
assert!(sec.contains_key(k2));
assert!(!sec.contains_key(k3));
assert_eq!(sec.len(), 2);
Clears the secondary map. 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 mut sec = SecondaryMap::new();
for i in 0..10 {
sec.insert(sm.insert(i), i);
}
assert_eq!(sec.len(), 10);
sec.clear();
assert_eq!(sec.len(), 0);
Clears the slot map, returning all key-value pairs in arbitrary order as an iterator. Keeps the allocated memory for reuse.
When the iterator is dropped all elements in the slot map are removed,
even if the iterator was not fully consumed. If the iterator is not
dropped (using e.g. std::mem::forget
), only the elements that were
iterated over are removed.
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 mut sec = SecondaryMap::new();
sec.insert(k, 1);
let v: Vec<_> = sec.drain().collect();
assert_eq!(sec.len(), 0);
assert_eq!(v, vec![(k, 1)]);
Returns a reference to the value corresponding to the key.
Examples
let mut sm = SlotMap::new();
let key = sm.insert("foo");
let mut sec = SecondaryMap::new();
sec.insert(key, "bar");
assert_eq!(sec.get(key), Some(&"bar"));
sec.remove(key);
assert_eq!(sec.get(key), None);
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("foo");
let mut sec = SecondaryMap::new();
sec.insert(key, "bar");
assert_eq!(unsafe { sec.get_unchecked(key) }, &"bar");
sec.remove(key);
// sec.get_unchecked(key) is now dangerous!
Returns a mutable reference to the value corresponding to the key.
Examples
let mut sm = SlotMap::new();
let key = sm.insert("test");
let mut sec = SecondaryMap::new();
sec.insert(key, 3.5);
if let Some(x) = sec.get_mut(key) {
*x += 3.0;
}
assert_eq!(sec[key], 6.5);
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");
let mut sec = SecondaryMap::new();
sec.insert(key, "bar");
unsafe { *sec.get_unchecked_mut(key) = "baz" };
assert_eq!(sec[key], "baz");
sec.remove(key);
// sec.get_unchecked_mut(key) is now dangerous!
Returns mutable references to the values corresponding to the given keys. All keys must be valid and disjoint, otherwise None is returned.
Requires at least stable Rust version 1.51.
Examples
let mut sm = SlotMap::new();
let mut sec = SecondaryMap::new();
let ka = sm.insert(()); sec.insert(ka, "butter");
let kb = sm.insert(()); sec.insert(kb, "apples");
let kc = sm.insert(()); sec.insert(kc, "charlie");
sec.remove(kc); // Make key c invalid.
assert_eq!(sec.get_disjoint_mut([ka, kb, kc]), None); // Has invalid key.
assert_eq!(sec.get_disjoint_mut([ka, ka]), None); // Not disjoint.
let [a, b] = sec.get_disjoint_mut([ka, kb]).unwrap();
std::mem::swap(a, b);
assert_eq!(sec[ka], "apples");
assert_eq!(sec[kb], "butter");
Returns mutable references to the values corresponding to the given keys. All keys must be valid and disjoint.
Requires at least stable Rust version 1.51.
Safety
This should only be used if contains_key(key)
is true for every given
key and no two keys are equal. Otherwise it is potentially unsafe.
Examples
let mut sm = SlotMap::new();
let mut sec = SecondaryMap::new();
let ka = sm.insert(()); sec.insert(ka, "butter");
let kb = sm.insert(()); sec.insert(kb, "apples");
let [a, b] = unsafe { sec.get_disjoint_unchecked_mut([ka, kb]) };
std::mem::swap(a, b);
assert_eq!(sec[ka], "apples");
assert_eq!(sec[kb], "butter");
An iterator visiting all key-value pairs in arbitrary order. The
iterator element type is (K, &'a V)
.
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 mut sec = SecondaryMap::new();
let k0 = sm.insert(0); sec.insert(k0, 10);
let k1 = sm.insert(1); sec.insert(k1, 11);
let k2 = sm.insert(2); sec.insert(k2, 12);
for (k, v) in sm.iter() {
println!("key: {:?}, val: {}", k, v);
}
An iterator visiting all key-value pairs in arbitrary order, with
mutable references to the values. The iterator element type is
(K, &'a mut V)
.
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 mut sec = SecondaryMap::new();
let k0 = sm.insert(1); sec.insert(k0, 10);
let k1 = sm.insert(2); sec.insert(k1, 20);
let k2 = sm.insert(3); sec.insert(k2, 30);
for (k, v) in sec.iter_mut() {
if k != k1 {
*v *= -1;
}
}
assert_eq!(sec[k0], -10);
assert_eq!(sec[k1], 20);
assert_eq!(sec[k2], -30);
An iterator visiting all keys in arbitrary order. The iterator element
type is K
.
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 mut sec = SecondaryMap::new();
let k0 = sm.insert(1); sec.insert(k0, 10);
let k1 = sm.insert(2); sec.insert(k1, 20);
let k2 = sm.insert(3); sec.insert(k2, 30);
let keys: HashSet<_> = sec.keys().collect();
let check: HashSet<_> = vec![k0, k1, k2].into_iter().collect();
assert_eq!(keys, check);
An iterator visiting all values in arbitrary order. The iterator element
type is &'a V
.
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 mut sec = SecondaryMap::new();
let k0 = sm.insert(1); sec.insert(k0, 10);
let k1 = sm.insert(2); sec.insert(k1, 20);
let k2 = sm.insert(3); sec.insert(k2, 30);
let values: HashSet<_> = sec.values().collect();
let check: HashSet<_> = vec![&10, &20, &30].into_iter().collect();
assert_eq!(values, check);
An iterator visiting all values mutably in arbitrary order. The iterator
element type is &'a mut V
.
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 mut sec = SecondaryMap::new();
sec.insert(sm.insert(1), 10);
sec.insert(sm.insert(2), 20);
sec.insert(sm.insert(3), 30);
sec.values_mut().for_each(|n| { *n *= 3 });
let values: HashSet<_> = sec.into_iter().map(|(_k, v)| v).collect();
let check: HashSet<_> = vec![30, 60, 90].into_iter().collect();
assert_eq!(values, check);
Gets the given key’s corresponding Entry
in the map for in-place
manipulation. May return None
if the key was removed from the
originating slot map.
Examples
let mut sm = SlotMap::new();
let mut sec = SecondaryMap::new();
let k = sm.insert(1);
let v = sec.entry(k).unwrap().or_insert(10);
assert_eq!(*v, 10);
Trait Implementations
Extends a collection with the contents of an iterator. Read more
extend_one
)Extends a collection with exactly one element.
extend_one
)Reserves capacity in a collection for the given number of additional elements. Read more
Extends a collection with the contents of an iterator. Read more
extend_one
)Extends a collection with exactly one element.
extend_one
)Reserves capacity in a collection for the given number of additional elements. Read more
Auto Trait Implementations
impl<K, V> RefUnwindSafe for SecondaryMap<K, V> where
V: RefUnwindSafe,
impl<K, V> Send for SecondaryMap<K, V> where
V: Send,
impl<K, V> Sync for SecondaryMap<K, V> where
V: Sync,
impl<K, V> Unpin for SecondaryMap<K, V> where
V: Unpin,
impl<K, V> UnwindSafe for SecondaryMap<K, V> where
V: UnwindSafe,
Blanket Implementations
Mutably borrows from an owned value. Read more