Creates an emptyHashMap.

The hash map is initially created with a capacity of 0, so it will not allocate until itis first inserted into.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<&str, i32> = HashMap::new();

Creates an emptyHashMap with at least the specified capacity.

The hash map will be able to hold at leastcapacity elements withoutreallocating. This method is allowed to allocate for more elements thancapacity. Ifcapacity is zero, the hash map will not allocate.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<&str, i32> = HashMap::with_capacity(10);

Creates an emptyHashMap which will use the given hash builder to hashkeys.

The created map has the default initial capacity.

Warning:hash_builder is normally randomly generated, andis designed to allow HashMaps to be resistant to attacks thatcause many collisions and very poor performance. Setting itmanually using this function can expose a DoS attack vector.

Thehash_builder passed should implement theBuildHasher trait fortheHashMap to be useful, see its documentation for details.

§Examples

usestd::collections::HashMap;usestd::hash::RandomState;lets = RandomState::new();letmutmap = HashMap::with_hasher(s);map.insert(1,2);

Creates an emptyHashMap with at least the specified capacity, usinghasher to hash the keys.

The hash map will be able to hold at leastcapacity elements withoutreallocating. This method is allowed to allocate for more elements thancapacity. Ifcapacity is zero, the hash map will not allocate.

Warning:hasher is normally randomly generated, andis designed to allow HashMaps to be resistant to attacks thatcause many collisions and very poor performance. Setting itmanually using this function can expose a DoS attack vector.

Thehasher passed should implement theBuildHasher trait fortheHashMap to be useful, see its documentation for details.

§Examples

usestd::collections::HashMap;usestd::hash::RandomState;lets = RandomState::new();letmutmap = HashMap::with_capacity_and_hasher(10, s);map.insert(1,2);

Returns the number of elements the map can hold without reallocating.

This number is a lower bound; theHashMap<K, V> might be able to holdmore, but is guaranteed to be able to hold at least this many.

§Examples

usestd::collections::HashMap;letmap: HashMap<i32, i32> = HashMap::with_capacity(100);assert!(map.capacity() >=100);

An iterator visiting all keys in arbitrary order.The iterator element type is&'a K.

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);forkeyinmap.keys() {println!("{key}");}

§Performance

In the current implementation, iterating over keys takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

Creates a consuming iterator visiting all the keys in arbitrary order.The map cannot be used after calling this.The iterator element type isK.

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);letmutvec: Vec<&str> = map.into_keys().collect();// The `IntoKeys` iterator produces keys in arbitrary order, so the// keys must be sorted to test them against a sorted array.vec.sort_unstable();assert_eq!(vec, ["a","b","c"]);

§Performance

In the current implementation, iterating over keys takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

An iterator visiting all values in arbitrary order.The iterator element type is&'a V.

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);forvalinmap.values() {println!("{val}");}

§Performance

In the current implementation, iterating over values takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

An iterator visiting all values mutably in arbitrary order.The iterator element type is&'a mut V.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);forvalinmap.values_mut() {*val =*val +10;}forvalinmap.values() {println!("{val}");}

§Performance

In the current implementation, iterating over values takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

Creates a consuming iterator visiting all the values in arbitrary order.The map cannot be used after calling this.The iterator element type isV.

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);letmutvec: Vec<i32> = map.into_values().collect();// The `IntoValues` iterator produces values in arbitrary order, so// the values must be sorted to test them against a sorted array.vec.sort_unstable();assert_eq!(vec, [1,2,3]);

§Performance

In the current implementation, iterating over values takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

An iterator visiting all key-value pairs in arbitrary order.The iterator element type is(&'a K, &'a V).

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);for(key, val)inmap.iter() {println!("key: {key} val: {val}");}

§Performance

In the current implementation, iterating over map takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

An iterator visiting all key-value pairs in arbitrary order,with mutable references to the values.The iterator element type is(&'a K, &'a mut V).

§Examples

usestd::collections::HashMap;letmutmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);// Update all valuesfor(_, val)inmap.iter_mut() {*val*=2;}for(key, val)in&map {println!("key: {key} val: {val}");}

§Performance

