Rollup merge of rust-lang#31035 - nathankleyn:improve-visibility-of-e…

…ntry-api, r=steveklabnik

Responding to [a thread of discussion on the Rust subreddit](https://www.reddit.com/r/rust/comments/3racik/mutable_lifetimes_are_too_long_when_matching_an/),
it was identified that the presence of the Entry API is not duly
publicised. This commit aims to add some reasonable examples of
common usages of this API to the main example secion of the `HashMap`
documentation.

This is part of issue rust-lang#29348.

src/libstd/collections/hash/map.rs

@@ -272,6 +272,35 @@ fn test_resize_policy() {
 /// }
 /// ```
 ///
+/// `HashMap` also implements an [`Entry API`](#method.entry), which allows
+/// for more complex methods of getting, setting, updating and removing keys and
+/// their values:
+///
+/// ```
+/// use std::collections::HashMap;
+///
+/// // type inference lets us omit an explicit type signature (which
+/// // would be `HashMap<&str, u8>` in this example).
+/// let mut player_stats = HashMap::new();
+///
+/// fn random_stat_buff() -> u8 {
+///   // could actually return some random value here - let's just return
+///   // some fixed value for now
+///   42
+/// }
+///
+/// // insert a key only if it doesn't already exist
+/// player_stats.entry("health").or_insert(100);
+///
+/// // insert a key using a function that provides a new value only if it
+/// // doesn't already exist
+/// player_stats.entry("defence").or_insert_with(random_stat_buff);
+///
+/// // update a key, guarding against the key possibly not being set
+/// let stat = player_stats.entry("attack").or_insert(100);
+/// *stat += random_stat_buff();
+/// ```
+///
 /// The easiest way to use `HashMap` with a custom type as key is to derive `Eq` and `Hash`.
 /// We must also derive `PartialEq`.
 ///