Struct mod_utilities::collections::map::Map

pub struct Map<K: PartialEq + Hash, V: PartialEq> { /* fields omitted */ }

An associative array of keys to values

Allows bi-directional lookup, using hashing for keys and direct comparison for values

Key types must implement PartialEq, Clone, and Hash

Value types must implement PartialEq

Implementations

impl<K: PartialEq + Hash, V: PartialEq> Map<K, V>

pub fn hash<EqK: Hash + ?Sized>(key: &EqK) -> u64 where
    K: PartialEq<EqK>, 

Used by all Maps of a given type to generate hashes from keys

pub fn with_capacity(cap: usize) -> Self

Create a Map and pre-allocate its Vecs with a specified capacity

pub fn new() -> Self

Create a Map and pre-allocate its Vecs with the Map::DEFAULT_CAPACITY

pub fn index_of_key<EqK: Hash + ?Sized>(&self, key: &EqK) -> Option<usize> where
    K: PartialEq<EqK>, 

Find the vec index of a key if it exists in a Map

pub fn index_of_value(&self, value: &V) -> Option<usize>

Find the vec index of a value if it exists in a Map

pub fn contains_key<EqK: Hash + ?Sized>(&self, key: &EqK) -> bool where
    K: PartialEq<EqK>, 

Determine if a Map contains a given key

pub fn contains_value(&self, value: &V) -> bool

Determine if a Map contains a given value

pub fn maybe_contains_key<EqK: Hash + ?Sized>(&self, key: &EqK) -> bool where
    K: PartialEq<EqK>, 

Determine if a Map potentially contains a given key

This works by comparing hashes only, and may yield false positives, but will never yield a false negative

pub fn len(&self) -> usize

Get the number of (key, value) pairs in a Map

pub fn is_empty(&self) -> bool

Determine if a Map contains any values

pub fn find_value<EqK: Hash + ?Sized>(&self, key: &EqK) -> Option<&V> where
    K: PartialEq<EqK>, 

Get an immutable reference to a value associated with a given key in a Map, if it contains a pair with a matching key

pub fn find_value_mut<EqK: Hash + ?Sized>(
    &mut self,
    key: &EqK
) -> Option<&mut V> where
    K: PartialEq<EqK>, 

Get a mutable reference to a value associated with a given key in a Map, if it contains a pair with a matching key

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

Get an immutable reference to a key associated with a given value in a Map, if it contains a pair with a matching value

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

Get a mutable reference to a key associated with a given value in a Map, if it contains a pair with a matching value

pub unsafe fn get_pair_unchecked(&self, idx: usize) -> (&K, &V)

Get an immutable references to a (key, value) pair in a Map by index

Safety

Does not range check the index

Note that the Map type does not necessarily preserve its order, so index-based referencing is temporaly unstable

pub unsafe fn get_pair_unchecked_mut(&mut self, idx: usize) -> (&mut K, &mut V)

Get a mutable references to a (key, value) pair in a Map by index

Safety

Does not range check the index

Note that the Map type does not necessarily preserve its order, so index-based referencing is temporaly unstable

pub fn get_pair(&self, idx: usize) -> Option<(&K, &V)>

Get an immutable references to a (key, value) pair in a Map by index

A range check is performed on the index

Note that the Map type does not necessarily preserve its order, so index-based referencing is temporaly unstable

pub fn get_pair_mut(&mut self, idx: usize) -> Option<(&mut K, &mut V)>

Get a mutable references to a (key, value) pair in a Map by index

A range check is performed on the index

Note that the Map type does not necessarily preserve its order, so index-based referencing is temporaly unstable

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

Insert a value at the given key in a Map even if one already exists

Returns the existing value if one is already bound to the key (The opposite of insert_unique)

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

Insert a value at the given key in a Map if they key does not already exist

Returns the (key, value) pair provided and does nothing if an existing key is found (The opposite of insert)

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

