@@ -937,20 +937,16 @@ pub trait Iterator {
937937 Enumerate :: new ( self )
938938 }
939939
940- /// Creates an iterator which can use [`peek`] to look at the next element of
941- /// the iterator without consuming it.
940+ /// Creates an iterator which can use the [`peek`] and [`peek_mut`] methods
941+ /// to look at the next element of the iterator without consuming it. See
942+ /// their documentation for more information.
942943///
943- /// Adds a [`peek`] method to an iterator. See its documentation for
944- /// more information.
944+ /// Note that the underlying iterator is still advanced when [`peek`] or
945+ /// [`peek_mut`] are called for the first time: In order to retrieve the
946+ /// next element, [`next`] is called on the underlying iterator, hence any
947+ /// side effects (i.e. anything other than fetching the next value) of
948+ /// the [`next`] method will occur.
945949///
946- /// Note that the underlying iterator is still advanced when [`peek`] is
947- /// called for the first time: In order to retrieve the next element,
948- /// [`next`] is called on the underlying iterator, hence any side effects (i.e.
949- /// anything other than fetching the next value) of the [`next`] method
950- /// will occur.
951- ///
952- /// [`peek`]: Peekable::peek
953- /// [`next`]: Iterator::next
954950///
955951/// # Examples
956952///
@@ -977,6 +973,32 @@ pub trait Iterator {
977973/// assert_eq!(iter.peek(), None);
978974/// assert_eq!(iter.next(), None);
979975/// ```
976+ ///
977+ /// Using [`peek_mut`] to mutate the next item without advancing the
978+ /// iterator:
979+ ///
980+ /// ```
981+ /// let xs = [1, 2, 3];
982+ ///
983+ /// let mut iter = xs.iter().peekable();
984+ ///
985+ /// // `peek_mut()` lets us see into the future
986+ /// assert_eq!(iter.peek_mut(), Some(&mut &1));
987+ /// assert_eq!(iter.peek_mut(), Some(&mut &1));
988+ /// assert_eq!(iter.next(), Some(&1));
989+ ///
990+ /// if let Some(mut p) = iter.peek_mut() {
991+ /// assert_eq!(*p, &2);
992+ /// // put a value into the iterator
993+ /// *p = &1000;
994+ /// }
995+ ///
996+ /// // The value reappears as the iterator continues
997+ /// assert_eq!(iter.collect::<Vec<_>>(), vec![&1000, &3]);
998+ /// ```
999+ /// [`peek`]: Peekable::peek
1000+ /// [`peek_mut`]: Peekable::peek_mut
1001+ /// [`next`]: Iterator::next
9801002#[ inline]
9811003 #[ stable( feature = "rust1" , since = "1.0.0" ) ]
9821004 fn peekable ( self ) -> Peekable < Self >
0 commit comments