Add basic usage example

1 files changed, 15 insertions, 0 deletions

diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs
index 416433e6b7d..d5e5b4ca16c 100644
--- a/library/core/src/iter/traits/iterator.rs
+++ b/library/core/src/iter/traits/iterator.rs
@@ -1535,6 +1535,21 @@ pub trait Iterator {
     ///
     /// # Examples
     ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// let mut words = vec!["hello", "world", "of", "Rust"].into_iter();
+    ///
+    /// // Take the first two words.
+    /// let hello_world: Vec<_> = words.by_ref().take(2).collect();
+    /// assert_eq!(hello_world, vec!["hello", "world"]);
+    ///
+    /// // Collect the rest of the words.
+    /// // We can only do this because we used `by_ref` earlier.
+    /// let of_rust: Vec<_> = words.collect();
+    /// assert_eq!(of_rust, vec!["of", "Rust"]);
+    /// ```
+    ///
     /// This demonstrates a use case that needs `by_ref`:
     ///
     /// ```compile_fail,E0382