In the current implementation, iterating over map takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

Returns the number of elements in the map.

§Examples

usestd::collections::HashMap;letmuta = HashMap::new();assert_eq!(a.len(),0);a.insert(1,"a");assert_eq!(a.len(),1);

Returnstrue if the map contains no elements.

§Examples

usestd::collections::HashMap;letmuta = HashMap::new();assert!(a.is_empty());a.insert(1,"a");assert!(!a.is_empty());

Clears the map, returning all key-value pairs as an iterator. Keeps theallocated memory for reuse.

If the returned iterator is dropped before being fully consumed, itdrops the remaining key-value pairs. The returned iterator keeps amutable borrow on the map to optimize its implementation.

§Examples

usestd::collections::HashMap;letmuta = HashMap::new();a.insert(1,"a");a.insert(2,"b");for(k, v)ina.drain().take(1) {assert!(k ==1|| k ==2);assert!(v =="a"|| v =="b");}assert!(a.is_empty());

Creates an iterator which uses a closure to determine if an element (key-value pair) should be removed.

If the closure returnstrue, the element is removed from the map andyielded. If the closure returnsfalse, or panics, the element remainsin the map and will not be yielded.

The iterator also lets you mutate the value of each element in theclosure, regardless of whether you choose to keep or remove it.

If the returnedExtractIf is not exhausted, e.g. because it is dropped without iteratingor the iteration short-circuits, then the remaining elements will be retained.Useretain with a negated predicate if you do not need the returned iterator.

§Examples

Splitting a map into even and odd keys, reusing the original map:

usestd::collections::HashMap;letmutmap: HashMap<i32, i32> = (0..8).map(|x| (x, x)).collect();letextracted: HashMap<i32, i32> = map.extract_if(|k, _v| k %2==0).collect();letmutevens = extracted.keys().copied().collect::<Vec<_>>();letmutodds = map.keys().copied().collect::<Vec<_>>();evens.sort();odds.sort();assert_eq!(evens,vec![0,2,4,6]);assert_eq!(odds,vec![1,3,5,7]);

Retains only the elements specified by the predicate.

In other words, remove all pairs(k, v) for whichf(&k, &mut v) returnsfalse.The elements are visited in unsorted (and unspecified) order.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<i32, i32> = (0..8).map(|x| (x, x*10)).collect();map.retain(|&k,_| k %2==0);assert_eq!(map.len(),4);

§Performance

In the current implementation, this operation takes O(capacity) timeinstead of O(len) because it internally visits empty buckets too.

Clears the map, removing all key-value pairs. Keeps the allocated memoryfor reuse.

§Examples

usestd::collections::HashMap;letmuta = HashMap::new();a.insert(1,"a");a.clear();assert!(a.is_empty());

Returns a reference to the map’sBuildHasher.

§Examples

usestd::collections::HashMap;usestd::hash::RandomState;lethasher = RandomState::new();letmap: HashMap<i32, i32> = HashMap::with_hasher(hasher);lethasher:&RandomState = map.hasher();

Reserves capacity for at leastadditional more elements to be insertedin theHashMap. The collection may reserve more space to speculativelyavoid frequent reallocations. After callingreserve,capacity will be greater than or equal toself.len() + additional.Does nothing if capacity is already sufficient.

§Panics

Panics if the new allocation size overflowsusize.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<&str, i32> = HashMap::new();map.reserve(10);

Tries to reserve capacity for at leastadditional more elements to be insertedin theHashMap. The collection may reserve more space to speculativelyavoid frequent reallocations. After callingtry_reserve,capacity will be greater than or equal toself.len() + additional ifit returnsOk(()).Does nothing if capacity is already sufficient.

§Errors

If the capacity overflows, or the allocator reports a failure, then an erroris returned.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<&str, isize> = HashMap::new();map.try_reserve(10).expect("why is the test harness OOMing on a handful of bytes?");

Shrinks the capacity of the map as much as possible. It will dropdown as much as possible while maintaining the internal rulesand possibly leaving some space in accordance with the resize policy.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<i32, i32> = HashMap::with_capacity(100);map.insert(1,2);map.insert(3,4);assert!(map.capacity() >=100);map.shrink_to_fit();assert!(map.capacity() >=2);

