Struct std::collections::HashMap

A map (dictionary) implemented as a hash table.

The implementation is a simple linear probing hash table. Keys must satisfy the Hashable and Equatable protocols. There are no restriction on the value type.

Example

use std::collections::HashMap;

let map = HashMap::new::<i32, i32>();
defer map.free();

map.insert(1, 2);
map.insert(2, 4);
map.insert(3, 5);

assert!(map.get(&1) == Option::some(2));
assert!(map.get(&2) == Option::some(4));
assert!(map.get(&3) == Option::some(5));
assert!(map.get(&4) == Option::none());
Run this example

Methods

• fn new() -> HashMap<K, V, H>

  source

  Creates an empty hash map

  Will not allocate until the first element is inserted.

• fn with_capacity(capacity: usize) -> HashMap<K, V, H>

  source

  Creates an empty hash map that can store up to capacity items without reallocating.

• fn with_size(size: usize) -> HashMap<K, V, H>

  source

  Creates a hashmap with a specific number of buckets.

  As HashMap uses amortized growth strategy, prefer to use with_capacity unless you want to strictly control the size of the underlying array.

• fn reserve(self: &mut HashMap<K, V, H>, additional: usize) -> bool

  source

  Reserves space for at least additional more elements to be inserted without reallocating.

  This follows the amortized growth strategy.

  Example

  use std::collections::HashMap;
  
  let map: HashMap<i32, i32> = HashMap::new();
  defer map.free();
  
  map.reserve(100);
  
  map.insert(1, 2);
  let ptr = map.get_ref(&1).unwrap();
  
  for i in 1..100 {
      map.insert(i, i * 2);
  }
  
  /// The first element is still at the same position.
  assert_eq!(ptr, map.get_ref(&1).unwrap());
  Run this example

• fn rehash(self: &mut HashMap<K, V, H>, new_capacity: usize)

  source

  Resizes the underlying array to exactly the given new_capacity.

  Note that this could lead to poor performance if the resulting load factor is close to 1. Prefer to use reserve to grow the map and shrink_to_fit to shrink it.

  Panics if the new capacity is lower than the current size.

  Example

  use std::collections::HashMap;
  
  let map: HashMap<i32, i32> = HashMap::new();
  defer map.free();
  
  map.insert(1, 2);
  map.insert(2, 4);
  map.insert(3, 5);
  
  map.rehash(1); // panics
  Run this example

• fn shrink_to_fit(self: &mut HashMap<K, V, H>)

  source

  Reduces the size of underlying storage to fit the contained elements if needed.

  Call this method after a lot of elements have been removed to shrink the underlying storage. This can also improve map performance as it removes the tombstones.

  This method keeps the load factor below 0.75 after shrinking.

  Example

  use std::collections::HashMap;
  
  let map: HashMap<i32, i32> = HashMap::from_iter(
      &(0..1000)
          .map(|i: i32| -> (i32, i32) { (i, i * 2) })
  );
  defer map.free();
  
  map.retain(|k: &i32, _v: &i32| -> bool { *k % 10 == 0 });
  map.shrink_to_fit(); // shrink the unused space
  Run this example

• fn insert(self: &mut HashMap<K, V, H>, key: K, value: V) -> Option<V>

  source

  Inserts a value into the map under a given key.

• fn get(self: &HashMap<K, V, H>, key: &K) -> Option<V>

  source

  Retreives the value by given key.

• fn get_ref(self: &HashMap<K, V, H>, key: &K) -> Option<&V>

  source

  Retreives a pointer to the value by given key.

• fn get_mut(self: &mut HashMap<K, V, H>, key: &K) -> Option<&mut V>

  source

  Retreives a mutable pointer to the value by given key.

• fn remove(self: &mut HashMap<K, V, H>, key: &K) -> Option<V>

  source

  Removes the element from the map.

  If the element with the given key was present in the map, the corresponding value is returned. Otherwise, Option::none() is returned.

• fn len(self: &HashMap<K, V, H>) -> usize

  source

  Returns the number of elements in the map.

  Example

  use std::collections::HashMap;
  
  let map: HashMap<i32, i32> = HashMap::new();
  assert_eq!(map.len(), 0);
  
  map.insert(1, 2);
  assert_eq!(map.len(), 1);
  Run this example

