pub struct HashMap<K, V, S = RandomState> { /* private fields */ }
Expand description
An unordered map.
An immutable hash map using [hash array mapped tries] 1.
Most operations on this map are O(logx n) for a
suitably high x that it should be nearly O(1) for most maps.
Because of this, it’s a great choice for a generic map as long as
you don’t mind that keys will need to implement
Hash
and Eq
.
Map entries will have a predictable order based on the hasher
being used. Unless otherwise specified, this will be the standard
RandomState
hasher.
Implementations§
source§impl<K, V> HashMap<K, V, RandomState>
impl<K, V> HashMap<K, V, RandomState>
source§impl<K, V, S> HashMap<K, V, S>
impl<K, V, S> HashMap<K, V, S>
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Test whether a hash map is empty.
Time: O(1)
§Examples
assert!(
!hashmap!{1 => 2}.is_empty()
);
assert!(
HashMap::<i32, i32>::new().is_empty()
);
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Get the size of a hash map.
Time: O(1)
§Examples
assert_eq!(3, hashmap!{
1 => 11,
2 => 22,
3 => 33
}.len());
sourcepub fn ptr_eq(&self, other: &Self) -> bool
pub fn ptr_eq(&self, other: &Self) -> bool
Test whether two maps refer to the same content in memory.
This is true if the two sides are references to the same map, or if the two maps refer to the same root node.
This would return true if you’re comparing a map to itself, or if you’re comparing a map to a fresh clone of itself.
Time: O(1)
sourcepub fn with_hasher<RS>(hasher: RS) -> Self
pub fn with_hasher<RS>(hasher: RS) -> Self
Construct an empty hash map using the provided hasher.
sourcepub fn hasher(&self) -> &Arc<S>
pub fn hasher(&self) -> &Arc<S>
Get a reference to the map’s BuildHasher
.
sourcepub fn new_from<K1, V1>(&self) -> HashMap<K1, V1, S>
pub fn new_from<K1, V1>(&self) -> HashMap<K1, V1, S>
Construct an empty hash map using the same hasher as the current hash map.
sourcepub fn iter(&self) -> Iter<'_, K, V> ⓘ
pub fn iter(&self) -> Iter<'_, K, V> ⓘ
Get an iterator over the key/value pairs of a hash map.
Please note that the order is consistent between maps using the same hasher, but no other ordering guarantee is offered. Items will not come out in insertion order or sort order. They will, however, come out in the same order every time for the same map.
sourcepub fn keys(&self) -> Keys<'_, K, V> ⓘ
pub fn keys(&self) -> Keys<'_, K, V> ⓘ
Get an iterator over a hash map’s keys.
Please note that the order is consistent between maps using the same hasher, but no other ordering guarantee is offered. Items will not come out in insertion order or sort order. They will, however, come out in the same order every time for the same map.
sourcepub fn values(&self) -> Values<'_, K, V> ⓘ
pub fn values(&self) -> Values<'_, K, V> ⓘ
Get an iterator over a hash map’s values.
Please note that the order is consistent between maps using the same hasher, but no other ordering guarantee is offered. Items will not come out in insertion order or sort order. They will, however, come out in the same order every time for the same map.
source§impl<K, V, S> HashMap<K, V, S>
impl<K, V, S> HashMap<K, V, S>
sourcepub fn get<BK>(&self, key: &BK) -> Option<&V>
pub fn get<BK>(&self, key: &BK) -> Option<&V>
Get the value for a key from a hash map.
Time: O(log n)
§Examples
let map = hashmap!{123 => "lol"};
assert_eq!(
map.get(&123),
Some(&"lol")
);
sourcepub fn get_key_value<BK>(&self, key: &BK) -> Option<(&K, &V)>
pub fn get_key_value<BK>(&self, key: &BK) -> Option<(&K, &V)>
Get the key/value pair for a key from a hash map.
Time: O(log n)
§Examples
let map = hashmap!{123 => "lol"};
assert_eq!(
map.get_key_value(&123),
Some((&123, &"lol"))
);
sourcepub fn contains_key<BK>(&self, k: &BK) -> bool
pub fn contains_key<BK>(&self, k: &BK) -> bool
Test for the presence of a key in a hash map.
Time: O(log n)
§Examples
let map = hashmap!{123 => "lol"};
assert!(
map.contains_key(&123)
);
assert!(
!map.contains_key(&321)
);
sourcepub fn is_submap_by<B, RM, F>(&self, other: RM, cmp: F) -> bool
pub fn is_submap_by<B, RM, F>(&self, other: RM, cmp: F) -> bool
Test whether a map is a submap of another map, meaning that all keys in our map must also be in the other map, with the same values.
Use the provided function to decide whether values are equal.
Time: O(n log n)
sourcepub fn is_proper_submap_by<B, RM, F>(&self, other: RM, cmp: F) -> bool
pub fn is_proper_submap_by<B, RM, F>(&self, other: RM, cmp: F) -> bool
Test whether a map is a proper submap of another map, meaning that all keys in our map must also be in the other map, with the same values. To be a proper submap, ours must also contain fewer keys than the other map.
Use the provided function to decide whether values are equal.
Time: O(n log n)
sourcepub fn is_submap<RM>(&self, other: RM) -> bool
pub fn is_submap<RM>(&self, other: RM) -> bool
Test whether a map is a submap of another map, meaning that all keys in our map must also be in the other map, with the same values.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 2 => 2};
let map2 = hashmap!{1 => 1, 2 => 2, 3 => 3};
assert!(map1.is_submap(map2));
sourcepub fn is_proper_submap<RM>(&self, other: RM) -> bool
pub fn is_proper_submap<RM>(&self, other: RM) -> bool
Test whether a map is a proper submap of another map, meaning that all keys in our map must also be in the other map, with the same values. To be a proper submap, ours must also contain fewer keys than the other map.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 2 => 2};
let map2 = hashmap!{1 => 1, 2 => 2, 3 => 3};
assert!(map1.is_proper_submap(map2));
let map3 = hashmap!{1 => 1, 2 => 2};
let map4 = hashmap!{1 => 1, 2 => 2};
assert!(!map3.is_proper_submap(map4));
source§impl<K, V, S> HashMap<K, V, S>
impl<K, V, S> HashMap<K, V, S>
sourcepub fn iter_mut(&mut self) -> IterMut<'_, K, V> ⓘ
pub fn iter_mut(&mut self) -> IterMut<'_, K, V> ⓘ
Get a mutable iterator over the values of a hash map.
Please note that the order is consistent between maps using the same hasher, but no other ordering guarantee is offered. Items will not come out in insertion order or sort order. They will, however, come out in the same order every time for the same map.
sourcepub fn get_mut<BK>(&mut self, key: &BK) -> Option<&mut V>
pub fn get_mut<BK>(&mut self, key: &BK) -> Option<&mut V>
Get a mutable reference to the value for a key from a hash map.
Time: O(log n)
§Examples
let mut map = hashmap!{123 => "lol"};
if let Some(value) = map.get_mut(&123) {
*value = "omg";
}
assert_eq!(
map.get(&123),
Some(&"omg")
);
sourcepub fn insert(&mut self, k: K, v: V) -> Option<V>
pub fn insert(&mut self, k: K, v: V) -> Option<V>
Insert a key/value mapping into a map.
If the map already has a mapping for the given key, the previous value is overwritten.
Time: O(log n)
§Examples
let mut map = hashmap!{};
map.insert(123, "123");
map.insert(456, "456");
assert_eq!(
map,
hashmap!{123 => "123", 456 => "456"}
);
sourcepub fn remove<BK>(&mut self, k: &BK) -> Option<V>
pub fn remove<BK>(&mut self, k: &BK) -> Option<V>
Remove a key/value pair from a map, if it exists, and return the removed value.
This is a copy-on-write operation, so that the parts of the set’s structure which are shared with other sets will be safely copied before mutating.
Time: O(log n)
§Examples
let mut map = hashmap!{123 => "123", 456 => "456"};
assert_eq!(Some("123"), map.remove(&123));
assert_eq!(Some("456"), map.remove(&456));
assert_eq!(None, map.remove(&789));
assert!(map.is_empty());
sourcepub fn remove_with_key<BK>(&mut self, k: &BK) -> Option<(K, V)>
pub fn remove_with_key<BK>(&mut self, k: &BK) -> Option<(K, V)>
Remove a key/value pair from a map, if it exists, and return the removed key and value.
Time: O(log n)
§Examples
let mut map = hashmap!{123 => "123", 456 => "456"};
assert_eq!(Some((123, "123")), map.remove_with_key(&123));
assert_eq!(Some((456, "456")), map.remove_with_key(&456));
assert_eq!(None, map.remove_with_key(&789));
assert!(map.is_empty());
sourcepub fn entry(&mut self, key: K) -> Entry<'_, K, V, S>
pub fn entry(&mut self, key: K) -> Entry<'_, K, V, S>
Get the Entry
for a key in the map for in-place manipulation.
Time: O(log n)
sourcepub fn update(&self, k: K, v: V) -> Self
pub fn update(&self, k: K, v: V) -> Self
Construct a new hash map by inserting a key/value mapping into a map.
If the map already has a mapping for the given key, the previous value is overwritten.
Time: O(log n)
§Examples
let map = hashmap!{};
assert_eq!(
map.update(123, "123"),
hashmap!{123 => "123"}
);
sourcepub fn update_with<F>(&self, k: K, v: V, f: F) -> Selfwhere
F: FnOnce(V, V) -> V,
pub fn update_with<F>(&self, k: K, v: V, f: F) -> Selfwhere
F: FnOnce(V, V) -> V,
Construct a new hash map by inserting a key/value mapping into a map.
If the map already has a mapping for the given key, we call the provided function with the old value and the new value, and insert the result as the new value.
Time: O(log n)
sourcepub fn update_with_key<F>(&self, k: K, v: V, f: F) -> Self
pub fn update_with_key<F>(&self, k: K, v: V, f: F) -> Self
Construct a new map by inserting a key/value mapping into a map.
If the map already has a mapping for the given key, we call the provided function with the key, the old value and the new value, and insert the result as the new value.
Time: O(log n)
sourcepub fn update_lookup_with_key<F>(&self, k: K, v: V, f: F) -> (Option<V>, Self)
pub fn update_lookup_with_key<F>(&self, k: K, v: V, f: F) -> (Option<V>, Self)
Construct a new map by inserting a key/value mapping into a map, returning the old value for the key as well as the new map.
If the map already has a mapping for the given key, we call the provided function with the key, the old value and the new value, and insert the result as the new value.
Time: O(log n)
sourcepub fn alter<F>(&self, f: F, k: K) -> Self
pub fn alter<F>(&self, f: F, k: K) -> Self
Update the value for a given key by calling a function with the current value and overwriting it with the function’s return value.
The function gets an Option<V>
and
returns the same, so that it can decide to delete a mapping
instead of updating the value, and decide what to do if the
key isn’t in the map.
Time: O(log n)
sourcepub fn without<BK>(&self, k: &BK) -> Self
pub fn without<BK>(&self, k: &BK) -> Self
Construct a new map without the given key.
Construct a map that’s a copy of the current map, absent the
mapping for key
if it’s present.
Time: O(log n)
sourcepub fn retain<F>(&mut self, f: F)
pub fn retain<F>(&mut self, f: F)
Filter out values from a map which don’t satisfy a predicate.
This is slightly more efficient than filtering using an iterator, in that it doesn’t need to rehash the retained values, but it still needs to reconstruct the entire tree structure of the map.
Time: O(n log n)
§Examples
let mut map = hashmap!{1 => 1, 2 => 2, 3 => 3};
map.retain(|k, v| *k > 1);
let expected = hashmap!{2 => 2, 3 => 3};
assert_eq!(expected, map);
sourcepub fn extract<BK>(&self, k: &BK) -> Option<(V, Self)>
pub fn extract<BK>(&self, k: &BK) -> Option<(V, Self)>
Remove a key/value pair from a map, if it exists, and return the removed value as well as the updated map.
Time: O(log n)
sourcepub fn extract_with_key<BK>(&self, k: &BK) -> Option<(K, V, Self)>
pub fn extract_with_key<BK>(&self, k: &BK) -> Option<(K, V, Self)>
Remove a key/value pair from a map, if it exists, and return the removed key and value as well as the updated list.
Time: O(log n)
sourcepub fn union(self, other: Self) -> Self
pub fn union(self, other: Self) -> Self
Construct the union of two maps, keeping the values in the current map when keys exist in both maps.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 3};
let map2 = hashmap!{2 => 2, 3 => 4};
let expected = hashmap!{1 => 1, 2 => 2, 3 => 3};
assert_eq!(expected, map1.union(map2));
sourcepub fn union_with<F>(self, other: Self, f: F) -> Selfwhere
F: FnMut(V, V) -> V,
pub fn union_with<F>(self, other: Self, f: F) -> Selfwhere
F: FnMut(V, V) -> V,
Construct the union of two maps, using a function to decide what to do with the value when a key is in both maps.
The function is called when a value exists in both maps, and receives the value from the current map as its first argument, and the value from the other map as the second. It should return the value to be inserted in the resulting map.
Time: O(n log n)
sourcepub fn union_with_key<F>(self, other: Self, f: F) -> Self
pub fn union_with_key<F>(self, other: Self, f: F) -> Self
Construct the union of two maps, using a function to decide what to do with the value when a key is in both maps.
The function is called when a value exists in both maps, and receives a reference to the key as its first argument, the value from the current map as the second argument, and the value from the other map as the third argument. It should return the value to be inserted in the resulting map.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 4};
let map2 = hashmap!{2 => 2, 3 => 5};
let expected = hashmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.union_with_key(
map2,
|key, left, right| left + right
));
sourcepub fn unions<I>(i: I) -> Selfwhere
S: Default,
I: IntoIterator<Item = Self>,
pub fn unions<I>(i: I) -> Selfwhere
S: Default,
I: IntoIterator<Item = Self>,
Construct the union of a sequence of maps, selecting the value of the leftmost when a key appears in more than one map.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 3};
let map2 = hashmap!{2 => 2};
let expected = hashmap!{1 => 1, 2 => 2, 3 => 3};
assert_eq!(expected, HashMap::unions(vec![map1, map2]));
sourcepub fn unions_with<I, F>(i: I, f: F) -> Self
pub fn unions_with<I, F>(i: I, f: F) -> Self
Construct the union of a sequence of maps, using a function to decide what to do with the value when a key is in more than one map.
The function is called when a value exists in multiple maps, and receives the value from the current map as its first argument, and the value from the next map as the second. It should return the value to be inserted in the resulting map.
Time: O(n log n)
sourcepub fn unions_with_key<I, F>(i: I, f: F) -> Self
pub fn unions_with_key<I, F>(i: I, f: F) -> Self
Construct the union of a sequence of maps, using a function to decide what to do with the value when a key is in more than one map.
The function is called when a value exists in multiple maps, and receives a reference to the key as its first argument, the value from the current map as the second argument, and the value from the next map as the third argument. It should return the value to be inserted in the resulting map.
Time: O(n log n)
sourcepub fn difference(self, other: Self) -> Self
👎Deprecated since 2.0.1: to avoid conflicting behaviors between std and imbl, the difference
alias for symmetric_difference
will be removed.
pub fn difference(self, other: Self) -> Self
difference
alias for symmetric_difference
will be removed.Construct the symmetric difference between two maps by discarding keys which occur in both maps.
This is an alias for the
symmetric_difference
method.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 4};
let map2 = hashmap!{2 => 2, 3 => 5};
let expected = hashmap!{1 => 1, 2 => 2};
assert_eq!(expected, map1.difference(map2));
sourcepub fn symmetric_difference(self, other: Self) -> Self
pub fn symmetric_difference(self, other: Self) -> Self
Construct the symmetric difference between two maps by discarding keys which occur in both maps.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 4};
let map2 = hashmap!{2 => 2, 3 => 5};
let expected = hashmap!{1 => 1, 2 => 2};
assert_eq!(expected, map1.symmetric_difference(map2));
sourcepub fn difference_with<F>(self, other: Self, f: F) -> Self
👎Deprecated since 2.0.1: to avoid conflicting behaviors between std and imbl, the difference_with
alias for symmetric_difference_with
will be removed.
pub fn difference_with<F>(self, other: Self, f: F) -> Self
difference_with
alias for symmetric_difference_with
will be removed.Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both.
This is an alias for the
symmetric_difference_with
method.
Time: O(n log n)
sourcepub fn symmetric_difference_with<F>(self, other: Self, f: F) -> Self
pub fn symmetric_difference_with<F>(self, other: Self, f: F) -> Self
Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both.
Time: O(n log n)
sourcepub fn difference_with_key<F>(self, other: Self, f: F) -> Self
👎Deprecated since 2.0.1: to avoid conflicting behaviors between std and imbl, the difference_with_key
alias for symmetric_difference_with_key
will be removed.
pub fn difference_with_key<F>(self, other: Self, f: F) -> Self
difference_with_key
alias for symmetric_difference_with_key
will be removed.Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both. The function receives the key as well as both values.
This is an alias for the
symmetric_difference_with
_key
method.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 4};
let map2 = hashmap!{2 => 2, 3 => 5};
let expected = hashmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.difference_with_key(
map2,
|key, left, right| Some(left + right)
));
sourcepub fn symmetric_difference_with_key<F>(self, other: Self, f: F) -> Self
pub fn symmetric_difference_with_key<F>(self, other: Self, f: F) -> Self
Construct the symmetric difference between two maps by using a function to decide what to do if a key occurs in both. The function receives the key as well as both values.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 3 => 4};
let map2 = hashmap!{2 => 2, 3 => 5};
let expected = hashmap!{1 => 1, 2 => 2, 3 => 9};
assert_eq!(expected, map1.symmetric_difference_with_key(
map2,
|key, left, right| Some(left + right)
));
sourcepub fn relative_complement(self, other: Self) -> Self
pub fn relative_complement(self, other: Self) -> Self
Construct the relative complement between two maps by discarding keys
which occur in other
.
Time: O(m log n) where m is the size of the other map
§Examples
let map1 = ordmap!{1 => 1, 3 => 4};
let map2 = ordmap!{2 => 2, 3 => 5};
let expected = ordmap!{1 => 1};
assert_eq!(expected, map1.relative_complement(map2));
sourcepub fn intersection(self, other: Self) -> Self
pub fn intersection(self, other: Self) -> Self
Construct the intersection of two maps, keeping the values from the current map.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 2 => 2};
let map2 = hashmap!{2 => 3, 3 => 4};
let expected = hashmap!{2 => 2};
assert_eq!(expected, map1.intersection(map2));
sourcepub fn intersection_with<B, C, F>(
self,
other: HashMap<K, B, S>,
f: F,
) -> HashMap<K, C, S>
pub fn intersection_with<B, C, F>( self, other: HashMap<K, B, S>, f: F, ) -> HashMap<K, C, S>
Construct the intersection of two maps, calling a function with both values for each key and using the result as the value for the key.
Time: O(n log n)
sourcepub fn intersection_with_key<B, C, F>(
self,
other: HashMap<K, B, S>,
f: F,
) -> HashMap<K, C, S>
pub fn intersection_with_key<B, C, F>( self, other: HashMap<K, B, S>, f: F, ) -> HashMap<K, C, S>
Construct the intersection of two maps, calling a function with the key and both values for each key and using the result as the value for the key.
Time: O(n log n)
§Examples
let map1 = hashmap!{1 => 1, 2 => 2};
let map2 = hashmap!{2 => 3, 3 => 4};
let expected = hashmap!{2 => 5};
assert_eq!(expected, map1.intersection_with_key(
map2,
|key, left, right| left + right
));
Trait Implementations§
source§impl<'de, K, V, S> Deserialize<'de> for HashMap<K, V, S>where
K: Deserialize<'de> + Hash + Eq + Clone,
V: Deserialize<'de> + Clone,
S: BuildHasher + Default,
impl<'de, K, V, S> Deserialize<'de> for HashMap<K, V, S>where
K: Deserialize<'de> + Hash + Eq + Clone,
V: Deserialize<'de> + Clone,
S: BuildHasher + Default,
source§fn deserialize<D>(des: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
fn deserialize<D>(des: D) -> Result<Self, D::Error>where
D: Deserializer<'de>,
source§impl<K, V, S, RK, RV> Extend<(RK, RV)> for HashMap<K, V, S>
impl<K, V, S, RK, RV> Extend<(RK, RV)> for HashMap<K, V, S>
source§fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (RK, RV)>,
fn extend<I>(&mut self, iter: I)where
I: IntoIterator<Item = (RK, RV)>,
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<'m, 'k, 'v, K, V, OK, OV, SA, SB> From<&'m HashMap<&'k K, &'v V, SA>> for HashMap<OK, OV, SB>
impl<'m, 'k, 'v, K, V, OK, OV, SA, SB> From<&'m HashMap<&'k K, &'v V, SA>> for HashMap<OK, OV, SB>
source§impl<'a, K: Ord + Hash + Eq + Clone, V: Clone, S: BuildHasher> From<&'a HashMap<K, V, S>> for OrdMap<K, V>
impl<'a, K: Ord + Hash + Eq + Clone, V: Clone, S: BuildHasher> From<&'a HashMap<K, V, S>> for OrdMap<K, V>
source§impl<K: Ord + Hash + Eq + Clone, V: Clone, S: BuildHasher> From<HashMap<K, V, S>> for OrdMap<K, V>
impl<K: Ord + Hash + Eq + Clone, V: Clone, S: BuildHasher> From<HashMap<K, V, S>> for OrdMap<K, V>
source§impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>
impl<K, V, S> FromIterator<(K, V)> for HashMap<K, V, S>
source§impl<'a, K, V, S> IntoIterator for &'a HashMap<K, V, S>
impl<'a, K, V, S> IntoIterator for &'a HashMap<K, V, S>
source§impl<K, V, S> IntoIterator for HashMap<K, V, S>
impl<K, V, S> IntoIterator for HashMap<K, V, S>
source§impl<K, V, S> PartialEq for HashMap<K, V, S>
impl<K, V, S> PartialEq for HashMap<K, V, S>
impl<K, V, S> Eq for HashMap<K, V, S>
Auto Trait Implementations§
impl<K, V, S> Freeze for HashMap<K, V, S>
impl<K, V, S> RefUnwindSafe for HashMap<K, V, S>
impl<K, V, S> Send for HashMap<K, V, S>
impl<K, V, S> Sync for HashMap<K, V, S>
impl<K, V, S> Unpin for HashMap<K, V, S>
impl<K, V, S> UnwindSafe for HashMap<K, V, S>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)