feat(corelib): Iterator::advance_by

corelib/src/iter/traits/iterator.cairo

@@ -38,4 +38,44 @@ pub trait Iterator<T> {
     /// assert_eq!(Option::None, iter.next());
     /// ```
     fn next(ref self: T) -> Option<Self::Item>;
+
+    /// Advances the iterator by `n` elements.
+    ///
+    /// This method will eagerly skip `n` elements by calling [`next`] up to `n`
+    /// times until [`None`] is encountered.
+    ///
+    /// `advance_by(n)` will return `Ok(())` if the iterator successfully advances by
+    /// `n` elements, or a `Err(NonZero<usize>)` with value `k` if [`None`] is encountered,
+    /// where `k` is remaining number of steps that could not be advanced because the iterator ran
+    /// out.
+    /// If `self` is empty and `n` is non-zero, then this returns `Err(n)`.
+    /// Otherwise, `k` is always less than `n`.
+    ///
+    /// [`None`]: Option::None
+    /// [`next`]: Iterator::next
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut iter = array![1_u8, 2, 3, 4].into_iter();
+    ///
+    /// assert_eq!(iter.advance_by(2), Result::Ok(()));
+    /// assert_eq!(iter.next(), Option::Some(3));
+    /// assert_eq!(iter.advance_by(0), Result::Ok(()));
+    /// assert_eq!(iter.advance_by(100), Result::Err(99));
+    /// ```
+    fn advance_by<+Destruct<T>, +Drop<Self::Item>>(
+        ref self: T, n: usize,
+    ) -> Result<
+        (), NonZero<usize>,
+    > {
+        let mut res = Result::Ok(());
+        for i in 0..n {
+            if Self::next(ref self).is_none() {
+                res = Result::Err((n - i).try_into().unwrap());
+                break;
+            }
+        };
+        res
+    }
 }

corelib/src/test.cairo

@@ -13,6 +13,7 @@ mod felt_test;
 mod fmt_test;
 mod hash_test;
 mod integer_test;
+mod iter_test;
 mod keccak_test;
 mod math_test;
 mod nullable_test;

corelib/src/test/iter_test.cairo

@@ -0,0 +1,9 @@
+#[test]
+fn test_advance_by() {
+    let mut iter = array![1_u8, 2, 3, 4].into_iter();
+
+    assert_eq!(iter.advance_by(2), Result::Ok(()));
+    assert_eq!(iter.next(), Option::Some(3));
+    assert_eq!(iter.advance_by(0), Result::Ok(()));
+    assert_eq!(iter.advance_by(100), Result::Err(99));
+}