Struct WeakKeyHashMap 

pub struct WeakKeyHashMap<K, V, S = RandomState>(/* private fields */);

A hash map with weak keys, hashed on key value.

When a weak pointer expires, its mapping is lazily removed.

Implementations

impl<K, V> WeakKeyHashMap<K, V, RandomState>

pub fn new() -> Self

Creates an empty WeakKeyHashMap.

O(1) time

pub fn with_capacity(capacity: usize) -> Self

Creates an empty WeakKeyHashMap with the given capacity.

O(n) time

impl<K, V, S: BuildHasher> WeakKeyHashMap<K, V, S>

pub fn with_hasher(hash_builder: S) -> Self

Creates an empty WeakKeyHashMap with the given hasher.

O(n) time

pub fn with_capacity_and_hasher(capacity: usize, hash_builder: S) -> Self

Creates an empty WeakKeyHashMap with the given capacity and hasher.

O(n) time

impl<K, V, S> WeakKeyHashMap<K, V, S>

pub fn hasher(&self) -> &S

Returns a reference to the map’s BuildHasher.

O(1) time

pub fn capacity(&self) -> usize

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

O(1) time

pub fn len(&self) -> usize

Returns an over-approximation of the number of elements.

(This is an over-approximation because it includes expired elements.)

O(1) time

pub fn is_empty(&self) -> bool

Is the map empty?

Note that this may return false even if all elements have expired, if they haven’t been collected yet.

O(1) time

pub fn load_factor(&self) -> f32

Returns proportion of buckets that are used.

This is an over-approximation because of expired elements.

O(1) time

pub fn clear(&mut self)

Remove all elements from the map.

O(n) time

impl<K: WeakKey, V, S: BuildHasher> WeakKeyHashMap<K, V, S>

pub fn remove_expired(&mut self)

Removes all mappings whose keys have expired.

O(n) time

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

Reserves room for additional elements.

This method ensures that at least additional_capacity insertions may be performed without reallocating.

O(n) time

pub fn try_reserve( &mut self, additional_capacity: usize, ) -> Result<(), TryReserveError>

Tries to reserve room for additional mappings.

If this method succeeds, then at least additional_capacity insertions may be performed without reallocating further.

O(n) time

pub fn shrink_to_fit(&mut self)

Shrinks the capacity to the minimum to hold the current number of mappings.

O(n) time

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity to hold no fewer than min_capacity mappings.

May remove expired items if necessary. Does nothing if the current capacity is already at min_capacity or below.

O(n) time

pub fn entry(&mut self, key: K::Strong) -> Entry<'_, K, V>

Gets the requested entry.

expected O(1) time; worst-case O(p) time

pub fn get<Q>(&self, key: &Q) -> Option<&V>

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

Returns a reference to the value corresponding to the key.

Returns None if no matching key is found.

expected O(1) time; worst-case O(p) time

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

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

Returns true if the map contains the specified key.

expected O(1) time; worst-case O(p) time

pub fn get_key<Q>(&self, key: &Q) -> Option<K::Strong>

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

Returns a strong reference to the key, if found.

expected O(1) time; worst-case O(p) time

pub fn get_both<Q>(&self, key: &Q) -> Option<(K::Strong, &V)>

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

Returns a pair of a strong reference to the key, and a reference to the value, if present.

expected O(1) time; worst-case O(p) time

pub fn get_mut<Q>(&mut self, key: &Q) -> Option<&mut V>

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

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

Returns None if no matching key is found.

expected O(1) time; worst-case O(p) time

pub fn get_both_mut<Q>(&mut self, key: &Q) -> Option<(K::Strong, &mut V)>

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

Returns a pair of a strong reference to the key, and a mutable reference to the value, if present.

expected O(1) time; worst-case O(p) time

pub fn get_disjoint_mut<Q, const N: usize>( &mut self, ks: [&Q; N], ) -> [Option<&mut V>; N]

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

Looks up mutable references to the values corresponding to several keys at a time.

(Because of borrowing rules, Rust doesn’t allow you to call get_mut() again while the result of a previous get_mut() is still live. This method exists to work around that limitation.)

