From b60fe399f3148c4af4ea568b262211661cab37ab Mon Sep 17 00:00:00 2001
From: philipp <descpl@yahoo.de>
Date: Tue, 26 May 2020 21:38:44 +0200
Subject: [PATCH] Add remark regarding DoubleEndedIterator

---
 src/libcore/iter/traits/double_ended.rs | 26 +++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/src/libcore/iter/traits/double_ended.rs b/src/libcore/iter/traits/double_ended.rs
index cceb373d552a8..f6329c6c593ed 100644
--- a/src/libcore/iter/traits/double_ended.rs
+++ b/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>;