diff --git a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt index 5efee83ac13..6c2cdd5c009 100644 --- a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt @@ -1818,7 +1818,7 @@ public fun Array.sort(): Unit { * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ public fun Array.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1827,7 +1827,7 @@ public fun Array.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1836,7 +1836,7 @@ public fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1845,7 +1845,7 @@ public fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1854,7 +1854,7 @@ public fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1863,7 +1863,7 @@ public fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1872,7 +1872,7 @@ public fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1881,7 +1881,7 @@ public fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * - * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable + * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ public fun CharArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) diff --git a/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt b/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt index d3c53e783f0..8fd30762dae 100644 --- a/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt +++ b/libraries/stdlib/jvm/src/kotlin/collections/MutableCollectionsJVM.kt @@ -24,6 +24,7 @@ public inline fun MutableList.sort(comparison: (T, T) -> Int): Unit = thr * Sorts elements in the list in-place according to their natural sort order. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * * @sample samples.collections.Collections.Sorting.sortMutableList */ public actual fun > MutableList.sort(): Unit { @@ -34,6 +35,8 @@ public actual fun > MutableList.sort(): Unit { * Sorts elements in the list in-place according to the order specified with [comparator]. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Collections.Sorting.sortMutableListWith */ public actual fun MutableList.sortWith(comparator: Comparator): Unit { if (size > 1) java.util.Collections.sort(this, comparator) diff --git a/libraries/stdlib/samples/test/samples/collections/arrays.kt b/libraries/stdlib/samples/test/samples/collections/arrays.kt index e609aca7ac4..b70cc0f4705 100644 --- a/libraries/stdlib/samples/test/samples/collections/arrays.kt +++ b/libraries/stdlib/samples/test/samples/collections/arrays.kt @@ -137,20 +137,20 @@ class Arrays { fun sortArray() { val intArray = intArrayOf(4, 3, 2, 1) + // before sorting assertPrints(intArray.joinToString(), "4, 3, 2, 1") intArray.sort() + // after sorting assertPrints(intArray.joinToString(), "1, 2, 3, 4") } @Sample fun sortArrayOfComparable() { - data class Person(val firstName: String, val lastName: String) : Comparable { - override fun compareTo(other: Person): Int { - return lastName.compareTo(other.lastName) - } - + class Person(val firstName: String, val lastName: String) : Comparable { + override fun compareTo(other: Person): Int = this.lastName.compareTo(other.lastName) + override fun toString(): String = "$firstName $lastName" } val people = arrayOf( @@ -159,11 +159,13 @@ class Arrays { Person("Sweyn", "Forkbeard") ) - assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)") + // before sorting + assertPrints(people.joinToString(), "Ragnar Lodbrok, Bjorn Ironside, Sweyn Forkbeard") people.sort() - assertPrints(people.joinToString(), "Person(firstName=Sweyn, lastName=Forkbeard), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok)") + // after sorting + assertPrints(people.joinToString(), "Sweyn Forkbeard, Bjorn Ironside, Ragnar Lodbrok") } @@ -171,13 +173,37 @@ class Arrays { fun sortRangeOfArray() { val intArray = intArrayOf(4, 3, 2, 1) + // before sorting assertPrints(intArray.joinToString(), "4, 3, 2, 1") intArray.sort(0, 3) + // after sorting assertPrints(intArray.joinToString(), "2, 3, 4, 1") } + @Sample + fun sortRangeOfArrayOfComparable() { + class Person(val firstName: String, val lastName: String) : Comparable { + override fun compareTo(other: Person): Int = this.lastName.compareTo(other.lastName) + override fun toString(): String = "$firstName $lastName" + } + + val people = arrayOf( + Person("Ragnar", "Lodbrok"), + Person("Bjorn", "Ironside"), + Person("Sweyn", "Forkbeard") + ) + + // before sorting + assertPrints(people.joinToString(), "Ragnar Lodbrok, Bjorn Ironside, Sweyn Forkbeard") + + people.sort(0, 2) + + // after sorting + assertPrints(people.joinToString(), "Bjorn Ironside, Ragnar Lodbrok, Sweyn Forkbeard") + } + } } \ No newline at end of file diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt index 32a3dd8e5a0..9f4370619ad 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -568,33 +568,32 @@ class Collections { fun sortMutableList() { val mutableList = mutableListOf(4, 3, 2, 1) + // before sorting assertPrints(mutableList.joinToString(), "4, 3, 2, 1") mutableList.sort() + // after sorting assertPrints(mutableList.joinToString(), "1, 2, 3, 4") } @Sample - fun sortRangeOfComparable() { - data class Person(val firstName: String, val lastName: String) : Comparable { - override fun compareTo(other: Person): Int { - return lastName.compareTo(other.lastName) - } - + fun sortMutableListWith() { + // non-comparable class + class Person(val firstName: String, val lastName: String) { + override fun toString(): String = "$firstName $lastName" } - val people = arrayOf( + val people = mutableListOf( Person("Ragnar", "Lodbrok"), Person("Bjorn", "Ironside"), Person("Sweyn", "Forkbeard") ) - assertPrints(people.joinToString(), "Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Sweyn, lastName=Forkbeard)") + people.sortWith(compareByDescending { it.firstName }) - people.sort(0, 2) - - assertPrints(people.joinToString(), "Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Sweyn, lastName=Forkbeard)") + // after sorting + assertPrints(people.joinToString(), "Sweyn Forkbeard, Ragnar Lodbrok, Bjorn Ironside") } } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt index 3fe9372075f..dd3a2e8cdf6 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt @@ -1146,8 +1146,11 @@ object ArrayOps : TemplateGroupBase() { doc { "Sorts a range in the array in-place." } specialFor(ArraysOfObjects) { appendStableSortNote() + sample("samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable") + } + specialFor(ArraysOfPrimitives) { + sample("samples.collections.Arrays.Sorting.sortRangeOfArray") } - sample("samples.collections.Arrays.Sorting.sortRangeOfComparable") returns("Unit") body { "java.util.Arrays.sort(this, fromIndex, toIndex)"