Struct MuleMap

pub struct MuleMap<K, V, S, const TABLE_MIN_VALUE: i128 = 0, const TABLE_SIZE: usize = { u8::MAX as usize + 1 }> { /* private fields */ }

MuleMap is a hybrid between a HashMap and a lookup table. It improves performance for frequently accessed keys in a known range. If a key (integer) is in the user specified range, then its value will be stored directly in the lookup table.

Differences between HashMap and MuleMap

• The key, K, must be an integer type. - The key is directly mapped to the index in the lookup, so it must be an integer.
• The key, K, is passed by value - Because it is a primitive integer type.
• The hash builder, S, does not have a default - You must specify your hash builder. The assumption being that if you need better performance you will likely also want to use a custom hash function.
• TABLE_MIN_VALUE and TABLE_SIZE - If a key is between TABLE_MIN_VALUE and TABLE_MIN_VALUE + TABLE_SIZE (exclusive), then the value will be stored directly in the lookup table, instead of using the HashMap.

NOTE: Currently the type of a const generic can’t depend on another generic type argument, so TABLE_MIN_VALUE can’t use the same type as the key. Because of this, We are using i128, but that means we can’t represent values near u128::MAX. Hopefully having frequent keys near u128::MAX is extremely rare.

Performance

Benchmarks (using random selection) start to show speed improvements when about 50% of the key accesses are in the lookup table. Performance is almost identical to HashMap with less than 50%.

Example

use mule_map::MuleMap;
use std::num::NonZero;
type Hash = fnv_rs::FnvBuildHasher;  // Use whatever hash function you prefer

// Using Entry API
let mut mule_map = MuleMap::<u32, usize, Hash>::new();
assert_eq!(mule_map.get(5), None);
let entry = mule_map.entry(5);
entry.or_insert(10);
assert_eq!(mule_map.get(5), Some(&10));

// Using NonZero and bump
let mut mule_map_non_zero = MuleMap::<u32, NonZero<i32>, Hash>::default();

mule_map_non_zero.bump_non_zero(10);
mule_map_non_zero.bump_non_zero(10);
mule_map_non_zero.bump_non_zero(999_999);
mule_map_non_zero.bump_non_zero(999_999);

assert_eq!(mule_map_non_zero.get(10), NonZero::<i32>::new(2).as_ref());
assert_eq!(mule_map_non_zero.get(999_999),NonZero::<i32>::new(2).as_ref());

Implementations

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

