Struct handy::HandleMap

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

HandleMaps are a collection data structure that allow you to reference their members by using a opaque handle.

In rust code, you often use these handles as a sort of lifetime-less reference. Handle is a paper-thin wrapper around a u64, so it is Copy + Send + Sync + Eq + Ord + ... even if T (or even &T) wouldn't be, however you need access to the map in order to read the value.

This is probably starting to sound like HandleMap is just a Vec, and Handle is just usize, but unlike usize:

• a HandleMap can tell if you try to use a Handle from a different map to access one of it's values.

• a HandleMap tracks insertion/removal of the value at each index, will know if you try to use a handle to get a value that was removed, even if another value occupies the same index.

Example

let mut m = HandleMap::new();
let h0 = m.insert(3usize);
assert_eq!(m[h0], 3);
m[h0] += 2;
assert_eq!(m[h0], 5);
let v = m.remove(h0);
assert_eq!(v, Some(5));
assert_eq!(m.get(h0), None);

Implementations

impl<T> HandleMap<T>

pub fn new() -> Self

Create a new handle map.

Example

let m: HandleMap<u32> = HandleMap::new();
// No allocation is performed by default.
assert_eq!(m.capacity(), 0);

pub fn with_capacity(c: usize) -> Self

Create a new handle map with at least the specified capacity.

Example

let m: HandleMap<u32> = HandleMap::with_capacity(10);
// Note that we don't guarantee the capacity will be exact.
// (though in practice it will so long as the requested
// capacity is >= 8)
assert!(m.capacity() >= 10);

pub fn capacity(&self) -> usize

Get the number of entries we can hold before reallocation.

Example

let mut m: HandleMap<u32> = HandleMap::new();
m.insert(10);
assert!(m.capacity() >= 1);

pub fn len(&self) -> usize

Get the number of occupied entries.

Example

let mut m: HandleMap<u32> = HandleMap::new();
assert_eq!(m.len(), 0);
m.insert(10u32);
assert_eq!(m.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if our length is zero

Example

let mut m: HandleMap<u32> = HandleMap::new();
assert!(m.is_empty());

pub fn map_id(&self) -> u16

Get the id of this map, which is used to validate handles.

This is typically not needed except for debugging and advanced usage.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.map_id(), h.map_id());

pub fn raw_set_map_id(&mut self, v: u16)

Set the id of this map, which is used to validate handles (See Handle documentation for more details).

Warning

Doing so will cause the map to fail to recognize handles that it previously returned, and probably other problems! You're recommended against using it unless you know what you're doing!

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

Add a new item, returning a handle to it.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m[h], 10);

pub fn remove(&mut self, handle: Handle) -> Option<T>

Remove the value referenced by this handle from the map, returning it.

If the handle doesn't point to an entry in the map we return None. This will happen if:

• The handle comes from a different map.
• The item it referenced has been removed already.
• It appears corrupt in some other way (For example, it's Handle::default(), or comes from a dubious Handle::from_raw_*)

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
// Present:
assert_eq!(m.remove(h), Some(10));
// Not present:
assert_eq!(m.remove(h), None);

pub fn clear(&mut self)

Remove all entries in this handle map.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
m.clear();
assert_eq!(m.len(), 0);
assert_eq!(m.get(h), None);

pub fn get(&self, handle: Handle) -> Option<&T>

Try and get a reference to the item backed by the handle.

If the handle doesn't point to an entry in the map we return None. This will happen if:

• The handle comes from a different map.
• The item it referenced has been removed already.
• It appears corrupt in some other way (For example, it's Handle::default(), or comes from a dubious Handle::from_raw_*)

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.get(h), Some(&10));
m.remove(h);
assert_eq!(m.get(h), None);

pub fn get_mut(&mut self, handle: Handle) -> Option<&mut T>

Try and get mutable a reference to the item backed by the handle.

If the handle doesn't point to an entry in the map we return None. This will happen if:

• The handle comes from a different map.
• The item it referenced has been removed already.
• It appears corrupt in some other way (For example, it's Handle::default(), or comes from a dubious Handle::from_raw_*)

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
*m.get_mut(h).unwrap() += 1;
assert_eq!(m[h], 11);
// Note: The following is equivalent if you're going to `unwrap` the result of get_mut:
m[h] += 1;
assert_eq!(m[h], 12);

pub fn contains(&self, h: Handle) -> bool

Returns true if the handle refers to an item present in this map.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert!(m.contains(h));
m.remove(h);
assert!(!m.contains(h));

pub fn contains_key(&self, h: Handle) -> bool

Returns true if the handle refers to an item present in this map.

This is equivalent to HandleMap::contains but provided for some compatibility with other Map apis.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert!(m.contains_key(h));
m.remove(h);
assert!(!m.contains_key(h));

pub fn find_handle(&self, item: &T) -> Option<Handle> where
    T: PartialEq, 

Search the map for item, and if it's found, return a handle to it.

If more than one value compare as equal to item, it's not specified which we will return.

Note that this is a naive O(n) search, so if you want this often, you might want to store the handle as a field on the value.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.find_handle(&10), Some(h));
assert_eq!(m.find_handle(&11), None);

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

Reserve space for sz additional items.

Example

let mut m: HandleMap<u32> = HandleMap::new();
assert_eq!(m.capacity(), 0);
m.reserve(10);
assert!(m.capacity() >= 10);

pub fn iter<'a>(&'a self) -> impl Iterator<Item = &'a T> + 'a