• fn is_empty(self: &HashMap<K, V, H>) -> bool

  source

  Returns true if the map is empty, false otherwise.

• fn clear(self: &mut HashMap<K, V, H>)

  source

  Removes all elements from the array.

  This does not shrink the underlying array after clearing. If this is desired, call shrink_to_fit afterwards.

• fn iter(self: &HashMap<K, V, H>) -> HashMapIterator<K, V>

  source

  Returns an iterator over the pointers of the items of this iterable.

  See IterableRef for details.

• fn iter_ref(self: &HashMap<K, V, H>) -> HashMapRefIterator<K, V>

  source

  Returns an iterator over the elements of this iterable.

  See Iterable for details.

• fn iter_mut(self: &mut HashMap<K, V, H>) -> HashMapMutIterator<K, V>

  source

  Returns an iterator over mutable pointers to the elements of the collection.

  See IterableMut for details.

• fn retain<F>(self: &mut HashMap<K, V, H>, func: F)

  F: Fn(&K, &V) -> bool

  source

  Removes the elements not mathing the given predicate.

  This is more efficient than calling remove for each element.

  Does not remove excess capacity, call shrink_to_fit afterwards, if this is desired.

  Example

  use std::collections::HashMap;
  
  let map = HashMap::new::<i32, i32>();
  defer map.free();
  
  map.insert(1, 1);
  map.insert(2, 100);
  map.insert(3, 100);
  map.insert(4, 4);
  
  map.retain(|k: &i32, v: &i32| -> bool { *k == *v });
  
  assert_eq!(map.get(&1), Option::some(1));
  assert_eq!(map.get(&2), Option::none());
  assert_eq!(map.get(&3), Option::none());
  assert_eq!(map.get(&4), Option::some(4));
  Run this example

• fn free(self: &mut HashMap<K, V, H>)

  source

  Frees the memory backing the object.

• fn free_all(self: &mut HashMap<K, V, H>)

  source

  Helper for collections that own heap-allocated objects. This is used to be able to do defer col.free_all() without much boilerplate.

  Example

  use std::collections::HashMap;
  use std::string::StringBuf;
  use std::fmt::format;
  
  let v: HashMap<StringBuf, StringBuf> = HashMap::new();
  defer v.free_all();
  
  for i in 1..10 {
      v.insert(
          "{} + {}".format!(i, i).unwrap(),
          "{}".format!(i + i).unwrap()
      );
  }
  Run this example

• fn move(self: &mut HashMap<K, V, H>) -> HashMap<K, V, H>

  source

  Creates a copy of the object, leaving an inert object behind.

  See Movable for details.

• fn clone(self: &HashMap<K, V, H>) -> HashMap<K, V, H>

  source

  Returns a copy of the object.

• fn get_borrowed(self: &HashMap<K, V, H>, key: B) -> Option<V>

  source

  Retreives the value by given borrowing of a key.

• fn get_borrowed_ref(self: &HashMap<K, V, H>, key: B) -> Option<&V>

  source

  Retreives a pointer to the value by given borrowing of a key.

• fn get_borrowed_mut(self: &mut HashMap<K, V, H>, key: B) -> Option<&mut V>

  source

  Retreives a mutable pointer to the value by given key.

• fn remove_borrowed(self: &mut HashMap<K, V, H>, key: B) -> Option<(K, V)>

  source

  Removes the element from the map by given borrowing of a key.

  If the element with the given key was present in the map, the corresponding value is returned along with the key. Otherwise, Option::none() is returned.

• fn from_iter(iter: &mut I) -> HashMap<K, V, H>

  source

  Creates a hash map from an iterator of key-value pairs

  Example

  use std::collections::HashMap;
  let map: HashMap<i32, i32> = HashMap::from_iter(
      &[(1, 2), (2, 4), (3, 5)].iter()
  );
  defer map.free();
  
  assert!(map.len() == 3);
  assert!(map.get(&1) == Option::some(2));
  Run this example

• fn extend(self: &mut HashMap<K, V, H>, iter: &mut I)

  source

  Inserts additional elements into the map from an iterator of key-value pairs.