Struct scc :: hash_map :: Reserve Copy item path

impl<'h, K, V, H> Reserve<'h, K, V, H>
where K: Eq + Hash, H: BuildHasher,

pub fn additional_capacity(&self) -> usize

Returns the number of reserved slots.

Methods from Deref<Target = HashMap<K, V, H>>§

pub fn reserve( &self, additional_capacity: usize ) -> Option<Reserve<'_, K, V, H>>

Temporarily increases the minimum capacity of the HashMap.

A Reserve is returned if the HashMap could increase the minimum capacity while the increased capacity is not exclusively owned by the returned Reserve, allowing others to benefit from it. The memory for the additional space may not be immediately allocated if the HashMap is empty or currently being resized, however once the memory is reserved eventually, the capacity will not shrink below the additional capacity until the returned Reserve is dropped.

§Errors

Returns None if a too large number is given.

§Examples

use scc::HashMap;

let hashmap: HashMap<usize, usize> = HashMap::with_capacity(1000);
assert_eq!(hashmap.capacity(), 1024);

let reserved = hashmap.reserve(10000);
assert!(reserved.is_some());
assert_eq!(hashmap.capacity(), 16384);

assert!(hashmap.reserve(usize::MAX).is_none());
assert_eq!(hashmap.capacity(), 16384);

for i in 0..16 {
    assert!(hashmap.insert(i, i).is_ok());
}
drop(reserved);

assert_eq!(hashmap.capacity(), 1024);

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

Gets the entry associated with the given key in the map for in-place manipulation.

§Examples

use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

for ch in "a short treatise on fungi".chars() {
    hashmap.entry(ch).and_modify(|counter| *counter += 1).or_insert(1);
}

assert_eq!(hashmap.read(&'s', |_, v| *v), Some(2));
assert_eq!(hashmap.read(&'t', |_, v| *v), Some(3));
assert!(hashmap.read(&'y', |_, v| *v).is_none());

pub async fn entry_async(&self, key: K) -> Entry<'_, K, V, H>

Gets the entry associated with the given key in the map for in-place manipulation.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

let future_entry = hashmap.entry_async('b');

pub fn first_entry(&self) -> Option<OccupiedEntry<'_, K, V, H>>

Gets the first occupied entry for in-place manipulation.

The returned OccupiedEntry in combination with OccupiedEntry::next or OccupiedEntry::next_async can act as a mutable iterator over entries.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());

let mut first_entry = hashmap.first_entry().unwrap();
*first_entry.get_mut() = 2;

assert!(first_entry.next().is_none());
assert_eq!(hashmap.read(&1, |_, v| *v), Some(2));

pub async fn first_entry_async(&self) -> Option<OccupiedEntry<'_, K, V, H>>

Gets the first occupied entry for in-place manipulation.

The returned OccupiedEntry in combination with OccupiedEntry::next or OccupiedEntry::next_async can act as a mutable iterator over entries.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<char, u32> = HashMap::default();

let future_entry = hashmap.first_entry_async();

pub fn insert(&self, key: K, val: V) -> Result<(), (K, V)>

Inserts a key-value pair into the HashMap.

§Errors

Returns an error along with the supplied key-value pair if the key exists.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert_eq!(hashmap.insert(1, 1).unwrap_err(), (1, 1));

pub async fn insert_async(&self, key: K, val: V) -> Result<(), (K, V)>

Inserts a key-value pair into the HashMap.

It is an asynchronous method returning an impl Future for the caller to await.

§Errors

Returns an error along with the supplied key-value pair if the key exists.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
let future_insert = hashmap.insert_async(11, 17);

pub fn update<Q, U, R>(&self, key: &Q, updater: U) -> Option<R>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized, U: FnOnce(&K, &mut V) -> R,

Updates an existing key-value pair in-place.

