Struct total_order_multi_map::TotalOrderMultiMap

pub struct TotalOrderMultiMap<K, V> where
    V: StableDeref + DerefMut,
    K: Hash + Eq + Copy,  { /* fields omitted */ }

A multi map with keeps the total ordering of inserted elements

The map is meant to contain values implementing StableDeref, methods like get and iter will iterate over the inner values referred to when dereferencing the values.

The key is currently limited to values implementing Copy.

See the module/crate level documentation for more details.

Unwind Safety

This type is unwind + resume safe. Through in the unlikely case that a panic happens inside of a function like insert,get the resulting state might be inconsistent in a safe way, i.e. some values might be in the map, accessible during iteration but hey won't appear when using get.

Note that this can only happen in a few rare cases:

1. Vec::pop/Vec::reserve panics
2. HashMap::insert/HashMap::reserve panics
3. for some reason oom does panic instead of aborting

Which mainly can happen in mainly following cases:

• the vector of key-value pairs tries to contain more then isize::MAX bytes
• you use zero-sized values and overflow usize (which can't really happen as we store at last some data per inserting, i.e. you would overflow the vec first)

Generally speaking you won't run into any of this in normal circumstances and if you do it's likely that you are close to a system wide oom anyway.

Methods

impl<K, V> TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

Important traits for Iter<'a, K, V>

impl<'a, K, V> Iterator for Iter<'a, K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut,  type Item = (K, &'a V::Target);

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

Returns a iterator over the key value pairs in insertion order.

As this is a multi map a key can appear more than one time.

impl<K, V> TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

Important traits for IterMut<'a, K, V>

impl<'a, K, V> Iterator for IterMut<'a, K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut,  type Item = (K, &'a mut V::Target);

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

impl<K, V> TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

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

return a entry for a given key

impl<K, V> TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

Important traits for Keys<'a, K, T>

impl<'a, K: 'a, T: 'a> Iterator for Keys<'a, K, T> where
    K: Copy,  type Item = K;

pub fn keys(&self) -> Keys<K, V::Target>

Return an iterator the keys of this multi map.

each key will only be returned once, there is no specific order in which they keys are returned

Important traits for GroupedValues<'a, K, T>

impl<'a, K, T: ?Sized> Iterator for GroupedValues<'a, K, T> where
    K: Copy + 'a,
    T: 'a,  type Item = Group<'a, K, T>;

pub fn group_iter(&self) -> GroupedValues<K, V::Target>

Returns a iterator over all values grouped by key.

Important traits for GroupedValuesMut<'a, K, T>

impl<'a, K, T: ?Sized> Iterator for GroupedValuesMut<'a, K, T> where
    K: Copy + 'a,
    T: 'a,  type Item = GroupMut<'a, K, T>;

pub fn group_iter_mut(&mut self) -> GroupedValuesMut<K, V::Target>

Returns a iterator over all values grouped by key

Important traits for Values<'a, K, V>

impl<'a, K: 'a, V: 'a> Iterator for Values<'a, K, V> where
    V: StableDeref + DerefMut,  type Item = &'a V::Target;

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

Returns a iterator over the inner-values in this multi map.

Inner-Values are returned in the order they where inserted into the map. Note that

Important traits for ValuesMut<'a, K, V>

impl<'a, K: 'a, V: 'a> Iterator for ValuesMut<'a, K, V> where
    V: StableDeref + DerefMut,  type Item = &'a mut V::Target;

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

Returns a iterator over the values in this multi map.

impl<K, V> TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

pub fn new() -> Self

Create a new empty map.

pub fn with_capacity(capacity: usize) -> Self

Crate a new map with a given capacity.

Note that this method will reserve the given capacity for the internal Vec and HashMap, but as it's a multi map it can not know how elements will be distributed, as such using with_capacity does not guarantee that there are no allocations if less than capacity elements are inserted. Through it still can reduce the number of allocations needed.

pub fn capacity(&self) -> usize

Returns the capacity (unreliable).

This is not reliable as it only returns the capacity of the underlying Vec not considering the underlying HashMap or the Vec used to turn the map into a multi map.

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

Reserves space for n additional elements.

The reservation is done in both the internal Vec and HashMap but as the map is a multi map this method is less helpful as e.g. on a pure Vec or HashMap

Panics

if the new allocation size overflows usize

pub fn reverse(&mut self)

Reverses insertion order.

After calling this the map will contains values as if they had been inserted in reversed order.

This will affect both the iteration order of the fill map as well as the iteration order of values returned by get.

pub fn shrink_to_fit(&mut self)

Shrinks all internal containers to not contains any additional capacity.

Whether or not memory is freed depends in the dens on the shrink_to_fit implementation of Vec and HashMap

pub fn len(&self) -> usize

Returns the total number of elements.

pub fn key_count(&self) -> usize

Returns the total number of different keys.

pub fn is_empty(&self) -> bool

Returns true if the map is empty.

pub fn clear(&mut self)

Empties this map.

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

Returns true if the key is contained in the map.

Does not state how many values are associated with it.

Important traits for EntryValues<'a, T>

impl<'a, T: ?Sized + 'a> Iterator for EntryValues<'a, T> type Item = &'a T;

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

Returns values associated with the given key.

If the key is not in the map this will return None. This also means that EntryValues has at last one element.

Important traits for EntryValuesMut<'a, T>

impl<'a, T: ?Sized + 'a> Iterator for EntryValuesMut<'a, T> type Item = &'a mut T;

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

Returns mutable references associated with the given key.

If the key is not in the map this will return None. This means the EntryValuesMut has at last one element.

Important traits for EntryValuesMut<'a, T>

impl<'a, T: ?Sized + 'a> Iterator for EntryValuesMut<'a, T> type Item = &'a mut T;

pub fn add(&mut self, key: K, value: V) -> EntryValuesMut<V::Target>

Adds a value for a given key to the multi map.

Returns access the all values already added to the key previously and this now added value through EntryValuesMut

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

Sets the value associated with the given key.

Values previously associated with the key are removed and returned.

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

Remove and return the element last inserted.

pub fn truncate(&mut self, to_len: usize)

Keeps the first to_len inserted headers, removing the remaining ones.

If to_len is equal or larger the current length nothing will happen.

This won't affect the capacity.

Which headers are keeps/removed depends on the insertion order of the headers in the map and is independent of the headers name or if there had been other headers with the same name inserted before/after.

pub fn remove_all(&mut self, key_to_remove: K) -> bool

removes all values associated with the given key

I.e. this removes all key-value pairs which key is equal to the given key.

Returns true if at last one value was removed

pub fn retain<FN>(&mut self, func: FN) where
    FN: FnMut(K, &V::Target) -> bool, 

retains only key value pairs for which func returns true

All key-value pairs for with the predicate func returns false will be removed.

Trait Implementations

impl<K, V> Send for TotalOrderMultiMap<K, V> where
    SyncSendHelper<K, V>: Send,
    V: StableDeref + DerefMut,
    K: Hash + Eq + Copy, 

see SendSyncHelper

impl<K, V> Sync for TotalOrderMultiMap<K, V> where
    SyncSendHelper<K, V>: Sync,
    V: StableDeref + DerefMut,
    K: Hash + Eq + Copy, 

see SendSyncHelper

impl<K, V> Extend<(K, V)> for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

fn extend<I>(&mut self, src: I) where
    I: IntoIterator<Item = (K, V)>, 

Extends a collection with the contents of an iterator.

impl<K, V> IntoIterator for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

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.

impl<K, V> Clone for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut + Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<K, V> Default for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

fn default() -> Self

Returns the "default value" for a type.

impl<K, V> Eq for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut + Eq, 

Compares for equality which does consider the insertion order

impl<K, V> PartialEq<TotalOrderMultiMap<K, V>> for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut + PartialEq<V>, 

Compares for equality which does consider the insertion order

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<K, V> Debug for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy + Debug,
    V: StableDeref + DerefMut + Debug, 

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

Formats the value using the given formatter.

impl<K, V> FromIterator<(K, V)> for TotalOrderMultiMap<K, V> where
    K: Hash + Eq + Copy,
    V: StableDeref + DerefMut, 

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

Creates a value from an iterator.