Rollup merge of #31870 - ivan:filter-explain, r=steveklabnik

As a Rust newbie, I found the book's explanation for why the `filter` closure gets a reference very confusing, and tried to figure out why `filter` is somehow less consumptive than `map` -- but it isn't; that's controlled by `iter`/`into_iter`.  I flailed around for a while until @habnabit explained it to me, and in retrospect it is quite obvious :-)

1 files changed, 6 insertions, 4 deletions

diff --git a/src/doc/book/iterators.md b/src/doc/book/iterators.md
index 5622326d20c..0c4f8041266 100644
--- a/src/doc/book/iterators.md
+++ b/src/doc/book/iterators.md
@@ -311,10 +311,12 @@ for i in (1..100).filter(|&x| x % 2 == 0) {
 ```
 
 This will print all of the even numbers between one and a hundred.
-(Note that because `filter` doesn't consume the elements that are
-being iterated over, it is passed a reference to each element, and
-thus the filter predicate uses the `&x` pattern to extract the integer
-itself.)
+(Note that, unlike `map`, the closure passed to `filter` is passed a reference
+to the element instead of the element itself. The filter predicate here uses
+the `&x` pattern to extract the integer. The filter closure is passed a
+reference because it returns `true` or `false` instead of the element,
+so the `filter` implementation must retain ownership to put the elements
+into the newly constructed iterator.)
 
 You can chain all three things together: start with an iterator, adapt it
 a few times, and then consume the result. Check it out: