KT-74034 Add samples for sortBy and sortByDescending functions
^KT-74034 fixed
Co-authored-by: Filipp Zhinkin <filipp.zhinkin@jetbrains.com>
Merge-request: KT-MR-23377
Merged-by: Filipp Zhinkin <filipp.zhinkin@jetbrains.com>
diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt
index 5253b6a..763efbf 100644
--- a/libraries/stdlib/common/src/generated/_Arrays.kt
+++ b/libraries/stdlib/common/src/generated/_Arrays.kt
@@ -6295,6 +6295,8 @@
*
* The sort is _stable_. It means that elements for which [selector] returned equal values preserve their order
* relative to each other after sorting.
+ *
+ * @sample samples.collections.Collections.Sorting.sortBy
*/
public inline fun <T, R : Comparable<R>> Array<out T>.sortBy(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareBy(selector))
@@ -6305,6 +6307,8 @@
*
* The sort is _stable_. It means that elements for which [selector] returned equal values preserve their order
* relative to each other after sorting.
+ *
+ * @sample samples.collections.Collections.Sorting.sortByDescending
*/
public inline fun <T, R : Comparable<R>> Array<out T>.sortByDescending(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareByDescending(selector))
diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt
index 281ec03..3e3c82c 100644
--- a/libraries/stdlib/common/src/generated/_Collections.kt
+++ b/libraries/stdlib/common/src/generated/_Collections.kt
@@ -1011,6 +1011,8 @@
*
* The sort is _stable_. It means that elements for which [selector] returned equal values preserve their order
* relative to each other after sorting.
+ *
+ * @sample samples.collections.Collections.Sorting.sortBy
*/
public inline fun <T, R : Comparable<R>> MutableList<T>.sortBy(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareBy(selector))
@@ -1021,6 +1023,8 @@
*
* The sort is _stable_. It means that elements for which [selector] returned equal values preserve their order
* relative to each other after sorting.
+ *
+ * @sample samples.collections.Collections.Sorting.sortByDescending
*/
public inline fun <T, R : Comparable<R>> MutableList<T>.sortByDescending(crossinline selector: (T) -> R?): Unit {
if (size > 1) sortWith(compareByDescending(selector))
diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt
index 6eb9602..ba51d2ff 100644
--- a/libraries/stdlib/samples/test/samples/collections/collections.kt
+++ b/libraries/stdlib/samples/test/samples/collections/collections.kt
@@ -1293,6 +1293,74 @@
}
@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 (ascending)
+ 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)]")
+
+ val breadBoxContent = mutableListOf(
+ Dish("🥯", 245, 4.8f),
+ Dish("🥨", 100, 5.0f),
+ Dish("🥐", 245, 4.9f)
+ )
+
+ // original order
+ assertPrints(breadBoxContent, "[Dish(🥯: 245 cal, taste 4.8/5), Dish(🥨: 100 cal, taste 5.0/5), Dish(🥐: 245 cal, taste 4.9/5)]")
+
+ // sort by calories (ascending)
+ breadBoxContent.sortBy { it.calories }
+ // note that the sorting is stable, so the 🥯 is before the 🥐
+ assertPrints(breadBoxContent, "[Dish(🥨: 100 cal, taste 5.0/5), Dish(🥯: 245 cal, taste 4.8/5), Dish(🥐: 245 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)
+ 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)]")
+
+ val breadBoxContent = mutableListOf(
+ Dish("🥯", 245, 4.8f),
+ Dish("🥨", 100, 5.0f),
+ Dish("🥐", 245, 4.9f)
+ )
+
+ // original order
+ assertPrints(breadBoxContent, "[Dish(🥯: 245 cal, taste 4.8/5), Dish(🥨: 100 cal, taste 5.0/5), Dish(🥐: 245 cal, taste 4.9/5)]")
+
+ // sort by calories (descending)
+ breadBoxContent.sortByDescending { it.calories }
+ // note that the sorting is stable, so the 🥯 is before the 🥐
+ assertPrints(breadBoxContent, "[Dish(🥯: 245 cal, taste 4.8/5), Dish(🥐: 245 cal, taste 4.9/5), Dish(🥨: 100 cal, taste 5.0/5)]")
+ }
+
+ @Sample
fun sortedBy() {
class Dish(val name: String, val calories: Int, val tasteRate: Float) {
override fun toString(): String = "Dish($name: $calories cal, taste $tasteRate/5)"
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
index 97381e4..f99f4c8 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt
@@ -424,6 +424,8 @@
returns("Unit")
typeParam("R : Comparable<R>")
specialFor(Lists) { receiver("MutableList<T>") }
+
+ sample("samples.collections.Collections.Sorting.sortBy")
body { """if (size > 1) sortWith(compareBy(selector))""" }
}
@@ -477,6 +479,8 @@
returns("Unit")
typeParam("R : Comparable<R>")
specialFor(Lists) { receiver("MutableList<T>") }
+
+ sample("samples.collections.Collections.Sorting.sortByDescending")
body {
"""if (size > 1) sortWith(compareByDescending(selector))""" }
