30f9939a0c
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:
|
||
|---|---|---|
| .github | ||
| compiler | ||
| library | ||
| LICENSES | ||
| src | ||
| tests | ||
| .clang-format | ||
| .editorconfig | ||
| .git-blame-ignore-revs | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .ignore | ||
| .mailmap | ||
| bootstrap.example.toml | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CODE_OF_CONDUCT.md | ||
| configure | ||
| CONTRIBUTING.md | ||
| COPYRIGHT | ||
| INSTALL.md | ||
| LICENSE-APACHE | ||
| license-metadata.json | ||
| LICENSE-MIT | ||
| package.json | ||
| README.md | ||
| RELEASES.md | ||
| REUSE.toml | ||
| rust-bors.toml | ||
| rustfmt.toml | ||
| triagebot.toml | ||
| typos.toml | ||
| x | ||
| x.ps1 | ||
| x.py | ||
| yarn.lock | ||
This is the main source code repository for Rust. It contains the compiler, standard library, and documentation.
Why Rust?
-
Performance: Fast and memory-efficient, suitable for critical services, embedded devices, and easily integrated with other languages.
-
Reliability: Our rich type system and ownership model ensure memory and thread safety, reducing bugs at compile-time.
-
Productivity: Comprehensive documentation, a compiler committed to providing great diagnostics, and advanced tooling including package manager and build tool (Cargo), auto-formatter (rustfmt), linter (Clippy) and editor support (rust-analyzer).
Quick Start
Read "Installation" from The Book.
Installing from Source
If you really want to install from source (though this is not recommended), see INSTALL.md.
Getting Help
See https://www.rust-lang.org/community for a list of chat platforms and forums.
Contributing
See CONTRIBUTING.md.
License
Rust is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.
See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.
Trademark
The Rust Foundation owns and protects the Rust and Cargo trademarks and logos (the "Rust Trademarks").
If you want to use these names or brands, please read the Rust language trademark policy.
Third-party logos may be subject to third-party copyrights and trademarks. See Licenses for details.