From ea6a6571758229382d3fcb3fcc9e273c9b854345 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Fri, 4 Aug 2017 08:21:28 -0400
Subject: [PATCH 1/3] Indicate why str::{get,get_mut} examples return None.

---
 src/liballoc/str.rs | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/liballoc/str.rs b/src/liballoc/str.rs
index 4df13c509a835..bbdc36b8737c0 100644
--- a/src/liballoc/str.rs
+++ b/src/liballoc/str.rs
@@ -328,11 +328,16 @@ impl str {
     /// # Examples
     ///
     /// ```
-    /// let v = "🗻∈🌏";
-    /// assert_eq!(Some("🗻"), v.get(0..4));
-    /// assert!(v.get(1..).is_none());
-    /// assert!(v.get(..8).is_none());
-    /// assert!(v.get(..42).is_none());
+    /// let mut v = String::from("🗻∈🌏");
+    ///
+    /// assert_eq!(Some("🗻"), v.get(0..4);
+    ///
+    /// // indices not on UTF-8 sequence boundaries
+    /// assert!(v.get_mut(1..).is_none());
+    /// assert!(v.get_mut(..8).is_none());
+    ///
+    /// // out of bounds
+    /// assert!(v.get_mut(..42).is_none());
     /// ```
     #[stable(feature = "str_checked_slicing", since = "1.20.0")]
     #[inline]
@@ -351,9 +356,14 @@ impl str {
     ///
     /// ```
     /// let mut v = String::from("🗻∈🌏");
+    ///
     /// assert_eq!(Some("🗻"), v.get_mut(0..4).map(|v| &*v));
+    ///
+    /// // indices not on UTF-8 sequence boundaries
     /// assert!(v.get_mut(1..).is_none());
     /// assert!(v.get_mut(..8).is_none());
+    ///
+    /// // out of bounds
     /// assert!(v.get_mut(..42).is_none());
     /// ```
     #[stable(feature = "str_checked_slicing", since = "1.20.0")]

From de4f1a170f96f7e99f28dda534a7b76010499587 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Fri, 4 Aug 2017 18:01:34 -0400
Subject: [PATCH 2/3] Update str::split_at_mut example to demonstrate
 mutability.

---
 src/liballoc/str.rs | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/liballoc/str.rs b/src/liballoc/str.rs
index bbdc36b8737c0..bf375ca0c43a8 100644
--- a/src/liballoc/str.rs
+++ b/src/liballoc/str.rs
@@ -330,7 +330,7 @@ impl str {
     /// ```
     /// let mut v = String::from("🗻∈🌏");
     ///
-    /// assert_eq!(Some("🗻"), v.get(0..4);
+    /// assert_eq!(Some("🗻"), v.get(0..4));
     ///
     /// // indices not on UTF-8 sequence boundaries
     /// assert!(v.get_mut(1..).is_none());
@@ -573,12 +573,16 @@ impl str {
     /// Basic usage:
     ///
     /// ```
-    /// let mut s = "Per Martin-Löf".to_string();
-    ///
-    /// let (first, last) = s.split_at_mut(3);
+    /// use std::ascii::AsciiExt;
     ///
-    /// assert_eq!("Per", first);
-    /// assert_eq!(" Martin-Löf", last);
+    /// let mut s = "Per Martin-Löf".to_string();
+    /// {
+    ///     let (first, last) = s.split_at_mut(3);
+    ///     first.make_ascii_uppercase();
+    ///     assert_eq!("PER", first);
+    ///     assert_eq!(" Martin-Löf", last);
+    /// }
+    /// assert_eq!("PER Martin-Löf", s);
     /// ```
     #[inline]
     #[stable(feature = "str_split_at", since = "1.4.0")]

From 6722185abdab8c5b83109a375e3fe14bd6aa8dc4 Mon Sep 17 00:00:00 2001
From: Corey Farwell <coreyf@rwell.org>
Date: Fri, 4 Aug 2017 23:08:29 -0400
Subject: [PATCH 3/3] Indicate how to turn byte slices back into a string
 slice.

---
 src/liballoc/str.rs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/liballoc/str.rs b/src/liballoc/str.rs
index bf375ca0c43a8..80317cd763b5c 100644
--- a/src/liballoc/str.rs
+++ b/src/liballoc/str.rs
@@ -273,7 +273,10 @@ impl str {
         core_str::StrExt::is_char_boundary(self, index)
     }
 
-    /// Converts a string slice to a byte slice.
+    /// Converts a string slice to a byte slice. To convert the byte slice back
+    /// into a string slice, use the [`str::from_utf8`] function.
+    ///
+    /// [`str::from_utf8`]: ./str/fn.from_utf8.html
     ///
     /// # Examples
     ///
@@ -289,7 +292,11 @@ impl str {
         core_str::StrExt::as_bytes(self)
     }
 
-    /// Converts a mutable string slice to a mutable byte slice.
+    /// Converts a mutable string slice to a mutable byte slice. To convert the
+    /// mutable byte slice back into a mutable string slice, use the
+    /// [`str::from_utf8_mut`] function.
+    ///
+    /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
     #[stable(feature = "str_mut_extras", since = "1.20.0")]
     #[inline(always)]
     pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {