Introduce new overloads of flatMap and flatMapTo

- Sequence<T>.flatMap((T) -> Iterable<R>)
- Iterable<T>.flatMap((T) -> Sequence<R>)
- Array<T>.flatMap((T) -> Sequence<R>)
- Map.flatMap((Entry) -> Sequence<R>)

KT-34506

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -10032,6 +10032,19 @@ public inline fun <R> CharArray.flatMap(transform: (Char) -> Iterable<R>): List<
     return flatMapTo(ArrayList<R>(), transform)
 }
 
+/**
+ * Returns a single list of all elements yielded from results of [transform] function being invoked on each element of original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.flatMap
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequence")
+public inline fun <T, R> Array<out T>.flatMap(transform: (T) -> Sequence<R>): List<R> {
+    return flatMapTo(ArrayList<R>(), transform)
+}
+
 /**
  * Appends all elements yielded from results of [transform] function being invoked on each element of original array, to the given [destination].
  */
@@ -10131,6 +10144,21 @@ public inline fun <R, C : MutableCollection<in R>> CharArray.flatMapTo(destinati
     return destination
 }
 
+/**
+ * Appends all elements yielded from results of [transform] function being invoked on each element of original array, to the given [destination].
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequenceTo")
+public inline fun <T, R, C : MutableCollection<in R>> Array<out T>.flatMapTo(destination: C, transform: (T) -> Sequence<R>): C {
+    for (element in this) {
+        val list = transform(element)
+        destination.addAll(list)
+    }
+    return destination
+}
+
 /**
  * Groups elements of the original array by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.

libraries/stdlib/common/src/generated/_Collections.kt

@@ -1286,6 +1286,19 @@ public inline fun <T, R> Iterable<T>.flatMap(transform: (T) -> Iterable<R>): Lis
     return flatMapTo(ArrayList<R>(), transform)
 }
 
+/**
+ * Returns a single list of all elements yielded from results of [transform] function being invoked on each element of original collection.
+ * 
+ * @sample samples.collections.Collections.Transformations.flatMap
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequence")
+public inline fun <T, R> Iterable<T>.flatMap(transform: (T) -> Sequence<R>): List<R> {
+    return flatMapTo(ArrayList<R>(), transform)
+}
+
 /**
  * Appends all elements yielded from results of [transform] function being invoked on each element of original collection, to the given [destination].
  */
@@ -1297,6 +1310,21 @@ public inline fun <T, R, C : MutableCollection<in R>> Iterable<T>.flatMapTo(dest
     return destination
 }
 
+/**
+ * Appends all elements yielded from results of [transform] function being invoked on each element of original collection, to the given [destination].
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequenceTo")
+public inline fun <T, R, C : MutableCollection<in R>> Iterable<T>.flatMapTo(destination: C, transform: (T) -> Sequence<R>): C {
+    for (element in this) {
+        val list = transform(element)
+        destination.addAll(list)
+    }
+    return destination
+}
+
 /**
  * Groups elements of the original collection by the key returned by the given [keySelector] function
  * applied to each element and returns a map where each group key is associated with a list of corresponding elements.

libraries/stdlib/common/src/generated/_Maps.kt

@@ -46,6 +46,19 @@ public inline fun <K, V, R> Map<out K, V>.flatMap(transform: (Map.Entry<K, V>) -
     return flatMapTo(ArrayList<R>(), transform)
 }
 
+/**
+ * Returns a single list of all elements yielded from results of [transform] function being invoked on each entry of original map.
+ * 
+ * @sample samples.collections.Collections.Transformations.flatMap
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequence")
+public inline fun <K, V, R> Map<out K, V>.flatMap(transform: (Map.Entry<K, V>) -> Sequence<R>): List<R> {
+    return flatMapTo(ArrayList<R>(), transform)
+}
+
 /**
  * Appends all elements yielded from results of [transform] function being invoked on each entry of original map, to the given [destination].
  */
@@ -57,6 +70,21 @@ public inline fun <K, V, R, C : MutableCollection<in R>> Map<out K, V>.flatMapTo
     return destination
 }
 
+/**
+ * Appends all elements yielded from results of [transform] function being invoked on each entry of original map, to the given [destination].
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapSequenceTo")
+public inline fun <K, V, R, C : MutableCollection<in R>> Map<out K, V>.flatMapTo(destination: C, transform: (Map.Entry<K, V>) -> Sequence<R>): C {
+    for (element in this) {
+        val list = transform(element)
+        destination.addAll(list)
+    }
+    return destination
+}
+
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each entry in the original map.

libraries/stdlib/common/src/generated/_Sequences.kt

@@ -765,6 +765,21 @@ public fun <T> Sequence<T>.toSet(): Set<T> {
     return toCollection(LinkedHashSet<T>()).optimizeReadOnlySet()
 }
 
+/**
+ * Returns a single sequence of all elements from results of [transform] function being invoked on each element of original sequence.
+ *
+ * The operation is _intermediate_ and _stateless_.
+ * 
+ * @sample samples.collections.Collections.Transformations.flatMap
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapIterable")
+public fun <T, R> Sequence<T>.flatMap(transform: (T) -> Iterable<R>): Sequence<R> {
+    return FlatteningSequence(this, transform, { it.iterator() })
+}
+
 /**
  * Returns a single sequence of all elements from results of [transform] function being invoked on each element of original sequence.
  *
@@ -776,6 +791,23 @@ public fun <T, R> Sequence<T>.flatMap(transform: (T) -> Sequence<R>): Sequence<R
     return FlatteningSequence(this, transform, { it.iterator() })
 }
 
+/**
+ * Appends all elements yielded from results of [transform] function being invoked on each element of original sequence, to the given [destination].
+ *
+ * The operation is _terminal_.
+ */
+@SinceKotlin("1.4")
+@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
+@OverloadResolutionByLambdaReturnType
+@kotlin.jvm.JvmName("flatMapIterableTo")
+public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.flatMapTo(destination: C, transform: (T) -> Iterable<R>): C {
+    for (element in this) {
+        val list = transform(element)
+        destination.addAll(list)
+    }
+    return destination
+}
+
 /**
  * Appends all elements yielded from results of [transform] function being invoked on each element of original sequence, to the given [destination].
  *