Enum EntryRef

pub enum EntryRef<'a, 'b, K, Q: ?Sized, V, S, A = Global>
where
    A: Allocator,

A view into a single entry in a map, which may either be vacant or occupied, with any borrowed form of the map's key type.

This enum is constructed from the entry_ref method on HashMap.

Hash and Eq on the borrowed form of the map's key type must match those for the key type. It also require that key may be constructed from the borrowed form through the ToOwned trait.

Examples

use hashbrown::hash_map::{EntryRef, HashMap, OccupiedEntry};

let mut map = HashMap::new();
map.extend([("a".to_owned(), 10), ("b".into(), 20), ("c".into(), 30)]);
assert_eq!(map.len(), 3);

// Existing key (insert)
let key = String::from("a");
let entry: EntryRef<_, _, _, _> = map.entry_ref(&key);
let _raw_o: OccupiedEntry<_, _, _, _> = entry.insert(1);
assert_eq!(map.len(), 3);
// Nonexistent key (insert)
map.entry_ref("d").insert(4);

// Existing key (or_insert)
let v = map.entry_ref("b").or_insert(2);
assert_eq!(std::mem::replace(v, 2), 20);
// Nonexistent key (or_insert)
map.entry_ref("e").or_insert(5);

// Existing key (or_insert_with)
let v = map.entry_ref("c").or_insert_with(|| 3);
assert_eq!(std::mem::replace(v, 3), 30);
// Nonexistent key (or_insert_with)
map.entry_ref("f").or_insert_with(|| 6);

println!("Our HashMap: {:?}", map);

for (key, value) in ["a", "b", "c", "d", "e", "f"].into_iter().zip(1..=6) {
    assert_eq!(map[key], value)
}
assert_eq!(map.len(), 6);

Variants

