Add peekable_iterator

Author: wmstack

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,42 @@
+#[unstable(feature = "peekable_iterator", issue = "132973")]
+/// Iterators which inherently support `peek()` without needing to be wrapped by a `Peekable`.
+pub trait PeekableIterator: Iterator {
+    /// returns a reference to the `next()` value without advancing the iterator.
+    /// Just like `next()`, if there is a value, it returns a reference to it in Some()
+    /// if the iteration is finished, a `None` is returned
+    ///
+    /// # Examples
+    /// Basic usage:
+    /// ```
+    /// let xs = [1, 2, 3];
+    /// let mut iter = xs.iter();
+    ///
+    /// // peek() allows us to check the future value
+    /// assert_eq!(iter.peek(), Some(&&1));
+    /// assert_eq!(iter.next(), Some(&1));
+    ///
+    /// // peek() doesn't move the iterator forward
+    /// assert_eq!(iter.peek(), Some(&&2));
+    /// assert_eq!(iter.peek(), Some(&&2));
+    ///
+    /// ```
+    fn peek(&mut self) -> Option<&Self::Item>;
+
+    /// returns the `next()` element if a predicate holds true
+    fn next_if(&mut self, func: impl FnOnce(&Self::Item) -> bool) -> Option<Self::Item> {
+        let Some(item) = self.peek() else {
+            return None;
+        };
+
+        if func(item) { self.next() } else { None }
+    }
+
+    /// move 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)
+    }
+}