Get an iterator over every occupied slot of this map.

See also iter_with_handles if you want the handles during iteration.

Example

let mut m: HandleMap<u32> = HandleMap::new();
m.insert(10u32);
assert_eq!(*m.iter().next().unwrap(), 10);

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

Get a mut iterator over every occupied slot of this map.

See also iter_mut_with_handles if you want the handles during iteration.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
for v in m.iter_mut() {
    *v += 1;
}
assert_eq!(m[h], 11);

pub fn iter_with_handles<'a>(
    &'a self
) -> impl Iterator<Item = (Handle, &'a T)> + 'a

Get an iterator over every occupied slot of this map, as well as a handle which can be used to fetch them later.

Example

for (h, v) in m.iter_with_handles() {
    println!("{:?} => {}", h, v);
}

pub fn iter_mut_with_handles<'a>(
    &'a mut self
) -> impl Iterator<Item = (Handle, &'a mut T)> + 'a

Get a mut iterator over every occupied slot of this map, as well as a handle which can be used to fetch them later.

Example

for (h, v) in m.iter_mut_with_handles() {
    *v += 1;
    println!("{:?}", h);
}

pub fn handle_for_index(&self, index: usize) -> Option<Handle>

If index refers to an occupied entry, return a Handle to it. Otherwise, return None. This is a low level API that shouldn't be needed for typical use.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.handle_for_index(h.index()), Some(h));

pub fn raw_value_at_index(&self, index: usize) -> Option<&T>

Access the value at the provided index, whatever it happens to be.

Returns none if index >= capacity() or if the index is unoccupied.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.raw_value_at_index(h.index()), Some(&10));

Caveat

This is a low level feature intended for advanced usage, typically you do not need to call this function.

pub fn raw_mut_value_at_index(&mut self, index: usize) -> Option<&mut T>

Access the value at the provided index, whatever it happens to be.

Returns none if index >= capacity() or if the index is unoccupied.

Example

let mut m: HandleMap<u32> = HandleMap::new();
let h = m.insert(10u32);
*m.raw_mut_value_at_index(h.index()).unwrap() = 11;
assert_eq!(m[h], 11);

Caveat

This is a low level feature intended for advanced usage, typically you do not need to call this function.

pub fn raw_generation_for_index(&self, index: usize) -> Option<u16>

Directly query the value of the generation at that index.

If index is greater then self.capacity(), then this returns None.

Advanced usage note: Even generations always indicate an occupied index, except for 0, which is never a valid generation.

Example

let mut m = HandleMap::new();
let h = m.insert(10u32);
assert_eq!(m.raw_generation_for_index(h.index()), Some(h.generation()));

Caveat

This is a low level feature intended for advanced usage, typically you do not need to call this function, however doing so is harmless.

Trait Implementations

impl<T: Clone> Clone for HandleMap<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T> Debug for HandleMap<T> where
    T: Debug, 

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

Formats the value using the given formatter.

impl<T> Default for HandleMap<T>

fn default() -> Self

Returns the "default value" for a type.

impl<T> Index<Handle> for HandleMap<T>

type Output = T

The returned type after indexing.

fn index(&self, h: Handle) -> &T

Performs the indexing (container[index]) operation.

impl<T> IndexMut<Handle> for HandleMap<T>

fn index_mut(&mut self, h: Handle) -> &mut T

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

impl<T> IntoIterator for HandleMap<T>

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

type Item = T

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.