Struct BumpMap 

pub struct BumpMap<K, V, S = RandomState> { /* private fields */ }

A hash map that uses bump allocation inside.

Read this module documentation for more details.

Implementations

impl<K, V> BumpMap<K, V, RandomState>

pub fn new() -> Self

Creates an empty BumpMap.

The new map will not allocate until it is first pair inserted into.

Examples

let mut map: BumpMap<&str, i32> = BumpMap::new();
assert_eq!(map.capacity(), 0);

pub fn with_capacity(capacity: usize) -> Self

Creates an empty BumpMap with at least the specified capacity.

The hash map will be able to hold at least capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If capacity is zero, the hash map will not allocate.

Examples

let map: BumpMap<&str, i32> = BumpMap::with_capacity(10);
assert!(map.capacity() >= 10);

impl<K, V, S> BumpMap<K, V, S>

pub const fn with_hasher(hasher: S) -> Self

Creates an empty BumpMap which will use the given hash builder to hash keys.

The new map will not allocate until it is first pair inserted into.

Examples

use bumpish::BumpMap;
use std::hash::RandomState;

let s = RandomState::new();
let mut map = BumpMap::with_hasher(s);
map.insert(1, 2);

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

Creates an empty BumpMap with at least the specified capacity, using hasher to hash the keys.

The map will be able to hold at least capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If capacity is zero, the hash map will not allocate.

Examples

use bumpish::BumpMap;
use std::hash::RandomState;

let s = RandomState::new();
let mut map = BumpMap::with_capacity_and_hasher(10, s);
map.insert(1, 2);
assert!(map.capacity() >= 10);

pub fn capacity(&self) -> usize

Returns the number of elements the map can hold without reallocating.

Examples

let map: BumpMap<i32, i32> = BumpMap::with_capacity(100);
assert!(map.capacity() >= 100);

pub fn len(&self) -> usize

Returns the number of elements in the map.

Examples

let mut a = BumpMap::new();
assert_eq!(a.len(), 0);
a.insert(1, "a");
assert_eq!(a.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the map contains no elements.

Examples

let mut a = BumpMap::new();
assert!(a.is_empty());
a.insert(1, "a");
assert!(!a.is_empty());

pub fn clear(&mut self)

Clears the map, removing all key-value pairs. Can keep some of the allocated memory for reuse.

Examples

let mut a = BumpMap::new();
a.insert(1, "a");
a.clear();
assert!(a.is_empty());

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

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

Examples

use bumpish::BumpMap;

let map = BumpMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

assert_eq!(
    map.iter().collect::<Vec<(_, _)>>(),
    [(&"a", &1), (&"b", &2), (&"c", &3)]
);

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

An iterator visiting all key-value pairs in insertion order, with mutable references to the values. The iterator element type is (&'a K, &'a mut V).

Examples

use bumpish::BumpMap;

let mut map = BumpMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

// Update all values
for (_, val) in map.iter_mut() {
    *val *= 2;
}

assert_eq!(
    map.iter().collect::<Vec<(_, _)>>(),
    [(&"a", &2), (&"b", &4), (&"c", &6)]
);

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

An iterator visiting all keys in insertion order. The iterator element type is &'a K.

Examples

use bumpish::BumpMap;

let map = BumpMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for key in map.keys() {
    println!("{key}");
}

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

An iterator visiting all values in insertion order. The iterator element type is &'a V.

Examples

use bumpish::BumpMap;

let map = BumpMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for val in map.values() {
    println!("{val}");
}

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

An iterator visiting all values mutably in insertion order. The iterator element type is &'a mut V.

Examples

use bumpish::BumpMap;

let mut map = BumpMap::from([
    ("a", 1),
    ("b", 2),
    ("c", 3),
]);

for val in map.values_mut() {
    *val = *val + 10;
}

for val in map.values() {
    println!("{val}");
}

impl<K, V, S> BumpMap<K, V, S>

where S: BuildHasher,

pub fn hasher(&self) -> &S

Returns a reference to the map’s BuildHasher.

Examples

use bumpish::BumpMap;
use std::hash::RandomState;

let hasher = RandomState::new();
let map: BumpMap<i32, i32> = BumpMap::with_hasher(hasher);
let hasher: &RandomState = map.hasher();

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

where Q: ?Sized + Hash + Equivalent<K>,

Returns true if the map contains a value with an equivalent key to key.

The Q type must hash like K.

Examples

let mut map = BumpMap::new();
map.insert("a".to_owned(), 1);
assert_eq!(map.contains_key("a"), true);
assert_eq!(map.contains_key(&"a".to_owned()), true);
assert_eq!(map.contains_key("b"), false);

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

where Q: ?Sized + Hash + Equivalent<K>,

Returns a reference to the value corresponding to the key.

The Q type must hash like K.

Examples

let mut map = BumpMap::new();
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.get(&2), None);

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

