diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 91c3a4b29b539..4fa0007bd2415 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1825,10 +1825,20 @@ pub trait Iterator { Inspect::new(self, f) } - /// Borrows an iterator, rather than consuming it. + /// Iterator adapter that turns ownership-taking methods into mutating methods. /// - /// This is useful to allow applying iterator adapters while still - /// retaining ownership of the original iterator. + /// Most `Iterator` methods, other than the `next` method (and this one), + /// take ownership (via a `self` parameter) of the iterator and then mutate it. + /// This method retuns a mutable reference to the original iterator, + /// that acts like the original iterator in all respects, + /// except that ownership-taking methods take ownership of the reference instead of of the original. + /// All mutation by ownership-taking methods will still mutate the original iterator. + /// + /// # Technical details + /// + /// The mutable reference that this method returns, implements the `Iterator` trait via: + /// [impl Iterator for &mut I { type Item = I::Item; ...}](https://doc.rust-lang.org/nightly/std/iter/trait.Iterator.html#impl-Iterator-for-%26mut+I). + /// This implementation simply passes all method calls on to the original iterator. /// /// # Examples /// @@ -4019,6 +4029,7 @@ where } } +/// Implements `Iterator` for mutable references to iterators, such as those produced by [`Iterator::by_ref`]. #[stable(feature = "rust1", since = "1.0.0")] impl Iterator for &mut I { type Item = I::Item;