Only one mutable reference can exist to any given value at a time. Therefore, all keys must refer to different values, or this method will panic.

expected O(1 N^2) time; worst-case O(p N^2) time, where N is the length of the array.

Panics

Panics if any keys refer to the same value.

pub fn get_both_disjoint_mut<Q, const N: usize>( &mut self, ks: [&Q; N], ) -> [Option<(K::Strong, &mut V)>; N]

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

Looks up mutable references to the values corresponding to several keys at a time. Returns those references along with their keys as stored in the table.

(Because of borrowing rules, Rust doesn’t allow you to call get_mut() again while the result of a previous get_mut() is still live. This method exists to work around that limitation.)

Only one mutable reference can exist to any given value at a time. Therefore, all keys must refer to different values, or this method will panic.

expected O(1 N^2) time; worst-case O(p N^2) time, where N is the length of the array.

Panics

Panics if any keys refer to the same value.

pub fn insert(&mut self, key: K::Strong, value: V) -> Option<V>

Unconditionally inserts the value, returning the old value if already present.

Unlike std::collections::HashMap, this replaces the key even the entry was occupied.

expected O(1) time; worst-case O(p) time

pub fn remove<Q>(&mut self, key: &Q) -> Option<V>

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

Removes the entry with the given key, if it exists, and returns the value.

expected O(1) time; worst-case O(p) time

pub fn remove_entry<Q>(&mut self, key: &Q) -> Option<(K::Strong, V)>

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

Removes the entry with the given key, if it exists, and returns both the key and value.

expected O(1) time; worst-case O(p) time

pub fn retain<F>(&mut self, f: F)

where F: FnMut(K::Strong, &mut V) -> bool,

Removes all mappings not satisfying the given predicate.

Also removes any expired mappings.

O(n) time

pub fn is_submap_with<F, S1, V1>( &self, other: &WeakKeyHashMap<K, V1, S1>, cmp: F, ) -> bool

where F: FnMut(&V, &V1) -> bool, S1: BuildHasher,

Is this map a submap of the other under the given value comparison cmp?

In particular, for every key k of self,

• k must also be a key of other and
• cmp(self[k], other[k]) must hold.

expected O(n) time; worst-case O(nq) time (where n is self.capacity() and q is the length of the probe sequences in other)

pub fn is_submap<V1, S1>(&self, other: &WeakKeyHashMap<K, V1, S1>) -> bool

where V: PartialEq<V1>, S1: BuildHasher,

Is self a submap of other?

expected O(n) time; worst-case O(nq) time (where n is self.capacity() and q is the length of the probe sequences in other)

pub fn domain_is_subset<V1, S1>( &self, other: &WeakKeyHashMap<K, V1, S1>, ) -> bool

where S1: BuildHasher,

Are the keys of self a subset of the keys of other?

expected O(n) time; worst-case O(nq) time (where n is self.capacity() and q is the length of the probe sequences in other)

impl<K: WeakElement, V, S> WeakKeyHashMap<K, V, S>

pub fn iter(&self) -> Iter<'_, K, V>

Gets an iterator over the keys and values.

O(1) time

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

Gets an iterator over the keys.

O(1) time

pub fn values(&self) -> Values<'_, K, V>

Gets an iterator over the values.

O(1) time

pub fn iter_mut(&mut self) -> IterMut<'_, K, V>

Gets an iterator over the keys and mutable values.

O(1) time

pub fn values_mut(&mut self) -> ValuesMut<'_, K, V>

Gets an iterator over the mutable values.

O(1) time

pub fn drain(&mut self) -> Drain<'_, K, V>

Gets a draining iterator, which removes all the values but retains the storage.

O(1) time (and O(n) time to dispose of the result)

pub fn into_keys(self) -> IntoKeys<K, V>

Returns an iterator that owns and consumes this map, returning the keys in the map.

O(1)

pub fn into_values(self) -> IntoValues<K, V>

Returns an iterator that owns and consumes this map, returning the keys in the map.

O(1)

pub fn extract_if<'a, F>(&'a mut self, f: F) -> ExtractIf<'a, K, V, F>

