Struct ordered_multimap::list_ordered_multimap::ListOrderedMultimap

pub struct ListOrderedMultimap<Key, Value, State = RandomState> { /* private fields */ }

A multimap that associates with each key a list of values.

Ordering

The primary guarantee this type gives is that regardless of what you do to the multimap, you are always able to iterate through all keys and values in the order they were inserted. Values can be iterated by their insertion order either for a specific key or for the entire map.

Allocations

Allocations may be performed on any key-value insertion.

Implementations

impl<Key, Value> ListOrderedMultimap<Key, Value, RandomState>

pub fn new() -> ListOrderedMultimap<Key, Value, RandomState>

Creates a new multimap with no initial capacity.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value1");
assert_eq!(map.get(&"key1"), Some(&"value1"));

pub fn with_capacity( key_capacity: usize, value_capacity: usize ) -> ListOrderedMultimap<Key, Value, RandomState>

Creates a new multimap with the specified capacities.

The multimap will be able to hold at least key_capacity keys and value_capacity values without reallocating. A capacity of 0 will result in no allocation for the respective container.

Examples

use ordered_multimap::ListOrderedMultimap;

let map: ListOrderedMultimap<&str, &str> = ListOrderedMultimap::new();
assert_eq!(map.keys_capacity(), 0);
assert_eq!(map.values_capacity(), 0);

let map: ListOrderedMultimap<&str, &str> = ListOrderedMultimap::with_capacity(5, 10);
assert_eq!(map.keys_capacity(), 5);
assert_eq!(map.values_capacity(), 10);

impl<Key, Value, State> ListOrderedMultimap<Key, Value, State>

where State: BuildHasher,

pub fn with_capacity_and_hasher( key_capacity: usize, value_capacity: usize, state: State ) -> ListOrderedMultimap<Key, Value, State>

Creates a new multimap with the specified capacities and the given hash builder to hash keys.

The multimap will be able to hold at least key_capacity keys and value_capacity values without reallocating. A capacity of 0 will result in no allocation for the respective container.

The state is normally randomly generated and is designed to allow multimaps to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

Examples

use ordered_multimap::ListOrderedMultimap;
use std::collections::hash_map::RandomState;

let state = RandomState::new();
let mut map = ListOrderedMultimap::with_capacity_and_hasher(10, 10, state);
map.insert("key", "value");
assert_eq!(map.keys_capacity(), 10);
assert_eq!(map.values_capacity(), 10);

pub fn with_hasher(state: State) -> ListOrderedMultimap<Key, Value, State>

Creates a new multimap with no capacity which will use the given hash builder to hash keys.

The state is normally randomly generated and is designed to allow multimaps to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

Examples

use ordered_multimap::ListOrderedMultimap;
use std::collections::hash_map::RandomState;

let state = RandomState::new();
let mut map = ListOrderedMultimap::with_hasher(state);
map.insert("key", "value");

impl<Key, Value, State> ListOrderedMultimap<Key, Value, State>

pub fn back(&self) -> Option<(&Key, &Value)>

Returns an immutable reference to the first key-value pair in the multimap

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.back(), None);

map.insert("key", "value");
assert_eq!(map.back(), Some((&"key", &"value")));

pub fn back_mut(&mut self) -> Option<(&Key, &mut Value)>

Returns an immutable reference to the first key-value pair in the multimap

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.back_mut(), None);

map.insert("key", "value");
assert_eq!(map.back_mut(), Some((&"key", &mut "value")));

pub fn clear(&mut self)

Removes all keys and values from the multimap.

Complexity: O(|K| + |V|) where |K| is the number of keys and |V| is the number of values.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key", "value");
assert_eq!(map.keys_len(), 1);
assert_eq!(map.values_len(), 1);

map.clear();
assert_eq!(map.keys_len(), 0);
assert_eq!(map.values_len(), 0);

pub fn front(&self) -> Option<(&Key, &Value)>

Returns an immutable reference to the first key-value pair in the multimap

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.front(), None);

map.insert("key", "value");
assert_eq!(map.front(), Some((&"key", &"value")));

pub fn front_mut(&mut self) -> Option<(&Key, &mut Value)>

Returns an immutable reference to the first key-value pair in the multimap

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.front_mut(), None);

map.insert("key", "value");
assert_eq!(map.front_mut(), Some((&"key", &mut "value")));