pub fn iter(&self) -> Iter<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

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

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for (key, value) in mule_map.iter()
{
    assert!((key == 10 && *value == 2) || (key == 999_999 && *value == 1));
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::iter

pub fn iter_mut(&mut self) -> IterMut<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

A mutable iterator visiting all key-value pairs in arbitrary order. The iterator element type is (K, &'a mut V).

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for (key, value) in mule_map.iter_mut()
{
    *value *= 2;
    assert!((key == 10 && *value == 4) || (key == 999_999 && *value == 2));
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::iter_mut

pub fn drain(&mut self) -> DrainIter<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Clears the map, returning all key-value pairs as an iterator. Keeps the allocated memory for reuse. If the returned iterator is dropped before being fully consumed, it drops the remaining key-value pairs. The returned iterator keeps a mutable borrow on the map to optimize its implementation.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

for (key, value)  in mule_map.drain().take(1) {
    assert!((key == 10 && value == 2) || (key == 999_999 && value == 1));
}
assert!(mule_map.is_empty());

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::drain

pub fn keys(&self) -> Keys<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

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

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for key in mule_map.keys()
{
    assert!(key == 10 || key == 999_999);
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::keys

pub fn into_keys(self) -> IntoKeys<K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates a consuming iterator visiting all the keys in arbitrary order. The map cannot be used after calling this. The iterator element type is K.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for key in mule_map.into_keys()
{
    assert!(key == 10 || key == 999_999);
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::into_keys

pub fn values(&self) -> Values<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator visiting all the values in arbitrary order. The iterator element type is &'a V.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for val in mule_map.values()
{
    assert!(*val == 1 || *val == 2);
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::values

pub fn values_mut(&mut self) -> ValuesMut<'_, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator visiting all the values in arbitrary order. The iterator element type is &'a mut V.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for val in mule_map.values_mut()
{
    *val *= 2;
    assert!(*val == 2 || *val == 4);
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::values_mut

pub fn into_values(self) -> IntoValues<K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator consuming all the values in arbitrary order. The map cannot be used after calling this. The iterator element type is V.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

let mut count = 0;
for val in mule_map.into_values()
{
    assert!(val == 1 || val == 2);
    count += 1;
}
assert_eq!(count, 2);

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::into_values

pub fn retain<F>(&mut self, f: F)

where F: FnMut(&K, &mut V) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all pairs (k, v) for which f(&k, &mut v) returns false. The elements are visited in unsorted (and unspecified) order.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(10);
mule_map.bump_int(999_999);

mule_map.retain(|&k, _| k % 2 == 0);
assert_eq!(mule_map.len(), 1);
assert_eq!(mule_map.get(10), Some(&2));

Performance

O(capacity of the HashMap) + O(TABLE_SIZE of the lookup table). Currently all TABLE_SIZE elements of the lookup table will be visited.

Analogous to HashMap::retain

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

pub fn new() -> Self

where S: Default, <K as TryFrom<i128>>::Error: Debug,

Creates an empty MuleMap.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::new();
assert!(mule_map.is_empty());

See: MuleMap::with_capacity_and_hasher

Analogous to HashMap::new

pub fn with_capacity(capacity: usize) -> Self

where S: Default, <K as TryFrom<i128>>::Error: Debug,

Creates an empty MuleMap with at least the provided capacity.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::with_capacity(100);
assert!(mule_map.is_empty());

See: MuleMap::with_capacity_and_hasher

Analogous to HashMap::with_capacity

pub fn with_hasher(hash_builder: S) -> Self

where <K as TryFrom<i128>>::Error: Debug,

Creates an empty MuleMap using hash_builder.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::with_hasher(Hash::default());
assert!(mule_map.is_empty());

See: MuleMap::with_capacity_and_hasher

Analogous to HashMap::with_hasher

pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> Self

where <K as TryFrom<i128>>::Error: Debug,

Creates an empty MuleMap with at least the provided capacity and using hash_builder.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::with_capacity_and_hasher(100, Hash::default());
assert!(mule_map.is_empty());

Panics

Panics if

• TABLE_MIN_VALUE or TABLE_MIN_VALUE + TABLE_SIZE - 1 doesn’t fit into key type, K.

Analogous to HashMap::with_capacity_and_hasher

pub fn capacity(&self) -> usize

Returns capacity of the underlying hash map.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::with_capacity(100);
assert!(mule_map.capacity() >= 100);

See HashMap::capacity

pub fn clear(&mut self)

Clears the map, removing all key-value pairs. Keeps the allocated memory for reuse.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
mule_map.clear();
assert!(mule_map.is_empty());

See HashMap::clear

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

Returns true if the map contains a value for the specified key.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
assert!(mule_map.contains_key(999_999));
assert!(mule_map.contains_key(1));
assert!(!mule_map.contains_key(2));
assert!(!mule_map.contains_key(999_998));

Analogous to HashMap::contains_key

pub fn get(&self, key: K) -> Option<&V>

Returns a reference to the value corresponding to the key.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
assert_eq!(mule_map.get(999_999), Some(&4));
assert_eq!(mule_map.get(1), Some(&2));
assert_eq!(mule_map.get(2), None);
assert_eq!(mule_map.get(999_998), None);

Analogous to HashMap::get

pub fn get_key_value(&self, key: K) -> Option<(K, &V)>

Returns the key-value pair corresponding to the supplied key.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
assert_eq!(mule_map.get_key_value(999_999), Some((999_999, &4)));
assert_eq!(mule_map.get_key_value(1), Some((1,&2)));
assert_eq!(mule_map.get_key_value(2), None);
assert_eq!(mule_map.get_key_value(999_998), None);

Analogous to HashMap::get_key_value

pub fn get_disjoint_mut<const N: usize>( &mut self, ks: [K; N], ) -> [Option<&mut V>; N]

where K: Key<TABLE_MIN_VALUE>,

Attempts to get mutable references to N values in the map at once.

…

Example

let mut map = mule_map::MuleMap::<_, _, fnv_rs::FnvBuildHasher>::from([(1, 1602), (2, 1807), (999_999, 1691), (999_998, 1800)]);

assert_eq!(map.get_disjoint_mut([1, 999_999]), [Some(&mut 1602), Some(&mut 1691)]);
assert_eq!(map.get_disjoint_mut([2, 4, 999_998, 999_990]), [Some(&mut 1807), None, Some(&mut 1800), None]);

Panics

Panics if any keys are overlapping.

Analogous to HashMap::get_disjoint_mut

pub unsafe fn get_disjoint_unchecked_mut<const N: usize>( &mut self, ks: [K; N], ) -> [Option<&mut V>; N]

where K: Key<TABLE_MIN_VALUE>,

Attempts to get mutable references to N values in the map at once, without validating that the values are unique.

…

Example

let mut map = mule_map::MuleMap::<_, _, fnv_rs::FnvBuildHasher>::from([(1, 1602), (2, 1807), (999_999, 1691), (999_998, 1800)]);

assert_eq!(unsafe {map.get_disjoint_unchecked_mut([1, 999_999])}, [Some(&mut 1602), Some(&mut 1691)]);
assert_eq!(unsafe {map.get_disjoint_unchecked_mut([2, 4, 999_998, 999_990])}, [Some(&mut 1807), None, Some(&mut 1800), None]);

Safety

Calling this method with overlapping keys is undefined behavior even if the resulting references are not used. This makes calls to HashMap::get_disjoint_unchecked_mut and slice::get_disjoint_unchecked_mut

Analogous to HashMap::get_disjoint_unchecked_mut

pub fn get_mut(&mut self, key: K) -> Option<&mut V>

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

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
assert_eq!(mule_map.get_mut(999_999), Some(&mut 4));
assert_eq!(mule_map.get_mut(1), Some(&mut 2));
assert_eq!(mule_map.get_mut(2), None);
assert_eq!(mule_map.get_mut(999_998), None);

Analogous to HashMap::get_mut

pub fn hasher(&self) -> &S

Returns a reference to the map’s BuildHasher.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
assert_eq!(&fnv_rs::FnvBuildHasher::default(), mule_map.hasher());

Analogous to HashMap::hasher

pub fn insert(&mut self, key: K, value: V) -> Option<V>

Inserts a key-value pair into the map. If the map did not have this key present, None is returned. If the map did have this key present, the value is updated, and the old value is returned.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(999_999,4);
assert_eq!(mule_map.get_key_value(999_999), Some((999_999, &4)));
assert_eq!(mule_map.get_key_value(1), Some((1,&2)));
assert_eq!(mule_map.get_key_value(2), None);
assert_eq!(mule_map.get_key_value(999_998), None);

Analogous to HashMap::insert

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements. Checks both the lookup table and the hashmap. Note, there is no tracking in the lookup table - in the worst case, we have to check all elements of the lookup table.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
assert!(mule_map.is_empty());
mule_map.insert(1,2);
assert!(!mule_map.is_empty());
mule_map.clear();
assert!(mule_map.is_empty());
mule_map.insert(999_999,4);
assert!(!mule_map.is_empty());
mule_map.clear();
assert!(mule_map.is_empty());

Analogous to HashMap::is_empty

pub fn len(&self) -> usize

Returns the number of elements in the map. Checks both the lookup table and the hashmap. Note, there is no tracking in the lookup table, so this will scan the whole table.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
assert_eq!(mule_map.len(), 0);
mule_map.insert(1,2);
assert_eq!(mule_map.len(), 1);
mule_map.insert(999_999,4);
assert_eq!(mule_map.len(), 2);
mule_map.clear();
assert_eq!(mule_map.len(), 0);

Analogous to HashMap::len

pub fn remove(&mut self, key: K) -> Option<V>

Removes a key from the map, returning the value at the key if the key was previously in the map.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
assert_eq!(mule_map.remove(0), None);
assert!(!mule_map.is_empty());
assert_eq!(mule_map.remove(1), Some(2));
assert!(mule_map.is_empty());
mule_map.insert(999_999,4);
assert_eq!(mule_map.remove(999_999), Some(4));
assert!(mule_map.is_empty());

Analogous to HashMap::remove

pub fn remove_entry(&mut self, key: K) -> Option<(K, V)>

Removes a key from the map, returning the stored key and value if the key was previously in the map.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
assert_eq!(mule_map.remove_entry(0), None);
assert!(!mule_map.is_empty());
assert_eq!(mule_map.remove_entry(1), Some((1, 2)));
assert!(mule_map.is_empty());
mule_map.insert(999_999,4);
assert_eq!(mule_map.remove_entry(999_999), Some((999_999,4)));
assert!(mule_map.is_empty());

Analogous to HashMap::remove_entry

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

Calls reserve on the underlying HashMap

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.reserve(100);

Analogous to HashMap::reserve

pub fn shrink_to(&mut self, min_capacity: usize)

Calls shrink_to on the underlying HashMap

Example

let mut map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::with_capacity(100);
map.insert(999_999, 2);
map.insert(999_998, 4);
assert!(map.capacity() >= 100);
map.shrink_to(10);
assert!(map.capacity() >= 10);
map.shrink_to(0);
assert!(map.capacity() >= 2);

Analogous to HashMap::shrink_to

pub fn shrink_to_fit(&mut self)

Calls shrink_to_fit on the underlying HashMap

Example

let mut map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::with_capacity(100);
map.insert(999_999, 2);
map.insert(999_998, 4);
assert!(map.capacity() >= 100);
map.shrink_to_fit();
assert!(map.capacity() >= 2);

Analogous to HashMap::shrink_to_fit

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Calls try_reserve on the underlying HashMap

Example

let mut map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::new();
map.try_reserve(10).expect("Should have space to allocate 10 elements");

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

Analogous to HashMap::try_reserve

pub fn modify_or_insert<F>(&mut self, key: K, f: F, default: V)

where F: FnOnce(&mut V),

Modify the values at location key by calling f on its value. If no value present, create a new value set to default.

Example

let mut map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::new();
map.modify_or_insert(10, |x| *x += 1, 100);
assert!(map.get(10) == Some(&100));
map.modify_or_insert(10, |x| *x += 1, 100);
assert!(map.get(10) == Some(&101));
map.modify_or_insert(999_999, |x| *x += 1, 100);
assert!(map.get(999_999) == Some(&100));
map.modify_or_insert(999_999, |x| *x += 1, 100);
assert!(map.get(999_999) == Some(&101));

pub fn bump_int(&mut self, key: K)

where V: AddAssign<V> + One + Zero,

Adds 1 to the value stored at location key. If the value is not present, the value 1 will be set at that location.

NOTE: This method can only be called with values that implement AddAssign, like primitives. For NonZero<T> values use MuleMap::bump_non_zero - It uses the niche optimization for better performance.

Example

let mut map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::new();
map.bump_int(10);
assert!(map.get(10) == Some(&1));
map.bump_int(10);
assert!(map.get(10) == Some(&2));
map.bump_int(999_999);
assert!(map.get(999_999) == Some(&1));
map.bump_int(999_999);
assert!(map.get(999_999) == Some(&2));

Panics

May panics if adding 1 results in overflow.

pub fn bump_non_zero(&mut self, key: K)

where V: NonZeroInt + PodInOption, <V as NonZeroInt>::UnderlyingType: AddAssign<V::UnderlyingType> + Pod + PrimInt,

Adds 1 to the value stored at location key. If the value is not present, the value 1 will be set at that location. Uses the niche optimization for better performance with Option<NonZero<T>>.

NOTE: This method can only be called with NonZero<T> values. For primitive values use MuleMap::bump_int.

Example

use std::num::NonZero;
let mut map = mule_map::MuleMap::<u32, NonZero<i32>, fnv_rs::FnvBuildHasher>::new();
map.bump_non_zero(10);

assert!(map.get(10) == Some(&const { NonZero::new(1).expect("1 is not 0") }));
map.bump_non_zero(10);
assert!(map.get(10) == Some(&const { NonZero::new(2).expect("2 is not 0") }));
map.bump_non_zero(999_999);
assert!(map.get(999_999) == Some(&const { NonZero::new(1).expect("1 is not 0") }));
map.bump_non_zero(999_999);
assert!(map.get(999_999) == Some(&const { NonZero::new(2).expect("2 is not 0") }));

Panics

Panics if adding 1 results in overflow.

pub fn entry(&mut self, key: K) -> Entry<'_, K, V>

Gets the given key’s corresponding entry in the map for in-place manipulation.

Example

let mut map = mule_map::MuleMap::<u32, usize, fnv_rs::FnvBuildHasher>::new();
map.entry(5).or_insert(3);
assert!(map.get(5) == Some(&3));
map.entry(5).and_modify(|e| *e += 1).or_insert(1);
assert!(map.get(5) == Some(&4));

Analogous to HashMap::entry

Trait Implementations

impl<K: Clone, V: Clone, S: Clone, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Clone for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

fn clone(&self) -> MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: Debug, V: Debug, S: Debug, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Debug for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

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

Formats the value using the given formatter.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Default for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: Default + BuildHasher, <K as TryFrom<i128>>::Error: Debug,

fn default() -> Self

Creates an empty MuleMap.

Example

type Hash = fnv_rs::FnvBuildHasher;
let mule_map = mule_map::MuleMap::<u32, usize, Hash>::default();
assert!(mule_map.is_empty());

See: MuleMap::with_capacity_and_hasher

Analogous to HashMap::default

impl<'a, K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Extend<(K, &'a V)> for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: Default + BuildHasher, V: Copy,

fn extend<T: IntoIterator<Item = (K, &'a V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.extend([(0, &10), (999_999, &3)].into_iter());

let mut mule_map2 = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map2.insert(0, 10);
mule_map2.insert(999_999, 3);
assert_eq!(mule_map, mule_map2);

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Extend<(K, V)> for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

fn extend<T: IntoIterator<Item = (K, V)>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.extend([(0, 10), (999_999, 3)].into_iter());

let mut mule_map2 = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map2.insert(0, 10);
mule_map2.insert(999_999, 3);
assert_eq!(mule_map, mule_map2);

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize, const N: usize> From<[(K, V); N]> for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher + Default, <K as TryFrom<i128>>::Error: Debug,

fn from(arr: [(K, V); N]) -> Self

Converts a [(K, V); N] into a MuleMap<K, V>.

If any entries in the array have equal keys, all but one of the corresponding values will be dropped.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(3,4);

let map1 = MuleMap::<_, _, fnv_rs::FnvBuildHasher>::from([(1, 2), (3, 4)]);
let map2: MuleMap<_, _, fnv_rs::FnvBuildHasher> = [(1, 2), (3, 4)].into();

assert_eq!(map1, mule_map);
assert_eq!(map2, mule_map);

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> FromIterator<(K, V)> for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher + Default, <K as TryFrom<i128>>::Error: Debug,

fn from_iter<T: IntoIterator<Item = (K, V)>>(iter: T) -> Self

Constructs a MuleMap<K, V> from an iterator of key-value pairs.

If the iterator produces any pairs with equal keys, all but one of the corresponding values will be dropped.

Example

use mule_map::MuleMap;

let mut mule_map = MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.insert(1,2);
mule_map.insert(3,4);

let map1 = MuleMap::<_, _, fnv_rs::FnvBuildHasher>::from_iter([(1, 2), (3, 4)].into_iter());

assert_eq!(map1, mule_map);

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Index<K> for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

fn index(&self, key: K) -> &V

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

Example

let mut mule_map = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map.bump_int(10);
mule_map.bump_int(999_999);
assert_eq!(mule_map[10], 1);
assert_eq!(mule_map[999_999], 1);
assert!(test_utils::catch_unwind_silent(|| mule_map[123]).is_err());

Panics

Panics if the key is not present in the MuleMap.

type Output = V

The returned type after indexing.

impl<'a, K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> IntoIterator for &'a MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

type Item = (K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator from a value.

impl<'a, K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> IntoIterator for &'a mut MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

type Item = (K, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IterMut<'a, K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator from a value.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> IntoIterator for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, S: BuildHasher,

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<K, V, TABLE_MIN_VALUE, TABLE_SIZE>

Creates an iterator from a value.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> PartialEq for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, V: PartialEq, S: BuildHasher,

fn eq(&self, other: &MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>) -> bool

Tests for self and other values to be equal, and is used by ==.

Example

let mut mule_map1 = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map1.bump_int(10);
mule_map1.bump_int(11);
mule_map1.bump_int(999_999);
mule_map1.bump_int(999_999);

let mut mule_map2 = mule_map::MuleMap::<u32, i32, fnv_rs::FnvBuildHasher>::default();
mule_map2.bump_int(10);
mule_map2.bump_int(11);
mule_map2.bump_int(999_999);
mule_map2.bump_int(999_999);

assert!(mule_map1 ==  mule_map2)

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, V, S, const TABLE_MIN_VALUE: i128, const TABLE_SIZE: usize> Eq for MuleMap<K, V, S, TABLE_MIN_VALUE, TABLE_SIZE>

where K: Key<TABLE_MIN_VALUE>, V: Eq, S: BuildHasher,