Struct handy::typed::TypedHandleMap

pub struct TypedHandleMap<T>(_);

A TypedHandleMap is a wrapper around a HandleMap which gives you some additional type safety, should you desire.

It accepts and returns TypedHandles, and you can only pass a TypedHandle<T> to a TypedHandleMap<T> -- attempting to pass it to a TypedHandleMap<U> will be statically detected.

Beyond this, it still can detect use of a handle that came from another map.

You use it with TypedHandles, which only will accept handles of the correct type. This could be useful if you have several handle maps in your program, and find

TypedHandle<T> is Copy + Send + Sync (and several others) regardless of T, which is not true for a naïve implementation of this, so it's provided even though I don't think it's that helpful for most usage (handle maps already detect this at runtime).

Methods

impl<T> TypedHandleMap<T>

pub fn new() -> Self

Create a new typed handle map.

Example

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

pub fn from_untyped(h: HandleMap<T>) -> Self

Create a typed handle map from one which accepts untyped handles.

Example

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

pub fn into_untyped(self) -> HandleMap<T>

Convert this map into it's wrapped HandleMap. See also TypedHandleMap::as_untyped_map and TypedHandleMap::as_mut_untyped_map.

Example

let mut tm: TypedHandleMap<u32> = TypedHandleMap::new();
let th = tm.insert(10u32);
let m = tm.into_untyped();
assert_eq!(m[th.handle()], 10);

pub fn with_capacity(c: usize) -> Self

Create a new typed handle map with the specified capacity.

Example

let m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::capacity on our wrapped map.

Example

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

pub fn len(&self) -> usize

Get the number of occupied entries.

This just calls HandleMap::len on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::is_empty on our wrapped map.

Example

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

pub fn as_untyped_map(&self) -> &HandleMap<T>

Get a reference to this map as a HandleMap.

This shouldn't be necessary except in advanced use, but may allow access to APIs that aren't mirrored, like most of the raw APIs.

Example

let mut tm: TypedHandleMap<u32> = TypedHandleMap::new();
let th = tm.insert(10u32);
assert_eq!(tm.as_untyped_map()[th.handle()], 10);

pub fn as_mut_untyped_map(&mut self) -> &mut HandleMap<T>

Get a mutable reference to this map as a HandleMap.

This shouldn't be necessary except in advanced use, but may allow access to APIs that aren't mirrored, like most of the raw APIs.

Example

let mut tm = TypedHandleMap::new();
let th = tm.insert(10u32);
tm.as_mut_untyped_map()[th.handle()] = 5;
assert_eq!(tm[th], 5);

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

Add a new item, returning a handle to it.

This just calls HandleMap::insert on our wrapped map.

Example

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

pub fn remove(&mut self, handle: TypedHandle<T>) -> 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.

This just calls HandleMap::remove on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::clear on our wrapped map.

Example

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

pub fn get(&self, handle: TypedHandle<T>) -> 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.

This just calls HandleMap::get on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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: TypedHandle<T>) -> 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.

This just calls HandleMap::get_mut on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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: TypedHandle<T>) -> bool

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

This just calls HandleMap::contains on our wrapped map.

Example

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

pub fn contains_key(&self, h: TypedHandle<T>) -> bool

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

This just calls HandleMap::contains_key on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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<TypedHandle<T>> 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.

This just calls HandleMap::find_handle on our wrapped map and wraps the resulting handle.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::reserve on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::iter on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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.

This just calls HandleMap::iter_mut on our wrapped map.

Example

let mut m: TypedHandleMap<u32> = TypedHandleMap::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 = (TypedHandle<T>, &'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.

This just calls HandleMap::iter_with_handles on our wrapped map and wraps the resulting handles.

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 = (TypedHandle<T>, &'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.

This just calls HandleMap::iter_mut_with_handles on our wrapped map and wraps the resulting handles

Example

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

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

If index refers to an occupied entry, return a Handle to it. Otherwise, return None.

This just calls HandleMap::handle_for_index on our wrapped map and wraps the resulting handle.

Example

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

Trait Implementations

impl<T: Debug> Debug for TypedHandleMap<T>

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

Formats the value using the given formatter.

impl<T> Index<TypedHandle<T>> for TypedHandleMap<T>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<T> IndexMut<TypedHandle<T>> for TypedHandleMap<T>

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

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

impl<T> IntoIterator for TypedHandleMap<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.

impl<T: Clone> Clone for TypedHandleMap<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Default> Default for TypedHandleMap<T>

fn default() -> TypedHandleMap<T>

Returns the "default value" for a type.