///
/// let mut iter = xs.iter().peekable();
///
- /// // peek_mut() lets us see into the future
+ /// // `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));
/// [`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 mut words = vec!["hello", "world", "of", "Rust"].into_iter();
///
- /// let sum: i32 = iter.take(5).fold(0, |acc, i| acc + i);
+ /// // Take the first two words.
+ /// let hello_world: Vec<_> = words.by_ref().take(2).collect();
+ /// assert_eq!(hello_world, vec!["hello", "world"]);
///
- /// assert_eq!(sum, 6);
- ///
- /// // 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);
- ///
- /// // 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