diff --git a/src/doc/unstable-book/src/library-features/entry-and-modify.md b/src/doc/unstable-book/src/library-features/entry-and-modify.md new file mode 100644 index 00000000000..1280c71e83c --- /dev/null +++ b/src/doc/unstable-book/src/library-features/entry-and-modify.md @@ -0,0 +1,77 @@ +# `entry_and_modify` + +The tracking issue for this feature is: [#44733] + +[#44733]: https://github.com/rust-lang/rust/issues/44733 + +------------------------ + +This introduces a new method for the Entry API of maps +(`std::collections::HashMap` and `std::collections::BTreeMap`), so that +occupied entries can be modified before any potential inserts into the +map. + +For example: + +```rust +#![feature(entry_and_modify)] +# fn main() { +use std::collections::HashMap; + +struct Foo { + new: bool, +} + +let mut map: HashMap<&str, Foo> = HashMap::new(); + +map.entry("quux") + .and_modify(|e| e.new = false) + .or_insert(Foo { new: true }); +# } +``` + +This is not possible with the stable API alone since inserting a default +_before_ modifying the `new` field would mean we would lose the default state: + +```rust +# fn main() { +use std::collections::HashMap; + +struct Foo { + new: bool, +} + +let mut map: HashMap<&str, Foo> = HashMap::new(); + +map.entry("quux").or_insert(Foo { new: true }).new = false; +# } +``` + +In the above code the `new` field will never be `true`, even though we only +intended to update that field to `false` for previously extant entries. + +To achieve the same effect as `and_modify` we would have to manually match +against the `Occupied` and `Vacant` variants of the `Entry` enum, which is +a little less user-friendly, and much more verbose: + +```rust +# fn main() { +use std::collections::HashMap; +use std::collections::hash_map::Entry; + +struct Foo { + new: bool, +} + +let mut map: HashMap<&str, Foo> = HashMap::new(); + +match map.entry("quux") { + Entry::Occupied(entry) => { + entry.into_mut().new = false; + }, + Entry::Vacant(entry) => { + entry.insert(Foo { new: true }); + }, +}; +# } +``` diff --git a/src/liballoc/btree/map.rs b/src/liballoc/btree/map.rs index 4c93fead172..b114dc640fb 100644 --- a/src/liballoc/btree/map.rs +++ b/src/liballoc/btree/map.rs @@ -2102,6 +2102,40 @@ impl<'a, K: Ord, V> Entry<'a, K, V> { Vacant(ref entry) => entry.key(), } } + + /// Provides in-place mutable access to an occupied entry before any + /// potential inserts into the map. + /// + /// # Examples + /// + /// ``` + /// #![feature(entry_and_modify)] + /// use std::collections::BTreeMap; + /// + /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); + /// + /// map.entry("poneyland") + /// .and_modify(|e| { *e += 1 }) + /// .or_insert(42); + /// assert_eq!(map["poneyland"], 42); + /// + /// map.entry("poneyland") + /// .and_modify(|e| { *e += 1 }) + /// .or_insert(42); + /// assert_eq!(map["poneyland"], 43); + /// ``` + #[unstable(feature = "entry_and_modify", issue = "44733")] + pub fn and_modify(self, mut f: F) -> Self + where F: FnMut(&mut V) + { + match self { + Occupied(mut entry) => { + f(entry.get_mut()); + Occupied(entry) + }, + Vacant(entry) => Vacant(entry), + } + } } impl<'a, K: Ord, V: Default> Entry<'a, K, V> { diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 406acde1f1c..3c0fa0860d3 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -2013,6 +2013,41 @@ impl<'a, K, V> Entry<'a, K, V> { Vacant(ref entry) => entry.key(), } } + + /// Provides in-place mutable access to an occupied entry before any + /// potential inserts into the map. + /// + /// # Examples + /// + /// ``` + /// #![feature(entry_and_modify)] + /// use std::collections::HashMap; + /// + /// let mut map: HashMap<&str, u32> = HashMap::new(); + /// + /// map.entry("poneyland") + /// .and_modify(|e| { *e += 1 }) + /// .or_insert(42); + /// assert_eq!(map["poneyland"], 42); + /// + /// map.entry("poneyland") + /// .and_modify(|e| { *e += 1 }) + /// .or_insert(42); + /// assert_eq!(map["poneyland"], 43); + /// ``` + #[unstable(feature = "entry_and_modify", issue = "44733")] + pub fn and_modify(self, mut f: F) -> Self + where F: FnMut(&mut V) + { + match self { + Occupied(mut entry) => { + f(entry.get_mut()); + Occupied(entry) + }, + Vacant(entry) => Vacant(entry), + } + } + } impl<'a, K, V: Default> Entry<'a, K, V> {