Struct VecMap

pub struct VecMap<const LOWER: usize, const UPPER: usize, K: Integer, V> { /* private fields */ }

A hash map, similar to std::collections::HashMap, but with a number of limitations in order to improve the performance for specific use cases.

It limits the keys to unsigned integers within a range specified by the generic parameters, which allows membership to be boiled to down to a boolean or a bit. For uses cases that fit these constraints, it significantly increases performance compared to regular hash maps; even ones with integer specific hashers, simply because there is no hashing.

The keys need to implement the Integer trait, which is currently implemented for u8, u16, u32, and usize. I specifically left out out u64, because on a 32bit machine usize would be 32bit, and casting from a u64 to usize would truncate.

Implementations

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> VecMap<LOWER, UPPER, K, V>

pub fn new() -> Self

Construct a new VecMap<LOWER, UPPER, T>, where LOWER and UPPER are usize integers that denote the boundaries of the VecMap keys, K is the type for the keys implementing the Integer trait, and V is the type for the values.

use firims::VecMap;
let foo = VecMap::<10, 20, usize, f32>::new();

pub fn clear(&mut self)

Removes all items from map.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(1, 11.1);
foo.insert(10, 22.2);
foo.insert(5, 33.3);

assert_eq!(foo.len(), 3);
assert!(!foo.is_empty());

foo.clear();
assert_eq!(foo.len(), 0);
assert!(foo.is_empty());

impl<const LOWER: usize, const UPPER: usize, K: Integer, V> VecMap<LOWER, UPPER, K, V>

pub fn len(&self) -> usize

Returns the number of elements in the map.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(1, 11.1);
foo.insert(10, 22.2);
foo.insert(5, 33.3);

assert_eq!(foo.len(), 3);

foo.remove(&1);
assert_eq!(foo.len(), 2);

pub fn is_empty(&self) -> bool

Checks whether the map is empty.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(1, 11.1);
assert_eq!(foo.len(), 1);
assert!(!foo.is_empty());

foo.remove(&1);
assert!(foo.is_empty());

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

Return whether a key is present in the map.

use firims::VecMap;

let mut foo = VecMap::<3, 32, usize, f32>::new();
foo.insert(3, 11.1);
foo.insert(10, 22.2);
foo.insert(5, 33.3);

assert_eq!(foo.len(), 3);
assert!(foo.contains_key(&3));
assert!(foo.contains_key(&10));
assert!(foo.contains_key(&5));

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

Insert 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.

This item x has to be constrained to LOWER <= x <= UPPER

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(10, 22.2);
foo.insert(32, 33.3);
assert!(foo.contains_key(&0));
assert!(foo.contains_key(&10));
assert!(foo.contains_key(&32));
assert!(!foo.contains_key(&2));

foo.remove(&0);
foo.remove(&10);
foo.remove(&32);
assert!(!foo.contains_key(&0));
assert!(!foo.contains_key(&10));
assert!(!foo.contains_key(&32));

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

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

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

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

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

An iterator visiting all keys in ascending order.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut keys = foo.keys();
assert_eq!(keys.next(), Some(0));
assert_eq!(keys.next(), Some(10));
assert_eq!(keys.next(), Some(32));
assert_eq!(keys.next(), None);

pub fn into_keys(self) -> IntoKeys<LOWER, UPPER, K, V>

A consuming iterator visiting all keys in ascending order.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut keys = foo.into_keys();
assert_eq!(keys.next(), Some(0));
assert_eq!(keys.next(), Some(10));
assert_eq!(keys.next(), Some(32));
assert_eq!(keys.next(), None);

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

An iterator visiting all values in order of ascending keys.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut values = foo.values();
assert_eq!(values.next(), Some(&11.1));
assert_eq!(values.next(), Some(&22.2));
assert_eq!(values.next(), Some(&33.3));
assert_eq!(values.next(), None);

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

An iterator visiting all values in order of ascending keys, returning mutable references.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut values = foo.values_mut();
assert_eq!(values.next(), Some(&mut 11.1));
assert_eq!(values.next(), Some(&mut 22.2));
assert_eq!(values.next(), Some(&mut 33.3));
assert_eq!(values.next(), None);

pub fn into_values(self) -> IntoValues<LOWER, UPPER, K, V>

A consuming iterator visiting all values in order of ascending order.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut values = foo.into_values();
assert_eq!(values.next(), Some(11.1));
assert_eq!(values.next(), Some(22.2));
assert_eq!(values.next(), Some(33.3));
assert_eq!(values.next(), None);

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

An iterator vising all key-value pairs in order of ascending keys.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut iter = foo.iter();
assert_eq!(iter.next(), Some((0, &11.1)));
assert_eq!(iter.next(), Some((10, &22.2)));
assert_eq!(iter.next(), Some((32, &33.3)));
assert_eq!(iter.next(), None);

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

