Tracking Issue for `PeekableIterator`

Feature gate: #![feature(peekable_iterator)]

This is a tracking issue for the PeekableIterator trait, which extends Iterator with peek_with and related methods that inspect the next element without consuming it.

Public API

// core::iter

pub trait PeekableIterator: Iterator {
  // required method
  fn peek_with<T>(&mut self, func: impl for<'a> FnOnce(Option<&'a Self::Item>) -> T) -> T;

  // provided methods
  fn peek_map<T>(&mut self, func: impl for<'a> FnOnce(&'a Self::Item) -> T) -> Option<T>;
  fn next_if(&mut self, func: impl FnOnce(&Self::Item) -> bool) -> Option<Self::Item>;
  fn next_if_eq<T>(&mut self, expected: &T) -> Option<Self::Item>
  where
    Self::Item: PartialEq<T>,
    T: ?Sized;
}

Steps / History

• ACP: rust-lang/libs-team#176
• Implementation:
  • Take 1: #132976
  • Take 2: #144935
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• Should peek take &mut self or &self? &self makes sense for iterators such as core::slice::iter but precludes implementing the trait on Peekable.
• What about the return type of peek? We could always make it return Self::Item like itertools’s PeekingNext, but that would prevent this trait from being implemented for consuming iterators such as vec::IntoIter, as well as Peekable itself. Resolved by having the method take a callback.
  • If we use an associated type, then what should be the bound for it: Borrow, AsRef, or something else?

Start with the core::iter public API in this issue and read implementation attempts #132976 and #144935 before doing any work. The open questions about receiver and callback design still need resolution; completion would require implementation, the final comment period, and a stabilization PR.