From 3e39f263793f2105fb628b85e92e08bea74a93f2 Mon Sep 17 00:00:00 2001
From: Benjamin Orsini <borsini.dev@pm.me>
Date: Mon, 20 May 2019 18:20:09 +0200
Subject: [PATCH] Add map() documentation sample

* docs: add map() sample
* docs: add samples for Map and CharSequence
* docs: add another sample for Maps.map()
---
 .../stdlib/common/src/generated/_Arrays.kt     | 18 ++++++++++++++++++
 .../common/src/generated/_Collections.kt       |  2 ++
 libraries/stdlib/common/src/generated/_Maps.kt |  2 ++
 .../stdlib/common/src/generated/_Sequences.kt  |  2 ++
 .../stdlib/common/src/generated/_Strings.kt    |  2 ++
 .../stdlib/common/src/generated/_UArrays.kt    |  8 ++++++++
 .../test/samples/collections/collections.kt    |  6 ++++++
 .../samples/test/samples/collections/maps.kt   | 11 ++++++++++-
 .../samples/test/samples/text/strings.kt       |  6 ++++++
 .../kotlin-stdlib-gen/src/templates/Mapping.kt | 13 +++++++++++++
 10 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt
index 8a8c893c8f8..c78bd1ca5d8 100644
--- a/libraries/stdlib/common/src/generated/_Arrays.kt
+++ b/libraries/stdlib/common/src/generated/_Arrays.kt
@@ -8757,6 +8757,8 @@ public inline fun <T, K> Array<out T>.groupingBy(crossinline keySelector: (T) ->
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <T, R> Array<out T>.map(transform: (T) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8765,6 +8767,8 @@ public inline fun <T, R> Array<out T>.map(transform: (T) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> ByteArray.map(transform: (Byte) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8773,6 +8777,8 @@ public inline fun <R> ByteArray.map(transform: (Byte) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> ShortArray.map(transform: (Short) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8781,6 +8787,8 @@ public inline fun <R> ShortArray.map(transform: (Short) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> IntArray.map(transform: (Int) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8789,6 +8797,8 @@ public inline fun <R> IntArray.map(transform: (Int) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> LongArray.map(transform: (Long) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8797,6 +8807,8 @@ public inline fun <R> LongArray.map(transform: (Long) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> FloatArray.map(transform: (Float) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8805,6 +8817,8 @@ public inline fun <R> FloatArray.map(transform: (Float) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> DoubleArray.map(transform: (Double) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8813,6 +8827,8 @@ public inline fun <R> DoubleArray.map(transform: (Double) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> BooleanArray.map(transform: (Boolean) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
@@ -8821,6 +8837,8 @@ public inline fun <R> BooleanArray.map(transform: (Boolean) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <R> CharArray.map(transform: (Char) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt
index 04ed43984c4..bc56551807b 100644
--- a/libraries/stdlib/common/src/generated/_Collections.kt
+++ b/libraries/stdlib/common/src/generated/_Collections.kt
@@ -1306,6 +1306,8 @@ public inline fun <T, K> Iterable<T>.groupingBy(crossinline keySelector: (T) ->
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original collection.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public inline fun <T, R> Iterable<T>.map(transform: (T) -> R): List<R> {
     return mapTo(ArrayList<R>(collectionSizeOrDefault(10)), transform)
diff --git a/libraries/stdlib/common/src/generated/_Maps.kt b/libraries/stdlib/common/src/generated/_Maps.kt
index 97f6085f593..26780febbc5 100644
--- a/libraries/stdlib/common/src/generated/_Maps.kt
+++ b/libraries/stdlib/common/src/generated/_Maps.kt
@@ -58,6 +58,8 @@ public inline fun <K, V, R, C : MutableCollection<in R>> Map<out K, V>.flatMapTo
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each entry in the original map.
+ * 
+ * @sample samples.collections.Maps.Transformations.mapToList
  */
 public inline fun <K, V, R> Map<out K, V>.map(transform: (Map.Entry<K, V>) -> R): List<R> {
     return mapTo(ArrayList<R>(size), transform)
diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt
index 2fabb56d79c..310780c11a4 100644
--- a/libraries/stdlib/common/src/generated/_Sequences.kt
+++ b/libraries/stdlib/common/src/generated/_Sequences.kt
@@ -854,6 +854,8 @@ public inline fun <T, K> Sequence<T>.groupingBy(crossinline keySelector: (T) ->
  * to each element in the original sequence.
  *
  * The operation is _intermediate_ and _stateless_.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 public fun <T, R> Sequence<T>.map(transform: (T) -> R): Sequence<R> {
     return TransformingSequence(this, transform)
diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt
index 8fa0be5e78d..683878bd918 100644
--- a/libraries/stdlib/common/src/generated/_Strings.kt
+++ b/libraries/stdlib/common/src/generated/_Strings.kt
@@ -828,6 +828,8 @@ public inline fun <K> CharSequence.groupingBy(crossinline keySelector: (Char) ->
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each character in the original char sequence.
+ * 
+ * @sample samples.text.Strings.map
  */
 public inline fun <R> CharSequence.map(transform: (Char) -> R): List<R> {
     return mapTo(ArrayList<R>(length), transform)
diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt
index 08aa642255d..758eb6a6660 100644
--- a/libraries/stdlib/common/src/generated/_UArrays.kt
+++ b/libraries/stdlib/common/src/generated/_UArrays.kt
@@ -4005,6 +4005,8 @@ public inline fun <K, V, M : MutableMap<in K, MutableList<V>>> UShortArray.group
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -4016,6 +4018,8 @@ public inline fun <R> UIntArray.map(transform: (UInt) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -4027,6 +4031,8 @@ public inline fun <R> ULongArray.map(transform: (ULong) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -4038,6 +4044,8 @@ public inline fun <R> UByteArray.map(transform: (UByte) -> R): List<R> {
 /**
  * Returns a list containing the results of applying the given [transform] function
  * to each element in the original array.
+ * 
+ * @sample samples.collections.Collections.Transformations.map
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt
index c8819de982d..1de750ddf8d 100644
--- a/libraries/stdlib/samples/test/samples/collections/collections.kt
+++ b/libraries/stdlib/samples/test/samples/collections/collections.kt
@@ -393,6 +393,12 @@ class Collections {
             assertPrints(chars.joinToString(limit = 5, truncated = "...!") { it.toUpperCase().toString() }, "A, B, C, D, E, ...!")
         }
 
+        @Sample
+        fun map() {
+            val numbers = listOf(1, 2, 3)
+            assertPrints(numbers.map { it * it }, "[1, 4, 9]")
+        }
+
         @Sample
         fun take() {
             val chars = ('a'..'z').toList()
diff --git a/libraries/stdlib/samples/test/samples/collections/maps.kt b/libraries/stdlib/samples/test/samples/collections/maps.kt
index c9c000d0104..1ea8cb95a16 100644
--- a/libraries/stdlib/samples/test/samples/collections/maps.kt
+++ b/libraries/stdlib/samples/test/samples/collections/maps.kt
@@ -277,7 +277,6 @@ class Maps {
             assertPrints(map2, "{beverage=2.7$, meal=12.4$}")
         }
 
-
         @Sample
         fun mapToSortedMap() {
             val map = mapOf(Pair("c", 3), Pair("b", 2), Pair("d", 1))
@@ -303,6 +302,16 @@ class Maps {
             assertPrints(props.getProperty("z", "fail"), "fail")
         }
 
+        @Sample
+        fun mapToList() {
+            val peopleToAge = mapOf("Alice" to 20, "Bob" to 21)
+            assertPrints(
+                peopleToAge.map { (name, age) -> "$name is $age years old" },
+                "[Alice is 20 years old, Bob is 21 years old]"
+            )
+            assertPrints(peopleToAge.map { it.value }, "[20, 21]")
+        }
+
     }
 
 }
diff --git a/libraries/stdlib/samples/test/samples/text/strings.kt b/libraries/stdlib/samples/test/samples/text/strings.kt
index f0fd8428a65..05e9579d950 100644
--- a/libraries/stdlib/samples/test/samples/text/strings.kt
+++ b/libraries/stdlib/samples/test/samples/text/strings.kt
@@ -284,4 +284,10 @@ class Strings {
         assertPrints(string.dropLastWhile { !it.isLetter() }, "<<<First Grade")
     }
 
+    @Sample
+    fun map() {
+        val string = "kotlin"
+        assertPrints(string.map { it.toUpperCase() }, "[K, O, T, L, I, N]")
+    }
+
 }
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
index bd08422d1b3..64d53433602 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt
@@ -92,6 +92,19 @@ object Mapping : TemplateGroupBase() {
             to each ${f.element} in the original ${f.collection}.
             """
         }
+
+        specialFor(Iterables, Sequences, ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) {
+            sample("samples.collections.Collections.Transformations.map")
+        }
+
+        specialFor(Maps) {
+            sample("samples.collections.Maps.Transformations.mapToList")
+        }
+
+        specialFor(CharSequences) {
+            sample("samples.text.Strings.map")
+        }
+
         typeParam("R")
         returns("List<R>")
         body(Iterables) {