Implement entry_and_modify

Author: mchlrhw

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 });
+    },
+};
+# }
+```

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<F>(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> {

src/libstd/collections/hash/map.rs

@@ -2002,6 +2002,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<F>(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> {