Rollup merge of rust-lang#72626 - phimuemue:doubleendediter_doc, r=dtolnay

Add remark regarding DoubleEndedIterator

While reviewing rust-itertools/itertools@14293bd#diff-2c16d2ada06ad2fd1fc754679646d471, I realized that a `DoubleEndedIterator` may yield different elements depending on whether it is traversed forwards or backwards. (Not only the *order*, but possibly also the yielded values.)

I found this remarkable, but could not find anything in the current docs, so I thought it may be worth mentioning this explicitly.

Unfortunately, I could not test these changes locally (`rustdoc` complains about `unresolved import`). Sorry if this causes headache.

If I should change something, please let me know. If it seems too trivial, feel free to just close this PR.

Author: Dylan-DPC

src/libcore/iter/traits/double_ended.rs

@@ -63,6 +63,32 @@ pub trait DoubleEndedIterator: Iterator {
     /// assert_eq!(None, iter.next());
     /// assert_eq!(None, iter.next_back());
     /// ```
+    ///
+    /// # Remarks
+    ///
+    /// The elements yielded by `DoubleEndedIterator`'s methods may differ from
+    /// the ones yielded by `Iterator`'s methods:
+    ///
+    /// ```
+    /// let vec = vec![(1, 'a'), (1, 'b'), (1, 'c'), (2, 'a'), (2, 'b')];
+    /// let uniq_by_fst_comp = || {
+    ///     let mut seen = std::collections::HashSet::new();
+    ///     vec.iter().copied().filter(move |x| seen.insert(x.0))
+    /// };
+    ///
+    /// assert_eq!(uniq_by_fst_comp().last(), Some((2, 'a')));
+    /// assert_eq!(uniq_by_fst_comp().next_back(), Some((2, 'b')));
+    ///
+    /// assert_eq!(
+    ///     uniq_by_fst_comp().fold(vec![], |mut v, x| {v.push(x); v}),
+    ///     vec![(1, 'a'), (2, 'a')]
+    /// );
+    /// assert_eq!(
+    ///     uniq_by_fst_comp().rfold(vec![], |mut v, x| {v.push(x); v}),
+    ///     vec![(2, 'b'), (1, 'c')]
+    /// );
+    /// ```
+    ///
     #[stable(feature = "rust1", since = "1.0.0")]
     fn next_back(&mut self) -> Option<Self::Item>;