Introduce associateWith and associateWithTo functions

#KT-13814

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

@@ -1059,6 +1059,36 @@ public inline fun <T, K, V, M : MutableMap<in K, in V>> Iterable<T>.associateTo(
     return destination
 }
 
+/**
+ * Returns a [Map] where keys are elements from the given collection and values are
+ * produced by the [valueSelector] function applied to each element.
+ * 
+ * If any two elements are equal, the last one gets added to the map.
+ * 
+ * The returned map preserves the entry iteration order of the original collection.
+ * 
+ * @sample samples.collections.Collections.Transformations.associateWith
+ */
+@SinceKotlin("1.3")
+public inline fun <K, V> Iterable<K>.associateWith(valueSelector: (K) -> V): Map<K, V> {
+    val result = LinkedHashMap<K, V>(mapCapacity(collectionSizeOrDefault(10)).coerceAtLeast(16))
+    return associateWithTo(result, valueSelector)
+}
+
+/**
+ * Populates and returns the [destination] mutable map with key-value pairs for each element of the given collection,
+ * where key is the element itself and value is provided by the [valueSelector] function applied to that key.
+ * 
+ * If any two elements are equal, the last one overwrites the former value in the map.
+ */
+@SinceKotlin("1.3")
+public inline fun <K, V, M : MutableMap<in K, in V>> Iterable<K>.associateWithTo(destination: M, valueSelector: (K) -> V): M {
+    for (element in this) {
+        destination.put(element, valueSelector(element))
+    }
+    return destination
+}
+
 /**
  * Appends all elements to the given [destination] collection.
  */

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

@@ -642,6 +642,40 @@ public inline fun <T, K, V, M : MutableMap<in K, in V>> Sequence<T>.associateTo(
     return destination
 }
 