where Q: ?Sized + Hash + Equivalent<K>,

Returns the key-value pair corresponding to the supplied key. This is potentially useful:

• for key types where non-identical keys can be considered equal;
• for getting the &K stored key value from an equivalent &Q lookup key; or
• for getting a reference to a key with the same lifetime as the collection.

The Q type must hash like K.

Examples

use bumpish::BumpMap;
use std::hash::{Hash, Hasher};

#[derive(Clone, Copy, Debug)]
struct S {
    id: u32,
    name: &'static str, // ignored by equality and hashing operations
}

impl PartialEq for S {
    fn eq(&self, other: &S) -> bool {
        self.id == other.id
    }
}

impl Eq for S {}

impl Hash for S {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.id.hash(state);
    }
}

let j_a = S { id: 1, name: "Jessica" };
let j_b = S { id: 1, name: "Jess" };
let p = S { id: 2, name: "Paul" };
assert_eq!(j_a, j_b);

let mut map = BumpMap::new();
map.insert(j_a, "Paris");
assert_eq!(map.get_key_value(&j_a), Some((&j_a, &"Paris")));
assert_eq!(map.get_key_value(&j_b), Some((&j_a, &"Paris"))); // the notable case
assert_eq!(map.get_key_value(&p), None);

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

where Q: ?Sized + Hash + Equivalent<K>,

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

The Q type must hash like K.

Examples

let mut map = BumpMap::new();
map.insert(1, "a");
if let Some(x) = map.get_mut(&1) {
    *x = "b";
}
assert_eq!(map[&1], "b");

impl<K, V, S> BumpMap<K, V, S>

where K: Hash + Eq, S: BuildHasher,

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

Inserts a key-value pair into the map if an equivalent key is not present.

If the new key-value pair is inserted, it returns a shared reference to the value. Otherwise, it returns None.

Examples

let mut map = BumpMap::new();

assert_eq!(map.insert(37, "a"), Some(&"a"));
assert_eq!(map.insert(37, "b"), None);
assert_eq!(map[&37], "a");

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

Inserts a key-value pair into the map if an equivalent key is not present.

If the new key-value pair is inserted, it returns a tuple of shared references to both key and value. Otherwise, it returns None.

Examples

let mut map = BumpMap::new();

assert_eq!(map.insert_full(37, "a"), Some((&37, &"a")));
assert_eq!(map.insert_full(37, "b"), None);
assert_eq!(map[&37], "a");

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

Inserts a key-value pair into the map if an equivalent key is not present.

If the new key-value pair is inserted, it returns a mutable reference to the value. Otherwise, it returns None.

Examples

let mut map = BumpMap::new();

assert_eq!(map.insert_mut(37, "a"), Some(&mut "a"));
assert_eq!(map.insert_mut(37, "b"), None);
assert_eq!(map[&37], "a");

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

Inserts a key-value pair into the map if an equivalent key is not present.

If the new key-value pair is inserted, it returns a tuple of shared reference to key and mutable reference to value. Otherwise, it returns None.

Examples

let mut map = BumpMap::new();

assert_eq!(map.insert_full(37, "a"), Some((&37, &"a")));
assert_eq!(map.insert_full(37, "b"), None);
assert_eq!(map[&37], "a");

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

Replaces the value associated with the given key. If an equivalent key is not present, inserts a new key-value pair.

Returns the old value if it existed, otherwise returns None.

Examples

let mut map = BumpMap::new();
assert_eq!(map.replace(37, "a"), None);
assert_eq!(map.replace(37, "b"), Some("a"));

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

Replaces both key and value associated with the given key. If an equivalent key is not present, inserts a new key-value pair.

