Rollup of 4 pull requests

src/libcore/marker.rs

@@ -709,6 +709,7 @@ unsafe impl<T: ?Sized> Freeze for &mut T {}
 /// So this, for example, can only be done on types implementing `Unpin`:
 ///
 /// ```rust
+/// # #![allow(unused_must_use)]
 /// use std::mem;
 /// use std::pin::Pin;
 ///

src/libcore/mem/mod.rs

@@ -808,6 +808,7 @@ pub fn take<T: Default>(dest: &mut T) -> T {
 /// [`Clone`]: ../../std/clone/trait.Clone.html
 #[inline]
 #[stable(feature = "rust1", since = "1.0.0")]
+#[must_use = "if you don't need the old value, you can just assign the new value directly"]
 pub fn replace<T>(dest: &mut T, mut src: T) -> T {
     swap(dest, &mut src);
     src

src/libcore/str/mod.rs

@@ -3010,6 +3010,12 @@ impl str {
     ///
     /// Returns `false` if it does not.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -3031,6 +3037,12 @@ impl str {
     ///
     /// Returns `false` if it does not.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -3051,6 +3063,12 @@ impl str {
     ///
     /// Returns `false` if it does not.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -3074,10 +3092,12 @@ impl str {
     ///
     /// Returns [`None`] if the pattern doesn't match.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
     ///
     /// [`None`]: option/enum.Option.html#variant.None
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Examples
     ///
@@ -3121,10 +3141,12 @@ impl str {
     ///
     /// Returns [`None`] if the pattern doesn't match.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
     ///
     /// [`None`]: option/enum.Option.html#variant.None
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Examples
     ///
@@ -3166,8 +3188,11 @@ impl str {
     /// An iterator over substrings of this string slice, separated by
     /// characters matched by a pattern.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3285,6 +3310,12 @@ impl str {
     /// `split` in that `split_inclusive` leaves the matched part as the
     /// terminator of the substring.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -3319,8 +3350,11 @@ impl str {
     /// An iterator over substrings of the given string slice, separated by
     /// characters matched by a pattern and yielded in reverse order.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3370,8 +3404,11 @@ impl str {
     /// An iterator over substrings of the given string slice, separated by
     /// characters matched by a pattern.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// Equivalent to [`split`], except that the trailing substring
     /// is skipped if empty.
@@ -3414,10 +3451,11 @@ impl str {
     /// An iterator over substrings of `self`, separated by characters
     /// matched by a pattern and yielded in reverse order.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
-    /// Additional libraries might provide more complex patterns like
-    /// regular expressions.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// Equivalent to [`split`], except that the trailing substring is
     /// skipped if empty.
@@ -3462,8 +3500,11 @@ impl str {
     /// If `n` substrings are returned, the last substring (the `n`th substring)
     /// will contain the remainder of the string.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3512,8 +3553,11 @@ impl str {
     /// If `n` substrings are returned, the last substring (the `n`th substring)
     /// will contain the remainder of the string.
     ///
-    /// The pattern can be any type that implements the Pattern trait. Notable
-    /// examples are `&str`, [`char`], and closures that determines the split.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3557,8 +3601,11 @@ impl str {
     /// An iterator over the disjoint matches of a pattern within the given string
     /// slice.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3593,8 +3640,11 @@ impl str {
     /// An iterator over the disjoint matches of a pattern within this string slice,
     /// yielded in reverse order.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3634,8 +3684,11 @@ impl str {
     /// For matches of `pat` within `self` that overlap, only the indices
     /// corresponding to the first match are returned.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines
-    /// if a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3676,8 +3729,11 @@ impl str {
     /// For matches of `pat` within `self` that overlap, only the indices
     /// corresponding to the last match are returned.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if a
-    /// character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Iterator behavior
     ///
@@ -3894,8 +3950,11 @@ impl str {
     /// Returns a string slice with all prefixes and suffixes that match a
     /// pattern repeatedly removed.
     ///
-    /// The pattern can be a [`char`] or a closure that determines if a
-    /// character matches.
+    /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
+    /// or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Examples
     ///
@@ -3939,8 +3998,11 @@ impl str {
     /// Returns a string slice with all prefixes that match a pattern
     /// repeatedly removed.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Text directionality
     ///
@@ -3981,6 +4043,12 @@ impl str {
     ///
     /// If the string does not start with `prefix`, `None` is returned.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -4005,6 +4073,12 @@ impl str {
     ///
     /// If the string does not end with `suffix`, `None` is returned.
     ///
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
+    ///
     /// # Examples
     ///
     /// ```
@@ -4027,8 +4101,11 @@ impl str {
     /// Returns a string slice with all suffixes that match a pattern
     /// repeatedly removed.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that
-    /// determines if a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
+    ///
+    /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Text directionality
     ///
@@ -4073,10 +4150,11 @@ impl str {
     /// Returns a string slice with all prefixes that match a pattern
     /// repeatedly removed.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that determines if
-    /// a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
     ///
     /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Text directionality
     ///
@@ -4109,10 +4187,11 @@ impl str {
     /// Returns a string slice with all suffixes that match a pattern
     /// repeatedly removed.
     ///
-    /// The pattern can be a `&str`, [`char`], or a closure that
-    /// determines if a character matches.
+    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
+    /// function or closure that determines if a character matches.
     ///
     /// [`char`]: primitive.char.html
+    /// [pattern]: str/pattern/index.html
     ///
     /// # Text directionality
     ///

src/libcore/str/pattern.rs

@@ -1,7 +1,41 @@
 //! The string Pattern API.
 //!
+//! The Pattern API provides a generic mechanism for using different pattern
+//! types when searching through a string.
+//!
 //! For more details, see the traits [`Pattern`], [`Searcher`],
 //! [`ReverseSearcher`], and [`DoubleEndedSearcher`].
+//!
+//! Although this API is unstable, it is exposed via stable APIs on the
+//! [`str`] type.
+//!
+//! # Examples
+//!
+//! [`Pattern`] is [implemented][pattern-impls] in the stable API for
+//! [`&str`], [`char`], slices of [`char`], and functions and closures
+//! implementing `FnMut(char) -> bool`.
+//!
+//! ```
+//! let s = "Can you find a needle in a haystack?";
+//!
+//! // &str pattern
+//! assert_eq!(s.find("you"), Some(4));
+//! // char pattern
+//! assert_eq!(s.find('n'), Some(2));
+//! // slice of chars pattern
+//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u'][..]), Some(1));
+//! // closure pattern
+//! assert_eq!(s.find(|c: char| c.is_ascii_punctuation()), Some(35));
+//! ```
+//!
+//! [`&str`]: ../../../std/primitive.str.html
+//! [`char`]: ../../../std/primitive.char.html
+//! [`str`]: ../../../std/primitive.str.html
+//! [`DoubleEndedSearcher`]: trait.DoubleEndedSearcher.html
+//! [`Pattern`]: trait.Pattern.html
+//! [`ReverseSearcher`]: trait.ReverseSearcher.html
+//! [`Searcher`]: trait.Searcher.html
+//! [pattern-impls]: trait.Pattern.html#implementors
 
 #![unstable(
     feature = "pattern",
@@ -702,7 +736,7 @@ unsafe impl<'a, 'b> ReverseSearcher<'a> for CharSliceSearcher<'a, 'b> {
 
 impl<'a, 'b> DoubleEndedSearcher<'a> for CharSliceSearcher<'a, 'b> {}
 
-/// Searches for chars that are equal to any of the chars in the array.
+/// Searches for chars that are equal to any of the chars in the slice.
 ///
 /// # Examples
 ///