Tracking issue for std::iter::Peekable::peek_mut

[lukaslueg]

Feature name: peekable_peek_mut

History:

• Implementation: Proposal to add Peekable::peek_mut #77491
• Stabilization: Stabilize peekable_peek_mut #81938

---

A "peekable" iterator has a peek()-method which provides an immutable reference to the next item. We currently do not have a method to modify that item, which we could easily add via a peek_mut(). A draft-implementation to add a new peek_mut-method is in #77491

A peek_mut would allow one to peek into the very next item the iterator will return and change it if so desired (essentially a single-shot .map()):

let xs = vec![1, 2, 3];
let mut it = xs.into_iter().peekable();
if let Some(ref mut p) = it.peek_mut() {
    if **p == 1 {
        **p = 5;
    }
}
assert_eq!(it.collect::<Vec<_>>(), vec![5, 2, 3]);