Struct VacantEntryRef 

pub struct VacantEntryRef<'map, 'key, K, Q: ?Sized, V, S, A: Allocator = Global> { /* private fields */ }

A view into a vacant entry in a HashMap. It is part of the EntryRef enum.

Examples

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

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

let entry_v: VacantEntryRef<_, _, _, _> = match map.entry_ref("a") {
    EntryRef::Vacant(view) => view,
    EntryRef::Occupied(_) => unreachable!(),
};
entry_v.insert(10);
assert!(map["a"] == 10 && map.len() == 1);

// Nonexistent key (insert and update)
match map.entry_ref("b") {
    EntryRef::Occupied(_) => unreachable!(),
    EntryRef::Vacant(view) => {
        let value = view.insert(2);
        assert_eq!(*value, 2);
        *value = 20;
    }
}
assert!(map["b"] == 20 && map.len() == 2);

Implementations

impl<'map, 'key, K, Q: ?Sized, V, S, A: Allocator> VacantEntryRef<'map, 'key, K, Q, V, S, A>

pub fn key(&self) -> &'key Q

Gets a reference to the key that would be used when inserting a value through the VacantEntryRef.

Examples

use hashbrown::HashMap;

let mut map: HashMap<String, u32> = HashMap::new();
let key: &str = "poneyland";
assert_eq!(map.entry_ref(key).key(), "poneyland");

pub fn insert(self, value: V) -> &'map mut V

where K: Hash, Q: ToOwned<Owned = K>, S: BuildHasher,

Sets the value of the entry with the VacantEntryRef’s key, and returns a mutable reference to it.

Examples

use hashbrown::HashMap;
use hashbrown::hash_map::EntryRef;

let mut map: HashMap<String, u32> = HashMap::new();
let key: &str = "poneyland";

if let EntryRef::Vacant(o) = map.entry_ref(key) {
    o.insert(37);
}
assert_eq!(map["poneyland"], 37);

pub fn insert_with_key(self, key: K, value: V) -> &'map mut V

where K: Hash, Q: Equivalent<K>, S: BuildHasher,

Sets the key and value of the entry and returns a mutable reference to the inserted value.

Unlike VacantEntryRef::insert, this method allows the key to be explicitly specified, which is useful for key types that don’t implement ToOwned.

Panics

This method panics if key is not equivalent to the key used to create the VacantEntryRef.

Example

use hashbrown::hash_map::EntryRef;
use hashbrown::HashMap;

let mut map = HashMap::<(String, String), char>::new();
let k = ("c".to_string(), "C".to_string());
let v =  match map.entry_ref(&k) {
  // Insert cannot be used here because tuples do not implement ToOwned.
  // However this works because we can manually clone instead.
  EntryRef::Vacant(r) => r.insert_with_key(k.clone(), 'c'),
  // In this branch we avoid the clone.
  EntryRef::Occupied(r) => r.into_mut(),
};
assert_eq!(*v, 'c');

pub unsafe fn insert_with_key_unchecked(self, key: K, value: V) -> &'map mut V

where K: Hash, S: BuildHasher,

Sets the key and value of the entry and returns a mutable reference to the inserted value, without checking the equivalence of the key.

See insert_with_key for more information.

Safety

This operation is safe if the keys are equivalent.

Additionally, this operation (and following operations) are guaranteed to not violate memory safety.

However this operation is still unsafe because the resulting HashMap may be passed to unsafe code which does expect the map to behave correctly. If the map has keys at unexpected positions inside it, future operations may panic, loop forever, or return unexpected results, potentially violating memory safety.

Example

use hashbrown::hash_map::EntryRef;
use hashbrown::HashMap;

let mut map = HashMap::<(String, String), char>::new();
let k = ("c".to_string(), "C".to_string());
let v =  match map.entry_ref(&k) {
  // SAFETY: We trust the `Clone` implementation to return an equivalent value
  EntryRef::Vacant(r) => unsafe { r.insert_with_key_unchecked(k.clone(), 'c') },
  // In this branch we avoid the clone.
  EntryRef::Occupied(r) => r.into_mut(),
};
assert_eq!(*v, 'c');

pub fn insert_entry(self, value: V) -> OccupiedEntry<'map, K, V, S, A>

where K: Hash, Q: ToOwned<Owned = K>, S: BuildHasher,

Sets the value of the entry with the VacantEntryRef’s key, and returns an OccupiedEntry.

Examples

use hashbrown::HashMap;
use hashbrown::hash_map::EntryRef;

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

if let EntryRef::Vacant(v) = map.entry_ref(&"poneyland") {
    let o = v.insert_entry(37);
    assert_eq!(o.get(), &37);
}

pub fn insert_entry_with_key( self, key: K, value: V, ) -> OccupiedEntry<'map, K, V, S, A>

where K: Hash, Q: Equivalent<K>, S: BuildHasher,

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

Unlike VacantEntryRef::insert_entry, this method allows the key to be explicitly specified, which is useful for key types that don’t implement ToOwned.

Panics

This method panics if key is not equivalent to the key used to create the VacantEntryRef.

Example

use hashbrown::hash_map::EntryRef;
use hashbrown::HashMap;

let mut map = HashMap::<(String, String), char>::new();
let k = ("c".to_string(), "C".to_string());
let r = match map.entry_ref(&k) {
  // Insert cannot be used here because tuples do not implement ToOwned.
  // However this works because we can manually clone instead.
  EntryRef::Vacant(r) => r.insert_entry_with_key(k.clone(), 'c'),
  // In this branch we avoid the clone.
  EntryRef::Occupied(r) => r,
};
assert_eq!(r.get(), &'c');

pub unsafe fn insert_entry_with_key_unchecked( self, key: K, value: V, ) -> OccupiedEntry<'map, K, V, S, A>

where K: Hash, S: BuildHasher,

Sets the key and value of the entry and returns an OccupiedEntry, without checking the equivalence of the key.

See insert_entry_with_key for more information.

Safety

This operation is safe if the keys are equivalent.

Additionally, this operation (and following operations) are guaranteed to not violate memory safety.

However this operation is still unsafe because the resulting HashMap may be passed to unsafe code which does expect the map to behave correctly. If the map has keys at unexpected positions inside it, future operations may panic, loop forever, or return unexpected results, potentially violating memory safety.

Example

use hashbrown::hash_map::EntryRef;
use hashbrown::HashMap;

let mut map = HashMap::<(String, String), char>::new();
let k = ("c".to_string(), "C".to_string());
let r = match map.entry_ref(&k) {
  // SAFETY: We trust the `Clone` implementation to return an equivalent key
  EntryRef::Vacant(r) => unsafe { r.insert_entry_with_key_unchecked(k.clone(), 'c') },
  // In this branch we avoid the clone.
  EntryRef::Occupied(r) => r,
};
assert_eq!(r.get(), &'c');

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

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

Trait Implementations

impl<K, Q, V, S, A> Debug for VacantEntryRef<'_, '_, K, Q, V, S, A>

where K: Borrow<Q>, Q: Debug + ?Sized, A: Allocator,

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

Formats the value using the given formatter.