add groupByOrdered

core/src/main/scala/flatgraph/traversal/Language.scala

@@ -57,7 +57,24 @@ class GenericSteps[A](iterator: Iterator[A]) extends AnyVal {
     counts.to(Map)
   }
 
-  def groupBy[K](f: A => K): Map[K, List[A]]                                       = l.groupBy(f)
+  /** Execute the traversal and group elements by a given transformation function, ignoring the iterator order. Use is discouraged. */
+  @Doc(info =
+    "Execute the traversal and group elements by a given transformation function, ignoring the iterator order. Use is discouraged."
+  )
+  def groupBy[K](f: A => K): Map[K, List[A]] = l.groupBy(f)
+
+  /** Execute the traversal and group elements by a given transformation function, respecting the order of the iterator */
+  @Doc(info = "Execute the traversal and group elements by a given transformation function, respecting the order of the iterator")
+  def groupByOrdered[K](f: A => K): Map[K, List[A]] = {
+    val res = mutable.LinkedHashMap[K, mutable.Builder[A, List[A]]]()
+    while (iterator.hasNext) {
+      val item = iterator.next
+      val key  = f(item)
+      res.getOrElseUpdate(key, List.newBuilder[A]).addOne(item)
+    }
+    scala.collection.immutable.VectorMap.from(res.iterator.map { kv => (kv._1, kv._2.result()) })
+  }
+
   def groupMap[K, B](key: A => K)(f: A => B): Map[K, List[B]]                      = l.groupMap(key)(f)
   def groupMapReduce[K, B](key: A => K)(f: A => B)(reduce: (B, B) => B): Map[K, B] = l.groupMapReduce(key)(f)(reduce)
 

core/src/test/scala/flatgraph/traversal/IterableOnceExtensionTests.scala

@@ -47,4 +47,10 @@ class IterableOnceExtensionTests extends AnyWordSpec with Matchers {
     Seq(1, 2).loneElementOption shouldBe None
   }
 
+  "groupBy respects iteration order" in {
+    Seq(5, 4, 3, 2, 1, 0).groupByOrdered(x => x % 3).valuesIterator.map { _.l }.l shouldBe List(List(5, 2), List(4, 1), List(3, 0))
+    Seq(5, 4, 3, 2, 1, 0).groupByOrdered(x => (x + 1) % 3).valuesIterator.map { _.l }.l shouldBe List(List(5, 2), List(4, 1), List(3, 0))
+    Seq(5, 4, 3, 2, 1, 0).groupByOrdered(x => (x + 2) % 3).valuesIterator.map { _.l }.l shouldBe List(List(5, 2), List(4, 1), List(3, 0))
+  }
+
 }