@@ -1050,6 +1050,30 @@ pub trait Iterator {
10501050/// // got a false, take_while() isn't used any more
10511051/// assert_eq!(iter.next(), None);
10521052/// ```
1053+ ///
1054+ /// Because `take_while()` needs to look at the value in order to see if it
1055+ /// should be included or not, consuming iterators will see that it is
1056+ /// removed:
1057+ ///
1058+ /// ```
1059+ /// let a = [1, 2, 3, 4];
1060+ /// let mut iter = a.into_iter();
1061+ ///
1062+ /// let result: Vec<i32> = iter.by_ref()
1063+ /// .take_while(|n| **n != 3)
1064+ /// .cloned()
1065+ /// .collect();
1066+ ///
1067+ /// assert_eq!(result, &[1, 2]);
1068+ ///
1069+ /// let result: Vec<i32> = iter.cloned().collect();
1070+ ///
1071+ /// assert_eq!(result, &[4]);
1072+ /// ```
1073+ ///
1074+ /// The `3` is no longer there, because it was consumed in order to see if
1075+ /// the iteration should stop, but wasn't placed back into the iterator or
1076+ /// some similar thing.
10531077#[ inline]
10541078 #[ stable( feature = "rust1" , since = "1.0.0" ) ]
10551079 fn take_while < P > ( self , predicate : P ) -> TakeWhile < Self , P > where
@@ -3258,6 +3282,49 @@ impl<A, B> DoubleEndedIterator for Zip<A, B> where
32583282///
32593283/// [`map()`]: trait.Iterator.html#method.map
32603284/// [`Iterator`]: trait.Iterator.html
3285+ ///
3286+ /// # Notes about side effects
3287+ ///
3288+ /// The [`map()`] iterator implements [`DoubleEndedIterator`], meaning that
3289+ /// you can also [`map()`] backwards:
3290+ ///
3291+ /// ```rust
3292+ /// let v: Vec<i32> = vec![1, 2, 3].into_iter().rev().map(|x| x + 1).collect();
3293+ ///
3294+ /// assert_eq!(v, [4, 3, 2]);
3295+ /// ```
3296+ ///
3297+ /// [`DoubleEndedIterator`]: trait.DoubleEndedIterator.html
3298+ ///
3299+ /// But if your closure has state, iterating backwards may act in a way you do
3300+ /// not expect. Let's go through an example. First, in the forward direction:
3301+ ///
3302+ /// ```rust
3303+ /// let mut c = 0;
3304+ ///
3305+ /// for pair in vec!['a', 'b', 'c'].into_iter()
3306+ /// .map(|letter| { c += 1; (letter, c) }) {
3307+ /// println!("{:?}", pair);
3308+ /// }
3309+ /// ```
3310+ ///
3311+ /// This will print "('a', 1), ('b', 2), ('c', 3)".
3312+ ///
3313+ /// Now consider this twist where we add a call to `rev`. This version will
3314+ /// print `('c', 1), ('b', 2), ('a', 3)`. Note that the letters are reversed,
3315+ /// but the values of the counter still go in order. This is because `map()` is
3316+ /// still being called lazilly on each item, but we are popping items off the
3317+ /// back of the vector now, instead of shifting them from the front.
3318+ ///
3319+ /// ```rust
3320+ /// let mut c = 0;
3321+ ///
3322+ /// for pair in vec!['a', 'b', 'c'].into_iter()
3323+ /// .map(|letter| { c += 1; (letter, c) })
3324+ /// .rev() {
3325+ /// println!("{:?}", pair);
3326+ /// }
3327+ /// ```
32613328#[ must_use = "iterator adaptors are lazy and do nothing unless consumed" ]
32623329#[ stable( feature = "rust1" , since = "1.0.0" ) ]
32633330#[ derive( Clone ) ]
0 commit comments