KT-20357 Add sortedBy() sample (#3283)

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

@@ -6162,6 +6162,8 @@ public fun <T> Array<out T>.sortedArrayWith(comparator: Comparator<in T>): Array
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
  * 
  * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <T, R : Comparable<R>> Array<out T>.sortedBy(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareBy(selector))
@@ -6169,6 +6171,8 @@ public inline fun <T, R : Comparable<R>> Array<out T>.sortedBy(crossinline selec
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> ByteArray.sortedBy(crossinline selector: (Byte) -> R?): List<Byte> {
     return sortedWith(compareBy(selector))
@@ -6176,6 +6180,8 @@ public inline fun <R : Comparable<R>> ByteArray.sortedBy(crossinline selector: (
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> ShortArray.sortedBy(crossinline selector: (Short) -> R?): List<Short> {
     return sortedWith(compareBy(selector))
@@ -6183,6 +6189,8 @@ public inline fun <R : Comparable<R>> ShortArray.sortedBy(crossinline selector:
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> IntArray.sortedBy(crossinline selector: (Int) -> R?): List<Int> {
     return sortedWith(compareBy(selector))
@@ -6190,6 +6198,8 @@ public inline fun <R : Comparable<R>> IntArray.sortedBy(crossinline selector: (I
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> LongArray.sortedBy(crossinline selector: (Long) -> R?): List<Long> {
     return sortedWith(compareBy(selector))
@@ -6197,6 +6207,8 @@ public inline fun <R : Comparable<R>> LongArray.sortedBy(crossinline selector: (
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> FloatArray.sortedBy(crossinline selector: (Float) -> R?): List<Float> {
     return sortedWith(compareBy(selector))
@@ -6204,6 +6216,8 @@ public inline fun <R : Comparable<R>> FloatArray.sortedBy(crossinline selector:
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> DoubleArray.sortedBy(crossinline selector: (Double) -> R?): List<Double> {
     return sortedWith(compareBy(selector))
@@ -6211,6 +6225,8 @@ public inline fun <R : Comparable<R>> DoubleArray.sortedBy(crossinline selector:
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> BooleanArray.sortedBy(crossinline selector: (Boolean) -> R?): List<Boolean> {
     return sortedWith(compareBy(selector))
@@ -6218,6 +6234,8 @@ public inline fun <R : Comparable<R>> BooleanArray.sortedBy(crossinline selector
 
 /**
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <R : Comparable<R>> CharArray.sortedBy(crossinline selector: (Char) -> R?): List<Char> {
     return sortedWith(compareBy(selector))

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

@@ -964,6 +964,8 @@ public fun <T : Comparable<T>> Iterable<T>.sorted(): List<T> {
  * Returns a list of all elements sorted according to natural sort order of the value returned by specified [selector] function.
  * 
  * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <T, R : Comparable<R>> Iterable<T>.sortedBy(crossinline selector: (T) -> R?): List<T> {
     return sortedWith(compareBy(selector))

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

@@ -533,6 +533,8 @@ public fun <T : Comparable<T>> Sequence<T>.sorted(): Sequence<T> {
  * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting.
  *
  * The operation is _intermediate_ and _stateful_.
+ * 
+ * @sample samples.collections.Collections.Sorting.sortedBy
  */
 public inline fun <T, R : Comparable<R>> Sequence<T>.sortedBy(crossinline selector: (T) -> R?): Sequence<T> {
     return sortedWith(compareBy(selector))

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

@@ -809,6 +809,14 @@ class Collections {
             assertPrints(people.joinToString(), "Sweyn Forkbeard, Ragnar Lodbrok, Bjorn Ironside")
         }
 
+        @Sample
+        fun sortedBy() {
+            val list = listOf("aaa", "cc", "bbbb")
+            val sorted = list.sortedBy { it.length }
+
+            assertPrints(list, "[aaa, cc, bbbb]")
+            assertPrints(sorted, "[cc, aaa, bbbb]")
+        }
     }
 
     class Filtering {

libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt

@@ -432,7 +432,6 @@ object Ordering : TemplateGroupBase() {
         if (f != ArraysOfPrimitives) {
             appendStableSortNote()
         }
-
         specialFor(Sequences) {
             returns("SELF")
             doc {
@@ -441,6 +440,8 @@ object Ordering : TemplateGroupBase() {
             appendStableSortNote()
             sequenceClassification(intermediate, stateful)
         }
+        sample("samples.collections.Collections.Sorting.sortedBy")
+
         body {
             "return sortedWith(compareBy(selector))"
         }