pub struct Map<K, V, C = Natural<K>>where
C: Compare<K>,{ /* private fields */ }
Expand description
An ordered map based on a binary search tree.
The behavior of this map is undefined if a key’s ordering relative to any other key changes
while the key is in the map. This is normally only possible through Cell
, RefCell
, or
unsafe code.
Implementations§
Source§impl<K, V> Map<K, V>where
K: Ord,
impl<K, V> Map<K, V>where
K: Ord,
Sourcepub fn new() -> Self
pub fn new() -> Self
Creates an empty map ordered according to the natural order of its keys.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
let mut it = map.iter();
assert_eq!(it.next(), Some((&1, &"a")));
assert_eq!(it.next(), Some((&2, &"b")));
assert_eq!(it.next(), Some((&3, &"c")));
assert_eq!(it.next(), None);
Source§impl<K, V, C> Map<K, V, C>where
C: Compare<K>,
impl<K, V, C> Map<K, V, C>where
C: Compare<K>,
Sourcepub fn with_cmp(cmp: C) -> Self
pub fn with_cmp(cmp: C) -> Self
Creates an empty map ordered according to the given comparator.
§Examples
use compare::{Compare, natural};
let mut map = tree::Map::with_cmp(natural().rev());
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
let mut it = map.iter();
assert_eq!(it.next(), Some((&3, &"c")));
assert_eq!(it.next(), Some((&2, &"b")));
assert_eq!(it.next(), Some((&1, &"a")));
assert_eq!(it.next(), None);
Sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Checks if the map is empty.
§Examples
let mut map = tree::Map::new();
assert!(map.is_empty());
map.insert(2, "b");
assert!(!map.is_empty());
Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of entries in the map.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.len(), 0);
map.insert(2, "b");
assert_eq!(map.len(), 1);
Sourcepub fn cmp(&self) -> &C
pub fn cmp(&self) -> &C
Returns a reference to the map’s comparator.
§Examples
use compare::{Compare, natural};
let map: tree::Map<i32, &str> = tree::Map::new();
assert!(map.cmp().compares_lt(&1, &2));
let map: tree::Map<i32, &str, _> = tree::Map::with_cmp(natural().rev());
assert!(map.cmp().compares_gt(&1, &2));
Sourcepub fn clear(&mut self)
pub fn clear(&mut self)
Removes all entries from the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.len(), 3);
assert_eq!(map.iter().next(), Some((&1, &"a")));
map.clear();
assert_eq!(map.len(), 0);
assert_eq!(map.iter().next(), None);
Sourcepub fn insert(&mut self, key: K, value: V) -> Option<V>
pub fn insert(&mut self, key: K, value: V) -> Option<V>
Inserts an entry into the map, returning the previous value, if any, associated with the key.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.insert(1, "a"), None);
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.insert(1, "b"), Some("a"));
assert_eq!(map.get(&1), Some(&"b"));
Sourcepub fn remove<Q: ?Sized>(&mut self, key: &Q) -> Option<(K, V)>where
C: Compare<Q, K>,
pub fn remove<Q: ?Sized>(&mut self, key: &Q) -> Option<(K, V)>where
C: Compare<Q, K>,
Removes and returns the entry whose key is equal to the given key, returning
None
if the map does not contain the key.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.len(), 3);
assert_eq!(map.get(&1), Some(&"a"));
assert_eq!(map.remove(&1), Some((1, "a")));
assert_eq!(map.len(), 2);
assert_eq!(map.get(&1), None);
assert_eq!(map.remove(&1), None);
Sourcepub fn entry(&mut self, key: K) -> Entry<'_, K, V>
pub fn entry(&mut self, key: K) -> Entry<'_, K, V>
Returns the map’s entry corresponding to the given key.
§Examples
let mut counts = tree::Map::new();
for s in vec!["a", "b", "a", "c", "a", "b"] {
*counts.entry(s).or_insert(0) += 1;
}
assert_eq!(counts[&"a"], 3);
assert_eq!(counts[&"b"], 2);
assert_eq!(counts[&"c"], 1);
Sourcepub fn contains_key<Q: ?Sized>(&self, key: &Q) -> boolwhere
C: Compare<Q, K>,
pub fn contains_key<Q: ?Sized>(&self, key: &Q) -> boolwhere
C: Compare<Q, K>,
Checks if the map contains the given key.
§Examples
let mut map = tree::Map::new();
assert!(!map.contains_key(&1));
map.insert(1, "a");
assert!(map.contains_key(&1));
Sourcepub fn get<Q: ?Sized>(&self, key: &Q) -> Option<&V>where
C: Compare<Q, K>,
pub fn get<Q: ?Sized>(&self, key: &Q) -> Option<&V>where
C: Compare<Q, K>,
Returns a reference to the value associated with the given key, or None
if the
map does not contain the key.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.get(&1), None);
map.insert(1, "a");
assert_eq!(map.get(&1), Some(&"a"));
Sourcepub fn get_mut<Q: ?Sized>(&mut self, key: &Q) -> Option<&mut V>where
C: Compare<Q, K>,
pub fn get_mut<Q: ?Sized>(&mut self, key: &Q) -> Option<&mut V>where
C: Compare<Q, K>,
Returns a mutable reference to the value associated with the given key, or None
if the map does not contain the key.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.get(&1), None);
map.insert(1, "a");
{
let value = map.get_mut(&1).unwrap();
assert_eq!(*value, "a");
*value = "b";
}
assert_eq!(map.get(&1), Some(&"b"));
Sourcepub fn max(&self) -> Option<(&K, &V)>
pub fn max(&self) -> Option<(&K, &V)>
Returns a reference to the map’s maximum key and a reference to its associated
value, or None
if the map is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.max(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.max(), Some((&3, &"c")));
Sourcepub fn max_mut(&mut self) -> Option<(&K, &mut V)>
pub fn max_mut(&mut self) -> Option<(&K, &mut V)>
Returns a reference to the map’s maximum key and a mutable reference to its
associated value, or None
if the map is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.max(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let max = map.max_mut().unwrap();
assert_eq!(max, (&3, &mut "c"));
*max.1 = "cc";
}
assert_eq!(map.max(), Some((&3, &"cc")));
Sourcepub fn remove_max(&mut self) -> Option<(K, V)>
pub fn remove_max(&mut self) -> Option<(K, V)>
Removes the map’s maximum key and returns it and its associated value, or None
if the map
is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.remove_max(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.remove_max(), Some((3, "c")));
Sourcepub fn max_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
pub fn max_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
Returns the map’s entry corresponding to its maximum key.
§Examples
let mut map = tree::Map::new();
assert!(map.max_entry().is_none());
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let mut e = map.max_entry().unwrap();
assert_eq!(*e.key(), 3);
assert_eq!(e.insert("cc"), "c");
}
assert_eq!(map[&3], "cc");
Sourcepub fn min(&self) -> Option<(&K, &V)>
pub fn min(&self) -> Option<(&K, &V)>
Returns a reference to the map’s minimum key and a reference to its associated
value, or None
if the map is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.min(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.min(), Some((&1, &"a")));
Sourcepub fn min_mut(&mut self) -> Option<(&K, &mut V)>
pub fn min_mut(&mut self) -> Option<(&K, &mut V)>
Returns a reference to the map’s minimum key and a mutable reference to its
associated value, or None
if the map is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.min(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let min = map.min_mut().unwrap();
assert_eq!(min, (&1, &mut "a"));
*min.1 = "aa";
}
assert_eq!(map.min(), Some((&1, &"aa")));
Sourcepub fn remove_min(&mut self) -> Option<(K, V)>
pub fn remove_min(&mut self) -> Option<(K, V)>
Removes the map’s minimum key and returns it and its associated value, or None
if the map
is empty.
§Examples
let mut map = tree::Map::new();
assert_eq!(map.remove_min(), None);
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.remove_min(), Some((1, "a")));
Sourcepub fn min_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
pub fn min_entry(&mut self) -> Option<OccupiedEntry<'_, K, V>>
Returns the map’s entry corresponding to its minimum key.
§Examples
let mut map = tree::Map::new();
assert!(map.min_entry().is_none());
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let mut e = map.min_entry().unwrap();
assert_eq!(*e.key(), 1);
assert_eq!(e.insert("aa"), "a");
}
assert_eq!(map[&1], "aa");
Sourcepub fn pred<Q: ?Sized>(&self, key: &Q, inclusive: bool) -> Option<(&K, &V)>where
C: Compare<Q, K>,
pub fn pred<Q: ?Sized>(&self, key: &Q, inclusive: bool) -> Option<(&K, &V)>where
C: Compare<Q, K>,
Returns a reference to the predecessor of the given key and a
reference to its associated value, or None
if no such key is present in the map.
If inclusive
is false
, this method finds the greatest key that is strictly less than
the given key. If inclusive
is true
, this method finds the greatest key that is less
than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.pred(&0, false), None);
assert_eq!(map.pred(&1, false), None);
assert_eq!(map.pred(&2, false), Some((&1, &"a")));
assert_eq!(map.pred(&3, false), Some((&2, &"b")));
assert_eq!(map.pred(&4, false), Some((&3, &"c")));
assert_eq!(map.pred(&0, true), None);
assert_eq!(map.pred(&1, true), Some((&1, &"a")));
assert_eq!(map.pred(&2, true), Some((&2, &"b")));
assert_eq!(map.pred(&3, true), Some((&3, &"c")));
assert_eq!(map.pred(&4, true), Some((&3, &"c")));
Sourcepub fn pred_mut<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(&K, &mut V)>where
C: Compare<Q, K>,
pub fn pred_mut<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(&K, &mut V)>where
C: Compare<Q, K>,
Returns a reference to the predecessor of the given key and a
mutable reference to its associated value, or None
if no such key is present in the map.
If inclusive
is false
, this method finds the greatest key that is strictly less than
the given key. If inclusive
is true
, this method finds the greatest key that is less
than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let pred = map.pred_mut(&2, false).unwrap();
assert_eq!(pred, (&1, &mut "a"));
*pred.1 = "aa";
}
assert_eq!(map.pred(&2, false), Some((&1, &"aa")));
{
let pred_or_eq = map.pred_mut(&1, true).unwrap();
assert_eq!(pred_or_eq, (&1, &mut "aa"));
*pred_or_eq.1 = "aaa";
}
{
let pred_or_eq = map.pred_mut(&4, true).unwrap();
assert_eq!(pred_or_eq, (&3, &mut "c"));
*pred_or_eq.1 = "cc";
}
assert_eq!(map.pred(&1, true), Some((&1, &"aaa")));
assert_eq!(map.pred(&4, true), Some((&3, &"cc")));
Sourcepub fn remove_pred<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(K, V)>where
C: Compare<Q, K>,
pub fn remove_pred<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(K, V)>where
C: Compare<Q, K>,
Removes the predecessor of the given key from the map and returns it and its associated
value, or None
if no such key is present in the map.
If inclusive
is false
, this method removes the greatest key that is strictly less than
the given key. If inclusive
is true
, this method removes the greatest key that is less
than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.remove_pred(&1, false), None);
assert!(map.contains_key(&1));
assert_eq!(map.remove_pred(&2, false), Some((1, "a")));
assert!(!map.contains_key(&1));
assert_eq!(map.remove_pred(&2, true), Some((2, "b")));
assert!(!map.contains_key(&2));
Sourcepub fn pred_entry<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<OccupiedEntry<'_, K, V>>where
C: Compare<Q, K>,
pub fn pred_entry<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<OccupiedEntry<'_, K, V>>where
C: Compare<Q, K>,
Returns the entry corresponding to the predecessor of the given key.
If inclusive
is false
, this method returns the entry corresponding to the greatest key
that is strictly less than the given key. If inclusive
is true
, this method returns
the entry corresponding to the greatest key that is less than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert!(map.pred_entry(&1, false).is_none());
{
let mut e = map.pred_entry(&4, true).unwrap();
assert_eq!(*e.key(), 3);
assert_eq!(e.insert("cc"), "c");
}
assert_eq!(map[&3], "cc");
{
let e = map.pred_entry(&3, false).unwrap();
assert_eq!(e.remove(), (2, "b"));
}
assert!(!map.contains_key(&2));
Sourcepub fn succ<Q: ?Sized>(&self, key: &Q, inclusive: bool) -> Option<(&K, &V)>where
C: Compare<Q, K>,
pub fn succ<Q: ?Sized>(&self, key: &Q, inclusive: bool) -> Option<(&K, &V)>where
C: Compare<Q, K>,
Returns a reference to the successor of the given key and a
reference to its associated value, or None
if no such key is present in the map.
If inclusive
is false
, this method finds the smallest key that is strictly greater than
the given key. If inclusive
is true
, this method finds the smallest key that is greater
than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.succ(&0, false), Some((&1, &"a")));
assert_eq!(map.succ(&1, false), Some((&2, &"b")));
assert_eq!(map.succ(&2, false), Some((&3, &"c")));
assert_eq!(map.succ(&3, false), None);
assert_eq!(map.succ(&4, false), None);
assert_eq!(map.succ(&0, true), Some((&1, &"a")));
assert_eq!(map.succ(&1, true), Some((&1, &"a")));
assert_eq!(map.succ(&2, true), Some((&2, &"b")));
assert_eq!(map.succ(&3, true), Some((&3, &"c")));
assert_eq!(map.succ(&4, true), None);
Sourcepub fn succ_mut<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(&K, &mut V)>where
C: Compare<Q, K>,
pub fn succ_mut<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(&K, &mut V)>where
C: Compare<Q, K>,
Returns a reference to the successor of the given key and a
mutable reference to its associated value, or None
if no such key is present in the map.
If inclusive
is false
, this method finds the smallest key that is strictly greater than
the given key. If inclusive
is true
, this method finds the smallest key that is greater
than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
{
let succ = map.succ_mut(&2, false).unwrap();
assert_eq!(succ, (&3, &mut "c"));
*succ.1 = "cc";
}
assert_eq!(map.succ(&2, false), Some((&3, &"cc")));
{
let succ_or_eq = map.succ_mut(&0, true).unwrap();
assert_eq!(succ_or_eq, (&1, &mut "a"));
*succ_or_eq.1 = "aa";
}
{
let succ_or_eq = map.succ_mut(&3, true).unwrap();
assert_eq!(succ_or_eq, (&3, &mut "cc"));
*succ_or_eq.1 = "ccc";
}
assert_eq!(map.succ(&0, true), Some((&1, &"aa")));
assert_eq!(map.succ(&3, true), Some((&3, &"ccc")));
Sourcepub fn remove_succ<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(K, V)>where
C: Compare<Q, K>,
pub fn remove_succ<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<(K, V)>where
C: Compare<Q, K>,
Removes the successor of the given key from the map and returns it and its associated
value, or None
if no such key is present in the map.
If inclusive
is false
, this method removes the smallest key that is strictly greater
than the given key. If inclusive
is true
, this method removes the smallest key that is
greater than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert_eq!(map.remove_succ(&3, false), None);
assert!(map.contains_key(&3));
assert_eq!(map.remove_succ(&2, false), Some((3, "c")));
assert!(!map.contains_key(&3));
assert_eq!(map.remove_succ(&2, true), Some((2, "b")));
assert!(!map.contains_key(&2));
Sourcepub fn succ_entry<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<OccupiedEntry<'_, K, V>>where
C: Compare<Q, K>,
pub fn succ_entry<Q: ?Sized>(
&mut self,
key: &Q,
inclusive: bool,
) -> Option<OccupiedEntry<'_, K, V>>where
C: Compare<Q, K>,
Returns the entry corresponding to the successor of the given key.
If inclusive
is false
, this method returns the entry corresponding to the smallest key
that is strictly greater than the given key. If inclusive
is true
, this method returns
the entry corresponding to the smallest key that is greater than or equal to the given key.
The given key need not itself be present in the map.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
assert!(map.succ_entry(&3, false).is_none());
{
let mut e = map.succ_entry(&0, true).unwrap();
assert_eq!(*e.key(), 1);
assert_eq!(e.insert("aa"), "a");
}
assert_eq!(map[&1], "aa");
{
let e = map.succ_entry(&1, false).unwrap();
assert_eq!(e.remove(), (2, "b"));
}
assert!(!map.contains_key(&2));
Sourcepub fn iter(&self) -> Iter<'_, K, V> ⓘ
pub fn iter(&self) -> Iter<'_, K, V> ⓘ
Returns an iterator over the map’s entries with immutable references to the values.
The iterator yields the entries in ascending order according to the map’s comparator.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
let mut it = map.iter();
assert_eq!(it.next(), Some((&1, &"a")));
assert_eq!(it.next(), Some((&2, &"b")));
assert_eq!(it.next(), Some((&3, &"c")));
assert_eq!(it.next(), None);
Sourcepub fn iter_mut(&mut self) -> IterMut<'_, K, V> ⓘ
pub fn iter_mut(&mut self) -> IterMut<'_, K, V> ⓘ
Returns an iterator over the map’s entries with mutable references to the values.
The iterator yields the entries in ascending order according to the map’s comparator.
§Examples
let mut map = tree::Map::new();
map.insert("b", 2);
map.insert("a", 1);
map.insert("c", 3);
let mut i = 1;
for (_, value) in map.iter_mut() {
assert_eq!(i, *value);
*value *= 2;
i += 1;
}
assert_eq!(map[&"a"], 2);
assert_eq!(map[&"b"], 4);
assert_eq!(map[&"c"], 6);
Trait Implementations§
Source§impl<K, V, C> Extend<(K, V)> for Map<K, V, C>where
C: Compare<K>,
impl<K, V, C> Extend<(K, V)> for Map<K, V, C>where
C: Compare<K>,
Source§fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, it: I)
fn extend<I: IntoIterator<Item = (K, V)>>(&mut self, it: I)
Source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)Source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)Source§impl<K, V, C> FromIterator<(K, V)> for Map<K, V, C>
impl<K, V, C> FromIterator<(K, V)> for Map<K, V, C>
Source§impl<'a, K, V, C> IntoIterator for &'a Map<K, V, C>where
C: Compare<K>,
impl<'a, K, V, C> IntoIterator for &'a Map<K, V, C>where
C: Compare<K>,
Source§impl<'a, K, V, C> IntoIterator for &'a mut Map<K, V, C>where
C: Compare<K>,
impl<'a, K, V, C> IntoIterator for &'a mut Map<K, V, C>where
C: Compare<K>,
Source§impl<K, V, C> IntoIterator for Map<K, V, C>where
C: Compare<K>,
impl<K, V, C> IntoIterator for Map<K, V, C>where
C: Compare<K>,
Source§fn into_iter(self) -> IntoIter<K, V> ⓘ
fn into_iter(self) -> IntoIter<K, V> ⓘ
Returns an iterator that consumes the map.
The iterator yields the entries in ascending order according to the map’s comparator.
§Examples
let mut map = tree::Map::new();
map.insert(2, "b");
map.insert(1, "a");
map.insert(3, "c");
let mut it = map.into_iter();
assert_eq!(it.next(), Some((1, "a")));
assert_eq!(it.next(), Some((2, "b")));
assert_eq!(it.next(), Some((3, "c")));
assert_eq!(it.next(), None);