Add HashMap Entry enums examples
This commit is contained in:
parent
a63e3fac8f
commit
ec33dab062
@ -1336,6 +1336,10 @@ impl<'a, K, V> InternalEntry<K, V, &'a mut RawTable<K, V>> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// A view into a single location in a map, which may be vacant or occupied.
|
/// A view into a single location in a map, which may be vacant or occupied.
|
||||||
|
/// This enum is constructed from the [`entry`] method on [`HashMap`].
|
||||||
|
///
|
||||||
|
/// [`HashMap`]: struct.HashMap.html
|
||||||
|
/// [`entry`]: struct.HashMap.html#method.entry
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub enum Entry<'a, K: 'a, V: 'a> {
|
pub enum Entry<'a, K: 'a, V: 'a> {
|
||||||
/// An occupied Entry.
|
/// An occupied Entry.
|
||||||
@ -1352,6 +1356,9 @@ pub enum Entry<'a, K: 'a, V: 'a> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// A view into a single occupied location in a HashMap.
|
/// A view into a single occupied location in a HashMap.
|
||||||
|
/// It is part of the [`Entry`] enum.
|
||||||
|
///
|
||||||
|
/// [`Entry`]: enum.Entry.html
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub struct OccupiedEntry<'a, K: 'a, V: 'a> {
|
pub struct OccupiedEntry<'a, K: 'a, V: 'a> {
|
||||||
key: Option<K>,
|
key: Option<K>,
|
||||||
@ -1359,6 +1366,9 @@ pub struct OccupiedEntry<'a, K: 'a, V: 'a> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// A view into a single empty location in a HashMap.
|
/// A view into a single empty location in a HashMap.
|
||||||
|
/// It is part of the [`Entry`] enum.
|
||||||
|
///
|
||||||
|
/// [`Entry`]: enum.Entry.html
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub struct VacantEntry<'a, K: 'a, V: 'a> {
|
pub struct VacantEntry<'a, K: 'a, V: 'a> {
|
||||||
hash: SafeHash,
|
hash: SafeHash,
|
||||||
@ -1518,6 +1528,20 @@ impl<'a, K, V> Entry<'a, K, V> {
|
|||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
/// Ensures a value is in the entry by inserting the default if empty, and returns
|
/// Ensures a value is in the entry by inserting the default if empty, and returns
|
||||||
/// a mutable reference to the value in the entry.
|
/// a mutable reference to the value in the entry.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 12);
|
||||||
|
///
|
||||||
|
/// *map.entry("poneyland").or_insert(12) += 10;
|
||||||
|
/// assert_eq!(map["poneyland"], 22);
|
||||||
|
/// ```
|
||||||
pub fn or_insert(self, default: V) -> &'a mut V {
|
pub fn or_insert(self, default: V) -> &'a mut V {
|
||||||
match self {
|
match self {
|
||||||
Occupied(entry) => entry.into_mut(),
|
Occupied(entry) => entry.into_mut(),
|
||||||
@ -1528,6 +1552,19 @@ impl<'a, K, V> Entry<'a, K, V> {
|
|||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
/// Ensures a value is in the entry by inserting the result of the default function if empty,
|
/// 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.
|
/// and returns a mutable reference to the value in the entry.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, String> = HashMap::new();
|
||||||
|
/// let s = "hoho".to_owned();
|
||||||
|
///
|
||||||
|
/// map.entry("poneyland").or_insert_with(|| s);
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], "hoho".to_owned());
|
||||||
|
/// ```
|
||||||
pub fn or_insert_with<F: FnOnce() -> V>(self, default: F) -> &'a mut V {
|
pub fn or_insert_with<F: FnOnce() -> V>(self, default: F) -> &'a mut V {
|
||||||
match self {
|
match self {
|
||||||
Occupied(entry) => entry.into_mut(),
|
Occupied(entry) => entry.into_mut(),
|
||||||
@ -1536,6 +1573,15 @@ impl<'a, K, V> Entry<'a, K, V> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// Returns a reference to this entry's key.
|
/// Returns a reference to this entry's key.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// assert_eq!(map.entry("poneyland").key(), &"poneyland");
|
||||||
|
/// ```
|
||||||
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
||||||
pub fn key(&self) -> &K {
|
pub fn key(&self) -> &K {
|
||||||
match *self {
|
match *self {
|
||||||
@ -1547,37 +1593,130 @@ impl<'a, K, V> Entry<'a, K, V> {
|
|||||||
|
|
||||||
impl<'a, K, V> OccupiedEntry<'a, K, V> {
|
impl<'a, K, V> OccupiedEntry<'a, K, V> {
|
||||||
/// Gets a reference to the key in the entry.
|
/// Gets a reference to the key in the entry.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
/// assert_eq!(map.entry("poneyland").key(), &"poneyland");
|
||||||
|
/// ```
|
||||||
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
||||||
pub fn key(&self) -> &K {
|
pub fn key(&self) -> &K {
|
||||||
self.elem.read().0
|
self.elem.read().0
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Take the ownership of the key and value from the map.
|
/// Take the ownership of the key and value from the map.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// #![feature(map_entry_recover_keys)]
|
||||||
|
///
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// if let Entry::Occupied(o) = map.entry("poneyland") {
|
||||||
|
/// // We delete the entry from the map.
|
||||||
|
/// o.remove_pair();
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// assert_eq!(map.contains_key("poneyland"), false);
|
||||||
|
/// ```
|
||||||
#[unstable(feature = "map_entry_recover_keys", issue = "34285")]
|
#[unstable(feature = "map_entry_recover_keys", issue = "34285")]
|
||||||
pub fn remove_pair(self) -> (K, V) {
|
pub fn remove_pair(self) -> (K, V) {
|
||||||
pop_internal(self.elem)
|
pop_internal(self.elem)
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Gets a reference to the value in the entry.
|
/// Gets a reference to the value in the entry.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// if let Entry::Occupied(o) = map.entry("poneyland") {
|
||||||
|
/// assert_eq!(o.get(), &12);
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn get(&self) -> &V {
|
pub fn get(&self) -> &V {
|
||||||
self.elem.read().1
|
self.elem.read().1
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Gets a mutable reference to the value in the entry.
|
/// Gets a mutable reference to the value in the entry.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 12);
|
||||||
|
/// if let Entry::Occupied(mut o) = map.entry("poneyland") {
|
||||||
|
/// *o.get_mut() += 10;
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 22);
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn get_mut(&mut self) -> &mut V {
|
pub fn get_mut(&mut self) -> &mut V {
|
||||||
self.elem.read_mut().1
|
self.elem.read_mut().1
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Converts the OccupiedEntry into a mutable reference to the value in the entry
|
/// Converts the OccupiedEntry into a mutable reference to the value in the entry
|
||||||
/// with a lifetime bound to the map itself
|
/// with a lifetime bound to the map itself.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 12);
|
||||||
|
/// if let Entry::Occupied(o) = map.entry("poneyland") {
|
||||||
|
/// *o.into_mut() += 10;
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 22);
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn into_mut(self) -> &'a mut V {
|
pub fn into_mut(self) -> &'a mut V {
|
||||||
self.elem.into_mut_refs().1
|
self.elem.into_mut_refs().1
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Sets the value of the entry, and returns the entry's old value
|
/// Sets the value of the entry, and returns the entry's old value.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// if let Entry::Occupied(mut o) = map.entry("poneyland") {
|
||||||
|
/// assert_eq!(o.insert(15), 12);
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// assert_eq!(map["poneyland"], 15);
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn insert(&mut self, mut value: V) -> V {
|
pub fn insert(&mut self, mut value: V) -> V {
|
||||||
let old_value = self.get_mut();
|
let old_value = self.get_mut();
|
||||||
@ -1585,7 +1724,23 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
|
|||||||
value
|
value
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Takes the value out of the entry, and returns it
|
/// Takes the value out of the entry, and returns it.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// map.entry("poneyland").or_insert(12);
|
||||||
|
///
|
||||||
|
/// if let Entry::Occupied(o) = map.entry("poneyland") {
|
||||||
|
/// assert_eq!(o.remove(), 12);
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// assert_eq!(map.contains_key("poneyland"), false);
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn remove(self) -> V {
|
pub fn remove(self) -> V {
|
||||||
pop_internal(self.elem).1
|
pop_internal(self.elem).1
|
||||||
@ -1601,20 +1756,58 @@ impl<'a, K, V> OccupiedEntry<'a, K, V> {
|
|||||||
|
|
||||||
impl<'a, K: 'a, V: 'a> VacantEntry<'a, K, V> {
|
impl<'a, K: 'a, V: 'a> VacantEntry<'a, K, V> {
|
||||||
/// Gets a reference to the key that would be used when inserting a value
|
/// Gets a reference to the key that would be used when inserting a value
|
||||||
/// through the VacantEntry.
|
/// through the `VacantEntry`.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
/// assert_eq!(map.entry("poneyland").key(), &"poneyland");
|
||||||
|
/// ```
|
||||||
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
#[stable(feature = "map_entry_keys", since = "1.10.0")]
|
||||||
pub fn key(&self) -> &K {
|
pub fn key(&self) -> &K {
|
||||||
&self.key
|
&self.key
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Take ownership of the key.
|
/// Take ownership of the key.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// #![feature(map_entry_recover_keys)]
|
||||||
|
///
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
///
|
||||||
|
/// if let Entry::Vacant(v) = map.entry("poneyland") {
|
||||||
|
/// v.into_key();
|
||||||
|
/// }
|
||||||
|
/// ```
|
||||||
#[unstable(feature = "map_entry_recover_keys", issue = "34285")]
|
#[unstable(feature = "map_entry_recover_keys", issue = "34285")]
|
||||||
pub fn into_key(self) -> K {
|
pub fn into_key(self) -> K {
|
||||||
self.key
|
self.key
|
||||||
}
|
}
|
||||||
|
|
||||||
/// Sets the value of the entry with the VacantEntry's key,
|
/// Sets the value of the entry with the VacantEntry's key,
|
||||||
/// and returns a mutable reference to it
|
/// and returns a mutable reference to it.
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// use std::collections::HashMap;
|
||||||
|
/// use std::collections::hash_map::Entry;
|
||||||
|
///
|
||||||
|
/// let mut map: HashMap<&str, u32> = HashMap::new();
|
||||||
|
///
|
||||||
|
/// if let Entry::Vacant(o) = map.entry("poneyland") {
|
||||||
|
/// o.insert(37);
|
||||||
|
/// }
|
||||||
|
/// assert_eq!(map["poneyland"], 37);
|
||||||
|
/// ```
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
pub fn insert(self, value: V) -> &'a mut V {
|
pub fn insert(self, value: V) -> &'a mut V {
|
||||||
match self.elem {
|
match self.elem {
|
||||||
|
Loading…
Reference in New Issue
Block a user