diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index d809c3bd83f22..2aae07f587dc8 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -6844,36 +6844,50 @@ public expect fun Array.plusElement(element: T): Array /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun IntArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun LongArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun ByteArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun ShortArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun DoubleArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun FloatArray.sort(): Unit /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public expect fun CharArray.sort(): Unit @@ -6881,6 +6895,8 @@ public expect fun CharArray.sort(): Unit * Sorts the array in-place according to the natural order of its elements. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Arrays.Sorting.sortArrayOfComparable */ public expect fun > Array.sort(): Unit diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 50e34a2d79af2..d18f9bf4c605f 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt @@ -3484,6 +3484,8 @@ public inline operator fun UShortArray.plus(elements: UShortArray): UShortArray /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3493,6 +3495,8 @@ public fun UIntArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3502,6 +3506,8 @@ public fun ULongArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3511,6 +3517,8 @@ public fun UByteArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt b/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt index 8e538974f3514..1eb3aab828341 100644 --- a/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt +++ b/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt @@ -1403,6 +1403,8 @@ public actual inline fun Array.plusElement(element: T): Array { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun IntArray.sort(): Unit { this.asDynamic().sort() @@ -1410,6 +1412,8 @@ public actual fun IntArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun LongArray.sort(): Unit { if (size > 1) sort { a: Long, b: Long -> a.compareTo(b) } @@ -1417,6 +1421,8 @@ public actual fun LongArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun ByteArray.sort(): Unit { this.asDynamic().sort() @@ -1424,6 +1430,8 @@ public actual fun ByteArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun ShortArray.sort(): Unit { this.asDynamic().sort() @@ -1431,6 +1439,8 @@ public actual fun ShortArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun DoubleArray.sort(): Unit { this.asDynamic().sort() @@ -1438,6 +1448,8 @@ public actual fun DoubleArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun FloatArray.sort(): Unit { this.asDynamic().sort() @@ -1445,6 +1457,8 @@ public actual fun FloatArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun CharArray.sort(): Unit { this.asDynamic().sort(::primitiveCompareTo) @@ -1454,6 +1468,8 @@ public actual fun CharArray.sort(): Unit { * Sorts the array in-place according to the natural order of its elements. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Arrays.Sorting.sortArrayOfComparable */ public actual fun > Array.sort(): Unit { if (size > 1) sortArray(this) diff --git a/libraries/stdlib/js/src/generated/_ArraysJs.kt b/libraries/stdlib/js/src/generated/_ArraysJs.kt index 7dbbc84c5b288..f0aac52d0a2e7 100644 --- a/libraries/stdlib/js/src/generated/_ArraysJs.kt +++ b/libraries/stdlib/js/src/generated/_ArraysJs.kt @@ -1415,6 +1415,8 @@ public actual inline fun Array.plusElement(element: T): Array { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun IntArray.sort(): Unit { @@ -1423,6 +1425,8 @@ public actual fun IntArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun LongArray.sort(): Unit { if (size > 1) sort { a: Long, b: Long -> a.compareTo(b) } @@ -1430,6 +1434,8 @@ public actual fun LongArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun ByteArray.sort(): Unit { @@ -1438,6 +1444,8 @@ public actual fun ByteArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun ShortArray.sort(): Unit { @@ -1446,6 +1454,8 @@ public actual fun ShortArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun DoubleArray.sort(): Unit { @@ -1454,6 +1464,8 @@ public actual fun DoubleArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun FloatArray.sort(): Unit { @@ -1462,6 +1474,8 @@ public actual fun FloatArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ @library("primitiveArraySort") public actual fun CharArray.sort(): Unit { @@ -1472,6 +1486,8 @@ public actual fun CharArray.sort(): Unit { * Sorts the array in-place according to the natural order of its elements. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Arrays.Sorting.sortArrayOfComparable */ public actual fun > Array.sort(): Unit { if (size > 1) sortArray(this) diff --git a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt index 1688df38ffae8..1c8ab9ad9ac8e 100644 --- a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt @@ -1791,6 +1791,8 @@ public actual inline fun Array.plusElement(element: T): Array { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun IntArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1798,6 +1800,8 @@ public actual fun IntArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun LongArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1805,6 +1809,8 @@ public actual fun LongArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun ByteArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1812,6 +1818,8 @@ public actual fun ByteArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun ShortArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1819,6 +1827,8 @@ public actual fun ShortArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun DoubleArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1826,6 +1836,8 @@ public actual fun DoubleArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun FloatArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1833,6 +1845,8 @@ public actual fun FloatArray.sort(): Unit { /** * Sorts the array in-place. + * + * @sample samples.collections.Arrays.Sorting.sortArray */ public actual fun CharArray.sort(): Unit { if (size > 1) java.util.Arrays.sort(this) @@ -1842,6 +1856,8 @@ public actual fun CharArray.sort(): Unit { * Sorts the array in-place according to the natural order of its elements. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Arrays.Sorting.sortArrayOfComparable */ @kotlin.internal.InlineOnly public actual inline fun > Array.sort(): Unit { @@ -1864,6 +1880,8 @@ public fun Array.sort(): Unit { * Sorts a range in the array in-place. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @sample samples.collections.Arrays.Sorting.sortRangeOfComparable */ public fun Array.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1871,6 +1889,8 @@ 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 */ public fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1878,6 +1898,8 @@ 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 */ public fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1885,6 +1907,8 @@ 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 */ public fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1892,6 +1916,8 @@ 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 */ public fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1899,6 +1925,8 @@ 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 */ public fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1906,6 +1934,8 @@ 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 */ public fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { java.util.Arrays.sort(this, fromIndex, toIndex) @@ -1913,6 +1943,8 @@ 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 */ 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 7d320b086adb2..d3c53e783f000 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 { if (size > 1) java.util.Collections.sort(this) diff --git a/libraries/stdlib/samples/test/samples/collections/arrays.kt b/libraries/stdlib/samples/test/samples/collections/arrays.kt index 2a6a5152d91f4..e609aca7ac4b4 100644 --- a/libraries/stdlib/samples/test/samples/collections/arrays.kt +++ b/libraries/stdlib/samples/test/samples/collections/arrays.kt @@ -131,4 +131,53 @@ class Arrays { } } + class Sorting { + + @Sample + fun sortArray() { + val intArray = intArrayOf(4, 3, 2, 1) + + assertPrints(intArray.joinToString(), "4, 3, 2, 1") + + intArray.sort() + + 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) + } + + } + + val people = arrayOf( + 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.sort() + + assertPrints(people.joinToString(), "Person(firstName=Sweyn, lastName=Forkbeard), Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok)") + + } + + @Sample + fun sortRangeOfArray() { + val intArray = intArrayOf(4, 3, 2, 1) + + assertPrints(intArray.joinToString(), "4, 3, 2, 1") + + intArray.sort(0, 3) + + assertPrints(intArray.joinToString(), "2, 3, 4, 1") + } + + } + } \ 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 1de750ddf8d12..32a3dd8e5a06d 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -561,4 +561,41 @@ class Collections { assertPrints(emptyList.elementAtOrElse(0) { "no int" }, "no int") } } + + class Sorting { + + @Sample + fun sortMutableList() { + val mutableList = mutableListOf(4, 3, 2, 1) + + assertPrints(mutableList.joinToString(), "4, 3, 2, 1") + + mutableList.sort() + + 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) + } + + } + + val people = arrayOf( + 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.sort(0, 2) + + assertPrints(people.joinToString(), "Person(firstName=Bjorn, lastName=Ironside), Person(firstName=Ragnar, lastName=Lodbrok), Person(firstName=Sweyn, lastName=Forkbeard)") + } + + } } \ No newline at end of file diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt index 0649daacca26e..5bd792e148aa5 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt @@ -1016,8 +1016,12 @@ object ArrayOps : TemplateGroupBase() { typeParam("T : Comparable") doc { "Sorts the array in-place according to the natural order of its elements." } appendStableSortNote() + specialFor(ArraysOfObjects) { + sample("samples.collections.Arrays.Sorting.sortArrayOfComparable") + } specialFor(ArraysOfPrimitives, ArraysOfUnsigned) { doc { "Sorts the array in-place." } + sample("samples.collections.Arrays.Sorting.sortArray") } returns("Unit") @@ -1143,6 +1147,7 @@ object ArrayOps : TemplateGroupBase() { specialFor(ArraysOfObjects) { appendStableSortNote() } + sample("samples.collections.Arrays.Sorting.sortRangeOfComparable") returns("Unit") body { "java.util.Arrays.sort(this, fromIndex, toIndex)"