+/**
+ * Returns a [Map] where keys are elements from the given sequence and values are
+ * produced by the [valueSelector] function applied to each element.
+ * 
+ * If any two elements are equal, the last one gets added to the map.
+ * 
+ * The returned map preserves the entry iteration order of the original sequence.
+ *
+ * The operation is _terminal_.
+ * 
+ * @sample samples.collections.Collections.Transformations.associateWith
+ */
+@SinceKotlin("1.3")
+public inline fun <K, V> Sequence<K>.associateWith(valueSelector: (K) -> V): Map<K, V> {
+    val result = LinkedHashMap<K, V>()
+    return associateWithTo(result, valueSelector)
+}
+
+/**
+ * Populates and returns the [destination] mutable map with key-value pairs for each element of the given sequence,
+ * where key is the element itself and value is provided by the [valueSelector] function applied to that key.
+ * 
+ * If any two elements are equal, the last one overwrites the former value in the map.
+ *
+ * The operation is _terminal_.
+ */
+@SinceKotlin("1.3")
+public inline fun <K, V, M : MutableMap<in K, in V>> Sequence<K>.associateWithTo(destination: M, valueSelector: (K) -> V): M {
+    for (element in this) {
+        destination.put(element, valueSelector(element))
+    }
+    return destination
+}
+
 /**
  * Appends all elements to the given [destination] collection.
  *

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

@@ -615,6 +615,36 @@ public inline fun <K, V, M : MutableMap<in K, in V>> CharSequence.associateTo(de
     return destination
 }
 
+/**
+ * Returns a [Map] where keys are characters from the given char sequence and values are
+ * produced by the [valueSelector] function applied to each character.
+ * 
+ * If any two characters are equal, the last one gets added to the map.
+ * 
+ * The returned map preserves the entry iteration order of the original char sequence.
+ * 
+ * @sample samples.text.Strings.associateWith
+ */
+@SinceKotlin("1.3")
+public inline fun <V> CharSequence.associateWith(valueSelector: (Char) -> V): Map<Char, V> {
+    val result = LinkedHashMap<Char, V>(mapCapacity(length).coerceAtLeast(16))
+    return associateWithTo(result, valueSelector)
+}
+
+/**
+ * Populates and returns the [destination] mutable map with key-value pairs for each character of the given char sequence,
+ * where key is the character itself and value is provided by the [valueSelector] function applied to that key.
+ * 
+ * If any two characters are equal, the last one overwrites the former value in the map.
+ */
+@SinceKotlin("1.3")
+public inline fun <V, M : MutableMap<in Char, in V>> CharSequence.associateWithTo(destination: M, valueSelector: (Char) -> V): M {
+    for (element in this) {
+        destination.put(element, valueSelector(element))
+    }
+    return destination
+}
+
 /**
  * Appends all characters to the given [destination] collection.
  */

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -300,6 +300,14 @@ class Collections {
 
     class Transformations {
 
+        @Sample
+        fun associateWith() {
+            val words = listOf("a", "abc", "ab", "def", "abcd")
+            val withLength = words.associateWith { it.length }
+            assertPrints(withLength.keys, "[a, abc, ab, def, abcd]")
+            assertPrints(withLength.values, "[1, 3, 2, 3, 4]")
+        }
+
         @Sample
         fun groupBy() {
             val words = listOf("a", "abc", "ab", "def", "abcd")

libraries/stdlib/samples/test/samples/text/strings.kt

@@ -84,6 +84,15 @@ class Strings {
         assertPrints(result, "[az, by, cx]")
     }
 
+    @Sample
+    fun associateWith() {
+        val string = "bonne journée"
+        // associate each character with its code
+        val result = string.associateWith { char -> char.toInt() }
+        // notice each letter occurs only once
+        assertPrints(result, "{b=98, o=111, n=110, e=101,  =32, j=106, u=117, r=114, é=233}")
+    }
+
     @Sample
     fun stringToByteArray() {
         val charset = Charsets.UTF_8

libraries/stdlib/test/collections/CollectionTest.kt

@@ -358,6 +358,18 @@ class CollectionTest {
         assertEquals(namesByTeam, mutableNamesByTeam)
     }
 
+    @Test fun associateWith() {
+        val items = listOf("Alice", "Bob", "Carol")
+        val itemsWithTheirLength = items.associateWith { it.length }
+
+        assertEquals(mapOf("Alice" to 5, "Bob" to 3, "Carol" to 5), itemsWithTheirLength)
+
+        val updatedLength =
+            items.drop(1).associateWithTo(itemsWithTheirLength.toMutableMap()) { name -> name.toLowerCase().count { it in "aeuio" }}
+
+        assertEquals(mapOf("Alice" to 5, "Bob" to 1, "Carol" to 2), updatedLength)
+    }
+
     @Test fun plusRanges() {
         val range1 = 1..3
         val range2 = 4..7

libraries/stdlib/test/collections/SequenceTest.kt

@@ -548,6 +548,18 @@ public class SequenceTest {
         assertEquals(listOf("act", "wast", "test"), sequenceOf("act", "test", "wast").sortedWith(comparator).toList())
     }
 
+    @Test fun associateWith() {
+        val items = sequenceOf("Alice", "Bob", "Carol")
+        val itemsWithTheirLength = items.associateWith { it.length }
+
+        assertEquals(mapOf("Alice" to 5, "Bob" to 3, "Carol" to 5), itemsWithTheirLength)
+
+        val updatedLength =
+            items.drop(1).associateWithTo(itemsWithTheirLength.toMutableMap()) { name -> name.toLowerCase().count { it in "aeuio" }}
+
+        assertEquals(mapOf("Alice" to 5, "Bob" to 1, "Carol" to 2), updatedLength)
+    }
+
     @Test fun orEmpty() {
         val s1: Sequence<Int>? = null
         assertEquals(emptySequence(), s1.orEmpty())

libraries/stdlib/test/text/StringTest.kt

@@ -1159,6 +1159,14 @@ class StringTest {
         assertEquals(listOf('A', 'A', 'B', 'D'), result[true])
     }
 
+    @Test fun associateWith() = withOneCharSequenceArg("abc") { data ->
+        val result = data.associateWith { it + 1 }
+        assertEquals(mapOf('a' to 'b', 'b' to 'c', 'c' to 'd'), result)
+
+        val mutableResult = data.drop(1).associateWithTo(result.toMutableMap()) { it - 1 }
+        assertEquals(mapOf('a' to 'b', 'b' to 'a', 'c' to 'b'), mutableResult)
+    }
+
     @Test fun joinToString() {
         val data = "abcd".toList()
         val result = data.joinToString("_", "(", ")")