From 0c7b04a4956933253ca275089d4c63369d01754c Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Tue, 21 Apr 2020 05:59:10 +0300 Subject: [PATCH] Document fromIndex and toIndex parameters #KT-38388 --- .../stdlib/common/src/generated/_Arrays.kt | 255 +++++++++++++++--- .../stdlib/common/src/generated/_UArrays.kt | 116 ++++++-- .../stdlib/js-ir/src/generated/_ArraysJs.kt | 153 ++++++++--- .../stdlib/js/src/generated/_ArraysJs.kt | 153 ++++++++--- .../stdlib/jvm/src/generated/_ArraysJvm.kt | 223 ++++++++++++--- .../stdlib/jvm/src/generated/_UArraysJvm.kt | 28 ++ .../stdlib/test/collections/ArraysTest.kt | 92 ++++--- .../kotlin-stdlib-gen/src/templates/Arrays.kt | 73 +++-- .../src/templates/Ordering.kt | 9 +- 9 files changed, 893 insertions(+), 209 deletions(-) diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index e971178f6e3..32e42d4e224 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -5251,6 +5251,12 @@ public fun CharArray.reverse(): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun Array.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5268,6 +5274,12 @@ public fun Array.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun ByteArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5285,6 +5297,12 @@ public fun ByteArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun ShortArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5302,6 +5320,12 @@ public fun ShortArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun IntArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5319,6 +5343,12 @@ public fun IntArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun LongArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5336,6 +5366,12 @@ public fun LongArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun FloatArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5353,6 +5389,12 @@ public fun FloatArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun DoubleArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5370,6 +5412,12 @@ public fun DoubleArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun BooleanArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -5387,6 +5435,12 @@ public fun BooleanArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun CharArray.reverse(fromIndex: Int, toIndex: Int): Unit { @@ -7272,8 +7326,11 @@ public expect fun Array.copyOf(newSize: Int): Array /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @Suppress("NO_ACTUAL_FOR_EXPECT") public expect fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Array @@ -7281,72 +7338,96 @@ public expect fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Array< /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): BooleanArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7357,8 +7438,8 @@ public expect fun Array.fill(element: T, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7369,8 +7450,8 @@ public expect fun ByteArray.fill(element: Byte, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7381,8 +7462,8 @@ public expect fun ShortArray.fill(element: Short, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7393,8 +7474,8 @@ public expect fun IntArray.fill(element: Int, fromIndex: Int = 0, toIndex: Int = /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7405,8 +7486,8 @@ public expect fun LongArray.fill(element: Long, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7417,8 +7498,8 @@ public expect fun FloatArray.fill(element: Float, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7429,8 +7510,8 @@ public expect fun DoubleArray.fill(element: Double, fromIndex: Int = 0, toIndex: /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7441,8 +7522,8 @@ public expect fun BooleanArray.fill(element: Boolean, fromIndex: Int = 0, toInde /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -7909,6 +7990,12 @@ public expect fun > Array.sort(): Unit * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ @SinceKotlin("1.4") @@ -7917,6 +8004,12 @@ public expect fun > Array.sort(fromIndex: Int = 0, toIn /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7925,6 +8018,12 @@ public expect fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7933,6 +8032,12 @@ public expect fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7941,6 +8046,12 @@ public expect fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7949,6 +8060,12 @@ public expect fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7957,6 +8074,12 @@ public expect fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7965,6 +8088,12 @@ public expect fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Uni /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -7975,6 +8104,12 @@ public expect fun CharArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit * The elements are sorted descending according to their natural sort order. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun > Array.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -7984,6 +8119,12 @@ public fun > Array.sortDescending(fromIndex: Int, toInd /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun ByteArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -7994,6 +8135,12 @@ public fun ByteArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun ShortArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8004,6 +8151,12 @@ public fun ShortArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun IntArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8014,6 +8167,12 @@ public fun IntArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun LongArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8024,6 +8183,12 @@ public fun LongArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun FloatArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8034,6 +8199,12 @@ public fun FloatArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun DoubleArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8044,6 +8215,12 @@ public fun DoubleArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") public fun CharArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { @@ -8062,6 +8239,12 @@ public expect fun Array.sortWith(comparator: Comparator): Unit * Sorts a range in the array in-place with the given [comparator]. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public expect fun Array.sortWith(comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size): Unit diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 2336ddb5787..30da9e3c9fa 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt @@ -2616,6 +2616,12 @@ public inline fun UShortArray.reverse(): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -2626,6 +2632,12 @@ public inline fun UIntArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -2636,6 +2648,12 @@ public inline fun ULongArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -2646,6 +2664,12 @@ public inline fun UByteArray.reverse(fromIndex: Int, toIndex: Int): Unit { /** * Reverses elements of the array in the specified range in-place. + * + * @param fromIndex the start of the range (inclusive) to reverse. + * @param toIndex the end of the range (exclusive) to reverse. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3621,8 +3645,11 @@ public inline fun UShortArray.copyOf(newSize: Int): UShortArray { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3634,8 +3661,11 @@ public inline fun UIntArray.copyOfRange(fromIndex: Int, toIndex: Int): UIntArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3647,8 +3677,11 @@ public inline fun ULongArray.copyOfRange(fromIndex: Int, toIndex: Int): ULongArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3660,8 +3693,11 @@ public inline fun UByteArray.copyOfRange(fromIndex: Int, toIndex: Int): UByteArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -3673,8 +3709,8 @@ public inline fun UShortArray.copyOfRange(fromIndex: Int, toIndex: Int): UShortA /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -3688,8 +3724,8 @@ public fun UIntArray.fill(element: UInt, fromIndex: Int = 0, toIndex: Int = size /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -3703,8 +3739,8 @@ public fun ULongArray.fill(element: ULong, fromIndex: Int = 0, toIndex: Int = si /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -3718,8 +3754,8 @@ public fun UByteArray.fill(element: UByte, fromIndex: Int = 0, toIndex: Int = si /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -3968,6 +4004,12 @@ public fun UShortArray.sort(): Unit { /** * Sorts a range in the array in-place. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3978,6 +4020,12 @@ public fun UIntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3988,6 +4036,12 @@ public fun ULongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -3998,6 +4052,12 @@ public fun UByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -4009,6 +4069,12 @@ public fun UShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -4020,6 +4086,12 @@ public fun UIntArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -4031,6 +4103,12 @@ public fun ULongArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -4042,6 +4120,12 @@ public fun UByteArray.sortDescending(fromIndex: Int, toIndex: Int): Unit { /** * Sorts elements of the array in the specified range in-place. * The elements are sorted descending according to their natural sort order. + * + * @param fromIndex the start of the range (inclusive) to sort. + * @param toIndex the end of the range (exclusive) to sort. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt b/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt index 80dcf6c9747..85090216f5d 100644 --- a/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt +++ b/libraries/stdlib/js-ir/src/generated/_ArraysJs.kt @@ -1268,8 +1268,11 @@ public actual fun Array.copyOf(newSize: Int): Array { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @Suppress("ACTUAL_WITHOUT_EXPECT") public actual fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Array { @@ -1280,8 +1283,11 @@ public actual fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Ar /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1291,8 +1297,11 @@ public actual fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1302,8 +1311,11 @@ public actual fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1313,8 +1325,11 @@ public actual fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1324,8 +1339,11 @@ public actual fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1335,8 +1353,11 @@ public actual fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1346,8 +1367,11 @@ public actual fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleA /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): BooleanArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1357,8 +1381,11 @@ public actual fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): Boolea /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1368,8 +1395,8 @@ public actual fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1384,8 +1411,8 @@ public actual fun Array.fill(element: T, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1400,8 +1427,8 @@ public actual fun ByteArray.fill(element: Byte, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1416,8 +1443,8 @@ public actual fun ShortArray.fill(element: Short, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1432,8 +1459,8 @@ public actual fun IntArray.fill(element: Int, fromIndex: Int = 0, toIndex: Int = /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1448,8 +1475,8 @@ public actual fun LongArray.fill(element: Long, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1464,8 +1491,8 @@ public actual fun FloatArray.fill(element: Float, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1480,8 +1507,8 @@ public actual fun DoubleArray.fill(element: Double, fromIndex: Int = 0, toIndex: /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1496,8 +1523,8 @@ public actual fun BooleanArray.fill(element: Boolean, fromIndex: Int = 0, toInde /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1831,6 +1858,12 @@ public fun Array.sort(comparison: (a: T, b: T) -> Int): Unit { * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ @SinceKotlin("1.4") @@ -1843,6 +1876,12 @@ public actual fun > Array.sort(fromIndex: Int = 0, toIn /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1856,6 +1895,12 @@ public actual fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1869,6 +1914,12 @@ public actual fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1882,6 +1933,12 @@ public actual fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1894,6 +1951,12 @@ public actual fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1907,6 +1970,12 @@ public actual fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1920,6 +1989,12 @@ public actual fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Uni /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1998,6 +2073,12 @@ public actual fun Array.sortWith(comparator: Comparator): Unit * Sorts a range in the array in-place with the given [comparator]. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") diff --git a/libraries/stdlib/js/src/generated/_ArraysJs.kt b/libraries/stdlib/js/src/generated/_ArraysJs.kt index df2f1a01cdd..d8d7cb88ba0 100644 --- a/libraries/stdlib/js/src/generated/_ArraysJs.kt +++ b/libraries/stdlib/js/src/generated/_ArraysJs.kt @@ -1298,8 +1298,11 @@ public actual fun Array.copyOf(newSize: Int): Array { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @Suppress("ACTUAL_WITHOUT_EXPECT") public actual fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Array { @@ -1310,8 +1313,11 @@ public actual fun Array.copyOfRange(fromIndex: Int, toIndex: Int): Ar /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1321,8 +1327,11 @@ public actual fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): ByteArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1332,8 +1341,11 @@ public actual fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): ShortArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1343,8 +1355,11 @@ public actual fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): IntArray { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1354,8 +1369,11 @@ public actual fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): LongArray /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1365,8 +1383,11 @@ public actual fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): FloatArr /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1376,8 +1397,11 @@ public actual fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): DoubleA /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): BooleanArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1387,8 +1411,11 @@ public actual fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): Boolea /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public actual fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray { AbstractList.checkRangeIndexes(fromIndex, toIndex, size) @@ -1398,8 +1425,8 @@ public actual fun CharArray.copyOfRange(fromIndex: Int, toIndex: Int): CharArray /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1414,8 +1441,8 @@ public actual fun Array.fill(element: T, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1430,8 +1457,8 @@ public actual fun ByteArray.fill(element: Byte, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1446,8 +1473,8 @@ public actual fun ShortArray.fill(element: Short, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1462,8 +1489,8 @@ public actual fun IntArray.fill(element: Int, fromIndex: Int = 0, toIndex: Int = /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1478,8 +1505,8 @@ public actual fun LongArray.fill(element: Long, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1494,8 +1521,8 @@ public actual fun FloatArray.fill(element: Float, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1510,8 +1537,8 @@ public actual fun DoubleArray.fill(element: Double, fromIndex: Int = 0, toIndex: /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1526,8 +1553,8 @@ public actual fun BooleanArray.fill(element: Boolean, fromIndex: Int = 0, toInde /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1849,6 +1876,12 @@ public fun Array.sort(comparison: (a: T, b: T) -> Int): Unit { * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ @SinceKotlin("1.4") @@ -1861,6 +1894,12 @@ public actual fun > Array.sort(fromIndex: Int = 0, toIn /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1874,6 +1913,12 @@ public actual fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1887,6 +1932,12 @@ public actual fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1900,6 +1951,12 @@ public actual fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1912,6 +1969,12 @@ public actual fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1925,6 +1988,12 @@ public actual fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -1938,6 +2007,12 @@ public actual fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Uni /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @SinceKotlin("1.4") @@ -2017,6 +2092,12 @@ public actual fun Array.sortWith(comparator: Comparator): Unit * Sorts a range in the array in-place with the given [comparator]. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.4") @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") diff --git a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt index 711f3fe9138..8282dd2eec7 100644 --- a/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_ArraysJvm.kt @@ -247,10 +247,18 @@ public actual fun CharArray.asList(): List { * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the element to search for. + * @param comparator the comparator according to which this array is sorted. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted according to the specified [comparator]. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun Array.binarySearch(element: T, comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element, comparator) @@ -262,10 +270,17 @@ public fun Array.binarySearch(element: T, comparator: Comparator Array.binarySearch(element: T, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -277,10 +292,17 @@ public fun Array.binarySearch(element: T, fromIndex: Int = 0, toIndex * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -292,10 +314,17 @@ public fun ByteArray.binarySearch(element: Byte, fromIndex: Int = 0, toIndex: In * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -307,10 +336,17 @@ public fun ShortArray.binarySearch(element: Short, fromIndex: Int = 0, toIndex: * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -322,10 +358,17 @@ public fun IntArray.binarySearch(element: Int, fromIndex: Int = 0, toIndex: Int * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -337,10 +380,17 @@ public fun LongArray.binarySearch(element: Long, fromIndex: Int = 0, toIndex: In * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -352,10 +402,17 @@ public fun FloatArray.binarySearch(element: Float, fromIndex: Int = 0, toIndex: * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -367,10 +424,17 @@ public fun DoubleArray.binarySearch(element: Double, fromIndex: Int = 0, toIndex * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ public fun CharArray.binarySearch(element: Char, fromIndex: Int = 0, toIndex: Int = size): Int { return java.util.Arrays.binarySearch(this, fromIndex, toIndex, element) @@ -1556,8 +1620,11 @@ public actual inline fun Array.copyOf(newSize: Int): Array { /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1573,8 +1640,11 @@ public actual inline fun Array.copyOfRange(fromIndex: Int, toIndex: Int): /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1590,8 +1660,11 @@ public actual inline fun ByteArray.copyOfRange(fromIndex: Int, toIndex: Int): By /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1607,8 +1680,11 @@ public actual inline fun ShortArray.copyOfRange(fromIndex: Int, toIndex: Int): S /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1624,8 +1700,11 @@ public actual inline fun IntArray.copyOfRange(fromIndex: Int, toIndex: Int): Int /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1641,8 +1720,11 @@ public actual inline fun LongArray.copyOfRange(fromIndex: Int, toIndex: Int): Lo /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1658,8 +1740,11 @@ public actual inline fun FloatArray.copyOfRange(fromIndex: Int, toIndex: Int): F /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1675,8 +1760,11 @@ public actual inline fun DoubleArray.copyOfRange(fromIndex: Int, toIndex: Int): /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1692,8 +1780,11 @@ public actual inline fun BooleanArray.copyOfRange(fromIndex: Int, toIndex: Int): /** * Returns a new array which is a copy of the specified range of the original array. * - * @param fromIndex the start of the range (inclusive), must be in `0..array.size` - * @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + * @param fromIndex the start of the range (inclusive) to copy. + * @param toIndex the end of the range (exclusive) to copy. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @JvmName("copyOfRangeInline") @kotlin.internal.InlineOnly @@ -1781,8 +1872,8 @@ internal fun CharArray.copyOfRangeImpl(fromIndex: Int, toIndex: Int): CharArray /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1795,8 +1886,8 @@ public actual fun Array.fill(element: T, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1809,8 +1900,8 @@ public actual fun ByteArray.fill(element: Byte, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1823,8 +1914,8 @@ public actual fun ShortArray.fill(element: Short, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1837,8 +1928,8 @@ public actual fun IntArray.fill(element: Int, fromIndex: Int = 0, toIndex: Int = /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1851,8 +1942,8 @@ public actual fun LongArray.fill(element: Long, fromIndex: Int = 0, toIndex: Int /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1865,8 +1956,8 @@ public actual fun FloatArray.fill(element: Float, fromIndex: Int = 0, toIndex: I /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1879,8 +1970,8 @@ public actual fun DoubleArray.fill(element: Double, fromIndex: Int = 0, toIndex: /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -1893,8 +1984,8 @@ public actual fun BooleanArray.fill(element: Boolean, fromIndex: Int = 0, toInde /** * Fills this array or its subrange with the specified [element] value. * - * @param fromIndex the start of the range (inclusive), 0 by default. - * @param toIndex the end of the range (exclusive), size of this array by default. + * @param fromIndex the start of the range (inclusive) to fill, 0 by default. + * @param toIndex the end of the range (exclusive) to fill, size of this array by default. * * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. @@ -2283,6 +2374,12 @@ public fun Array.sort(): Unit { * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ @SinceKotlin("1.4") @@ -2294,6 +2391,12 @@ public actual fun > Array.sort(fromIndex: Int = 0, toIn /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2304,6 +2407,12 @@ public actual fun ByteArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2314,6 +2423,12 @@ public actual fun ShortArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2324,6 +2439,12 @@ public actual fun IntArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2334,6 +2455,12 @@ public actual fun LongArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2344,6 +2471,12 @@ public actual fun FloatArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2354,6 +2487,12 @@ public actual fun DoubleArray.sort(fromIndex: Int = 0, toIndex: Int = size): Uni /** * Sorts a range in the array in-place. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArray */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -2366,6 +2505,12 @@ public actual fun CharArray.sort(fromIndex: Int = 0, toIndex: Int = size): Unit * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + * * @sample samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable */ public fun Array.sort(fromIndex: Int = 0, toIndex: Int = size): Unit { @@ -2385,6 +2530,12 @@ public actual fun Array.sortWith(comparator: Comparator): Unit * Sorts a range in the array in-place with the given [comparator]. * * The sort is _stable_. It means that equal elements preserve their order relative to each other after sorting. + * + * @param fromIndex the start of the range (inclusive) to sort, 0 by default. + * @param toIndex the end of the range (exclusive) to sort, size of this array by default. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @Suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") public actual fun Array.sortWith(comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size): Unit { diff --git a/libraries/stdlib/jvm/src/generated/_UArraysJvm.kt b/libraries/stdlib/jvm/src/generated/_UArraysJvm.kt index e20b7bede38..f69468e33ee 100644 --- a/libraries/stdlib/jvm/src/generated/_UArraysJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_UArraysJvm.kt @@ -135,10 +135,17 @@ public actual fun UShortArray.asList(): List { * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -167,10 +174,17 @@ public fun UIntArray.binarySearch(element: UInt, fromIndex: Int = 0, toIndex: In * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -199,10 +213,17 @@ public fun ULongArray.binarySearch(element: ULong, fromIndex: Int = 0, toIndex: * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -231,10 +252,17 @@ public fun UByteArray.binarySearch(element: UByte, fromIndex: Int = 0, toIndex: * * If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. * + * @param element the to search for. + * @param fromIndex the start of the range (inclusive) to search in, 0 by default. + * @param toIndex the end of the range (exclusive) to search in, size of this array by default. + * * @return the index of the element, if it is contained in the array within the specified range; * otherwise, the inverted insertion point `(-insertion point - 1)`. * The insertion point is defined as the index at which the element should be inserted, * so that the array (or the specified subrange of array) still remains sorted. + * + * @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. + * @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/test/collections/ArraysTest.kt b/libraries/stdlib/test/collections/ArraysTest.kt index 0dd4d25f2e1..8a51eb9d091 100644 --- a/libraries/stdlib/test/collections/ArraysTest.kt +++ b/libraries/stdlib/test/collections/ArraysTest.kt @@ -1886,6 +1886,8 @@ class ArraysTest { } } + testStableSort({ sort(1, 5) }, { sort(1, 5) }) + testStableSort({ sort(0, 6) }, { sort(0, 6) }) doTest(build = { map {it.toString()}.toTypedArray() }, sort = { from, to -> sort(from, to) }, snapshot = { toList() }) doTest(build = { map {it.toString()}.toTypedArray() as Array }, sort = { from, to -> sort(from, to) }, snapshot = { toList() }) @@ -1927,6 +1929,8 @@ class ArraysTest { } } + testStableSort({ sortDescending(1, 5) }, { sortDescending(1, 5) }) + testStableSort({ sortDescending(0, 6) }, { sortDescending(0, 6) }) doTest(build = { map {it.toString()}.toTypedArray() }, sortDescending = { from, to -> sortDescending(from, to) }, snapshot = { toList() }) doTest(build = { map {it.toString()}.toTypedArray() as Array }, sortDescending = { from, to -> sortDescending(from, to) }, snapshot = { toList() }) @@ -1943,39 +1947,6 @@ class ArraysTest { doTest(build = { map {it.toUShort()}.toUShortArray() }, sortDescending = { from, to -> sortDescending(from, to) }, snapshot = { toList() }) } - @Test - fun sortDescendingRangeInPlace_Objects() { - data class Text(val data: String) : Comparable { - override fun compareTo(other: Text): Int = data.compareTo(other.data) - } - - val first1 = Text("first") - val first2 = Text(first1.data) - val first3 = Text(first1.data) - val second1 = Text("second") - val second2 = Text(second1.data) - val third1 = Text("third") - - assertEquals(first1, first2) - assertEquals(first1, first3) - assertNotSame(first1, first2) - assertNotSame(first1, first3) - assertNotSame(first2, first3) - - assertEquals(second1, second2) - assertNotSame(second1, second2) - - val original = arrayOf(first3, third1, second2, first2, first1, second1) - original.copyOf().apply { sortDescending(1, 5) }.forEachIndexed { i, e -> - assertSame(original[i], e) - } - - val sorted = arrayOf(third1, second2, second1, first3, first2, first1) - original.apply { sortDescending(0, 6) }.forEachIndexed { i, e -> - assertSame(sorted[i], e) - } - } - @Test fun sortedTests() { assertTrue(arrayOf().sorted().none()) assertEquals(listOf(1), arrayOf(1).sorted()) @@ -2093,6 +2064,61 @@ class ArraysTest { val array = Array(6) { it } array.sortWith(comparator) array.iterator().assertSorted { a, b -> comparator.compare(a, b) <= 0 } + + testStableSort({ sortWith(reverseOrder()) }, { sortWith(reverseOrder()) }) + testStableSort({ sortWith(naturalOrder()) }, { sortWith(naturalOrder()) }) + + val from = 2 + val to = 5 + val comp = comparator.reversed() + val sorted = array.sliceArray(from until to).sortedWith(comp).toTypedArray() + val expected = array.sliceArray(0 until from) + sorted + array.sliceArray(to until 6) + array.sortWith(comp, from, to) + assertTrue(expected contentEquals array) + + testStableSort({ sortWith(reverseOrder(), from, to) }, { sortWith(reverseOrder(), from, to) }) + testStableSort({ sortWith(naturalOrder(), from, to) }, { sortWith(naturalOrder(), from, to) }) + + assertFailsWith { array.sortWith(comp, -1, 6) } + assertFailsWith { array.sortWith(comp, 0, 7) } + assertFailsWith { array.sortWith(comp, 0, -1) } + } + + private data class Text(val data: String) : Comparable { + override fun compareTo(other: Text): Int = data.compareTo(other.data) + } + + private fun testStableSort(stableSort: Array.() -> Unit, intSort: Array.() -> Unit) { + + fun checkEqualsButNotSame(array: Array) { + for (i in array.indices) { + for (j in i + 1 until array.size) { + assertEquals(array[i], array[j]) + assertNotSame(array[i], array[j]) + } + } + } + + val first = arrayOf(Text("first"), Text("first"), Text("first")) + val second = arrayOf(Text("second"), Text("second")) + val third = arrayOf(Text("third")) + + val text = arrayOf(first, second, third) + + text.forEach { array -> + checkEqualsButNotSame(array) + } + + val sorted = arrayOf(first[0], third[0], second[0], first[1], first[2], second[1]).apply(stableSort) + val indexes = arrayOf(0, 2, 1, 0, 0, 1).apply(intSort) + + val counters = IntArray(3) + for (i in 0 until 6) { + val index = indexes[i] + val expected = text[index][counters[index]++] + val actual = sorted[i] + assertSame(expected, actual) + } } private inline fun testShuffle(array: T, shuffle: T.() -> Unit, toList: T.() -> List<*>) { diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt index f06b768c694..0e03b6fb383 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Arrays.kt @@ -5,6 +5,7 @@ package templates +import templates.DocExtensions.collection import templates.Family.* import templates.Ordering.appendStableSortNote import templates.Ordering.stableSortNote @@ -940,9 +941,8 @@ object ArrayOps : TemplateGroupBase() { doc { """ Returns a new array which is a copy of the specified range of the original array. - - @param fromIndex the start of the range (inclusive), must be in `0..array.size` - @param toIndex the end of the range (exclusive), must be in `fromIndex..array.size` + + ${rangeDoc(hasDefault = false, action = "copy")} """ } returns("SELF") @@ -1295,8 +1295,15 @@ object ArrayOps : TemplateGroupBase() { platforms(Platform.JVM) include(ArraysOfObjects) } builder { - doc { "Sorts a range in the array in-place." } - appendStableSortNote() + doc { + """ + Sorts a range in the array in-place. + + $stableSortNote + + ${rangeDoc(hasDefault = true, action = "sort")} + """ + } sample("samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable") returns("Unit") body { "java.util.Arrays.sort(this, fromIndex, toIndex)" } @@ -1309,9 +1316,14 @@ object ArrayOps : TemplateGroupBase() { on(Platform.Common) { since("1.4") } typeParam("T : Comparable") - doc { "Sorts a range in the array in-place." } + doc { + """ + Sorts a range in the array in-place. + ${if (f == ArraysOfObjects) "\n$stableSortNote\n" else ""} + ${rangeDoc(hasDefault = true, action = "sort")} + """ + } specialFor(ArraysOfObjects) { - appendStableSortNote() sample("samples.collections.Arrays.Sorting.sortRangeOfArrayOfComparable") } specialFor(ArraysOfPrimitives) { @@ -1378,8 +1390,15 @@ object ArrayOps : TemplateGroupBase() { val f_sortWith_range = fn("sortWith(comparator: Comparator, fromIndex: Int = 0, toIndex: Int = size)") { include(ArraysOfObjects) } builder { - doc { "Sorts a range in the array in-place with the given [comparator]." } - appendStableSortNote() + doc { + """ + Sorts a range in the array in-place with the given [comparator]. + + $stableSortNote + + ${rangeDoc(hasDefault = true, action = "sort")} + """ + } returns("Unit") on(Platform.JVM) { suppress("ACTUAL_FUNCTION_WITH_DEFAULT_ARGUMENTS") @@ -1417,13 +1436,14 @@ object ArrayOps : TemplateGroupBase() { """ Sorts elements of the ${f.collection} in the specified range in-place. The elements are sorted descending according to their natural sort order. + ${if (f == ArraysOfObjects) "\n$stableSortNote\n" else ""} + ${rangeDoc(hasDefault = false, action = "sort")} """ } returns("Unit") typeParam("T : Comparable") specialFor(ArraysOfObjects) { - appendStableSortNote() body { """sortWith(reverseOrder(), fromIndex, toIndex)""" } } body(ArraysOfPrimitives, ArraysOfUnsigned) { @@ -1529,6 +1549,22 @@ object ArrayOps : TemplateGroupBase() { } } + fun MemberBuilder.rangeParamDoc(hasDefault: Boolean, action: String): String = """ + @param fromIndex the start of the range (inclusive) to $action${if (hasDefault) ", 0 by default" else ""}. + @param toIndex the end of the range (exclusive) to $action${if (hasDefault) ", ${f.code.size} of this ${f.collection} by default" else ""}. + """.trimIndent() + + fun MemberBuilder.rangeThrowsDoc(): String = """ + @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the ${f.code.size} of this ${f.collection}. + @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + """.trimIndent() + + fun MemberBuilder.rangeDoc(hasDefault: Boolean, action: String): String = """ + ${rangeParamDoc(hasDefault, action)} + + ${rangeThrowsDoc()} + """.trimIndent() + val f_fill = fn("fill(element: T, fromIndex: Int = 0, toIndex: Int = size)") { include(InvariantArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) } builder { @@ -1536,11 +1572,7 @@ object ArrayOps : TemplateGroupBase() { """ Fills this array or its subrange with the specified [element] value. - @param fromIndex the start of the range (inclusive), 0 by default. - @param toIndex the end of the range (exclusive), size of this array by default. - - @throws IndexOutOfBoundsException if [fromIndex] is less than zero or [toIndex] is greater than the size of this array. - @throws IllegalArgumentException if [fromIndex] is greater than [toIndex]. + ${rangeDoc(hasDefault = true, action = "fill")} """ } returns("Unit") @@ -1593,11 +1625,16 @@ object ArrayOps : TemplateGroupBase() { The array is expected to be sorted, otherwise the result is undefined. If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. + + @param element the to search for. + ${rangeParamDoc(hasDefault = true, action = "search in")} @return the index of the element, if it is contained in the array within the specified range; otherwise, the inverted insertion point `(-insertion point - 1)`. The insertion point is defined as the index at which the element should be inserted, so that the array (or the specified subrange of array) still remains sorted. + + ${rangeThrowsDoc()} """ } returns("Int") @@ -1666,10 +1703,16 @@ object ArrayOps : TemplateGroupBase() { If the array contains multiple elements equal to the specified [element], there is no guarantee which one will be found. + @param element the element to search for. + @param comparator the comparator according to which this array is sorted. + ${rangeParamDoc(hasDefault = true, action = "search in")} + @return the index of the element, if it is contained in the array within the specified range; otherwise, the inverted insertion point `(-insertion point - 1)`. The insertion point is defined as the index at which the element should be inserted, so that the array (or the specified subrange of array) still remains sorted according to the specified [comparator]. + + ${rangeThrowsDoc()} """ } returns("Int") diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt index 47ab64d95b4..4f719f88537 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Ordering.kt @@ -5,6 +5,7 @@ package templates +import templates.ArrayOps.rangeDoc import templates.Family.* import templates.SequenceClass.* @@ -57,7 +58,13 @@ object Ordering : TemplateGroupBase() { include(InvariantArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) } builder { since("1.4") - doc { "Reverses elements of the ${f.collection} in the specified range in-place." } + doc { + """ + Reverses elements of the ${f.collection} in the specified range in-place. + + ${rangeDoc(hasDefault = false, action = "reverse")} + """ + } returns("Unit") body { """