KT-20357: Add samples for associate* functions (#2798)

* KT-20357: Add samples for functions related to associate

* KT-20357: Use same fib function for both samples

* KT-20357: Use examples with duplicate keys and simplify examples with primitives

* KT-20357: Use primitive samples for all arrays

* KT-20357: Use String splitting example to better illustrate the use for associate over associateBy with a valueSelector

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

@@ -64,6 +64,72 @@ class Arrays {
 
     class Transformations {
 
+        @Sample
+        fun associateArrayOfPrimitives() {
+            val charCodes = intArrayOf(72, 69, 76, 76, 79)
+
+            val byCharCode = charCodes.associate { it to it.toChar() }
+
+            // 76=L only occurs once because only the last pair with the same key gets added
+            assertPrints(byCharCode, "{72=H, 69=E, 76=L, 79=O}")
+        }
+
+
+        @Sample
+        fun associateArrayOfPrimitivesBy() {
+            val charCodes = intArrayOf(72, 69, 76, 76, 79)
+
+            val byChar = charCodes.associateBy { it.toChar() }
+
+            // L=76 only occurs once because only the last pair with the same key gets added
+            assertPrints(byChar, "{H=72, E=69, L=76, O=79}")
+        }
+
+        @Sample
+        fun associateArrayOfPrimitivesByWithValueTransform() {
+            val charCodes = intArrayOf(65, 65, 66, 67, 68, 69)
+
+            val byUpperCase = charCodes.associateBy({ it.toChar() }, { (it + 32).toChar() })
+
+            // A=a only occurs once because only the last pair with the same key gets added
+            assertPrints(byUpperCase, "{A=a, B=b, C=c, D=d, E=e}")
+        }
+
+        @Sample
+        fun associateArrayOfPrimitivesByTo() {
+            val charCodes = intArrayOf(72, 69, 76, 76, 79)
+            val byChar = mutableMapOf<Char, Int>()
+
+            assertTrue(byChar.isEmpty())
+            charCodes.associateByTo(byChar) { it.toChar() }
+
+            assertTrue(byChar.isNotEmpty())
+            // L=76 only occurs once because only the last pair with the same key gets added
+            assertPrints(byChar, "{H=72, E=69, L=76, O=79}")
+        }
+
+        @Sample
+        fun associateArrayOfPrimitivesByToWithValueTransform() {
+            val charCodes = intArrayOf(65, 65, 66, 67, 68, 69)
+
+            val byUpperCase = mutableMapOf<Char, Char>()
+            charCodes.associateByTo(byUpperCase, { it.toChar() }, { (it + 32).toChar() } )
+
+            // A=a only occurs once because only the last pair with the same key gets added
+            assertPrints(byUpperCase, "{A=a, B=b, C=c, D=d, E=e}")
+        }
+
+        @Sample
+        fun associateArrayOfPrimitivesTo() {
+            val charCodes = intArrayOf(72, 69, 76, 76, 79)
+
+            val byChar = mutableMapOf<Int, Char>()
+            charCodes.associateTo(byChar) { it to it.toChar() }
+
+            // 76=L only occurs once because only the last pair with the same key gets added
+            assertPrints(byChar, "{72=H, 69=E, 76=L, 79=O}")
+        }
+
         @Sample
         fun flattenArray() {
             val deepArray = arrayOf(

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

@@ -337,6 +337,92 @@ class Collections {
 
     class Transformations {
 
+        @Sample
+        fun associate() {
+            val names = listOf("Grace Hopper", "Jacob Bernoulli", "Johann Bernoulli")
+
+            val byLastName = names.associate { it.split(" ").let { (firstName, lastName) -> lastName to firstName } }
+
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace, Bernoulli=Johann}")
+        }
+
+        @Sample
+        fun associateBy() {
+            data class Person(val firstName: String, val lastName: String) {
+                override fun toString(): String = "$firstName $lastName"
+            }
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Johann", "Bernoulli"))
+
+            val byLastName = scientists.associateBy { it.lastName }
+
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace Hopper, Bernoulli=Johann Bernoulli}")
+        }
+
+        @Sample
+        fun associateByWithValueTransform() {
+            data class Person(val firstName: String, val lastName: String)
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Johann", "Bernoulli"))
+
+            val byLastName = scientists.associateBy({ it.lastName }, { it.firstName })
+
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace, Bernoulli=Johann}")
+        }
+
+        @Sample
+        fun associateByTo() {
+            data class Person(val firstName: String, val lastName: String) {
+                override fun toString(): String = "$firstName $lastName"
+            }
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Johann", "Bernoulli"))
+
+            val byLastName = mutableMapOf<String, Person>()
+            assertTrue(byLastName.isEmpty())
+
+            scientists.associateByTo(byLastName) { it.lastName }
+
+            assertTrue(byLastName.isNotEmpty())
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace Hopper, Bernoulli=Johann Bernoulli}")
+        }
+
+        @Sample
+        fun associateByToWithValueTransform() {
+            data class Person(val firstName: String, val lastName: String)
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Johann", "Bernoulli"))
+
+            val byLastName = mutableMapOf<String, String>()
+            assertTrue(byLastName.isEmpty())
+
+            scientists.associateByTo(byLastName, { it.lastName }, { it.firstName} )
+
+            assertTrue(byLastName.isNotEmpty())
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace, Bernoulli=Johann}")
+        }
+
+        @Sample
+        fun associateTo() {
+            data class Person(val firstName: String, val lastName: String)
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Johann", "Bernoulli"))
+
+            val byLastName = mutableMapOf<String, String>()
+            assertTrue(byLastName.isEmpty())
+
+            scientists.associateTo(byLastName) { it.lastName to it.firstName }
+
+            assertTrue(byLastName.isNotEmpty())
+            // Jacob Bernoulli does not occur in the map because only the last pair with the same key gets added
+            assertPrints(byLastName, "{Hopper=Grace, Bernoulli=Johann}")
+        }
+
         @Sample
         fun associateWith() {
             val words = listOf("a", "abc", "ab", "def", "abcd")
@@ -345,6 +431,23 @@ class Collections {
             assertPrints(withLength.values, "[1, 3, 2, 3, 4]")
         }
 
+        @Sample
+        fun associateWithTo() {
+            data class Person(val firstName: String, val lastName: String) {
+                override fun toString(): String = "$firstName $lastName"
+            }
+
+            val scientists = listOf(Person("Grace", "Hopper"), Person("Jacob", "Bernoulli"), Person("Jacob", "Bernoulli"))
+            val withLengthOfNames = mutableMapOf<Person, Int>()
+            assertTrue(withLengthOfNames.isEmpty())
+
+            scientists.associateWithTo(withLengthOfNames) { it.firstName.length + it.lastName.length }
+
+            assertTrue(withLengthOfNames.isNotEmpty())
+            // Jacob Bernoulli only occurs once in the map because only the last pair with the same key gets added
+            assertPrints(withLengthOfNames, "{Grace Hopper=11, Jacob Bernoulli=14}")
+        }
+
         @Sample
         fun groupBy() {
             val words = listOf("a", "abc", "ab", "def", "abcd")

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

@@ -85,6 +85,63 @@ class Strings {
         assertPrints(result, "[az, by, cx]")
     }
 
+    @Sample
+    fun associate() {
+        val string = "bonne journée"
+        // associate each character with its code
+        val result = string.associate { char -> char to 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 associateBy() {
+        val string = "bonne journée"
+        // associate each character by its code
+        val result = string.associateBy { char -> char.toInt() }
+        // notice each char code occurs only once
+        assertPrints(result, "{98=b, 111=o, 110=n, 101=e, 32= , 106=j, 117=u, 114=r, 233=é}")
+    }
+
+    @Sample
+    fun associateByWithValueTransform() {
+        val string = "bonne journée"
+        // associate each character by the code of its upper case equivalent and transform the character to upper case
+        val result = string.associateBy({ char -> char.toUpperCase().toInt() }, { char -> char.toUpperCase() })
+        // notice each char code occurs only once
+        assertPrints(result, "{66=B, 79=O, 78=N, 69=E, 32= , 74=J, 85=U, 82=R, 201=É}")
+    }
+
+    @Sample
+    fun associateByTo() {
+        val string = "bonne journée"
+        // associate each character by its code
+        val result = mutableMapOf<Int, Char>()
+        string.associateByTo(result) { char -> char.toInt() }
+        // notice each char code occurs only once
+        assertPrints(result, "{98=b, 111=o, 110=n, 101=e, 32= , 106=j, 117=u, 114=r, 233=é}")
+    }
+
+    @Sample
+    fun associateByToWithValueTransform() {
+        val string = "bonne journée"
+        // associate each character by the code of its upper case equivalent and transform the character to upper case
+        val result = mutableMapOf<Int, Char>()
+        string.associateByTo(result, { char -> char.toUpperCase().toInt() }, { char -> char.toUpperCase() })
+        // notice each char code occurs only once
+        assertPrints(result, "{66=B, 79=O, 78=N, 69=E, 32= , 74=J, 85=U, 82=R, 201=É}")
+    }
+
+    @Sample
+    fun associateTo() {
+        val string = "bonne journée"
+        // associate each character with its code
+        val result = mutableMapOf<Char, Int>()
+        string.associateTo(result) { char -> char to 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 associateWith() {
         val string = "bonne journée"
@@ -94,6 +151,16 @@ class Strings {
         assertPrints(result, "{b=98, o=111, n=110, e=101,  =32, j=106, u=117, r=114, é=233}")
     }
 
+    @Sample
+    fun associateWithTo() {
+        val string = "bonne journée"
+        // associate each character with its code
+        val result = mutableMapOf<Char, Int>()
+        string.associateWithTo(result) { 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