Struct OccupiedEntry

pub struct OccupiedEntry<'a, T, A = Global>
where
    A: Allocator,
{ /* private fields */ }

A view into an occupied entry in a HashTable. It is part of the Entry enum.

Examples

use hashbrown::hash_table::{Entry, OccupiedEntry};
use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
for x in ["a", "b", "c"] {
    table.insert_unique(hasher(&x), x, hasher);
}
assert_eq!(table.len(), 3);

let _entry_o: OccupiedEntry<_, _> = table.find_entry(hasher(&"a"), |&x| x == "a").unwrap();
assert_eq!(table.len(), 3);

// Existing key
match table.entry(hasher(&"a"), |&x| x == "a", hasher) {
    Entry::Vacant(_) => unreachable!(),
    Entry::Occupied(view) => {
        assert_eq!(view.get(), &"a");
    }
}

assert_eq!(table.len(), 3);

// Existing key (take)
match table.entry(hasher(&"c"), |&x| x == "c", hasher) {
    Entry::Vacant(_) => unreachable!(),
    Entry::Occupied(view) => {
        assert_eq!(view.remove().0, "c");
    }
}
assert_eq!(table.find(hasher(&"c"), |&x| x == "c"), None);
assert_eq!(table.len(), 2);

Implementations

impl<'a, T, A> OccupiedEntry<'a, T, A>

where A: Allocator,

pub fn remove(self) -> (T, VacantEntry<'a, T, A>)

Takes the value out of the entry, and returns it along with a VacantEntry that can be used to insert another value with the same hash as the one that was just removed.

Examples

use hashbrown::hash_table::Entry;
use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table: HashTable<&str> = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
// The table is empty
assert!(table.is_empty() && table.capacity() == 0);

table.insert_unique(hasher(&"poneyland"), "poneyland", hasher);
let capacity_before_remove = table.capacity();

if let Entry::Occupied(o) = table.entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) {
    assert_eq!(o.remove().0, "poneyland");
}

assert!(table
    .find(hasher(&"poneyland"), |&x| x == "poneyland")
    .is_none());
// Now table hold none elements but capacity is equal to the old one
assert!(table.len() == 0 && table.capacity() == capacity_before_remove);

pub fn get(&self) -> &T

Gets a reference to the value in the entry.

Examples

use hashbrown::hash_table::Entry;
use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table: HashTable<&str> = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
table.insert_unique(hasher(&"poneyland"), "poneyland", hasher);

match table.entry(hasher(&"poneyland"), |&x| x == "poneyland", hasher) {
    Entry::Vacant(_) => panic!(),
    Entry::Occupied(entry) => assert_eq!(entry.get(), &"poneyland"),
}

pub fn get_mut(&mut self) -> &mut T

Gets a mutable reference to the value in the entry.

If you need a reference to the OccupiedEntry which may outlive the destruction of the Entry value, see into_mut.

Examples

use hashbrown::hash_table::Entry;
use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table: HashTable<(&str, u32)> = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
table.insert_unique(hasher(&"poneyland"), ("poneyland", 12), |(k, _)| hasher(&k));

assert_eq!(
    table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",),
    Some(&("poneyland", 12))
);

if let Entry::Occupied(mut o) = table.entry(
    hasher(&"poneyland"),
    |&(x, _)| x == "poneyland",
    |(k, _)| hasher(&k),
) {
    o.get_mut().1 += 10;
    assert_eq!(o.get().1, 22);

    // We can use the same Entry multiple times.
    o.get_mut().1 += 2;
}

assert_eq!(
    table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",),
    Some(&("poneyland", 24))
);

pub fn into_mut(self) -> &'a mut T

Converts the OccupiedEntry into a mutable reference to the value in the entry with a lifetime bound to the table itself.

If you need multiple references to the OccupiedEntry, see get_mut.

Examples

use hashbrown::hash_table::Entry;
use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table: HashTable<(&str, u32)> = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
table.insert_unique(hasher(&"poneyland"), ("poneyland", 12), |(k, _)| hasher(&k));

assert_eq!(
    table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",),
    Some(&("poneyland", 12))
);

let value: &mut (&str, u32);
match table.entry(
    hasher(&"poneyland"),
    |&(x, _)| x == "poneyland",
    |(k, _)| hasher(&k),
) {
    Entry::Occupied(entry) => value = entry.into_mut(),
    Entry::Vacant(_) => panic!(),
}
value.1 += 10;

assert_eq!(
    table.find(hasher(&"poneyland"), |&(x, _)| x == "poneyland",),
    Some(&("poneyland", 22))
);

pub fn into_table(self) -> &'a mut HashTable<T, A>

Converts the OccupiedEntry into a mutable reference to the underlying table.

pub fn bucket_index(&self) -> usize

Returns the bucket index in the table for this entry.

This can be used to store a borrow-free “reference” to the entry, later using HashTable::get_bucket, HashTable::get_bucket_mut, or HashTable::get_bucket_entry to access it again without hash probing.

The index is only meaningful as long as the table is not resized and no entries are added or removed. After such changes, it may end up pointing to a different entry or none at all.

Examples

use hashbrown::{HashTable, DefaultHashBuilder};
use std::hash::BuildHasher;

let mut table = HashTable::new();
let hasher = DefaultHashBuilder::default();
let hasher = |val: &_| hasher.hash_one(val);
table.insert_unique(hasher(&1), (1, 1), |val| hasher(&val.0));
table.insert_unique(hasher(&2), (2, 2), |val| hasher(&val.0));
table.insert_unique(hasher(&3), (3, 3), |val| hasher(&val.0));

let index = table
    .entry(hasher(&2), |val| val.0 == 2, |val| hasher(&val.0))
    .or_insert((2, -2))
    .bucket_index();
assert_eq!(table.get_bucket(index), Some(&(2, 2)));

// Full mutation would invalidate any normal reference
for (_key, value) in &mut table {
    *value *= 11;
}

// The index still reaches the same key with the updated value
assert_eq!(table.get_bucket(index), Some(&(2, 22)));

Trait Implementations

impl<T, A> Debug for OccupiedEntry<'_, T, A>

where T: Debug, A: Allocator,

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

Formats the value using the given formatter.

impl<T, A> Send for OccupiedEntry<'_, T, A>

where T: Send, A: Send + Allocator,

impl<T, A> Sync for OccupiedEntry<'_, T, A>

where T: Sync, A: Sync + Allocator,