doc: Iterator::collect

corelib/src/iter/traits/iterator.cairo

@@ -313,6 +313,53 @@ pub trait Iterator<T> {
         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>>(