pub fn hasher(&self) -> &State

Returns a reference to the multimap’s BuildHasher.

Examples

use ordered_multimap::ListOrderedMultimap;

let map: ListOrderedMultimap<&str, &str> = ListOrderedMultimap::new();
let hasher = map.hasher();

pub fn is_empty(&self) -> bool

Returns whether the multimap is empty.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert!(map.is_empty());

map.insert("key1", "value");
assert!(!map.is_empty());

map.remove(&"key1");
assert!(map.is_empty());

pub fn iter(&self) -> Iter<'_, Key, Value>

Returns an iterator that yields immutable references to all key-value pairs in the multimap by insertion order.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value1");
map.insert("key2", "value1");
map.append(&"key1", "value2");
map.append(&"key2", "value2");

let mut iter = map.iter();
assert_eq!(iter.size_hint(), (4, Some(4)));
assert_eq!(iter.next(), Some((&"key1", &"value1")));
assert_eq!(iter.next(), Some((&"key2", &"value1")));
assert_eq!(iter.next(), Some((&"key1", &"value2")));
assert_eq!(iter.next(), Some((&"key2", &"value2")));
assert_eq!(iter.next(), None);

pub fn iter_mut(&mut self) -> IterMut<'_, Key, Value>

Returns an iterator that yields mutable references to all key-value pairs in the multimap by insertion order.

Only the values are mutable, the keys are immutable.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value1");
map.insert("key2", "value1");
map.append(&"key1", "value2");
map.append(&"key2", "value2");

let mut iter = map.iter_mut();
assert_eq!(iter.size_hint(), (4, Some(4)));

let first = iter.next().unwrap();
assert_eq!(first, (&"key1", &mut "value1"));
*first.1 = "value3";

assert_eq!(iter.next(), Some((&"key2", &mut "value1")));
assert_eq!(iter.next(), Some((&"key1", &mut "value2")));
assert_eq!(iter.next(), Some((&"key2", &mut "value2")));
assert_eq!(iter.next(), None);

assert_eq!(map.get(&"key1"), Some(&"value3"));

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

Returns an iterator that yields immutable references to all keys in the multimap by insertion order.

Insertion order of keys is determined by the order in which a given key is first inserted into the multimap with a value. Any subsequent insertions with that key without first removing it will not affect its ordering.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value");
map.insert("key2", "value");
map.insert("key3", "value");

let mut keys = map.keys();
assert_eq!(keys.next(), Some(&"key1"));
assert_eq!(keys.next(), Some(&"key2"));
assert_eq!(keys.next(), Some(&"key3"));
assert_eq!(keys.next(), None);

pub fn keys_capacity(&self) -> usize

Returns the number of keys the multimap can hold without reallocating.

This number is a lower bound, and the multimap may be able to hold more.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.keys_capacity(), 0);

map.insert("key", "value");
assert!(map.keys_capacity() > 0);

pub fn keys_len(&self) -> usize

Returns the number of keys in the multimap.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.keys_len(), 0);

map.insert("key1", "value");
map.insert("key2", "value");
map.insert("key3", "value");
assert_eq!(map.keys_len(), 3);

pub fn pairs(&self) -> KeyValues<'_, Key, Value, State>

Returns an iterator that yields immutable references to keys and all associated values with those keys as separate iterators. The order of yielded pairs will be the order in which the keys were first inserted into the multimap.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

map.insert("key", "value1");
map.append("key", "value2");

let mut iter = map.pairs();

let (key, mut values) = iter.next().unwrap();
assert_eq!(key, &"key");
assert_eq!(values.next(), Some(&"value1"));
assert_eq!(values.next(), Some(&"value2"));
assert_eq!(values.next(), None);

pub fn pairs_mut(&mut self) -> KeyValuesMut<'_, Key, Value, State>

Returns an iterator that yields immutable references to keys and mutable references to all associated values with those keys as separate iterators. The order of yielded pairs will be the order in which the keys were first inserted into the multimap.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

map.insert("key", "value1");
map.append("key", "value2");

let mut iter = map.pairs_mut();

let (key, mut values) = iter.next().unwrap();
assert_eq!(key, &"key");
assert_eq!(values.next(), Some(&mut "value1"));
assert_eq!(values.next(), Some(&mut "value2"));
assert_eq!(values.next(), None);

pub fn reserve_values(&mut self, additional_capacity: usize)

