squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

Improve the documentation of filter() and filter_map().

Browse source 
I believe the documentation is currently a little misleading.

For example, in the docs for `filter()`:

> If the closure returns `false`, it will try again, and call the closure on
> the next element, seeing if it passes the test.

This kind of implies that if the closure returns true then we *don't* "try
again" and no further elements are considered. In actuality that's not the
case, every element is tried regardless of what happened with the previous
element.

This change tries to clarify that by removing the uses of "try again"
altogether.
This commit is contained in:
Edd Barrett 2020-08-26 17:39:43 +01:00
parent 7d289aeade
commit 8af85fa1f7
1 changed files with 8 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
library/core/src/iter/traits/iterator.rs
View file

@ -648,11 +648,9 @@ pub trait Iterator {
/// Creates an iterator which uses a closure to determine if an element
/// should be yielded.
///
/// The closure must return `true` or `false`. `filter()` creates an
/// iterator which calls this closure on each element. If the closure
/// returns `true`, then the element is returned. If the closure returns
/// `false`, it will try again, and call the closure on the next element,
/// seeing if it passes the test.
/// Given an element the closure must return `true` or `false`. The returned
/// iterator will yield only the elements for which the closure returns
/// true.
///
/// # Examples
///
@ -719,24 +717,16 @@ pub trait Iterator {
/// Creates an iterator that both filters and maps.
///
/// The closure must return an [`Option<T>`]. `filter_map` creates an
/// iterator which calls this closure on each element. If the closure
/// returns [`Some(element)`][`Some`], then that element is returned. If the
/// closure returns [`None`], it will try again, and call the closure on the
/// next element, seeing if it will return [`Some`].
/// The returned iterator yields only the `value`s for which the supplied
/// closure returns `Some(value)`.
///
/// Why `filter_map` and not just [`filter`] and [`map`]? The key is in this
/// part:
/// `filter_map` can be used to make chains of [`filter`] and [`map`] more
/// concise. The example below shows how a `map().filter().map()` can be
/// shortened to a single call to `filter_map`.
///
/// [`filter`]: Iterator::filter
/// [`map`]: Iterator::map
///
/// > If the closure returns [`Some(element)`][`Some`], then that element is returned.
///
/// In other words, it removes the [`Option<T>`] layer automatically. If your
/// mapping is already returning an [`Option<T>`] and you want to skip over
/// [`None`]s, then `filter_map` is much, much nicer to use.
///
/// # Examples
///
/// Basic usage: