From 1dd207c10f90f490da9396e06228916279c3be7f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gunnlaugur=20=C3=9E=C3=B3r=20Briem?= Date: Thu, 14 Jul 2022 14:41:22 +0000 Subject: [PATCH 1/2] doc: clearer and more correct Iterator::scan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The `Iterator::scan` documentation seemed a little misleading to my newcomer eyes, and this tries to address that. * I found “similar to `fold`” unhelpful because (a) the similarity is only that they maintain state between iterations, and (b) the _dissimilarity_ is no less important: one returns a final value and the other an iterator. So this replaces that with “which, like `fold`, holds internal state, but unlike `fold`, produces a new iterator. * I found “the return value from the closure, an [`Option`], is yielded by the iterator” to be downright incorrect, because “yielded by the iterator” means “returned by the `next` method wrapped in `Some`”, so this implied that `scan` would convert an input iterator of `T` to an output iterator of `Option`. So this replaces “yielded by the iterator” with “returned by the `next` method” and elaborates: “Thus the closure can return `Some(value)` to yield `value`, or `None` to end the iteration.” * This also changes the example to illustrate the latter point by returning `None` to terminate the iteration early based on `state`. --- library/core/src/iter/traits/iterator.rs | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 275412b57b55f..3e9521713aace 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1380,8 +1380,8 @@ pub trait Iterator { Take::new(self, n) } - /// An iterator adapter similar to [`fold`] that holds internal state and - /// produces a new iterator. + /// An iterator adapter which, like [`fold`], holds internal state, but + /// unlike [`fold`], produces a new iterator. /// /// [`fold`]: Iterator::fold /// @@ -1393,20 +1393,25 @@ pub trait Iterator { /// /// On iteration, the closure will be applied to each element of the /// iterator and the return value from the closure, an [`Option`], is - /// yielded by the iterator. + /// returned by the `next` method. Thus the closure can return + /// `Some(value)` to yield `value`, or `None` to end the iteration. /// /// # Examples /// /// Basic usage: /// /// ``` - /// let a = [1, 2, 3]; + /// let a = [1, 2, 3, 4]; /// /// let mut iter = a.iter().scan(1, |state, &x| { - /// // each iteration, we'll multiply the state by the element + /// // each iteration, we'll multiply the state by the element ... /// *state = *state * x; /// - /// // then, we'll yield the negation of the state + /// // ... and terminate if the state exceeds 6 + /// if (*state > 6) { + /// return None; + /// } + /// // ... else yield the negation of the state /// Some(-*state) /// }); /// From 588592b78b7a5cc64679b2164f794e79c444d766 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gunnlaugur=20=C3=9E=C3=B3r=20Briem?= Date: Thu, 14 Jul 2022 17:06:01 +0000 Subject: [PATCH 2/2] lint: remove unnecessary parentheses --- library/core/src/iter/traits/iterator.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs index 3e9521713aace..d2347598dd1a7 100644 --- a/library/core/src/iter/traits/iterator.rs +++ b/library/core/src/iter/traits/iterator.rs @@ -1408,7 +1408,7 @@ pub trait Iterator { /// *state = *state * x; /// /// // ... and terminate if the state exceeds 6 - /// if (*state > 6) { + /// if *state > 6 { /// return None; /// } /// // ... else yield the negation of the state