stabilize `Peekable::next_if_map` (`#![feature(peekable_next_if_map)]`)
# Stabilization report
## Summary
`#![feature(peekable_next_if_map)]` is a variation of `next_if` on peekable iterators that can transform the peeked item. This creates a way to take ownership of the next item in an iterator when some condition holds, but put the item back when the condition doesn't hold. This pattern would otherwise have needed unwraps in many cases.
[Tracking issue](https://github.com/rust-lang/rust/issues/143702)
### What is stabilized
```rust
impl<I: Iterator> Peekable<I> {
pub fn next_if_map<R>(
&mut self,
f: impl FnOnce(I::Item) -> Result<R, I::Item>,
) -> Option<R> {
..
}
pub fn next_if_map_mut<R>(
&mut self,
f: impl FnOnce(&mut I::Item) -> Option<R>,
) -> Option<R> {
..
}
}
```
Example usage adapted from the ACP:
```rust
let mut it = Peekable::new("123".chars());
while let Some(digit) = it.next_if_map(|c| c.to_digit(10).ok_or(c)) {
codepoint = codepoint * 10 + digit;
}
```
or with `next_if_map_mut`:
```rust
let mut it = Peekable::new("123".chars());
while let Some(digit) = iter.next_if_map_mut(|c| c.to_digit(10)) {
line_num = line_num * 10 + digit;
}
```
Note that the major difference here is that `next_if_map_mut` does not get owned items from the iterator, but mutable references. With that api, the closure can return an `Option` which avoids an `ok_or`. This may require cloning or copying the iterator elements, so if that is expensive, the owned version, `next_if_map`, may be preferable.
### Nightly use
At the moment, this feature is barely used in nightly, though I've found multiple good uses for it in my own projects, hence my pushing for stabilization. It makes the kind of patterns used in recursive descent parsing super concise and maybe with its stabilization it will find more use.
### Test coverage
Besides a quite comprehensive doctest, this feature is tested (including panicking in the closure) here:
c880acdd31/library/coretests/tests/iter/adapters/peekable.rs (L275-L359)
## History
- ACP: https://github.com/rust-lang/libs-team/issues/613 accepted with https://github.com/rust-lang/libs-team/issues/613#issuecomment-3049844223
- implementation: https://github.com/rust-lang/rust/pull/143725 with tests, and no issues reported since july.
## Acknowledgments
ACP, implementation and tracking issue for this feature all by @kennytm <3
30f9939a0c