Auto merge of #29498 - wthrowe:replace-pattern, r=alexcrichton

It appears this was left out of RFC rust-lang/rfcs#528 because it might be useful to
also generalize the second argument in some way.  That doesn't seem to
prevent generalizing the first argument now, however.

This is a [breaking-change] because it could cause type-inference to
fail where it previously succeeded.

Also update docs for a few other methods that still referred to `&str` instead of patterns.

diff --combined src/libcollections/str.rs
index 92c23ef2f38b828f8827754f21ddfd123b5c84e0,be2542dbdca6bda39e2307d1a402359de09ce1ce..f3bdb0efeef1d82bf72a2e92d76c4d2b43731a9c
--- 1/src/libcollections/str.rs
--- 2/src/libcollections/str.rs
+++ b/src/libcollections/str.rs
@@@ -305,7 -305,7 +305,7 @@@ impl str 
      /// satisifed:
      ///
      /// * `begin` must come before `end`.
 -    /// * `begin` and `end` must be bye positions within the string slice.
 +    /// * `begin` and `end` must be byte positions within the string slice.
      /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
      ///
      /// # Examples
@@@ -348,7 -348,7 +348,7 @@@
      /// satisifed:
      ///
      /// * `begin` must come before `end`.
 -    /// * `begin` and `end` must be bye positions within the string slice.
 +    /// * `begin` and `end` must be byte positions within the string slice.
      /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
      #[stable(feature = "str_slice_mut", since = "1.5.0")]
      #[inline]
@@@ -640,7 -640,7 +640,7 @@@
      /// Value, and may not match your idea of what a 'character' is. Iteration
      /// over grapheme clusters may be what you actually want.
      ///
 -    /// [`char`]: ../primitive.char.html
 +    /// [`char`]: primitive.char.html
      ///
      /// # Examples
      ///
@@@ -857,9 -857,10 +857,10 @@@
          Utf16Units { encoder: Utf16Encoder::new(self[..].chars()) }
      }
  
-     /// Returns `true` if the given `&str` is a sub-slice of this string slice.
+     /// Returns `true` if the given pattern matches a sub-slice of
+     /// this string slice.
      ///
-     /// Returns `false` if it's not.
+     /// Returns `false` if it does not.
      ///
      /// # Examples
      ///
@@@ -876,9 -877,10 +877,10 @@@
          core_str::StrExt::contains(self, pat)
      }
  
-     /// Returns `true` if the given `&str` is a prefix of this string slice.
+     /// Returns `true` if the given pattern matches a prefix of this
+     /// string slice.
      ///
-     /// Returns `false` if it's not.
+     /// Returns `false` if it does not.
      ///
      /// # Examples
      ///
@@@ -895,9 -897,10 +897,10 @@@
          core_str::StrExt::starts_with(self, pat)
      }
  
-     /// Returns `true` if the given `&str` is a suffix of this string slice.
+     /// Returns `true` if the given pattern matches a suffix of this
+     /// string slice.
      ///
-     /// Returns `false` if not.
+     /// Returns `false` if it does not.
      ///
      /// # Examples
      ///
@@@ -1551,7 -1554,7 +1554,7 @@@
      /// The pattern can be a `&str`, [`char`], or a closure that determines
      /// if a character matches.
      ///
 -    /// [`char`]: primtive.char.html
 +    /// [`char`]: primitive.char.html
      ///
      /// # Examples
      ///
@@@ -1643,7 -1646,7 +1646,7 @@@
      ///
      /// `parse()` can parse any type that implements the [`FromStr`] trait.
      ///
 -    /// [`FromStr`]: trait.FromStr.html
 +    /// [`FromStr`]: str/trait.FromStr.html
      ///
      /// # Failure
      ///
@@@ -1681,11 -1684,11 +1684,11 @@@
          core_str::StrExt::parse(self)
      }
  
-     /// Replaces all occurrences of one string with another.
+     /// Replaces all matches of a pattern with another string.
      ///
      /// `replace` creates a new [`String`], and copies the data from this string slice into it.
-     /// While doing so, it attempts to find a sub-`&str`. If it finds it, it replaces it with
-     /// the replacement string slice.
+     /// While doing so, it attempts to find matches of a pattern. If it finds any, it
+     /// replaces them with the replacement string slice.
      ///
      /// [`String`]: string/struct.String.html
      ///
@@@ -1699,14 -1702,14 +1702,14 @@@
      /// assert_eq!("this is new", s.replace("old", "new"));
      /// ```
      ///
-     /// When a `&str` isn't found:
+     /// When the pattern doesn't match:
      ///
      /// ```
      /// let s = "this is old";
      /// assert_eq!(s, s.replace("cookie monster", "little lamb"));
      /// ```
      #[stable(feature = "rust1", since = "1.0.0")]
-     pub fn replace(&self, from: &str, to: &str) -> String {
+     pub fn replace<'a, P: Pattern<'a>>(&'a self, from: P, to: &str) -> String {
          let mut result = String::new();
          let mut last_end = 0;
          for (start, part) in self.match_indices(from) {