Returns None if the key does not exist.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.update(&1, |_, _| true).is_none());
assert!(hashmap.insert(1, 0).is_ok());
assert_eq!(hashmap.update(&1, |_, v| { *v = 2; *v }).unwrap(), 2);
assert_eq!(hashmap.read(&1, |_, v| *v).unwrap(), 2);

pub async fn update_async<Q, U, R>(&self, key: &Q, updater: U) -> Option<R>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized, U: FnOnce(&K, &mut V) -> R,

Updates an existing key-value pair in-place.

Returns None if the key does not exist. It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
let future_update = hashmap.update_async(&1, |_, v| { *v = 2; *v });

pub fn remove<Q>(&self, key: &Q) -> Option<(K, V)>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Removes a key-value pair if the key exists.

Returns None if the key does not exist.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.remove(&1).is_none());
assert!(hashmap.insert(1, 0).is_ok());
assert_eq!(hashmap.remove(&1).unwrap(), (1, 0));
assert_eq!(hashmap.capacity(), 0);

pub async fn remove_async<Q>(&self, key: &Q) -> Option<(K, V)>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Removes a key-value pair if the key exists.

Returns None if the key does not exist. It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
let future_insert = hashmap.insert_async(11, 17);
let future_remove = hashmap.remove_async(&11);

pub fn remove_if<Q, F: FnOnce(&mut V) -> bool>( &self, key: &Q, condition: F ) -> Option<(K, V)>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Removes a key-value pair if the key exists and the given condition is met.

Returns None if the key does not exist or the condition was not met.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.remove_if(&1, |v| { *v += 1; false }).is_none());
assert_eq!(hashmap.remove_if(&1, |v| *v == 1).unwrap(), (1, 1));
assert_eq!(hashmap.capacity(), 0);

pub async fn remove_if_async<Q, F: FnOnce(&mut V) -> bool>( &self, key: &Q, condition: F ) -> Option<(K, V)>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Removes a key-value pair if the key exists and the given condition is met.

Returns None if the key does not exist or the condition was not met. It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
let future_insert = hashmap.insert_async(11, 17);
let future_remove = hashmap.remove_if_async(&11, |_| true);

pub fn get<Q>(&self, key: &Q) -> Option<OccupiedEntry<'_, K, V, H>>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Gets the OccupiedEntry corresponding to the key.

Returns None if the key does not exist.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.get(&1).is_none());
assert!(hashmap.insert(1, 10).is_ok());
assert_eq!(*hashmap.get(&1).unwrap().get(), 10);

pub async fn get_async<Q>(&self, key: &Q) -> Option<OccupiedEntry<'_, K, V, H>>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Gets the OccupiedEntry corresponding to the key.

Returns None if the key does not exist. It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
let future_insert = hashmap.insert_async(11, 17);
let future_get = hashmap.get_async(&11);

pub fn read<Q, R, F: FnOnce(&K, &V) -> R>( &self, key: &Q, reader: F ) -> Option<R>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Reads a key-value pair.

Returns None if the key does not exist.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.read(&1, |_, v| *v).is_none());
assert!(hashmap.insert(1, 10).is_ok());
assert_eq!(hashmap.read(&1, |_, v| *v).unwrap(), 10);

pub async fn read_async<Q, R, F: FnOnce(&K, &V) -> R>( &self, key: &Q, reader: F ) -> Option<R>
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Reads a key-value pair.

Returns None if the key does not exist. It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();
let future_insert = hashmap.insert_async(11, 17);
let future_read = hashmap.read_async(&11, |_, v| *v);

pub fn contains<Q>(&self, key: &Q) -> bool
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Returns true if the HashMap contains a value for the specified key.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(!hashmap.contains(&1));
assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.contains(&1));

pub async fn contains_async<Q>(&self, key: &Q) -> bool
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Returns true if the HashMap contains a value for the specified key.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_contains = hashmap.contains_async(&1);

pub fn scan<F: FnMut(&K, &V)>(&self, scanner: F)

Scans all the entries.

Key-value pairs that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same key-value pair can be visited more than once if the HashMap gets resized by another thread.

