Improve eagerly evaluating an iterator for its side-effects

[mattico]

0b_0101_001_1010 had a good idea on Reddit. I'll paraphrase it here.

The only way to eagerly consume an iterator, e.g., for its side-effects, on stable Rust is to call .collect or .count (.for_each is nightly only). Most beginners don't associate .count with this, so they use .collect, which is horrible.

There are a few things we could do to help make it more obvious what the correct thing to do is:

• make .collect's result #[must_use]. If you are throwing .collect's result away, you are doing it wrong, and should not have used .collect in the first place. A loop or .for_each would do.
• make .count's result #[must_use]: while .count is "efficent" (when compared to .collect) it doesn't convey what the code is actually doing
• add an .eval() == .for_each(|_|): because .for_each(|_|) is also ugly
• address this in docs: .collect means copy the results of the iterator into a collection, not "eagerly evaluate", or similar

[Mark-Simulacrum]

Making collect must_use seems reasonable. I don't think it'll be a common accident in practice, but might help beginners out -- for _ in iter {} seems reasonable enough for the edge case where you have a side-effect causing iterator. IMO, it's an antipattern for an iterator to cause side effects anyway...

[cuviper]

• add an .eval() == .for_each(|_|): because .for_each(|_|) is also ugly

I suspect that most of the time you might reach for this, there will probably be a .map(f) right before that can become .for_each(f) instead.

IMO, it's an antipattern for an iterator to cause side effects anyway...

It's not an antipattern for an iter_mut(), where the primary side effect is to update items.

Just a comment on naming... 🚲 🚲 🚲
I think .drain() would be more idiomatic than .eval().

[bluss]

.exhaust() is my favourite name (by @tbu-). On balance I think this method would be a win, although I am also hoping that .for_each will simply fill this role.

See also previous discussion in rust-itertools/itertools/pull/131

[tbu-]

I think we should have a dedicated name for this, even for_each(|_| ()) is a bit annoying to type, to just evaluate the iterator.

[dtolnay]

As of #45379 there is collect::<()>().

let mut sum = 0;
(0..10).map(|x| sum += x).collect::<()>();
println!("{}", sum);

It is slightly more handy than exhaust() because you get all the usual folding you get with FromIterator, such as running through a sequence of Results until the first failure if any.

use std::io::*;
let res: Result<()> = (0..10)
    .map(|x| writeln!(stdout(), "{}", x))
    .collect();
assert!(res.is_ok());

Does that address the request in this issue or do we feel that there is more room for improvement?

[tbu-]

I'd still say that it's annoying to type, compare collect::<()>() to exhaust().

[bluss]

And collect to unit is hard to discover, too, isn't it? (It is kind of automatically available if one calls collect(); maybe that would be the only intuitive entry.)

[dtolnay]

I would be prepared to consider a PR for Iterator::exhaust.