From 814d6cf39caa03d67a33470fb13e18611e0014d2 Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Tue, 12 Mar 2019 19:57:15 +0300 Subject: [PATCH] Document Array and String get() function behavior (KT-30141) --- core/builtins/native/kotlin/Array.kt | 10 +- core/builtins/native/kotlin/Arrays.kt | 120 +++++++++++++++--- core/builtins/native/kotlin/CharSequence.kt | 5 + core/builtins/native/kotlin/String.kt | 6 + generators/builtins/arrays.kt | 15 ++- generators/builtins/unsignedTypes.kt | 14 +- .../stdlib/unsigned/src/kotlin/UByteArray.kt | 14 +- .../stdlib/unsigned/src/kotlin/UIntArray.kt | 14 +- .../stdlib/unsigned/src/kotlin/ULongArray.kt | 14 +- .../stdlib/unsigned/src/kotlin/UShortArray.kt | 14 +- 10 files changed, 196 insertions(+), 30 deletions(-) diff --git a/core/builtins/native/kotlin/Array.kt b/core/builtins/native/kotlin/Array.kt index 32f771b4446..ad86c9fa34d 100644 --- a/core/builtins/native/kotlin/Array.kt +++ b/core/builtins/native/kotlin/Array.kt @@ -21,19 +21,25 @@ public class Array { /** * Returns the array element at the specified [index]. This method can be called using the - * index operator: + * index operator. * ``` * value = arr[index] * ``` + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. */ public operator fun get(index: Int): T /** * Sets the array element at the specified [index] to the specified [value]. This method can - * be called using the index operator: + * be called using the index operator. * ``` * arr[index] = value * ``` + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. */ public operator fun set(index: Int, value: T): Unit diff --git a/core/builtins/native/kotlin/Arrays.kt b/core/builtins/native/kotlin/Arrays.kt index 3a44ed1012f..349fca3b826 100644 --- a/core/builtins/native/kotlin/Arrays.kt +++ b/core/builtins/native/kotlin/Arrays.kt @@ -18,9 +18,20 @@ public class ByteArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Byte) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Byte - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Byte): Unit /** Returns the number of elements in the array. */ @@ -41,9 +52,20 @@ public class CharArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Char) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Char - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Char): Unit /** Returns the number of elements in the array. */ @@ -64,9 +86,20 @@ public class ShortArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Short) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Short - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Short): Unit /** Returns the number of elements in the array. */ @@ -87,9 +120,20 @@ public class IntArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Int) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Int - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Int): Unit /** Returns the number of elements in the array. */ @@ -110,9 +154,20 @@ public class LongArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Long) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Long - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Long): Unit /** Returns the number of elements in the array. */ @@ -133,9 +188,20 @@ public class FloatArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Float) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Float - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Float): Unit /** Returns the number of elements in the array. */ @@ -156,9 +222,20 @@ public class DoubleArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Double) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Double - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Double): Unit /** Returns the number of elements in the array. */ @@ -179,9 +256,20 @@ public class BooleanArray(size: Int) { */ public inline constructor(size: Int, init: (Int) -> Boolean) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): Boolean - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: Boolean): Unit /** Returns the number of elements in the array. */ diff --git a/core/builtins/native/kotlin/CharSequence.kt b/core/builtins/native/kotlin/CharSequence.kt index 32f3ac1ac79..335bc9bb63d 100644 --- a/core/builtins/native/kotlin/CharSequence.kt +++ b/core/builtins/native/kotlin/CharSequence.kt @@ -27,6 +27,11 @@ public interface CharSequence { /** * Returns the character at the specified [index] in this character sequence. + * + * @throws [IndexOutOfBoundsException] if the [index] is out of bounds of this character sequence. + * + * Note that the [String] implementation of this interface in Kotlin/JS has unspecified behavior + * if the [index] is out of its bounds. */ public operator fun get(index: Int): Char diff --git a/core/builtins/native/kotlin/String.kt b/core/builtins/native/kotlin/String.kt index 6b3f7f6e52c..d987f2a7912 100644 --- a/core/builtins/native/kotlin/String.kt +++ b/core/builtins/native/kotlin/String.kt @@ -30,6 +30,12 @@ public class String : Comparable, CharSequence { public override val length: Int + /** + * Returns the character of this string at the specified [index]. + * + * If the [index] is out of bounds of this string, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public override fun get(index: Int): Char public override fun subSequence(startIndex: Int, endIndex: Int): CharSequence diff --git a/generators/builtins/arrays.kt b/generators/builtins/arrays.kt index a39cfce35e9..831a9f02c02 100644 --- a/generators/builtins/arrays.kt +++ b/generators/builtins/arrays.kt @@ -43,9 +43,20 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) { out.println(" */") out.println(" public inline constructor(size: Int, init: (Int) -> $s)") out.println() - out.println(" /** Returns the array element at the given [index]. This method can be called using the index operator. */") + out.println(" /**") + out.println(" * Returns the array element at the given [index]. This method can be called using the index operator.") + out.println(" *") + out.println(" * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS") + out.println(" * where the behavior is unspecified.") + out.println(" */") out.println(" public operator fun get(index: Int): $s") - out.println(" /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */") + out.println() + out.println(" /**") + out.println(" * Sets the element at the given [index] to the given [value]. This method can be called using the index operator.") + out.println(" *") + out.println(" * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS") + out.println(" * where the behavior is unspecified.") + out.println(" */") out.println(" public operator fun set(index: Int, value: $s): Unit") out.println() out.println(" /** Returns the number of elements in the array. */") diff --git a/generators/builtins/unsignedTypes.kt b/generators/builtins/unsignedTypes.kt index fca81ed3a9f..4a0955d5bdd 100644 --- a/generators/builtins/unsignedTypes.kt +++ b/generators/builtins/unsignedTypes.kt @@ -428,10 +428,20 @@ class UnsignedArrayGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIn /** Creates a new array of the specified [size], with all elements initialized to zero. */ public constructor(size: Int) : this($storageArrayType(size)) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): $elementType = storage[index].to$elementType() - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: $elementType) { storage[index] = value.to$storageElementType() } diff --git a/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt b/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt index d6942aea744..ccdd4920f88 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt @@ -17,10 +17,20 @@ internal constructor(@PublishedApi internal val storage: ByteArray) : Collection /** Creates a new array of the specified [size], with all elements initialized to zero. */ public constructor(size: Int) : this(ByteArray(size)) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): UByte = storage[index].toUByte() - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: UByte) { storage[index] = value.toByte() } diff --git a/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt b/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt index d53864d0dcc..2644ea31fa7 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt @@ -17,10 +17,20 @@ internal constructor(@PublishedApi internal val storage: IntArray) : Collection< /** Creates a new array of the specified [size], with all elements initialized to zero. */ public constructor(size: Int) : this(IntArray(size)) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): UInt = storage[index].toUInt() - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: UInt) { storage[index] = value.toInt() } diff --git a/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt b/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt index 253ea81e48a..fb609daf97b 100644 --- a/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt @@ -17,10 +17,20 @@ internal constructor(@PublishedApi internal val storage: LongArray) : Collection /** Creates a new array of the specified [size], with all elements initialized to zero. */ public constructor(size: Int) : this(LongArray(size)) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): ULong = storage[index].toULong() - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: ULong) { storage[index] = value.toLong() } diff --git a/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt b/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt index df96e10e32e..a4c592ac1d8 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt @@ -17,10 +17,20 @@ internal constructor(@PublishedApi internal val storage: ShortArray) : Collectio /** Creates a new array of the specified [size], with all elements initialized to zero. */ public constructor(size: Int) : this(ShortArray(size)) - /** Returns the array element at the given [index]. This method can be called using the index operator. */ + /** + * Returns the array element at the given [index]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun get(index: Int): UShort = storage[index].toUShort() - /** Sets the element at the given [index] to the given [value]. This method can be called using the index operator. */ + /** + * Sets the element at the given [index] to the given [value]. This method can be called using the index operator. + * + * If the [index] is out of bounds of this array, throws an [IndexOutOfBoundsException] except in Kotlin/JS + * where the behavior is unspecified. + */ public operator fun set(index: Int, value: UShort) { storage[index] = value.toShort() }