§Examples

use scc::HashMap;

let hashmap: HashMap<usize, usize> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(2, 1).is_ok());

let mut sum = 0;
hashmap.scan(|k, v| { sum += *k + *v; });
assert_eq!(sum, 4);

pub async fn scan_async<F: FnMut(&K, &V)>(&self, scanner: F)

Scans all the entries.

Key-value pairs that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same key-value pair can be visited more than once if the HashMap gets resized by another task.

§Examples

use scc::HashMap;

let hashmap: HashMap<usize, usize> = HashMap::default();

let future_insert = hashmap.insert_async(1, 0);
let future_scan = hashmap.scan_async(|k, v| println!("{k} {v}"));

pub fn any<P: FnMut(&K, &V) -> bool>(&self, pred: P) -> bool

Searches for any entry that satisfies the given predicate.

Key-value pairs that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same key-value pair can be visited more than once if the HashMap gets resized by another thread.

Returns true as soon as an entry satisfying the predicate is found.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(2, 1).is_ok());
assert!(hashmap.insert(3, 2).is_ok());

assert!(hashmap.any(|k, v| *k == 1 && *v == 0));
assert!(!hashmap.any(|k, v| *k == 2 && *v == 0));

pub async fn any_async<P: FnMut(&K, &V) -> bool>(&self, pred: P) -> bool

Searches for any entry that satisfies the given predicate.

Key-value pairs that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same key-value pair can be visited more than once if the HashMap gets resized by another task.

It is an asynchronous method returning an impl Future for the caller to await.

Returns true as soon as an entry satisfying the predicate is found.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_insert = hashmap.insert_async(1, 0);
let future_any = hashmap.any_async(|k, _| *k == 1);

pub fn retain<F: FnMut(&K, &mut V) -> bool>(&self, pred: F)

Retains the entries specified by the predicate.

This method allows the predicate closure to modify the value field.

Entries that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same entry can be visited more than once if the HashMap gets resized by another thread.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(2, 1).is_ok());
assert!(hashmap.insert(3, 2).is_ok());

hashmap.retain(|k, v| *k == 1 && *v == 0);

assert!(hashmap.contains(&1));
assert!(!hashmap.contains(&2));
assert!(!hashmap.contains(&3));

pub async fn retain_async<F: FnMut(&K, &mut V) -> bool>(&self, pred: F)

Retains the entries specified by the predicate.

This method allows the predicate closure to modify the value field.

Entries that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same entry can be visited more than once if the HashMap gets resized by another thread.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_insert = hashmap.insert_async(1, 0);
let future_retain = hashmap.retain_async(|k, v| *k == 1);

pub fn prune<F: FnMut(&K, V) -> Option<V>>(&self, pred: F)

Prunes the entries specified by the predicate.

If the value is consumed by the predicate, in other words, if the predicate returns None, the entry is removed, otherwise the entry is retained.

Entries that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same entry can be visited more than once if the HashMap gets resized by another thread.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert!(hashmap.insert(2, 1).is_ok());
assert!(hashmap.insert(3, 2).is_ok());

hashmap.prune(|k, v| if *k == 1 { Some(v) } else { None });
assert_eq!(hashmap.len(), 1);

pub async fn prune_async<F: FnMut(&K, V) -> Option<V>>(&self, pred: F)

Prunes the entries specified by the predicate.

If the value is consumed by the predicate, in other words, if the predicate returns None, the entry is removed, otherwise the entry is retained.

Entries that have existed since the invocation of the method are guaranteed to be visited if they are not removed, however the same entry can be visited more than once if the HashMap gets resized by another thread.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_insert = hashmap.insert_async(1, 0);
let future_prune = hashmap.prune_async(|k, v| if *k == 1 { Some(v) } else { None });

pub fn clear(&self)

Clears the HashMap by removing all key-value pairs.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
hashmap.clear();

assert!(!hashmap.contains(&1));

pub async fn clear_async(&self)

Clears the HashMap by removing all key-value pairs.

It is an asynchronous method returning an impl Future for the caller to await.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

let future_insert = hashmap.insert_async(1, 0);
let future_clear = hashmap.clear_async();

pub fn len(&self) -> usize

Returns the number of entries in the HashMap.

It reads the entire metadata area of the bucket array to calculate the number of valid entries, making its time complexity O(N). Furthermore, it may overcount entries if an old bucket array has yet to be dropped.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.insert(1, 0).is_ok());
assert_eq!(hashmap.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the HashMap is empty.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert!(hashmap.is_empty());
assert!(hashmap.insert(1, 0).is_ok());
assert!(!hashmap.is_empty());

pub fn capacity(&self) -> usize

Returns the capacity of the HashMap.

§Examples

use scc::HashMap;

let hashmap_default: HashMap<u64, u32> = HashMap::default();
assert_eq!(hashmap_default.capacity(), 0);

assert!(hashmap_default.insert(1, 0).is_ok());
assert_eq!(hashmap_default.capacity(), 64);

let hashmap: HashMap<u64, u32> = HashMap::with_capacity(1000000);
assert_eq!(hashmap.capacity(), 1048576);

pub fn capacity_range(&self) -> RangeInclusive<usize>

Returns the current capacity range of the HashMap.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::default();

assert_eq!(hashmap.capacity_range(), 0..=(1_usize << (usize::BITS - 1)));

let reserved = hashmap.reserve(1000);
assert_eq!(hashmap.capacity_range(), 1000..=(1_usize << (usize::BITS - 1)));

pub fn bucket_index<Q>(&self, key: &Q) -> usize
where K: Borrow<Q>, Q: Eq + Hash + ?Sized,

Returns the index of the bucket that may contain the key.

The method returns the index of the bucket associated with the key. The number of buckets can be calculated by dividing 32 into the capacity.

§Examples

use scc::HashMap;

let hashmap: HashMap<u64, u32> = HashMap::with_capacity(1024);

let bucket_index = hashmap.bucket_index(&11);
assert!(bucket_index < hashmap.capacity() / 32);

Trait Implementations§

impl<'h, K, V, H> AsRef<HashMap<K, V, H>> for Reserve<'h, K, V, H>
where K: Eq + Hash, H: BuildHasher,

fn as_ref(&self) -> &HashMap<K, V, H>

Converts this type into a shared reference of the (usually inferred) input type.

impl<'h, K, V, H> Debug for Reserve<'h, K, V, H>
where K: Eq + Hash, H: BuildHasher,

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

Formats the value using the given formatter. Read more

impl<'h, K, V, H> Deref for Reserve<'h, K, V, H>
where K: Eq + Hash, H: BuildHasher,

type Target = HashMap<K, V, H>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'h, K, V, H> Drop for Reserve<'h, K, V, H>
where K: Eq + Hash, H: BuildHasher,

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

impl<'h, K, V, H> Freeze for Reserve<'h, K, V, H>

impl<'h, K, V, H> RefUnwindSafe for Reserve<'h, K, V, H>
where H: RefUnwindSafe,

impl<'h, K, V, H> Send for Reserve<'h, K, V, H>
where H: Sync, K: Sync, V: Sync,

impl<'h, K, V, H> Sync for Reserve<'h, K, V, H>
where H: Sync, K: Sync, V: Sync,

impl<'h, K, V, H> Unpin for Reserve<'h, K, V, H>

impl<'h, K, V, H> UnwindSafe for Reserve<'h, K, V, H>
where H: RefUnwindSafe,

Blanket Implementations§

impl<T> Any for T
where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

impl<T> Borrow<T> for T
where T: ?Sized,

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

impl<T> BorrowMut<T> for T
where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

impl<T> From<T> for T

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for T
where U: From<T>,

fn into(self) -> U

Calls U::from(self).

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

impl<T, U> TryFrom for T
where U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

impl<T, U> TryInto for T
where U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.