Returns the old key and value if they existed, otherwise returns None.

Examples

let mut map = BumpMap::new();
assert_eq!(map.replace_full(37, "a"), None);
assert_eq!(map.replace_full(37, "b"), Some((37, "a")));

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

Gets the given key’s corresponding entry in the map.

As distinct from standard HashMap::entry, this method returns an Entry that can’t be used to modify the value associated with the key. That allows to call entry method with a shared reference to the map.

But this still allows to insert a new key-value pair into the vacant entry.

Examples

use bumpish::BumpMap;

let mut letters = BumpMap::new();

for ch in "a short treatise on fungi".chars() {
    letters.entry(ch).or_insert(true);
}

assert_eq!(letters[&'s'], true);
assert_eq!(letters[&'t'], true);
assert_eq!(letters[&'u'], true);
assert_eq!(letters.get(&'y'), None);

impl<K, V, S> BumpMap<K, V, S>

where K: Eq + Hash, S: BuildHasher,

pub fn augment<I>(&self, iter: I)

where I: IntoIterator<Item = (K, V)>,

Augment the map with the contents of an iterator. If a key (the first element of a tuple) already exists in this map, the key and corresponding value are dropped.

Unlike Extend trait, this method does not replace existing entries, and requires a shared reference to the map.

Examples

let ages = BumpMap::new();

ages.augment([("John", 18), ("Anna", 24), ("Lily", 99)]);

assert_eq!(ages[&"John"], 18);
assert_eq!(ages[&"Anna"], 24);
assert_eq!(ages[&"Lily"], 99);

ages.augment([("John", 25), ("Anna", 3), ("Will", 54)]);

assert_eq!(ages[&"John"], 18); // keeps the old value
assert_eq!(ages[&"Anna"], 24); // keeps the old value
assert_eq!(ages[&"Lily"], 99);
assert_eq!(ages[&"Will"], 54);

Trait Implementations

impl<K, V, S> Clone for BumpMap<K, V, S>

where K: Clone, V: Clone, S: Clone,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K, V, S> Debug for BumpMap<K, V, S>

where K: Debug, V: Debug,

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

Formats the value using the given formatter.

impl<K, V, S> Default for BumpMap<K, V, S>

where S: Default,

fn default() -> Self

Creates an empty BumpMap<K, V, S>, with the Default value for the hasher.

impl<'a, K, V, S> Extend<(&'a K, &'a V)> for BumpMap<K, V, S>

where K: Eq + Hash + Copy, V: Copy, S: BuildHasher,

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<K, V, S> Extend<(K, V)> for BumpMap<K, V, S>

where K: Eq + Hash, S: BuildHasher,

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<K, V, const N: usize> From<[(K, V); N]> for BumpMap<K, V, RandomState>

where K: Eq + Hash,

Available on crate feature std only.

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

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

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

Examples

let map1 = BumpMap::from([(1, 2), (3, 4)]);
let map2: BumpMap<_, _> = [(1, 2), (3, 4)].into();
assert_eq!(map1, map2);

impl<K, V, S> FromIterator<(K, V)> for BumpMap<K, V, S>

where K: Eq + Hash, S: BuildHasher + Default,

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

Constructs a BumpMap<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.

impl<K, Q, V, S> Index<&Q> for BumpMap<K, V, S>

where K: Eq + Hash, Q: Eq + Hash + Equivalent<K> + ?Sized, S: BuildHasher,

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

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

Panics

Panics if the key is not present in the BumpMap.

type Output = V

The returned type after indexing.

impl<'a, K, V, S> IntoIterator for &'a BumpMap<K, V, S>

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

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

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

Creates an iterator from a value.

impl<'a, K, V, S> IntoIterator for &'a mut BumpMap<K, V, S>

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

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

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

Creates an iterator from a value.

impl<K, V, S> IntoIterator for BumpMap<K, V, S>

type Item = (K, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V>

Which kind of iterator are we turning this into?

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

Creates an iterator from a value.

impl<K, V, S> PartialEq for BumpMap<K, V, S>

where K: Eq + Hash, V: PartialEq, S: BuildHasher,

fn eq(&self, other: &Self) -> 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<K, V, S> Eq for BumpMap<K, V, S>

where K: Eq + Hash, V: Eq, S: BuildHasher,