Insert a value at the given key in a Map if the value does not already exist

Returns the (key, value) pair provided and does nothing if an existing value is found (The opposite of insert)

pub fn remove_by_index(&mut self, idx: usize) -> Option<(K, V)>

Removes a (key, value) pair at the given index in a Map if it is in range

Returns the pair if one is found

Does not preserve order

pub fn remove_by_key<EqK: Hash + ?Sized>(&mut self, key: &EqK) -> Option<(K, V)> where
    K: PartialEq<EqK>, 

Removes a (key, value) pair matching the given key in a Map if one exists

Returns the pair if one is found

Does not preserve order

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

Removes the first (key, value) pair matching the given value in a Map if one exists

Returns the pair if one is found

Does not preserve order

pub fn pop(&mut self) -> Option<(K, V)>

Remove a (key, value) pair from a Map if there are any

Returns the pair if one exists

Preserves order, removing the last pair of the Map

pub fn keys(&self) -> &[K]

Get an immutable slice of the keys of a Map

pub fn keys_mut(&mut self) -> &mut [K]

Get a mutable iterator over the keys of a Map

pub fn values(&self) -> &[V]

Get a mutable slice of the values of a Map

pub fn values_mut(&mut self) -> &mut [V]

Get a mutable iterator over the values of a Map

pub fn key_iter(&self) -> SliceIter<K>

Get an immutable iterator over the keys of a Map

pub fn key_iter_mut(&mut self) -> SliceIterMut<K>

Get a mutable iterator over the keys of a Map

pub fn value_iter(&self) -> SliceIter<V>

Get an immutable iterator over the values of a Map

pub fn value_iter_mut(&mut self) -> SliceIterMut<V>

Get a mutable iterator over the values of a Map

pub fn iter(&self) -> PairIter<K, V>

Get an immutable iterator over the (key, value) pairs of a Map

pub fn iter_mut(&mut self) -> PairIterMut<K, V>

Get a mutable iterator over the (key, value) pairs of a Map

pub fn merge_discard(&mut self, other: Self)

Move the (key, value) pairs of another Map into a Map

Uses insert_unique to move values, thereby discarding values from the other Map, if they share a key with an existing entry

Consumes the other Map

Use merge_discard_to_vec to retain the discarded values

pub fn merge_discard_to_vec(&mut self, other: Self) -> Vec<(K, V)>

Move the (key, value) pairs of another Map into a Map

Uses insert_unique to move values, thereby discarding values from the other Map, if they share a key with an existing entry

Consumes the other Map and retains discarded values in a Vec

Use merge_discard to drop discard values immediately

pub fn merge_overwrite(&mut self, other: Self)

Move the (key, value) pairs of another Map into a Map

Uses insert to move values, therby overwriting values from the Map, if they share a key with an entry from the other Map

Consumes the other Map

Trait Implementations

impl<K: Clone + PartialEq + Hash, V: Clone + PartialEq> Clone for Map<K, V>

fn clone(&self) -> Map<K, V>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K: Debug + PartialEq + Hash, V: Debug + PartialEq> Debug for Map<K, V>

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

Formats the value using the given formatter.

impl<K: PartialEq + Hash, V: PartialEq> FromIterator<(K, V)> for Map<K, V>

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

Creates a value from an iterator.

impl<'_, EqK: Hash + ?Sized, K: PartialEq + Hash, V: PartialEq> Index<&'_ EqK> for Map<K, V> where
    K: PartialEq<EqK>, 

type Output = V

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'_, EqK: Hash + ?Sized, K: PartialEq + Hash, V: PartialEq> IndexMut<&'_ EqK> for Map<K, V> where
    K: PartialEq<EqK>, 

fn index_mut(&mut self, key: &EqK) -> &mut Self::Output

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

impl<K: PartialEq + Hash, V: PartialEq> IntoIterator for Map<K, V>

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) -> Self::IntoIter

Creates an iterator from a value.