where F: FnMut(K::Strong, &mut V) -> bool + 'a,

Gets an iterator that removes and returns elements matching a given predicate.

Expired elements are also removed.

If this iterator is dropped before it is completed, then no further elements are removed. (This is in contrast to the behavior of drain).

O(1) time

Trait Implementations

impl<K: Clone, V: Clone, S: Clone> Clone for WeakKeyHashMap<K, V, S>

fn clone(&self) -> WeakKeyHashMap<K, V, S>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<K: WeakElement, V: Debug, S> Debug for WeakKeyHashMap<K, V, S>

where K::Strong: Debug,

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

Formats the value using the given formatter.

impl<K, V, S: BuildHasher + Default> Default for WeakKeyHashMap<K, V, S>

fn default() -> Self

Returns the “default value” for a type.

impl<K: WeakKey, V: Eq, S: BuildHasher> Eq for WeakKeyHashMap<K, V, S>

impl<'a, K, V, S> Extend<(&'a <K as WeakElement>::Strong, &'a V)> for WeakKeyHashMap<K, V, S>

where K: 'a + WeakKey, K::Strong: Clone, V: 'a + Clone, S: BuildHasher,

fn extend<T: IntoIterator<Item = (&'a K::Strong, &'a V)>>(&mut self, iter: T)

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<K, V, S> Extend<(<K as WeakElement>::Strong, V)> for WeakKeyHashMap<K, V, S>

where K: WeakKey, S: BuildHasher,

fn extend<T: IntoIterator<Item = (K::Strong, V)>>(&mut self, iter: T)

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<K: WeakKey, V, const N: usize> From<[(<K as WeakElement>::Strong, V); N]> for WeakKeyHashMap<K, V, RandomState>

fn from(value: [(K::Strong, V); N]) -> Self

Converts an array of key-value pairs into a map.

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

impl<K, V, S> FromIterator<(<K as WeakElement>::Strong, V)> for WeakKeyHashMap<K, V, S>

where K: WeakKey, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = (K::Strong, V)>>(iter: T) -> Self

Creates a value from an iterator.

impl<'a, K, V, S, Q> Index<&'a Q> for WeakKeyHashMap<K, V, S>

where K: WeakKey, K::Key: Borrow<Q>, S: BuildHasher, Q: ?Sized + Eq + Hash,

type Output = V

The returned type after indexing.

fn index(&self, index: &'a Q) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a, K, V, S, Q> IndexMut<&'a Q> for WeakKeyHashMap<K, V, S>

where K: WeakKey, K::Key: Borrow<Q>, S: BuildHasher, Q: ?Sized + Eq + Hash,

fn index_mut(&mut self, index: &'a Q) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<K: WeakElement, V, S> IntoIterator for WeakKeyHashMap<K, V, S>

fn into_iter(self) -> Self::IntoIter

Creates an owning iterator from self.

O(1) time (and O(n) time to dispose of the result)

type Item = (<K as WeakElement>::Strong, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<K, V>

Which kind of iterator are we turning this into?

impl<'a, K: WeakElement, V, S> IntoIterator for &'a WeakKeyHashMap<K, V, S>

fn into_iter(self) -> Self::IntoIter

Creates a borrowing iterator from self.

O(1) time

type Item = (<K as WeakElement>::Strong, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, K, V>

Which kind of iterator are we turning this into?

impl<'a, K: WeakElement, V, S> IntoIterator for &'a mut WeakKeyHashMap<K, V, S>

fn into_iter(self) -> Self::IntoIter

Creates a borrowing iterator from self.

O(1) time

type Item = (<K as WeakElement>::Strong, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, K, V>

Which kind of iterator are we turning this into?

impl<K, V, V1, S, S1> PartialEq<WeakKeyHashMap<K, V1, S1>> for WeakKeyHashMap<K, V, S>

where K: WeakKey, V: PartialEq<V1>, S: BuildHasher, S1: BuildHasher,

fn eq(&self, other: &WeakKeyHashMap<K, V1, S1>) -> bool

Equality operator ==.

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

Inequality operator !=.