Reserves additional capacity such that more values can be stored in the multimap.

If the existing capacity minus the current length is enough to satisfy the additional capacity, the capacity will remain unchanged.

If the capacity is increased, the capacity may be increased by more than what was requested.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::with_capacity(1, 1);

map.insert("key", "value");
assert_eq!(map.values_capacity(), 1);

map.reserve_values(10);
assert!(map.values_capacity() >= 11);

pub fn values(&self) -> Values<'_, Key, Value>

Returns an iterator that yields immutable references to all values in the multimap by insertion order.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value1");
map.insert("key2", "value1");
map.append(&"key1", "value2");
map.append(&"key2", "value2");

let mut iter = map.values();
assert_eq!(iter.size_hint(), (4, Some(4)));
assert_eq!(iter.next(), Some(&"value1"));
assert_eq!(iter.next(), Some(&"value1"));
assert_eq!(iter.next(), Some(&"value2"));
assert_eq!(iter.next(), Some(&"value2"));
assert_eq!(iter.next(), None);

pub fn values_mut(&mut self) -> ValuesMut<'_, Key, Value>

Returns an iterator that yields mutable references to all values in the multimap by insertion order.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key1", "value1");
map.insert("key2", "value1");
map.append(&"key1", "value2");
map.append(&"key2", "value2");

let mut iter = map.values_mut();
assert_eq!(iter.size_hint(), (4, Some(4)));

let first = iter.next().unwrap();
assert_eq!(first, &mut "value1");
*first = "value3";

assert_eq!(iter.next(), Some(&mut "value1"));
assert_eq!(iter.next(), Some(&mut "value2"));
assert_eq!(iter.next(), Some(&mut "value2"));
assert_eq!(iter.next(), None);

assert_eq!(map.get(&"key1"), Some(&"value3"));

pub fn values_capacity(&self) -> usize

Returns the number of values the multimap can hold without reallocating.

This number is a lower bound, and the multimap may be able to hold more.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.values_capacity(), 0);

map.insert("key", "value");
assert!(map.values_capacity() > 0);

pub fn values_len(&self) -> usize

Returns the total number of values in the multimap across all keys.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.values_len(), 0);

map.insert("key1", "value1");
assert_eq!(map.values_len(), 1);

map.append("key1", "value2");
assert_eq!(map.values_len(), 2);

impl<Key, Value, State> ListOrderedMultimap<Key, Value, State>

where Key: Eq + Hash, State: BuildHasher,

pub fn append(&mut self, key: Key, value: Value) -> bool

Appends a value to the list of values associated with the given key.

If the key is not already in the multimap, this will be identical to an insert and the return value will be false. Otherwise, true will be returned.

Complexity: amortized O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
let already_exists = map.append("key", "value");
assert!(!already_exists);
assert_eq!(map.values_len(), 1);
assert_eq!(map.get(&"key"), Some(&"value"));

let already_exists = map.append("key", "value2");
assert!(already_exists);
assert_eq!(map.values_len(), 2);

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

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns whether the given key is in the multimap.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert!(!map.contains_key(&"key"));
map.insert("key", "value");
assert!(map.contains_key(&"key"));

pub fn entry(&mut self, key: Key) -> Entry<'_, Key, Value, State>

Returns whether the given key is in the multimap.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
let value = map.entry("key").or_insert("value");
assert_eq!(value, &"value");
assert_eq!(map.get(&"key"), Some(&"value"));

pub fn entry_len<KeyQuery>(&self, key: &KeyQuery) -> usize

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns the number of values associated with a key.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.entry_len(&"key"), 0);

map.insert("key", "value1");
assert_eq!(map.entry_len(&"key"), 1);

map.append(&"key", "value2");
assert_eq!(map.entry_len(&"key"), 2);

pub fn get<KeyQuery>(&self, key: &KeyQuery) -> Option<&Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns an immutable reference to the first value, by insertion order, associated with the given key, or None if the key is not in the multimap.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map: ListOrderedMultimap<&str, &str> = ListOrderedMultimap::new();
assert_eq!(map.get(&"key"), None);

pub fn get_all<KeyQuery>(&self, key: &KeyQuery) -> EntryValues<'_, Key, Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns an iterator that yields immutable references to all values associated with the given key by insertion order.

If the key is not in the multimap, the iterator will yield no values.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key", "value");
map.append("key", "value2");