Shrinks the capacity of the map with a lower limit. It will dropdown no lower than the supplied limit while maintaining the internal rulesand possibly leaving some space in accordance with the resize policy.

If the current capacity is less than the lower limit, this is a no-op.

§Examples

usestd::collections::HashMap;letmutmap: HashMap<i32, i32> = HashMap::with_capacity(100);map.insert(1,2);map.insert(3,4);assert!(map.capacity() >=100);map.shrink_to(10);assert!(map.capacity() >=10);map.shrink_to(0);assert!(map.capacity() >=2);

Gets the given key’s corresponding entry in the map for in-place manipulation.

§Examples

usestd::collections::HashMap;letmutletters = HashMap::new();forchin"a short treatise on fungi".chars() {    letters.entry(ch).and_modify(|counter|*counter +=1).or_insert(1);}assert_eq!(letters[&'s'],2);assert_eq!(letters[&'t'],3);assert_eq!(letters[&'u'],1);assert_eq!(letters.get(&'y'),None);

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();map.insert(1,"a");assert_eq!(map.get(&1),Some(&"a"));assert_eq!(map.get(&2),None);

Returns the key-value pair corresponding to the supplied key. This ispotentially useful:

• for key types where non-identical keys can be considered equal;
• for getting the&K stored key value from a borrowed&Q lookup key; or
• for getting a reference to a key with the same lifetime as the collection.

The supplied key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;usestd::hash::{Hash, Hasher};#[derive(Clone, Copy, Debug)]structS {    id: u32,    name:&'staticstr,// ignored by equality and hashing operations}implPartialEqforS {fneq(&self, other:&S) -> bool {self.id == other.id    }}implEqforS {}implHashforS {fnhash<H: Hasher>(&self, state:&mutH) {self.id.hash(state);    }}letj_a = S { id:1, name:"Jessica"};letj_b = S { id:1, name:"Jess"};letp = S { id:2, name:"Paul"};assert_eq!(j_a, j_b);letmutmap = HashMap::new();map.insert(j_a,"Paris");assert_eq!(map.get_key_value(&j_a),Some((&j_a,&"Paris")));assert_eq!(map.get_key_value(&j_b),Some((&j_a,&"Paris")));// the notable caseassert_eq!(map.get_key_value(&p),None);

Attempts to get mutable references toN values in the map at once.

Returns an array of lengthN with the results of each query. For soundness, at most onemutable reference will be returned to any value.None will be used if the key is missing.

This method performs a check to ensure there are no duplicate keys, which currently has a time-complexity of O(n^2),so be careful when passing many keys.

§Panics

Panics if any keys are overlapping.

§Examples

usestd::collections::HashMap;letmutlibraries = HashMap::new();libraries.insert("Bodleian Library".to_string(),1602);libraries.insert("Athenæum".to_string(),1807);libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(),1691);libraries.insert("Library of Congress".to_string(),1800);// Get Athenæum and Bodleian Librarylet[Some(a),Some(b)] = libraries.get_disjoint_mut(["Athenæum","Bodleian Library",])else{panic!() };// Assert values of Athenæum and Library of Congressletgot = libraries.get_disjoint_mut(["Athenæum","Library of Congress",]);assert_eq!(    got,    [Some(&mut1807),Some(&mut1800),    ],);// Missing keys result in Noneletgot = libraries.get_disjoint_mut(["Athenæum","New York Public Library",]);assert_eq!(    got,    [Some(&mut1807),None]);

usestd::collections::HashMap;letmutlibraries = HashMap::new();libraries.insert("Athenæum".to_string(),1807);// Duplicate keys panic!letgot = libraries.get_disjoint_mut(["Athenæum","Athenæum",]);

Attempts to get mutable references toN values in the map at once, without validating thatthe values are unique.

Returns an array of lengthN with the results of each query.None will be used ifthe key is missing.

For a safe alternative seeget_disjoint_mut.

§Safety

Calling this method with overlapping keys isundefined behavior even if the resultingreferences are not used.

§Examples

