Enumerate::new(self)
}
- /// Creates an iterator which can use [`peek`] to look at the next element of
- /// the iterator without consuming it.
+ /// Creates an iterator which can use the [`peek`] and [`peek_mut`] methods
+ /// to look at the next element of the iterator without consuming it. See
+ /// their documentation for more information.
///
- /// Adds a [`peek`] method to an iterator. See its documentation for
- /// more information.
+ /// Note that the underlying iterator is still advanced when [`peek`] or
+ /// [`peek_mut`] are called for the first time: In order to retrieve the
+ /// next element, [`next`] is called on the underlying iterator, hence any
+ /// side effects (i.e. anything other than fetching the next value) of
+ /// the [`next`] method will occur.
///
- /// Note that the underlying iterator is still advanced when [`peek`] is
- /// called for the first time: In order to retrieve the next element,
- /// [`next`] is called on the underlying iterator, hence any side effects (i.e.
- /// anything other than fetching the next value) of the [`next`] method
- /// will occur.
- ///
- /// [`peek`]: Peekable::peek
- /// [`next`]: Iterator::next
///
/// # Examples
///
/// assert_eq!(iter.peek(), None);
/// assert_eq!(iter.next(), None);
/// ```
+ ///
+ /// Using [`peek_mut`] to mutate the next item without advancing the
+ /// iterator:
+ ///
+ /// ```
+ /// let xs = [1, 2, 3];
+ ///
+ /// let mut iter = xs.iter().peekable();
+ ///
+ /// // `peek_mut()` lets us see into the future
+ /// assert_eq!(iter.peek_mut(), Some(&mut &1));
+ /// assert_eq!(iter.peek_mut(), Some(&mut &1));
+ /// assert_eq!(iter.next(), Some(&1));
+ ///
+ /// if let Some(mut p) = iter.peek_mut() {
+ /// assert_eq!(*p, &2);
+ /// // put a value into the iterator
+ /// *p = &1000;
+ /// }
+ ///
+ /// // The value reappears as the iterator continues
+ /// assert_eq!(iter.collect::<Vec<_>>(), vec![&1000, &3]);
+ /// ```
+ /// [`peek`]: Peekable::peek
+ /// [`peek_mut`]: Peekable::peek_mut
+ /// [`next`]: Iterator::next
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
fn peekable(self) -> Peekable<Self>
/// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a
/// [`None`] is given, it will always return [`None`] forever.
///
+ /// Note that the [`Fuse`] wrapper is a no-op on iterators that implement
+ /// the [`FusedIterator`] trait. `fuse()` may therefore behave incorrectly
+ /// if the [`FusedIterator`] trait is improperly implemented.
+ ///
/// [`Some(T)`]: Some
+ /// [`FusedIterator`]: crate::iter::FusedIterator
///
/// # Examples
///
/// Basic usage:
///
/// ```
- /// let a = [1, 2, 3];
- ///
- /// let iter = a.iter();
- ///
- /// let sum: i32 = iter.take(5).fold(0, |acc, i| acc + i);
- ///
- /// assert_eq!(sum, 6);
+ /// let mut words = vec!["hello", "world", "of", "Rust"].into_iter();
///
- /// // if we try to use iter again, it won't work. The following line
- /// // gives "error: use of moved value: `iter`
- /// // assert_eq!(iter.next(), None);
+ /// // Take the first two words.
+ /// let hello_world: Vec<_> = words.by_ref().take(2).collect();
+ /// assert_eq!(hello_world, vec!["hello", "world"]);
///
- /// // let's try that again
- /// let a = [1, 2, 3];
- ///
- /// let mut iter = a.iter();
- ///
- /// // instead, we add in a .by_ref()
- /// let sum: i32 = iter.by_ref().take(2).fold(0, |acc, i| acc + i);
- ///
- /// assert_eq!(sum, 3);
- ///
- /// // now this is just fine:
- /// assert_eq!(iter.next(), Some(&3));
- /// assert_eq!(iter.next(), None);
+ /// // Collect the rest of the words.
+ /// // We can only do this because we used `by_ref` earlier.
+ /// let of_rust: Vec<_> = words.collect();
+ /// assert_eq!(of_rust, vec!["of", "Rust"]);
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn by_ref(&mut self) -> &mut Self