Add Iterator::exhaust

[varkor]

This adds an Iterator::exhaust method for evaluating the side effects of an iterator conveniently. There are already ways to do this simply, but a little uglily (e.g. iter.for_each(|_| ()) or iter.collect::<()>()) and it was proposed in #44546 that it'd be nicer to have a dedicated (and discoverable) method to do this.

Closes #44546.

r? @dtolnay

[rust-highfive]

Your PR failed on Travis (raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

Resolving deltas: 100% (615875/615875), completed with 4899 local objects.
---
[00:00:41] configure: rust.quiet-tests     := True
---
[00:45:07] .................................................................................i..................
[00:45:13] ........................i...........................................................................
---
[00:45:54] ........................i..........................................................................i
[00:46:00] ....................................................................................................
[00:46:06] .............ii.....................................................................................
---
[00:46:51] .............................................i......................................................
---
[00:50:42] ..............................i.....................................................................
[00:50:56] ...............................................................i....................................
[00:51:11] .................................................i..................................................
[00:51:31] ....................................................................................................
[00:51:52] ....................................................................................................
[00:52:13] ....................................................................................................
[00:52:37] .......i............................................................................................
[00:53:06] ...i....................................................................................test [run-pass] run-pass/mir_heavy_promoted.rs has been running for over 60 seconds
[00:53:12] ............
[00:53:44] ....................................................................................................
[00:54:15] .....................................................................ii.............................
[00:55:06] ................................i....................................................i.ii....test [run-pass] run-pass/saturating-float-casts.rs has been running for over 60 seconds
[00:55:09] .......
[00:55:51] .............................................................................................iiiiiii
---
[00:58:02] ...................i............................................................ii.iii..............
[00:58:09] ....................................................................................................
[00:58:17] ........i..............................i............................................................
[00:58:24] ....................................................................................................
[00:58:31] ..........i.........................................................................................
[00:58:39] ....................................................................................................
[00:58:48] ....................................................................................................
[00:58:58] ....................................................................................................
[00:59:08] ....................................................................................................
[00:59:22] ....................................................................................................
[00:59:30] ...i................................................................................................
[00:59:39] .......i..ii........................................................................................
[00:59:49] ....................................................................................................
[00:59:58] ....................................................................................................
[01:00:07] .........................................................................i..........................
[01:00:17] ...................i................................................................................
---
[01:00:50] ...........................i........................................................................
[01:00:51] ....................................................................i...............................
[01:00:52] ................i.......................................................
---
[01:01:07] .............i........................
---
[01:01:36] i...i..ii....i.............ii.........iii......i..i...i...ii..i..i..ii.....
---
[01:01:39] i.......i......................i.......
---
[01:02:17] iiii.......i..i........i..i.i.............i..........iiii...........i...i..........ii.i.i.......ii..
[01:02:18] ....ii...
---
[01:10:08] ..................i.................................................................................
[01:11:41] .......i............................................................................................
---
[01:13:38] .....................................i..............................................................
[01:13:58] ....................................................................................................
[01:14:19] ..........................................i.........................................................
---
[01:15:48] .........................................................ii.........................................
---
[01:16:50] ......................................................F.............................................
[01:17:08] ......................i.............................................................................
---
[01:20:33] ---- iter/iterator.rs - iter::iterator::Iterator::exhaust (line 2264) stdout ----
[01:20:33]  error[E0689]: can't call method `map` on ambiguous numeric type `{integer}`
[01:20:33]  --> iter/iterator.rs:2266:26
[01:20:33]   |
[01:20:33] 5 | let count_aloud = 1..=10.map(|x| println!("{}", x));
[01:20:33]   |                          ^^^
[01:20:33] help: you must specify a concrete type for this numeric value, like `i32`
[01:20:33]   |
[01:20:33] 5 | let count_aloud = 1..=10_i32.map(|x| println!("{}", x));
[01:20:33]   |                       ^^^^^^
[01:20:33]
[01:20:33] error[E0658]: use of unstable library feature 'iter_exhaust' (see issue #44546)
[01:20:33]   --> iter/iterator.rs:2271:13
[01:20:33]    |
[01:20:33] 10 | count_aloud.exhaust();
[01:20:33]    |             ^^^^^^^
[01:20:33]    |
[01:20:33]    = help: add #![feature(iter_exhaust)] to the crate attributes to enable
[01:20:33]
[01:20:33] thread 'iter/iterator.rs - iter::iterator::Iterator::exhaust (line 2264)' panicked at 'couldn't compile the test', librustdoc/test.rs:318:13
[01:20:33] note: Run with `RUST_BACKTRACE=1` for a backtrace.
[01:20:33]
[01:20:33]
[01:20:33] failures:
[01:20:33]     iter/iterator.rs - iter::iterator::Iterator::exhaust (line 2264)
---
[01:20:33] command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "test" "--target" "x86_64-unknown-linux-gnu" "--release" "--locked" "--color" "always" "--features" "panic-unwind jemalloc backtrace" "--manifest-path" "/checkout/src/libstd/Cargo.toml" "-p" "core" "--" "--quiet"
[01:20:33] expected success, got: exit code: 101
[01:20:33]
[01:20:33]
[01:20:33] failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test
[01:20:33] Build completed unsuccessfully in 0:36:42
[01:20:33] make: *** [check] Error 1
[01:20:33] Makefile:58: recipe for target 'check' failed
---
$ dmesg | grep -i kill
[   10.988691] init: failsafe main process (1093) killed by TERM signal

I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact @TimNN. (Feature Requests)

[sfackler]

I think this is what #48945 originally proposed.

[varkor]

@sfackler: oh, I hadn't seen that! #44546 should probably be closed with a reference to that, then.

[cuviper]

This should use for_each to get internal iteration, rather than (implicit) next() calls.

[varkor]

It doesn't matter so much now the PR's closed, but out of curiosity, what difference in behaviour would using for_each have?

[cuviper]

The difference is that some iterators can apply a fold much more efficiently than they can next one item at a time. For instance, Chain::fold can fold its first part as a whole, then its second part as a whole, but Chain::next has to check whether it's on the first or second part every time. This is demonstrated in the benchmarks added to the for_each PR, #42782, in commit 4a8ddac.

[varkor]

Ah, of course, that makes a lot of sense. Thanks for explaining!