let mut iter = map.get_all(&"key");
assert_eq!(iter.next(), Some(&"value"));
assert_eq!(iter.next(), Some(&"value2"));
assert_eq!(iter.next(), None);

pub fn get_all_mut<KeyQuery>( &mut self, key: &KeyQuery ) -> EntryValuesMut<'_, Key, Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns an iterator that yields mutable references to all values associated with the given key by insertion order.

If the key is not in the multimap, the iterator will yield no values.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
map.insert("key", "value1");
map.append("key", "value2");

let mut iter = map.get_all_mut(&"key");

let first = iter.next().unwrap();
assert_eq!(first, &mut "value1");
*first = "value3";

assert_eq!(iter.next(), Some(&mut "value2"));
assert_eq!(iter.next(), None);

assert_eq!(map.get(&"key"), Some(&"value3"));

pub fn get_mut<KeyQuery>(&mut self, key: &KeyQuery) -> Option<&mut Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Returns a mutable reference to the first value, by insertion order, associated with the given key, or None if the key is not in the multimap.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert_eq!(map.get(&"key"), None);

map.insert("key", "value");
assert_eq!(map.get(&"key"), Some(&"value"));

let mut value = map.get_mut(&"key").unwrap();
*value = "value2";

assert_eq!(map.get(&"key"), Some(&"value2"));

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

Inserts the key-value pair into the multimap and returns the first value, by insertion order, that was already associated with the key.

If the key is not already in the multimap, None will be returned. If the key is already in the multimap, the insertion ordering of the keys will remain unchanged.

Complexity: O(1) amortized

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert!(map.is_empty());

let old_value = map.insert("key", "value");
assert!(old_value.is_none());
assert_eq!(map.values_len(), 1);
assert_eq!(map.get(&"key"), Some(&"value"));

let old_value = map.insert("key", "value2");
assert_eq!(old_value, Some("value"));
assert_eq!(map.values_len(), 1);
assert_eq!(map.get(&"key"), Some(&"value2"));

pub fn insert_all( &mut self, key: Key, value: Value ) -> EntryValuesDrain<'_, Key, Value>

Inserts the key-value pair into the multimap and returns an iterator that yields all values previously associated with the key by insertion order.

If the key is not already in the multimap, the iterator will yield no values.If the key is already in the multimap, the insertion ordering of the keys will remain unchanged.

Complexity: O(1) amortized

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();
assert!(map.is_empty());

{
  let mut old_values = map.insert_all("key", "value");
  assert_eq!(old_values.next(), None);
}

assert_eq!(map.values_len(), 1);
assert_eq!(map.get(&"key"), Some(&"value"));

map.append("key", "value2");

{
  let mut old_values = map.insert_all("key", "value3");
  assert_eq!(old_values.next(), Some("value"));
  assert_eq!(old_values.next(), Some("value2"));
  assert_eq!(old_values.next(), None);
}

assert_eq!(map.values_len(), 1);
assert_eq!(map.get(&"key"), Some(&"value3"));

pub fn pack_to( &mut self, keys_minimum_capacity: usize, values_minimum_capacity: usize )

where State: Default,

Reorganizes the multimap to ensure maximum spatial locality and changes the key and value capacities to the provided values.

This function can be used to actually increase the capacity of the multimap.

Complexity: O(|K| + |V|) where |K| is the number of keys and |V| is the number of values.

Panics

Panics if either of the given minimum capacities are less than their current respective lengths.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::with_capacity(10, 10);

map.insert("key1", "value1");
map.insert("key2", "value2");
map.append("key2", "value3");
map.append("key1", "value4");
map.pack_to(5, 5);

assert_eq!(map.keys_capacity(), 5);
assert_eq!(map.keys_len(), 2);
assert_eq!(map.values_capacity(), 5);
assert_eq!(map.values_len(), 4);

pub fn pack_to_fit(&mut self)

where State: Default,

Reorganizes the multimap to ensure maximum spatial locality and removes any excess key and value capacity.

Complexity: O(|K| + |V|) where |K| is the number of keys and |V| is the number of values.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::with_capacity(5, 5);

map.insert("key1", "value1");
map.insert("key2", "value2");
map.append("key2", "value3");
map.append("key1", "value4");
map.pack_to_fit();

