From f7558991adcdf15f1cb1093810c8b05894b12dd3 Mon Sep 17 00:00:00 2001 From: Camelid Date: Thu, 7 Jan 2021 17:29:27 -0800 Subject: [PATCH 1/4] Improve `Iterator::by_ref` example I split the example into two: one that fails to compile, and one that works. I also made them identical except for the addition of `by_ref` so we don't confuse readers with random differences. --- library/core/src/iter/traits/iterator.rs | 36 +++++++++++------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 0023de65d2b3b..7affe0c2000da 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1535,34 +1535,32 @@ pub trait Iterator { /// /// # Examples /// - /// Basic usage: + /// This demonstrates a use case that needs `by_ref`: /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let iter = a.iter(); - /// - /// let sum: i32 = iter.take(5).fold(0, |acc, i| acc + i); + /// ```compile_fail,E0382 + /// let a = [1, 2, 3, 4, 5]; + /// let mut iter = a.iter(); + /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i); /// /// assert_eq!(sum, 6); /// - /// // if we try to use iter again, it won't work. The following line - /// // gives "error: use of moved value: `iter` - /// // assert_eq!(iter.next(), None); + /// // Error! We can't use `iter` again because it was moved + /// // by `take`. + /// assert_eq!(iter.next(), Some(&4)); + /// ``` /// - /// // let's try that again - /// let a = [1, 2, 3]; + /// Now, let's use `by_ref` to make this work: /// + /// ``` + /// let a = [1, 2, 3, 4, 5]; /// let mut iter = a.iter(); + /// // We add in a call to `by_ref` here so `iter` isn't moved. + /// let sum: i32 = iter.by_ref().take(3).fold(0, |acc, i| acc + i); /// - /// // instead, we add in a .by_ref() - /// let sum: i32 = iter.by_ref().take(2).fold(0, |acc, i| acc + i); - /// - /// assert_eq!(sum, 3); + /// assert_eq!(sum, 6); /// - /// // now this is just fine: - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.next(), None); + /// // And now we can use `iter` again because we still own it. + /// assert_eq!(iter.next(), Some(&4)); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn by_ref(&mut self) -> &mut Self From bfb027965334e168b50cf5a8940e8f6c671caba4 Mon Sep 17 00:00:00 2001 From: Camelid Date: Sun, 7 Feb 2021 19:47:38 -0800 Subject: [PATCH 2/4] Better line grouping --- library/core/src/iter/traits/iterator.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 7affe0c2000da..416433e6b7d96 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1540,8 +1540,8 @@ pub trait Iterator { /// ```compile_fail,E0382 /// let a = [1, 2, 3, 4, 5]; /// let mut iter = a.iter(); - /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i); /// + /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i); /// assert_eq!(sum, 6); /// /// // Error! We can't use `iter` again because it was moved @@ -1554,9 +1554,9 @@ pub trait Iterator { /// ``` /// let a = [1, 2, 3, 4, 5]; /// let mut iter = a.iter(); + /// /// // We add in a call to `by_ref` here so `iter` isn't moved. /// let sum: i32 = iter.by_ref().take(3).fold(0, |acc, i| acc + i); - /// /// assert_eq!(sum, 6); /// /// // And now we can use `iter` again because we still own it. From c1df9f1b6b59733ff94f2b74e943ab669c06c67d Mon Sep 17 00:00:00 2001 From: Camelid Date: Sat, 13 Feb 2021 21:25:41 -0800 Subject: [PATCH 3/4] Add basic usage example --- library/core/src/iter/traits/iterator.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 416433e6b7d96..d5e5b4ca16c1b 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 From 49ccc3f320a4728b80f393d8a60fa4466f8a4c0c Mon Sep 17 00:00:00 2001 From: Camelid Date: Sat, 20 Mar 2021 14:09:38 -0700 Subject: [PATCH 4/4] Remove redundant second example --- library/core/src/iter/traits/iterator.rs | 28 ------------------------ 1 file changed, 28 deletions(-) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index d5e5b4ca16c1b..6d211d7795210 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1549,34 +1549,6 @@ pub trait Iterator { /// 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 - /// let a = [1, 2, 3, 4, 5]; - /// let mut iter = a.iter(); - /// - /// let sum: i32 = iter.take(3).fold(0, |acc, i| acc + i); - /// assert_eq!(sum, 6); - /// - /// // Error! We can't use `iter` again because it was moved - /// // by `take`. - /// assert_eq!(iter.next(), Some(&4)); - /// ``` - /// - /// Now, let's use `by_ref` to make this work: - /// - /// ``` - /// let a = [1, 2, 3, 4, 5]; - /// let mut iter = a.iter(); - /// - /// // We add in a call to `by_ref` here so `iter` isn't moved. - /// let sum: i32 = iter.by_ref().take(3).fold(0, |acc, i| acc + i); - /// assert_eq!(sum, 6); - /// - /// // And now we can use `iter` again because we still own it. - /// assert_eq!(iter.next(), Some(&4)); - /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn by_ref(&mut self) -> &mut Self where