///
/// # Examples
///
- /// Basic usage:
+ /// This demonstrates a use case that needs `by_ref`:
///
- /// ```
- /// let a = [1, 2, 3];
- ///
- /// let iter = a.iter();
- ///
- /// let sum: i32 = iter.take(5).fold(0, |acc, i| acc + i);
+ /// ```compile_fail,E0382
+ /// let a = [1, 2, 3, 4, 5];
+ /// let mut iter = a.iter();
+ /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i);
///
/// 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);
+ /// // Error! We can't use `iter` again because it was moved
+ /// // by `take`.
+ /// assert_eq!(iter.next(), Some(&4));
+ /// ```
///
- /// // let's try that again
- /// let a = [1, 2, 3];
+ /// Now, let's use `by_ref` to make this work:
///
+ /// ```
+ /// let a = [1, 2, 3, 4, 5];
/// let mut iter = a.iter();
+ /// // We add in a call to `by_ref` here so `iter` isn't moved.
+ /// let sum: i32 = iter.by_ref().take(3).fold(0, |acc, i| acc + i);
///
- /// // 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);
+ /// assert_eq!(sum, 6);
///
- /// // now this is just fine:
- /// assert_eq!(iter.next(), Some(&3));
- /// assert_eq!(iter.next(), None);
+ /// // And now we can use `iter` again because we still own it.
+ /// assert_eq!(iter.next(), Some(&4));
/// ```
#[stable(feature = "rust1", since = "1.0.0")]
fn by_ref(&mut self) -> &mut Self