An iterator vising all key-value pairs in order of ascending keys, returning mutable references to those values.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut iter = foo.iter_mut();
assert_eq!(iter.next(), Some((0, &mut 11.1)));
assert_eq!(iter.next(), Some((10, &mut 22.2)));
assert_eq!(iter.next(), Some((32, &mut 33.3)));
assert_eq!(iter.next(), None);

pub fn drain(&mut self) -> Drain<'_, LOWER, UPPER, K, V>

A draining iterator vising all key-value pairs in order of ascending keys.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

{
    let mut drain = foo.drain();
    assert_eq!(drain.next(), Some((0, 11.1)));
    assert_eq!(drain.next(), Some((10, 22.2)));
    assert_eq!(drain.next(), Some((32, 33.3)));
    assert_eq!(drain.next(), None);
}
assert!(foo.is_empty());

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

where F: Fn(&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 order of ascending keys.

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

Returns a reference to the value corresponding to the key.

use firims::VecMap;
let mut foo = VecMap::<10, 20, usize, f32>::new();

foo.insert(10, 11.1);
assert_eq!(foo.get(&10), Some(&11.1));
assert_eq!(foo.get(&20), None);

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

Returns a reference to the key-value pair corresponding to the key.

use firims::VecMap;
let mut foo = VecMap::<10, 20, usize, f32>::new();

foo.insert(10, 11.1);
assert_eq!(foo.get_key_value(&10), Some((10, &11.1)));
assert_eq!(foo.get_key_value(&20), None);

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

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

use firims::VecMap;
let mut foo = VecMap::<10, 20, usize, f32>::new();

foo.insert(10, 11.1);
assert_eq!(foo.get_mut(&10), Some(&mut 11.1));
assert_eq!(foo.get(&20), None);

Trait Implementations

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Clone for VecMap<LOWER, UPPER, K, V>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Debug> Debug for VecMap<LOWER, UPPER, K, V>

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

Formats the value using the given formatter.

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Default for VecMap<LOWER, UPPER, K, V>

fn default() -> Self

Construct a new VecMap<LOWER, UPPER, T>, where LOWER and UPPER are usize integers that denote the boundaries of the VecMap keys, K is the type for the keys implementing the Integer trait, and V is the type for the values.

use firims::VecMap;
let foo = VecMap::<10, 20, usize, f32>::default();

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Extend<&'a (K, V)> for VecMap<LOWER, UPPER, K, V>

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

Extends a collection with the contents of an iterator.

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<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Extend<(&'a K, &'a V)> for VecMap<LOWER, UPPER, K, V>

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

Extends a collection with the contents of an iterator.

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<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Extend<(&'a K, V)> for VecMap<LOWER, UPPER, K, V>

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

Extends a collection with the contents of an iterator.

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<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Extend<(K, V)> for VecMap<LOWER, UPPER, K, V>

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

Extends a collection with the contents of an iterator.

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<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone, const N: usize> From<[(K, V); N]> for VecMap<LOWER, UPPER, K, V>

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

Converts a [(K, V); N] into a VecMap.

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

use firims::VecMap;

let map1 = VecMap::<0, 32, usize, i32>::from([(1, 2), (3, 4)]);
let map2: VecMap::<0, 32, usize, i32> = [(1, 2), (3, 4)].into();
assert_eq!(map1, map2);

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> FromIterator<&'a (K, V)> for VecMap<LOWER, UPPER, K, V>

fn from_iter<I: IntoIterator<Item = &'a (K, V)>>(iter: I) -> Self

Construct a VecMap<LOWER, UPPER, K, V> from an iterator of &'a (K, V)s.

use firims::VecMap;

let v = vec![(1, 11.1), (2, 22.2), (3, 33.3)];
let mut a = VecMap::<1, 6, usize, f32>::from_iter(v.into_iter());

assert_eq!(a.len(), 3);
assert_eq!(a, [(1, 11.1), (2, 22.2), (3, 33.3)].into_iter().collect());

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> FromIterator<(&'a K, &'a V)> for VecMap<LOWER, UPPER, K, V>

fn from_iter<I: IntoIterator<Item = (&'a K, &'a V)>>(iter: I) -> Self

Construct a VecMap<LOWER, UPPER, K, V> from an iterator of (&'a K, &'a V)s.

use firims::VecMap;

let v = vec![(1, 11.1), (2, 22.2), (3, 33.3)];
let a = VecMap::<1, 6, usize, f32>::from_iter(v.iter());

assert_eq!(a.len(), 3);
assert_eq!(a, [(1, 11.1), (2, 22.2), (3, 33.3)].into_iter().collect());

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> FromIterator<(&'a K, V)> for VecMap<LOWER, UPPER, K, V>

fn from_iter<I: IntoIterator<Item = (&'a K, V)>>(iter: I) -> Self

Construct a VecMap<LOWER, UPPER, K, V> from an iterator of (&'a K, V)s.

use firims::VecMap;

let v = vec![(1, 11.1), (2, 22.2), (3, 33.3)];
let a = VecMap::<1, 6, usize, f32>::from_iter(v.iter());

assert_eq!(a.len(), 3);
assert_eq!(a, [(1, 11.1), (2, 22.2), (3, 33.3)].into_iter().collect());

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> FromIterator<(K, V)> for VecMap<LOWER, UPPER, K, V>

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

Construct a VecMap<LOWER, UPPER, K, V> from an iterator of (K, V)s.

use firims::VecMap;

let v = vec![(1, 11.1), (2, 22.2), (3, 33.3)];
let mut a = VecMap::<1, 6, usize, f32>::from_iter(v.into_iter());

assert_eq!(a.len(), 3);
assert_eq!(a, [(1, 11.1), (2, 22.2), (3, 33.3)].into_iter().collect());

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Index<&K> for VecMap<LOWER, UPPER, K, V>

fn index(&self, index: &K) -> &Self::Output

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

Panics

Panics if the key is not present in the VecMap.

type Output = V

The returned type after indexing.

impl<const LOWER: usize, const UPPER: usize, K: Integer, V: Clone> Index<K> for VecMap<LOWER, UPPER, K, V>

fn index(&self, index: K) -> &Self::Output

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

Panics

Panics if the key is not present in the VecMap.

type Output = V

The returned type after indexing.

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V> IntoIterator for &'a VecMap<LOWER, UPPER, K, V>

fn into_iter(self) -> Self::IntoIter

An iterator consuming a VecMap reference, vising all key-value pairs in order of ascending keys.

use firims::VecMap;

let foo = {
    let mut foo = VecMap::<0, 32, usize, f32>::new();
    foo.insert(0, 11.1);
    foo.insert(32, 33.3);
    foo.insert(10, 22.2);
    foo
};
let bar = &foo;

let mut iter = bar.into_iter();
assert_eq!(iter.next(), Some((0, &11.1)));
assert_eq!(iter.next(), Some((10, &22.2)));
assert_eq!(iter.next(), Some((32, &33.3)));
assert_eq!(iter.next(), None);

type Item = (K, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, LOWER, UPPER, K, V>

Which kind of iterator are we turning this into?

impl<'a, const LOWER: usize, const UPPER: usize, K: Integer, V> IntoIterator for &'a mut VecMap<LOWER, UPPER, K, V>

fn into_iter(self) -> Self::IntoIter

An iterator consuming a VecMap reference, vising all key-value pairs in order of ascending keys.

use firims::VecMap;

let mut foo = {
    let mut foo = VecMap::<0, 32, usize, f32>::new();
    foo.insert(0, 11.1);
    foo.insert(32, 33.3);
    foo.insert(10, 22.2);
    foo
};
let bar = &mut foo;

let mut iter = bar.into_iter();
assert_eq!(iter.next(), Some((0, &mut 11.1)));
assert_eq!(iter.next(), Some((10, &mut 22.2)));
assert_eq!(iter.next(), Some((32, &mut 33.3)));
assert_eq!(iter.next(), None);

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

The type of the elements being iterated over.

type IntoIter = IterMut<'a, LOWER, UPPER, K, V>

Which kind of iterator are we turning this into?

impl<const LOWER: usize, const UPPER: usize, K: Integer, V> IntoIterator for VecMap<LOWER, UPPER, K, V>

fn into_iter(self) -> Self::IntoIter

A consuming iterator vising all key-value pairs in order of ascending keys.

use firims::VecMap;

let mut foo = VecMap::<0, 32, usize, f32>::new();
foo.insert(0, 11.1);
foo.insert(32, 33.3);
foo.insert(10, 22.2);

let mut iter = foo.into_iter();
assert_eq!(iter.next(), Some((0, 11.1)));
assert_eq!(iter.next(), Some((10, 22.2)));
assert_eq!(iter.next(), Some((32, 33.3)));
assert_eq!(iter.next(), None);

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<LOWER, UPPER, K, V>

Which kind of iterator are we turning this into?

impl<const LOWER: usize, const UPPER: usize, K: PartialEq + Integer, V: PartialEq> PartialEq for VecMap<LOWER, UPPER, K, V>

fn eq(&self, other: &VecMap<LOWER, UPPER, K, V>) -> bool

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

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<const LOWER: usize, const UPPER: usize, K: Integer, V> StructuralPartialEq for VecMap<LOWER, UPPER, K, V>