usestd::collections::HashMap;letmutlibraries = HashMap::new();libraries.insert("Bodleian Library".to_string(),1602);libraries.insert("Athenæum".to_string(),1807);libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(),1691);libraries.insert("Library of Congress".to_string(),1800);// SAFETY: The keys do not overlap.let[Some(a),Some(b)] = (unsafe{ libraries.get_disjoint_unchecked_mut(["Athenæum","Bodleian Library",]) })else{panic!() };// SAFETY: The keys do not overlap.letgot =unsafe{ libraries.get_disjoint_unchecked_mut(["Athenæum","Library of Congress",]) };assert_eq!(    got,    [Some(&mut1807),Some(&mut1800),    ],);// SAFETY: The keys do not overlap.letgot =unsafe{ libraries.get_disjoint_unchecked_mut(["Athenæum","New York Public Library",]) };// Missing keys result in Noneassert_eq!(got, [Some(&mut1807),None]);

Returnstrue if the map contains a value for the specified key.

The key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();map.insert(1,"a");assert_eq!(map.contains_key(&1),true);assert_eq!(map.contains_key(&2),false);

Returns a mutable reference to the value corresponding to the key.

The key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();map.insert(1,"a");if letSome(x) = map.get_mut(&1) {*x ="b";}assert_eq!(map[&1],"b");

Inserts a key-value pair into the map.

If the map did not have this key present,None is returned.

If the map did have this key present, the value is updated, and the oldvalue is returned. The key is not updated, though; this matters fortypes that can be== without being identical. See themodule-leveldocumentation for more.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();assert_eq!(map.insert(37,"a"),None);assert_eq!(map.is_empty(),false);map.insert(37,"b");assert_eq!(map.insert(37,"c"),Some("b"));assert_eq!(map[&37],"c");

Tries to insert a key-value pair into the map, and returnsa mutable reference to the value in the entry.

If the map already had this key present, nothing is updated, andan error containing the occupied entry and the value is returned.

§Examples

Basic usage:

#![feature(map_try_insert)]usestd::collections::HashMap;letmutmap = HashMap::new();assert_eq!(map.try_insert(37,"a").unwrap(),&"a");leterr = map.try_insert(37,"b").unwrap_err();assert_eq!(err.entry.key(),&37);assert_eq!(err.entry.get(),&"a");assert_eq!(err.value,"b");

Removes a key from the map, returning the value at the key if the keywas previously in the map.

The key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();map.insert(1,"a");assert_eq!(map.remove(&1),Some("a"));assert_eq!(map.remove(&1),None);

Removes a key from the map, returning the stored key and value if thekey was previously in the map.

The key may be any borrowed form of the map’s key type, butHash andEq on the borrowed formmust match those forthe key type.

§Examples

usestd::collections::HashMap;letmutmap = HashMap::new();map.insert(1,"a");assert_eq!(map.remove_entry(&1),Some((1,"a")));assert_eq!(map.remove(&1),None);

Creates an emptyHashMap<K, V, S>, with theDefault value for the hasher.

Converts a[(K, V); N] into aHashMap<K, V>.

If any entries in the array have equal keys,all but one of the corresponding values will be dropped.

§Examples

usestd::collections::HashMap;letmap1 = HashMap::from([(1,2), (3,4)]);letmap2: HashMap<_,_> = [(1,2), (3,4)].into();assert_eq!(map1, map2);

Constructs aHashMap<K, V> from an iterator of key-value pairs.

If the iterator produces any pairs with equal keys,all but one of the corresponding values will be dropped.

Returns a reference to the value corresponding to the supplied key.

§Panics

Panics if the key is not present in theHashMap.

Creates a consuming iterator, that is, one that moves each key-valuepair out of the map in arbitrary order. The map cannot be used aftercalling this.

§Examples

usestd::collections::HashMap;letmap = HashMap::from([    ("a",1),    ("b",2),    ("c",3),]);// Not possible with .iter()letvec: Vec<(&str, i32)> = map.into_iter().collect();

Returns the argument unchanged.

CallsU::from(self).

That is, this conversion is whatever the implementation ofFrom<T> for U chooses to do.