feat(corelib): Iterator::collect (#7086)

Author: julio4

corelib/src/iter/traits/collect.cairo

@@ -65,7 +65,7 @@
 ///
 /// assert_eq!(c.arr, array![0, 1, 2, 3, 4]);
 /// ```
-pub trait FromIterator<T, G> {
+pub trait FromIterator<T, A> {
     /// Creates a value from an iterator.
     ///
     /// See the [module-level documentation] for more.
@@ -81,7 +81,7 @@ pub trait FromIterator<T, G> {
     ///
     /// assert_eq!(v, array![0, 1, 2, 3, 4]);
     /// ```
-    fn from_iter<I, +Iterator<I>[Item: G], +Destruct<I>>(iter: I) -> T;
+    fn from_iter<I, +Iterator<I>[Item: A], +Destruct<I>>(iter: I) -> T;
 }
 
 /// Conversion into an [`Iterator`].

corelib/src/iter/traits/iterator.cairo

@@ -312,4 +312,59 @@ pub trait Iterator<T> {
     ) -> Zip<T, UIntoIter::IntoIter> {
         zipped_iterator(self, other.into_iter())
     }
+
+    /// Transforms an iterator into a collection.
+    ///
+    /// `collect()` can take anything iterable, and turn it into a relevant
+    /// collection. This is one of the more powerful methods in the core
+    /// library, used in a variety of contexts.
+    ///
+    /// The most basic pattern in which `collect()` is used is to turn one
+    /// collection into another. You take a collection, call [`iter`] on it,
+    /// do a bunch of transformations, and then `collect()` at the end.
+    ///
+    /// `collect()` can also create instances of types that are not typical
+    /// collections.
+    ///
+    /// Because `collect()` is so general, it can cause problems with type
+    /// inference. As such, `collect()` is one of the few times you'll see
+    /// the syntax affectionately known as the 'turbofish': `::<>`. This
+    /// helps the inference algorithm understand specifically which collection
+    /// you're trying to collect into.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// let doubled: Array<u32> = array![1, 2, 3].into_iter().map(|x| x * 2).collect();
+    ///
+    /// assert_eq!(array![2, 4, 6], doubled);
+    /// ```
+    ///
+    /// Note that we needed the `: Array<u32>` on the left-hand side.
+    ///
+    /// Using the 'turbofish' instead of annotating `doubled`:
+    ///
+    /// ```
+    /// let doubled = array![1, 2, 3].into_iter().map(|x| x * 2).collect::<Array<u32>>();
+    ///
+    /// assert_eq!(array![2, 4, 6], doubled);
+    /// ```
+    ///
+    /// Because `collect()` only cares about what you're collecting into, you can
+    /// still use a partial type hint, `_`, with the turbofish:
+    ///
+    /// ```
+    /// let doubled = array![1, 2, 3].into_iter().map(|x| x * 2).collect::<Array<_>>();
+    ///
+    /// assert_eq!(array![2, 4, 6], doubled);
+    /// ```
+    #[inline]
+    #[must_use]
+    fn collect<B, +FromIterator<B, Self::Item>, +Destruct<T>>(
+        self: T,
+    ) -> B {
+        FromIterator::<B, Self::Item>::from_iter::<T, Self>(self)
+    }
 }

corelib/src/test/iter_test.cairo

@@ -53,3 +53,8 @@ fn test_iter_adapter_fold() {
 
     assert_eq!(sum, 6);
 }
+
+#[test]
+fn test_iter_adapter_collect() {
+    assert_eq!((0..3_u32).into_iter().collect(), array![0, 1, 2]);
+}