From: Lukas Lueg <lukas.lueg@gmail.com>
Date: Wed, 13 Jan 2021 20:07:59 +0000 (+0100)
Subject: Improve Iterator::intersperse_ docs
X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=9b2f085110c70a8ae92a47ce0c510db82f759992;p=rust.git

Improve Iterator::intersperse_ docs
---

diff --git a/library/core/src/iter/adapters/intersperse.rs b/library/core/src/iter/adapters/intersperse.rs
index 25115beb851..1d01e9b5fb7 100644
--- a/library/core/src/iter/adapters/intersperse.rs
+++ b/library/core/src/iter/adapters/intersperse.rs
@@ -2,7 +2,7 @@
 
 /// An iterator adapter that places a separator between all elements.
 ///
-/// This `struct` is created by [`Iterator::intersperse`]. See it's documentation
+/// This `struct` is created by [`Iterator::intersperse`]. See its documentation
 /// for more information.
 #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
 #[derive(Debug, Clone)]
@@ -59,7 +59,7 @@ fn size_hint(&self) -> (usize, Option<usize>) {
 
 /// An iterator adapter that places a separator between all elements.
 ///
-/// This `struct` is created by [`Iterator::intersperse_with`]. See it's
+/// This `struct` is created by [`Iterator::intersperse_with`]. See its
 /// documentation for more information.
 #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
 pub struct IntersperseWith<I, G>
diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
index 91d7a47907a..732d465fcae 100644
--- a/library/core/src/iter/traits/iterator.rs
+++ b/library/core/src/iter/traits/iterator.rs
@@ -571,6 +571,9 @@ fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
 
     /// Places a copy of `separator` between all elements.
     ///
+    /// In case the separator does not implement [`Clone`] or needs to be
+    /// computed every time, use [`intersperse_with`].
+    ///
     /// # Examples
     ///
     /// Basic usage:
@@ -578,9 +581,12 @@ fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter>
     /// ```
     /// #![feature(iter_intersperse)]
     ///
-    /// let hello = ["Hello", "World"].iter().copied().intersperse(" ").collect::<String>();
-    /// assert_eq!(hello, "Hello World");
+    /// let hello = ["Hello", "World", "!"].iter().copied().intersperse(" ").collect::<String>();
+    /// assert_eq!(hello, "Hello World !");
     /// ```
+    ///
+    /// [`Clone`]: crate::clone::Clone
+    /// [`intersperse_with`]: Iterator::intersperse_with
     #[inline]
     #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
     fn intersperse(self, separator: Self::Item) -> Intersperse<Self>
@@ -600,11 +606,13 @@ fn intersperse(self, separator: Self::Item) -> Intersperse<Self>
     /// ```
     /// #![feature(iter_intersperse)]
     ///
-    /// let src = ["Hello", "to", "all", "people"].iter().copied();
-    /// let mut separator = [" ❤️ ", " 😀 "].iter().copied().cycle();
+    /// let src = ["Hello", "to", "all", "people", "!!"].iter().copied();
+    ///
+    /// let mut happy_emojis = [" ❤️ ", " 😀 "].iter().copied();
+    /// let separator = || happy_emojis.next().unwrap_or(" 🦀 ");
     ///
-    /// let result = src.intersperse_with(|| separator.next().unwrap()).collect::<String>();
-    /// assert_eq!(result, "Hello ❤️ to 😀 all ❤️ people");
+    /// let result = src.intersperse_with(separator).collect::<String>();
+    /// assert_eq!(result, "Hello ❤️ to 😀 all 🦀 people 🦀 !!");
     /// ```
     #[inline]
     #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]