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.

js/js.libraries/src/core/grouping.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2010-2016 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package kotlin.collections
+
+/**
+ * Groups elements from the [Grouping] source by key and counts elements in each group.
+ *
+ * @return a [Map] associating the key of each group with the count of element in the group.
+ */
+@SinceKotlin("1.1")
+public fun <T, K> Grouping<T, K>.eachCount(): Map<K, Int> =
+        fold(0) { acc, e -> acc + 1 }
+
+/**
+ * Groups elements from the [Grouping] source by key and sums values provided by the [valueSelector] function for elements in each group.
+ *
+ * @return a [Map] associating the key of each group with the count of element in the group.
+ */
+@SinceKotlin("1.1")
+public inline fun <T, K> Grouping<T, K>.eachSumOf(valueSelector: (T) -> Int): Map<K, Int> =
+        fold(0) { acc, e -> acc + valueSelector(e) }