[KT-74034] feat: add samples for sortBy and sortByDescending

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

diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt
index 6eb9602..bde171f 100644
--- a/libraries/stdlib/samples/test/samples/collections/collections.kt
+++ b/libraries/stdlib/samples/test/samples/collections/collections.kt
@@ -1261,6 +1261,60 @@
     class Sorting {
 
         @Sample
+        fun sortBy() {
+            class Dish(val name: String, val calories: Int, val tasteRate: Float) {
+                override fun toString(): String = "Dish($name: $calories cal, taste $tasteRate/5)"
+            }
+
+            val fridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // Original order
+            assertPrints(fridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // Sort by taste rate (in-place)
+            fridgeContent.sortBy { it.tasteRate }
+            assertPrints(fridgeContent, "[Dish(🥦: 34 cal, taste 2.3/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // Create a new list with the same elements
+            val newFridgeContent = mutableListOf<Dish>().apply { addAll(fridgeContent) }
+            
+            // Sort by calories (in-place)
+            newFridgeContent.sortBy { it.calories }
+            // Note that the sorting is stable, so the 🥦 is before the 🧃
+            assertPrints(newFridgeContent, "[Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5), Dish(🍨: 207 cal, taste 4.7/5)]")
+            
+            // The original list remains unchanged after sorting the new list
+            assertPrints(fridgeContent, "[Dish(🥦: 34 cal, taste 2.3/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+        }
+        
+        @Sample
+        fun sortByDescending() {
+            class Dish(val name: String, val calories: Int, val tasteRate: Float) {
+                override fun toString(): String = "Dish($name: $calories cal, taste $tasteRate/5)"
+            }
+
+            val fridgeContent = mutableListOf(Dish("🍨", 207, 4.7f), Dish("🥦", 34, 2.3f), Dish("🧃", 34, 4.9f))
+            
+            // Original order
+            assertPrints(fridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5), Dish(🧃: 34 cal, taste 4.9/5)]")
+            
+            // Sort by taste rate descending (in-place)
+            fridgeContent.sortByDescending { it.tasteRate }
+            assertPrints(fridgeContent, "[Dish(🧃: 34 cal, taste 4.9/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5)]")
+            
+            // Create a new list with the same elements
+            val newFridgeContent = mutableListOf<Dish>().apply { addAll(fridgeContent) }
+            
+            // Sort by calories descending (in-place)
+            newFridgeContent.sortByDescending { it.calories }
+            // Note that the sorting is stable, so the order of items with equal calories is preserved
+            assertPrints(newFridgeContent, "[Dish(🍨: 207 cal, taste 4.7/5), Dish(🧃: 34 cal, taste 4.9/5), Dish(🥦: 34 cal, taste 2.3/5)]")
+            
+            // The original list remains unchanged after sorting the new list
+            assertPrints(fridgeContent, "[Dish(🧃: 34 cal, taste 4.9/5), Dish(🍨: 207 cal, taste 4.7/5), Dish(🥦: 34 cal, taste 2.3/5)]")
+        }
+
+        @Sample
         fun sortMutableList() {
             val mutableList = mutableListOf(4, 3, 2, 1)
 

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

diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
index acd7cb9..e1f49d5 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
@@ -424,6 +424,12 @@
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
+        
+        when (f) {
+            Lists -> {
+                sample("samples.collections.Collections.Sorting.sortBy")
+            }
+        }
 
         body { """if (size > 1) sortWith(compareBy(selector))""" }
     }
@@ -477,6 +483,12 @@
         returns("Unit")
         typeParam("R : Comparable<R>")
         specialFor(Lists) { receiver("MutableList<T>") }
+        
+        when (f) {
+            Lists -> {
+                sample("samples.collections.Collections.Sorting.sortByDescending")
+            }
+        }
 
         body {
             """if (size > 1) sortWith(compareByDescending(selector))""" }