Add PeekableIterator trait

library/core/src/array/iter.rs

@@ -1,7 +1,7 @@
 //! Defines the `IntoIter` owned iterator for arrays.
 
 use crate::intrinsics::transmute_unchecked;
-use crate::iter::{FusedIterator, TrustedLen, TrustedRandomAccessNoCoerce};
+use crate::iter::{FusedIterator, PeekableIterator, TrustedLen, TrustedRandomAccessNoCoerce};
 use crate::mem::MaybeUninit;
 use crate::num::NonZero;
 use crate::ops::{IndexRange, Range, Try};
@@ -350,6 +350,13 @@ impl<T, const N: usize> FusedIterator for IntoIter<T, N> {}
 #[stable(feature = "array_value_iter_impls", since = "1.40.0")]
 unsafe impl<T, const N: usize> TrustedLen for IntoIter<T, N> {}
 
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+impl<T, const N: usize> PeekableIterator for IntoIter<T, N> {
+ fn peek_with<U>(&mut self, func: impl for<'b> FnOnce(Option<&'b Self::Item>) -> U) -> U {
+ self.unsize_mut().peek_with(func)
+ }
+}
+
 #[doc(hidden)]
 #[unstable(issue = "none", feature = "std_internals")]
 #[rustc_unsafe_specialization_marker]

library/core/src/array/iter/iter_inner.rs

@@ -175,6 +175,19 @@ impl<T> PolymorphicIter<[MaybeUninit<T>]> {
  })
  }
 
+ #[inline]
+ pub(super) fn peek_with<U>(&self, func: impl for<'b> FnOnce(Option<&'b T>) -> U) -> U {
+ let tmp = self.alive.clone().next().map(|idx| {
+ // SAFETY: `idx` is in self.alive range
+ unsafe { self.data.get_unchecked(idx).assume_init_read() }
+ });
+
+ let out = func(tmp.as_ref());
+ // Avoid dropping before the item is consumed
+ crate::mem::forget(tmp);
+ out
+ }
+
  #[inline]
  pub(super) fn size_hint(&self) -> (usize, Option<usize>) {
  let len = self.len();

library/core/src/iter/adapters/peekable.rs

@@ -1,5 +1,5 @@
 use crate::iter::adapters::SourceIter;
-use crate::iter::{FusedIterator, TrustedLen};
+use crate::iter::{FusedIterator, PeekableIterator, TrustedLen};
 use crate::ops::{ControlFlow, Try};
 
 /// An iterator with a `peek()` that returns an optional reference to the next
@@ -322,6 +322,14 @@ impl<I: Iterator> Peekable<I> {
 #[unstable(feature = "trusted_len", issue = "37572")]
 unsafe impl<I> TrustedLen for Peekable<I> where I: TrustedLen {}
 
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+impl<I: Iterator> PeekableIterator for Peekable<I> {
+ fn peek_with<T>(&mut self, func: impl for<'a> FnOnce(Option<&'a Self::Item>) -> T) -> T {
+ let tmp = self.peek();
+ func(tmp)
+ }
+}
+
 #[unstable(issue = "none", feature = "inplace_iteration")]
 unsafe impl<I: Iterator> SourceIter for Peekable<I>
 where

library/core/src/iter/mod.rs

@@ -452,6 +452,8 @@ pub use self::traits::FusedIterator;
 pub use self::traits::InPlaceIterable;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use self::traits::Iterator;
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+pub use self::traits::PeekableIterator;
 #[unstable(issue = "none", feature = "trusted_fused")]
 pub use self::traits::TrustedFused;
 #[unstable(feature = "trusted_len", issue = "37572")]

library/core/src/iter/traits/mod.rs

@@ -4,6 +4,7 @@ mod double_ended;
 mod exact_size;
 mod iterator;
 mod marker;
+mod peekable;
 mod unchecked_iterator;
 
 #[unstable(issue = "none", feature = "inplace_iteration")]
@@ -12,6 +13,8 @@ pub use self::marker::InPlaceIterable;
 pub use self::marker::TrustedFused;
 #[unstable(feature = "trusted_step", issue = "85731")]
 pub use self::marker::TrustedStep;
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+pub use self::peekable::PeekableIterator;
 pub(crate) use self::unchecked_iterator::UncheckedIterator;
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use self::{

library/core/src/iter/traits/peekable.rs

@@ -0,0 +1,28 @@
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+/// Iterators which inherently support peeking without needing to be wrapped by a `Peekable`.
+pub trait PeekableIterator: Iterator {
+ /// Executes the closure with a reference to the `next()` value without advancing the iterator.
+ fn peek_with<T>(&mut self, func: impl for<'a> FnOnce(Option<&'a Self::Item>) -> T) -> T;
+
+ /// Executes the closure on the `next()` element without advancing the iterator, or returns `None` if the iterator is exhausted.
+ fn peek_map<T>(&mut self, func: impl for<'a> FnOnce(&'a Self::Item) -> T) -> Option<T> {
+ self.peek_with(|x| x.map(|y| func(y)))
+ }
+
+ /// Returns the `next()` element if the given predicate holds true.
+ fn next_if(&mut self, func: impl FnOnce(&Self::Item) -> bool) -> Option<Self::Item> {
+ match self.peek_map(func) {
+ Some(true) => self.next(),
+ _ => None,
+ }
+ }
+
+ /// Moves forward and return the `next()` item if it is equal to the expected value.
+ fn next_if_eq<T>(&mut self, expected: &T) -> Option<Self::Item>
+ where
+ Self::Item: PartialEq<T>,
+ T: ?Sized,
+ {
+ self.next_if(|x| x == expected)
+ }
+}

