Elide clone operation when calling iter::Cloned::advance_{back}_by()

This is a change in user-visible behavior.

Author: the8472

library/core/src/iter/adapters/cloned.rs

@@ -60,6 +60,11 @@ where
         self.it.map(T::clone).fold(init, f)
     }
 
+    #[inline]
+    fn advance_by(&mut self, n: usize) -> Result<(), usize> {
+        self.it.advance_by(n)
+    }
+
     #[doc(hidden)]
     unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> T
     where
@@ -96,6 +101,11 @@ where
     {
         self.it.map(T::clone).rfold(init, f)
     }
+
+    #[inline]
+    fn advance_back_by(&mut self, n: usize) -> Result<(), usize> {
+        self.it.advance_back_by(n)
+    }
 }
 
 #[stable(feature = "iter_cloned", since = "1.1.0")]

library/core/src/iter/traits/double_ended.rs

@@ -107,8 +107,14 @@ pub trait DoubleEndedIterator: Iterator {
     /// outer iterator until it finds an inner iterator that is not empty, which then often
     /// allows it to return a more accurate `size_hint()` than in its initial state.
     ///
+    /// Implementations may elide side-effects such as calling closures or `clone` when they are
+    /// not necessary to determine by how many steps an iterator can be advanced. For example
+    /// [`Cloned::advance_back_by`] avoids unnecessary allocations by directly advancing its inner iterator
+    /// instead.
+    ///
     /// [`advance_by`]: Iterator::advance_by
     /// [`Flatten`]: crate::iter::Flatten
+    /// [`Cloned::advance_back_by`]: crate::iter::Cloned::advance_back_by
     /// [`next_back`]: DoubleEndedIterator::next_back
     ///
     /// # Examples

library/core/src/iter/traits/iterator.rs

@@ -250,7 +250,13 @@ pub trait Iterator {
     /// can advance its outer iterator until it finds an inner iterator that is not empty, which
     /// then often allows it to return a more accurate `size_hint()` than in its initial state.
     ///
+    /// Implementations may elide side-effects such as calling closures or `clone` when they are
+    /// not necessary to determine by how many steps an iterator can be advanced. For example
+    /// [`Cloned::advance_by`] avoids unnecessary allocations by directly advancing its inner iterator
+    /// instead.
+    ///
     /// [`Flatten`]: crate::iter::Flatten
+    /// [`Cloned::advance_by`]: crate::iter::Cloned::advance_by
     /// [`next`]: Iterator::next
     ///
     /// # Examples