JS: document array destructuring behavior (KT-17544)

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -19,6 +19,9 @@ import kotlin.ranges.reversed
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> Array<out T>.component1(): T {
@@ -27,6 +30,9 @@ public inline operator fun <T> Array<out T>.component1(): T {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ByteArray.component1(): Byte {
@@ -35,6 +41,9 @@ public inline operator fun ByteArray.component1(): Byte {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ShortArray.component1(): Short {
@@ -43,6 +52,9 @@ public inline operator fun ShortArray.component1(): Short {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun IntArray.component1(): Int {
@@ -51,6 +63,9 @@ public inline operator fun IntArray.component1(): Int {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun LongArray.component1(): Long {
@@ -59,6 +74,9 @@ public inline operator fun LongArray.component1(): Long {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun FloatArray.component1(): Float {
@@ -67,6 +85,9 @@ public inline operator fun FloatArray.component1(): Float {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun DoubleArray.component1(): Double {
@@ -75,6 +96,9 @@ public inline operator fun DoubleArray.component1(): Double {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun BooleanArray.component1(): Boolean {
@@ -83,6 +107,9 @@ public inline operator fun BooleanArray.component1(): Boolean {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun CharArray.component1(): Char {
@@ -91,6 +118,9 @@ public inline operator fun CharArray.component1(): Char {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> Array<out T>.component2(): T {
@@ -99,6 +129,9 @@ public inline operator fun <T> Array<out T>.component2(): T {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ByteArray.component2(): Byte {
@@ -107,6 +140,9 @@ public inline operator fun ByteArray.component2(): Byte {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ShortArray.component2(): Short {
@@ -115,6 +151,9 @@ public inline operator fun ShortArray.component2(): Short {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun IntArray.component2(): Int {
@@ -123,6 +162,9 @@ public inline operator fun IntArray.component2(): Int {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun LongArray.component2(): Long {
@@ -131,6 +173,9 @@ public inline operator fun LongArray.component2(): Long {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun FloatArray.component2(): Float {
@@ -139,6 +184,9 @@ public inline operator fun FloatArray.component2(): Float {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun DoubleArray.component2(): Double {
@@ -147,6 +195,9 @@ public inline operator fun DoubleArray.component2(): Double {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun BooleanArray.component2(): Boolean {
@@ -155,6 +206,9 @@ public inline operator fun BooleanArray.component2(): Boolean {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun CharArray.component2(): Char {
@@ -163,6 +217,9 @@ public inline operator fun CharArray.component2(): Char {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> Array<out T>.component3(): T {
@@ -171,6 +228,9 @@ public inline operator fun <T> Array<out T>.component3(): T {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ByteArray.component3(): Byte {
@@ -179,6 +239,9 @@ public inline operator fun ByteArray.component3(): Byte {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ShortArray.component3(): Short {
@@ -187,6 +250,9 @@ public inline operator fun ShortArray.component3(): Short {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun IntArray.component3(): Int {
@@ -195,6 +261,9 @@ public inline operator fun IntArray.component3(): Int {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun LongArray.component3(): Long {
@@ -203,6 +272,9 @@ public inline operator fun LongArray.component3(): Long {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun FloatArray.component3(): Float {
@@ -211,6 +283,9 @@ public inline operator fun FloatArray.component3(): Float {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun DoubleArray.component3(): Double {
@@ -219,6 +294,9 @@ public inline operator fun DoubleArray.component3(): Double {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun BooleanArray.component3(): Boolean {
@@ -227,6 +305,9 @@ public inline operator fun BooleanArray.component3(): Boolean {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun CharArray.component3(): Char {
@@ -235,6 +316,9 @@ public inline operator fun CharArray.component3(): Char {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> Array<out T>.component4(): T {
@@ -243,6 +327,9 @@ public inline operator fun <T> Array<out T>.component4(): T {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ByteArray.component4(): Byte {
@@ -251,6 +338,9 @@ public inline operator fun ByteArray.component4(): Byte {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ShortArray.component4(): Short {
@@ -259,6 +349,9 @@ public inline operator fun ShortArray.component4(): Short {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun IntArray.component4(): Int {
@@ -267,6 +360,9 @@ public inline operator fun IntArray.component4(): Int {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun LongArray.component4(): Long {
@@ -275,6 +371,9 @@ public inline operator fun LongArray.component4(): Long {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun FloatArray.component4(): Float {
@@ -283,6 +382,9 @@ public inline operator fun FloatArray.component4(): Float {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun DoubleArray.component4(): Double {
@@ -291,6 +393,9 @@ public inline operator fun DoubleArray.component4(): Double {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun BooleanArray.component4(): Boolean {
@@ -299,6 +404,9 @@ public inline operator fun BooleanArray.component4(): Boolean {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun CharArray.component4(): Char {
@@ -307,6 +415,9 @@ public inline operator fun CharArray.component4(): Char {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> Array<out T>.component5(): T {
@@ -315,6 +426,9 @@ public inline operator fun <T> Array<out T>.component5(): T {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ByteArray.component5(): Byte {
@@ -323,6 +437,9 @@ public inline operator fun ByteArray.component5(): Byte {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun ShortArray.component5(): Short {
@@ -331,6 +448,9 @@ public inline operator fun ShortArray.component5(): Short {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun IntArray.component5(): Int {
@@ -339,6 +459,9 @@ public inline operator fun IntArray.component5(): Int {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun LongArray.component5(): Long {
@@ -347,6 +470,9 @@ public inline operator fun LongArray.component5(): Long {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun FloatArray.component5(): Float {
@@ -355,6 +481,9 @@ public inline operator fun FloatArray.component5(): Float {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun DoubleArray.component5(): Double {
@@ -363,6 +492,9 @@ public inline operator fun DoubleArray.component5(): Double {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun BooleanArray.component5(): Boolean {
@@ -371,6 +503,9 @@ public inline operator fun BooleanArray.component5(): Boolean {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun CharArray.component5(): Char {

libraries/stdlib/common/src/generated/_Collections.kt

@@ -19,6 +19,8 @@ import kotlin.ranges.reversed
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * Throws an [IndexOutOfBoundsException] if this list is empty.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> List<T>.component1(): T {
@@ -27,6 +29,8 @@ public inline operator fun <T> List<T>.component1(): T {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * Throws an [IndexOutOfBoundsException] if the size of this list is less than 2.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> List<T>.component2(): T {
@@ -35,6 +39,8 @@ public inline operator fun <T> List<T>.component2(): T {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * Throws an [IndexOutOfBoundsException] if the size of this list is less than 3.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> List<T>.component3(): T {
@@ -43,6 +49,8 @@ public inline operator fun <T> List<T>.component3(): T {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * Throws an [IndexOutOfBoundsException] if the size of this list is less than 4.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> List<T>.component4(): T {
@@ -51,6 +59,8 @@ public inline operator fun <T> List<T>.component4(): T {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * Throws an [IndexOutOfBoundsException] if the size of this list is less than 5.
  */
 @kotlin.internal.InlineOnly
 public inline operator fun <T> List<T>.component5(): T {

libraries/stdlib/common/src/generated/_UArrays.kt

@@ -20,6 +20,9 @@ import kotlin.ranges.reversed
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -30,6 +33,9 @@ public inline operator fun UIntArray.component1(): UInt {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -40,6 +46,9 @@ public inline operator fun ULongArray.component1(): ULong {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -50,6 +59,9 @@ public inline operator fun UByteArray.component1(): UByte {
 
 /**
  * Returns 1st *element* from the collection.
+ * 
+ * If this array is empty, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -60,6 +72,9 @@ public inline operator fun UShortArray.component1(): UShort {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -70,6 +85,9 @@ public inline operator fun UIntArray.component2(): UInt {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -80,6 +98,9 @@ public inline operator fun ULongArray.component2(): ULong {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -90,6 +111,9 @@ public inline operator fun UByteArray.component2(): UByte {
 
 /**
  * Returns 2nd *element* from the collection.
+ * 
+ * If the size of this array is less than 2, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -100,6 +124,9 @@ public inline operator fun UShortArray.component2(): UShort {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -110,6 +137,9 @@ public inline operator fun UIntArray.component3(): UInt {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -120,6 +150,9 @@ public inline operator fun ULongArray.component3(): ULong {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -130,6 +163,9 @@ public inline operator fun UByteArray.component3(): UByte {
 
 /**
  * Returns 3rd *element* from the collection.
+ * 
+ * If the size of this array is less than 3, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -140,6 +176,9 @@ public inline operator fun UShortArray.component3(): UShort {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -150,6 +189,9 @@ public inline operator fun UIntArray.component4(): UInt {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -160,6 +202,9 @@ public inline operator fun ULongArray.component4(): ULong {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -170,6 +215,9 @@ public inline operator fun UByteArray.component4(): UByte {
 
 /**
  * Returns 4th *element* from the collection.
+ * 
+ * If the size of this array is less than 4, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -180,6 +228,9 @@ public inline operator fun UShortArray.component4(): UShort {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -190,6 +241,9 @@ public inline operator fun UIntArray.component5(): UInt {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -200,6 +254,9 @@ public inline operator fun ULongArray.component5(): ULong {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes
@@ -210,6 +267,9 @@ public inline operator fun UByteArray.component5(): UByte {
 
 /**
  * Returns 5th *element* from the collection.
+ * 
+ * If the size of this array is less than 5, throws an [IndexOutOfBoundsException] except in Kotlin/JS
+ * where the behavior is unspecified.
  */
 @SinceKotlin("1.3")
 @ExperimentalUnsignedTypes

libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt

@@ -964,7 +964,25 @@ object Elements : TemplateGroupBase() {
                 3 -> "rd"
                 else -> "th"
             }
-            doc { "Returns ${getOrdinal(n)} *element* from the collection." }
+
+            val condition = if (n == 1) "this ${f.doc.collection} is empty" else "the size of this ${f.doc.collection} is less than $n"
+            doc {
+                """
+                Returns ${getOrdinal(n)} *element* from the collection.
+            
+                Throws an [IndexOutOfBoundsException] if $condition.
+                """
+            }
+            specialFor(ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) {
+                doc {
+                    """
+                    Returns ${getOrdinal(n)} *element* from the collection.
+            
+                    If $condition, throws an [IndexOutOfBoundsException] except in Kotlin/JS 
+                    where the behavior is unspecified.
+                    """
+                }
+            }
             returns("T")
             body { "return get(${n-1})" }
         }