library/core/src/slice/iter.rs

@@ -6,7 +6,8 @@ mod macros;
 use super::{from_raw_parts, from_raw_parts_mut};
 use crate::hint::assert_unchecked;
 use crate::iter::{
- FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce, UncheckedIterator,
+ FusedIterator, PeekableIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce,
+ UncheckedIterator,
 };
 use crate::marker::PhantomData;
 use crate::mem::{self, SizedTypeProperties};

library/core/src/slice/iter/macros.rs

@@ -468,6 +468,34 @@ macro_rules! iterator {
  }
  }
 
+ #[unstable(feature = "peekable_iterator", issue = "132973")]
+ impl<'a, T> PeekableIterator for $name<'a, T> {
+ fn peek_with<U>(&mut self, func: impl for<'b> FnOnce(Option<&'b Self::Item>) -> U) -> U {
+ let ptr = self.ptr;
+ let end_or_len = self.end_or_len;
+
+ // SAFETY: See inner comments.
+ unsafe {
+ if T::IS_ZST {
+ let len = end_or_len.addr();
+ if len == 0 {
+ return func(None);
+ }
+ } else {
+ // SAFETY: by type invariant, the `end_or_len` field is always
+ // non-null for a non-ZST pointee. (This transmute ensures we
+ // get `!nonnull` metadata on the load of the field.)
+ if ptr == crate::intrinsics::transmute::<$ptr, NonNull<T>>(end_or_len) {
+ return func(None);
+ }
+ }
+ // SAFETY: Now that we know it wasn't empty
+ // we can give out a reference to it.
+ let tmp = {ptr}.$into_ref();
+ func(Some(&tmp))
+ }
+ }
+ }
  #[stable(feature = "default_iters", since = "1.70.0")]
  impl<T> Default for $name<'_, T> {
  /// Creates an empty slice iterator.

library/core/src/str/iter.rs

@@ -8,8 +8,8 @@ use super::{
 };
 use crate::fmt::{self, Write};
 use crate::iter::{
- Chain, Copied, Filter, FlatMap, Flatten, FusedIterator, Map, TrustedLen, TrustedRandomAccess,
- TrustedRandomAccessNoCoerce,
+ Chain, Copied, Filter, FlatMap, Flatten, FusedIterator, Map, PeekableIterator, TrustedLen,
+ TrustedRandomAccess, TrustedRandomAccessNoCoerce,
 };
 use crate::num::NonZero;
 use crate::ops::Try;
@@ -132,6 +132,14 @@ impl<'a> DoubleEndedIterator for Chars<'a> {
  }
 }
 
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+impl<'a> PeekableIterator for Chars<'a> {
+ fn peek_with<T>(&mut self, func: impl for<'b> FnOnce(Option<&'b Self::Item>) -> T) -> T {
+ let tmp = self.clone().next();
+ func(tmp.as_ref())
+ }
+}
+
 #[stable(feature = "fused", since = "1.26.0")]
 impl FusedIterator for Chars<'_> {}