Further explain take_while

This is a behavior that some find confusing, so it deserves its own example.

Fixes #31318

diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs
index 3f1c0f6a5492a1cc8ff81ec1c4511873f3fbea76..65d1b96f81d1dd5171cb8803a5041419bc80634a 100644 (file)
--- a/src/libcore/iter.rs
+++ b/src/libcore/iter.rs
@@ -1050,6 +1050,30 @@ fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where
     /// // got a false, take_while() isn't used any more
     /// assert_eq!(iter.next(), None);
     /// ```
+    ///
+    /// Because `take_while()` needs to look at the value in order to see if it
+    /// should be included or not, consuming iterators will see that it is
+    /// removed:
+    ///
+    /// ```
+    /// let a = [1, 2, 3, 4];
+    /// let mut iter = a.into_iter();
+    ///
+    /// let result: Vec<i32> = iter.by_ref()
+    ///                            .take_while(|n| **n != 3)
+    ///                            .cloned()
+    ///                            .collect();
+    ///
+    /// assert_eq!(result, &[1, 2]);
+    ///
+    /// let result: Vec<i32> = iter.cloned().collect();
+    ///
+    /// assert_eq!(result, &[4]);
+    /// ```
+    ///
+    /// The `3` is no longer there, because it was consumed in order to see if
+    /// the iteration should stop, but wasn't placed back into the iterator or
+    /// some similar thing.
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where