KEEP-23 implement group and fold operations

Docs for group-and-fold operations

Fix implementation for countEach and sumEachBy

countEach and sumEachBy implementations for JS

Rename keySelector to keyOf

Generate additional sources for groupingBy + headers

Rename countEach and sumEachBy to eachCount and eachSumOf.

js/js.libraries/src/core/generated/_ArraysJs.kt

@@ -7630,6 +7630,18 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> CharArray.groupBy
     return destination
 }
 
+/**
+ * Creates a [Grouping] source from an array to be used later with one of group-and-fold operations
+ * using the specified [keySelector] function to extract a key from each element.
+ */
+@SinceKotlin("1.1")
+public inline fun <T, K> Array<out T>.groupingBy(crossinline keySelector: (T) -> K): Grouping<T, K> {
+    return object : Grouping<T, K> {
+        override fun elementIterator(): Iterator<T> = this@groupingBy.iterator()
+        override fun keyOf(element: T): K = keySelector(element)
+    }
+}
+
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.

js/js.libraries/src/core/generated/_CollectionsJs.kt

@@ -1179,6 +1179,18 @@ public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Iterable<T>.gr
     return destination
 }
 
+/**
+ * Creates a [Grouping] source from a collection to be used later with one of group-and-fold operations
+ * using the specified [keySelector] function to extract a key from each element.
+ */
+@SinceKotlin("1.1")
+public inline fun <T, K> Iterable<T>.groupingBy(crossinline keySelector: (T) -> K): Grouping<T, K> {
+    return object : Grouping<T, K> {
+        override fun elementIterator(): Iterator<T> = this@groupingBy.iterator()
+        override fun keyOf(element: T): K = keySelector(element)
+    }
+}
+
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original collection.

js/js.libraries/src/core/generated/_SequencesJs.kt

@@ -644,6 +644,18 @@ public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Sequence<T>.gr
     return destination
 }
 
+/**
+ * Creates a [Grouping] source from a sequence to be used later with one of group-and-fold operations
+ * using the specified [keySelector] function to extract a key from each element.
+ */
+@SinceKotlin("1.1")
+public inline fun <T, K> Sequence<T>.groupingBy(crossinline keySelector: (T) -> K): Grouping<T, K> {
+    return object : Grouping<T, K> {
+        override fun elementIterator(): Iterator<T> = this@groupingBy.iterator()
+        override fun keyOf(element: T): K = keySelector(element)
+    }
+}
+
 /**
  * Returns a sequence containing the results of applying the given [transform] function
  * to each element in the original sequence.

js/js.libraries/src/core/generated/_StringsJs.kt

@@ -701,6 +701,18 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> CharSequence.grou
     return destination
 }
 
+/**
+ * Creates a [Grouping] source from a char sequence to be used later with one of group-and-fold operations
+ * using the specified [keySelector] function to extract a key from each character.
+ */
+@SinceKotlin("1.1")
+public inline fun <K> CharSequence.groupingBy(crossinline keySelector: (Char) -> K): Grouping<Char, K> {
+    return object : Grouping<Char, K> {
+        override fun elementIterator(): Iterator<Char> = this@groupingBy.iterator()
+        override fun keyOf(element: Char): K = keySelector(element)
+    }
+}
+
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each character in the original char sequence.