assert_eq!(map.keys_capacity(), 2);
assert_eq!(map.keys_len(), 2);
assert_eq!(map.values_capacity(), 4);
assert_eq!(map.values_len(), 4);

pub fn pop_back(&mut self) -> Option<(KeyWrapper<'_, Key>, Value)>

Removes the last key-value pair to have been inserted.

Because a single key can be associated with many values, the key returned by this function is a KeyWrapper which can be either owned or borrowed. If the value removed was the only value associated with the key, then the key will be returned. Otherwise, a reference to the key will be returned.

This function along with ListOrderedMultimap::pop_front act as replacements for a drain iterator since an iterator cannot be done over KeyWrapper.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;
use ordered_multimap::list_ordered_multimap::KeyWrapper;

let mut map = ListOrderedMultimap::new();

map.insert("key", "value1");
map.append("key", "value2");

let (key, value) = map.pop_back().unwrap();
assert_eq!(key, KeyWrapper::Borrowed(&"key"));
assert_eq!(&value, &"value2");

let (key, value) = map.pop_back().unwrap();
assert_eq!(key, KeyWrapper::Owned("key"));
assert_eq!(&value, &"value1");

pub fn pop_front(&mut self) -> Option<(KeyWrapper<'_, Key>, Value)>

Removes the first key-value pair to have been inserted.

Because a single key can be associated with many values, the key returned by this function is a KeyWrapper which can be either owned or borrowed. If the value removed was the only value associated with the key, then the key will be returned. Otherwise, a reference to the key will be returned.

This function along with ListOrderedMultimap::pop_back act as replacements for a drain iterator since an iterator cannot be done over KeyWrapper.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;
use ordered_multimap::list_ordered_multimap::KeyWrapper;

let mut map = ListOrderedMultimap::new();

map.insert("key", "value1");
map.append("key", "value2");

let (key, value) = map.pop_front().unwrap();
assert_eq!(key, KeyWrapper::Borrowed(&"key"));
assert_eq!(&value, &"value1");

let (key, value) = map.pop_front().unwrap();
assert_eq!(key, KeyWrapper::Owned("key"));
assert_eq!(&value, &"value2");

pub fn remove<KeyQuery>(&mut self, key: &KeyQuery) -> Option<Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Removes all values associated with the given key from the map and returns the first value by insertion order.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

let removed_value = map.remove(&"key");
assert_eq!(removed_value, None);

map.insert("key", "value");
assert_eq!(map.get(&"key"), Some(&"value"));

let removed_value = map.remove(&"key");
assert_eq!(removed_value, Some("value"));
assert_eq!(map.get(&"key"), None);

pub fn remove_all<KeyQuery>( &mut self, key: &KeyQuery ) -> EntryValuesDrain<'_, Key, Value>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Removes all values associated with the given key from the map and returns an iterator that yields those values.

If the key is not already in the map, the iterator will yield no values.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

{
    let mut removed_values = map.remove_all(&"key");
    assert_eq!(removed_values.next(), None);
}

map.insert("key", "value1");
map.append("key", "value2");
assert_eq!(map.get(&"key"), Some(&"value1"));

{
    let mut removed_values = map.remove_all(&"key");
    assert_eq!(removed_values.next(), Some("value1"));
    assert_eq!(removed_values.next(), Some("value2"));
    assert_eq!(removed_values.next(), None);
}

assert_eq!(map.get(&"key"), None);

pub fn remove_entry<KeyQuery>(&mut self, key: &KeyQuery) -> Option<(Key, Value)>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Removes all values associated with the given key from the map and returns the key and first value.

If the key is not already in the map, then None will be returned.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

let entry = map.remove_entry(&"key");
assert_eq!(entry, None);

map.insert("key", "value");
assert_eq!(map.get(&"key"), Some(&"value"));

let entry = map.remove_entry(&"key");
assert_eq!(entry, Some(("key", "value")));
assert_eq!(map.get(&"key"), None);

pub fn remove_entry_all<KeyQuery>( &mut self, key: &KeyQuery ) -> Option<(Key, EntryValuesDrain<'_, Key, Value>)>

where Key: Borrow<KeyQuery>, KeyQuery: ?Sized + Eq + Hash,

Removes all values associated with the given key from the map and returns the key and an iterator that yields those values.

If the key is not already in the map, then None will be returned.

Complexity: O(1)

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

{
    let entry = map.remove_entry_all(&"key");
    assert!(entry.is_none());
}

map.insert("key", "value1");
map.append("key", "value2");
assert_eq!(map.get(&"key"), Some(&"value1"));

{
    let (key, mut iter) = map.remove_entry_all(&"key").unwrap();
    assert_eq!(key, "key");
    assert_eq!(iter.next(), Some("value1"));
    assert_eq!(iter.next(), Some("value2"));
    assert_eq!(iter.next(), None);
}

assert_eq!(map.get(&"key"), None);

pub fn reserve_keys(&mut self, additional_capacity: usize)

Reserves additional capacity such that more keys can be stored in the multimap.

If the existing capacity minus the current length is enough to satisfy the additional capacity, the capacity will remain unchanged.

If the capacity is increased, the capacity may be increased by more than what was requested.

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::with_capacity(1, 1);

map.insert("key", "value");
assert_eq!(map.keys_capacity(), 1);

map.reserve_keys(10);
assert!(map.keys_capacity() >= 11);
assert_eq!(map.get(&"key"), Some(&"value"));

pub fn retain<Function>(&mut self, function: Function)

where Function: FnMut(&Key, &mut Value) -> bool,

Keeps all key-value pairs that satisfy the given predicate function.

Complexity: O(|V|) where |V| is the number of values

Examples

use ordered_multimap::ListOrderedMultimap;

let mut map = ListOrderedMultimap::new();

map.insert("key1", 1);
map.insert("key2", 5);
map.append("key1", -1);
map.insert("key3", -10);

map.retain(|_, &mut value| value >= 0);

let mut iter = map.iter();
assert_eq!(iter.next(), Some((&"key1", &1)));
assert_eq!(iter.next(), Some((&"key2", &5)));
assert_eq!(iter.next(), None);

Trait Implementations

impl<Key: Clone, Value: Clone, State: Clone> Clone for ListOrderedMultimap<Key, Value, State>

fn clone(&self) -> ListOrderedMultimap<Key, Value, State>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Key, Value, State> Debug for ListOrderedMultimap<Key, Value, State>

where Key: Debug, Value: Debug,

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

Formats the value using the given formatter.

impl<Key, Value> Default for ListOrderedMultimap<Key, Value, RandomState>

fn default() -> Self

Returns the “default value” for a type.

impl<'a, Key, Value, State> Extend<(&'a Key, &'a Value)> for ListOrderedMultimap<Key, Value, State>

where Key: Copy + Eq + Hash, Value: Copy, State: BuildHasher,

fn extend<Iter>(&mut self, iter: Iter)

where Iter: IntoIterator<Item = (&'a Key, &'a Value)>,

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<Key, Value, State> Extend<(Key, Value)> for ListOrderedMultimap<Key, Value, State>

where Key: Eq + Hash, State: BuildHasher,

fn extend<Iter>(&mut self, iter: Iter)

where Iter: IntoIterator<Item = (Key, Value)>,

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<Key, Value, State> FromIterator<(Key, Value)> for ListOrderedMultimap<Key, Value, State>

where Key: Eq + Hash, State: BuildHasher + Default,

fn from_iter<Iter>(iter: Iter) -> Self

where Iter: IntoIterator<Item = (Key, Value)>,

Creates a value from an iterator.

impl<'map, Key, Value, State> IntoIterator for &'map ListOrderedMultimap<Key, Value, State>

type IntoIter = Iter<'map, Key, Value>

Which kind of iterator are we turning this into?

type Item = (&'map Key, &'map Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'map, Key, Value, State> IntoIterator for &'map mut ListOrderedMultimap<Key, Value, State>

type IntoIter = IterMut<'map, Key, Value>

Which kind of iterator are we turning this into?

type Item = (&'map Key, &'map mut Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Key, Value, State> IntoIterator for ListOrderedMultimap<Key, Value, State>

where Key: Clone,

type IntoIter = IntoIter<Key, Value>

Which kind of iterator are we turning this into?

type Item = (Key, Value)

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Key, Value, State> PartialEq for ListOrderedMultimap<Key, Value, State>

where Key: PartialEq, Value: PartialEq,

fn eq(&self, other: &ListOrderedMultimap<Key, Value, State>) -> bool

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

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

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

impl<Key, Value, State> Eq for ListOrderedMultimap<Key, Value, State>

where Key: Eq, Value: PartialEq,