Document Array and String get() function behavior (KT-30141)

core/builtins/native/kotlin/Array.kt

@@ -21,19 +21,25 @@ public class Array<T> {
 
     /**
      * 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
 

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. */

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
 

core/builtins/native/kotlin/String.kt

@@ -30,6 +30,12 @@ public class String : Comparable<String>, 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

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. */")

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()
     }

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()
     }

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()
     }

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()
     }

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()
     }