Occupied(OccupiedEntry<'a, K, V, S, A>)

An occupied entry.

Examples

use hashbrown::hash_map::{EntryRef, HashMap};
let mut map: HashMap<_, _> = [("a".to_owned(), 100), ("b".into(), 200)].into();

match map.entry_ref("a") {
    EntryRef::Vacant(_) => unreachable!(),
    EntryRef::Occupied(_) => { }
}
Vacant(VacantEntryRef<'a, 'b, K, Q, V, S, A>)

A vacant entry.

Examples

use hashbrown::hash_map::{EntryRef, HashMap};
let mut map: HashMap<String, i32> = HashMap::new();

match map.entry_ref("a") {
    EntryRef::Occupied(_) => unreachable!(),
    EntryRef::Vacant(_) => { }
}

Implementations

impl<'a, 'b, K, Q: ?Sized, V, S, A: Allocator> EntryRef<'a, 'b, K, Q, V, S, A>

fn insert(self, value: V) -> OccupiedEntry<'a, K, V, S, A>
where
    K: Hash,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Sets the value of the entry, and returns an OccupiedEntry.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();
let entry = map.entry_ref("horseyland").insert(37);

assert_eq!(entry.key(), "horseyland");

fn or_insert(self, default: V) -> &'a mut V
where
    K: Hash,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Ensures a value is in the entry by inserting the default if empty, and returns a mutable reference to the value in the entry.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();

// nonexistent key
map.entry_ref("poneyland").or_insert(3);
assert_eq!(map["poneyland"], 3);

// existing key
*map.entry_ref("poneyland").or_insert(10) *= 2;
assert_eq!(map["poneyland"], 6);

fn or_insert_with<F: FnOnce() -> V>(self, default: F) -> &'a mut V
where
    K: Hash,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Ensures a value is in the entry by inserting the result of the default function if empty, and returns a mutable reference to the value in the entry.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();

// nonexistent key
map.entry_ref("poneyland").or_insert_with(|| 3);
assert_eq!(map["poneyland"], 3);

// existing key
*map.entry_ref("poneyland").or_insert_with(|| 10) *= 2;
assert_eq!(map["poneyland"], 6);

fn or_insert_with_key<F: FnOnce(&Q) -> V>(self, default: F) -> &'a mut V
where
    K: Hash + Borrow<Q>,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Ensures a value is in the entry by inserting, if empty, the result of the default function. This method allows for generating key-derived values for insertion by providing the default function an access to the borrower form of the key.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, usize> = HashMap::new();

// nonexistent key
map.entry_ref("poneyland").or_insert_with_key(|key| key.chars().count());
assert_eq!(map["poneyland"], 9);

// existing key
*map.entry_ref("poneyland").or_insert_with_key(|key| key.chars().count() * 10) *= 2;
assert_eq!(map["poneyland"], 18);

fn key(&self) -> &Q
where
    K: Borrow<Q>,

Returns a reference to this entry's key.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();
map.entry_ref("poneyland").or_insert(3);
// existing key
assert_eq!(map.entry_ref("poneyland").key(), "poneyland");
// nonexistent key
assert_eq!(map.entry_ref("horseland").key(), "horseland");

fn and_modify<F>(self, f: F) -> Self
where
    F: FnOnce(&mut V),

Provides in-place mutable access to an occupied entry before any potential inserts into the map.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();

map.entry_ref("poneyland")
   .and_modify(|e| { *e += 1 })
   .or_insert(42);
assert_eq!(map["poneyland"], 42);

map.entry_ref("poneyland")
   .and_modify(|e| { *e += 1 })
   .or_insert(42);
assert_eq!(map["poneyland"], 43);

fn into_map(self) -> &'a mut HashMap<K, V, S, A>

Converts the EntryRef into a mutable reference to the underlying map.

impl<'a, 'b, K, Q: ?Sized, V: Default, S, A: Allocator> EntryRef<'a, 'b, K, Q, V, S, A>

fn or_default(self) -> &'a mut V
where
    K: Hash,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Ensures a value is in the entry by inserting the default value if empty, and returns a mutable reference to the value in the entry.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, Option<u32>> = HashMap::new();

// nonexistent key
map.entry_ref("poneyland").or_default();
assert_eq!(map["poneyland"], None);

map.insert("horseland".to_string(), Some(3));

// existing key
assert_eq!(map.entry_ref("horseland").or_default(), &mut Some(3));

fn or_default_entry(self) -> OccupiedEntry<'a, K, V, S, A>
where
    K: Hash,
    Q: ToOwned<Owned = K>,
    S: BuildHasher,

Ensures a value is in the entry by inserting the default value if empty, and returns an OccupiedEntry.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, Option<u32>> = HashMap::new();

// nonexistent key
let entry = map.entry_ref("poneyland").or_default_entry();
assert_eq!(entry.key(), &"poneyland");
assert_eq!(entry.get(), &None);

// existing key
map.insert("horseland".to_string(), Some(3));
let entry = map.entry_ref("horseland").or_default_entry();
assert_eq!(entry.key(), &"horseland");
assert_eq!(entry.get(), &Some(3));

Trait Implementations

impl<K, Q, V, S, A> Debug for EntryRef<'_, '_, K, Q, V, S, A> where K: Debug + Borrow<Q>, Q: Debug + ?Sized, V: Debug, A: Allocator,

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

Auto Trait Implementations

impl<'a, 'b, K, Q, V, S, A = Global> !UnwindSafe for EntryRef<'a, 'b, K, Q, V, S, A>

impl<'a, 'b, K, Q, V, S, A> Freeze for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: Freeze, VacantEntryRef<'a, 'b, K, Q, V, S, A>: Freeze, Q: ?Sized,

impl<'a, 'b, K, Q, V, S, A> RefUnwindSafe for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: RefUnwindSafe, VacantEntryRef<'a, 'b, K, Q, V, S, A>: RefUnwindSafe, Q: ?Sized,

impl<'a, 'b, K, Q, V, S, A> Send for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: Send, VacantEntryRef<'a, 'b, K, Q, V, S, A>: Send, Q: ?Sized,

impl<'a, 'b, K, Q, V, S, A> Sync for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: Sync, VacantEntryRef<'a, 'b, K, Q, V, S, A>: Sync, Q: ?Sized,

impl<'a, 'b, K, Q, V, S, A> Unpin for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: Unpin, VacantEntryRef<'a, 'b, K, Q, V, S, A>: Unpin, Q: ?Sized,

impl<'a, 'b, K, Q, V, S, A> UnsafeUnpin for EntryRef<'a, 'b, K, Q, V, S, A> where OccupiedEntry<'a, K, V, S, A>: UnsafeUnpin, VacantEntryRef<'a, 'b, K, Q, V, S, A>: UnsafeUnpin, Q: ?Sized,

Blanket Implementations

impl<T> Any for EntryRef<'a, 'b, K, Q, V, S, A> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for EntryRef<'a, 'b, K, Q, V, S, A> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for EntryRef<'a, 'b, K, Q, V, S, A> where T: ?Sized,

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

impl<T> From<T> for EntryRef<'a, 'b, K, Q, V, S, A>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into<U> for EntryRef<'a, 'b, K, Q, V, S, A> 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<U> for EntryRef<'a, 'b, K, Q, V, S, A> where U: Into<T>,

type Error = never;
fn try_from(value: U) -> Result<T, never>

impl<T, U> TryInto<U> for EntryRef<'a, 'b, K, Q, V, S, A> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>