implement Iter::group_by (#1998)

* implement Iter::group_by

* added suggested improvements

* new version using a Map

Author: juliano

builtin/builtin.mbti

@@ -233,6 +233,7 @@ impl Iter {
   flat_map[T, R](Self[T], (T) -> Self[R]) -> Self[R]
   flatten[T](Self[Self[T]]) -> Self[T]
   fold[T, B](Self[T], init~ : B, (B, T) -> B) -> B
+  group_by[T, K : Eq + Hash](Self[T], (T) -> K) -> Map[K, Array[T]]
   head[A](Self[A]) -> A?
   intersperse[A](Self[A], A) -> Self[A]
   iter[T](Self[T]) -> Self[T]

builtin/iter.mbt

@@ -998,3 +998,41 @@ pub fn Iter::minimum[T : Compare](self : Iter[T]) -> T? {
   }
   res
 }
+
+///|
+/// Groups elements of an iterator according to a discriminator function.
+///
+/// # Parameters
+///
+/// * `self` - The input iterator.
+/// * `f` - The discriminator function that maps elements to keys.
+///
+/// # Returns
+///
+/// A Map where keys are the result of applying the discriminator function to elements,
+/// and values are arrays containing all elements that share the same key.
+///
+/// # Example
+///
+/// ```moonbit
+/// test "group_by" {
+///   let iter = [1, 1, 2, 3, 2, 2, 1].iter()
+///   let result = iter.group_by(fn(x) { x })
+///   assert_eq!(result.get(1), Some([1, 1, 1]))
+///   assert_eq!(result.get(2), Some([2, 2, 2]))
+///   assert_eq!(result.get(3), Some([3]))
+/// }
+pub fn Iter::group_by[T, K : Eq + Hash](
+  self : Iter[T],
+  f : (T) -> K
+) -> Map[K, Array[T]] {
+  let result = Map::new()
+  for element in self {
+    let key = f(element)
+    match result.get(key) {
+      Some(arr) => result.set(key, arr + [element])
+      None => result.set(key, [element])
+    }
+  }
+  result
+}

builtin/iter_test.mbt

@@ -758,3 +758,70 @@ test "Float::until negative step" {
   let result = 10.0.until(0.0, step=-2.0).collect()
   inspect!(result, content="[10, 8, 6, 4, 2]")
 }
+
+///|
+test "group_by with consecutive identical elements" {
+  let iter = [1, 1, 2, 2, 3, 3].iter()
+  let grouped = iter.group_by(fn(x) { x })
+  assert_eq!(grouped.get(1), Some([1, 1]))
+  assert_eq!(grouped.get(2), Some([2, 2]))
+  assert_eq!(grouped.get(3), Some([3, 3]))
+}
+
+///|
+test "group_by with non-consecutive identical elements" {
+  let iter = [1, 2, 1, 3, 2, 1].iter()
+  let grouped = iter.group_by(fn(x) { x })
+  assert_eq!(grouped.get(1), Some([1, 1, 1]))
+  assert_eq!(grouped.get(2), Some([2, 2]))
+  assert_eq!(grouped.get(3), Some([3]))
+}
+
+///|
+test "group_by with empty input" {
+  let iter : Iter[Int] = Iter::empty()
+  let grouped = iter.group_by(fn(x) { x })
+  assert_eq!(grouped.size(), 0)
+}
+
+///|
+test "group_by with single element input" {
+  let iter = [42].iter()
+  let grouped = iter.group_by(fn(x) { x })
+  assert_eq!(grouped.get(42), Some([42]))
+}
+
+///|
+test "group_by with custom key function" {
+  let iter = [1, 2, 3, 4].iter()
+  let grouped = iter.group_by(fn(x) { x % 2 })
+  assert_eq!(grouped.get(0), Some([2, 4]))
+  assert_eq!(grouped.get(1), Some([1, 3]))
+}
+
+///|
+test "group_by with strings" {
+  let iter = ["apple", "avocado", "banana", "cherry", "blueberry"].iter()
+  let grouped = iter.group_by(fn(s) { s[0] })
+  assert_eq!(grouped.get('a'), Some(["apple", "avocado"]))
+  assert_eq!(grouped.get('b'), Some(["banana", "blueberry"]))
+  assert_eq!(grouped.get('c'), Some(["cherry"]))
+}
+
+///|
+test "group_by with complex objects" {
+  struct Person {
+    name : String
+    age : Int
+  }
+  let people = [
+    Person::{ name: "Alice", age: 25 },
+    Person::{ name: "Bob", age: 25 },
+    Person::{ name: "Charlie", age: 30 },
+    Person::{ name: "Dave", age: 35 },
+    Person::{ name: "Eve", age: 30 },
+  ].iter()
+  let grouped = people.group_by(fn(p) { p.age })
+  let groups = grouped.values().map(fn(a) { a.map(fn(p) { p.name }) }).collect()
+  assert_eq!(groups, [["Alice", "Bob"], ["Charlie", "Eve"], ["Dave"]])
+}