Document that array constructor throws RuntimeException on negative size

core/builtins/native/kotlin/Array.kt

@@ -19,6 +19,8 @@ public class Array<T> {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> T)
 

core/builtins/native/kotlin/Arrays.kt

@@ -10,6 +10,7 @@ package kotlin
 /**
  * An array of bytes. When targeting the JVM, instances of this class are represented as `byte[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class ByteArray(size: Int) {
     /**
@@ -18,6 +19,8 @@ public class ByteArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Byte)
 
@@ -47,6 +50,7 @@ public class ByteArray(size: Int) {
 /**
  * An array of chars. When targeting the JVM, instances of this class are represented as `char[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to null char (`\u0000').
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class CharArray(size: Int) {
     /**
@@ -55,6 +59,8 @@ public class CharArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Char)
 
@@ -84,6 +90,7 @@ public class CharArray(size: Int) {
 /**
  * An array of shorts. When targeting the JVM, instances of this class are represented as `short[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class ShortArray(size: Int) {
     /**
@@ -92,6 +99,8 @@ public class ShortArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Short)
 
@@ -121,6 +130,7 @@ public class ShortArray(size: Int) {
 /**
  * An array of ints. When targeting the JVM, instances of this class are represented as `int[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class IntArray(size: Int) {
     /**
@@ -129,6 +139,8 @@ public class IntArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Int)
 
@@ -158,6 +170,7 @@ public class IntArray(size: Int) {
 /**
  * An array of longs. When targeting the JVM, instances of this class are represented as `long[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class LongArray(size: Int) {
     /**
@@ -166,6 +179,8 @@ public class LongArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Long)
 
@@ -195,6 +210,7 @@ public class LongArray(size: Int) {
 /**
  * An array of floats. When targeting the JVM, instances of this class are represented as `float[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class FloatArray(size: Int) {
     /**
@@ -203,6 +219,8 @@ public class FloatArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Float)
 
@@ -232,6 +250,7 @@ public class FloatArray(size: Int) {
 /**
  * An array of doubles. When targeting the JVM, instances of this class are represented as `double[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class DoubleArray(size: Int) {
     /**
@@ -240,6 +259,8 @@ public class DoubleArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Double)
 
@@ -269,6 +290,7 @@ public class DoubleArray(size: Int) {
 /**
  * An array of booleans. When targeting the JVM, instances of this class are represented as `boolean[]`.
  * @constructor Creates a new array of the specified [size], with all elements initialized to `false`.
+ * @throws RuntimeException if the specified [size] is negative.
  */
 public class BooleanArray(size: Int) {
     /**
@@ -277,6 +299,8 @@ public class BooleanArray(size: Int) {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     public inline constructor(size: Int, init: (Int) -> Boolean)
 

generators/builtins/arrays.kt

@@ -35,6 +35,7 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             out.println("/**")
             out.println(" * An array of ${typeLower}s. When targeting the JVM, instances of this class are represented as `$typeLower[]`.")
             out.println(" * @constructor Creates a new array of the specified [size], with all elements initialized to $defaultValue.")
+            out.println(" * @throws RuntimeException if the specified [size] is negative.")
             out.println(" */")
             out.println("public class ${s}Array(size: Int) {")
             out.println("    /**")
@@ -43,6 +44,8 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             out.println("     *")
             out.println("     * The function [init] is called for each array element sequentially starting from the first one.")
             out.println("     * It should return the value for an array element given its index.")
+            out.println("     *")
+            out.println("     * @throws RuntimeException if the specified [size] is negative.")
             out.println("     */")
             out.println("    public inline constructor(size: Int, init: (Int) -> $s)")
             out.println()

kotlin-native/runtime/src/main/kotlin/kotlin/Array.kt

@@ -25,6 +25,8 @@ public final class Array<T> {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("TYPE_PARAMETER_AS_REIFIED", "WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> T): this(size) {

kotlin-native/runtime/src/main/kotlin/kotlin/Arrays.kt

@@ -17,10 +17,14 @@ import kotlin.native.internal.PointsTo
 
 /**
  * An array of bytes.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theByteArrayTypeInfo")
 public final class ByteArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -30,6 +34,8 @@ public final class ByteArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Byte): this(size) {
@@ -38,6 +44,7 @@ public final class ByteArray {
         }
     }
 
+    /** Returns the number of elements in the array. */
     public val size: Int
         get() = getArrayLength()
 
@@ -81,10 +88,14 @@ private class ByteIteratorImpl(val collection: ByteArray) : ByteIterator() {
 
 /**
  * An array of chars.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theCharArrayTypeInfo")
 public final class CharArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to null char (`\u0000').
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -94,6 +105,8 @@ public final class CharArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Char): this(size) {
@@ -146,10 +159,14 @@ private class CharIteratorImpl(val collection: CharArray) : CharIterator() {
 
 /**
  * An array of shorts.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theShortArrayTypeInfo")
 public final class ShortArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -159,6 +176,8 @@ public final class ShortArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Short): this(size) {
@@ -210,11 +229,15 @@ private class ShortIteratorImpl(val collection: ShortArray) : ShortIterator() {
 }
 
 /**
- * An array of ints. When targeting the JVM, instances of this class are represented as `int[]`.
+ * An array of ints.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theIntArrayTypeInfo")
 public final class IntArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -224,6 +247,8 @@ public final class IntArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Int): this(size) {
@@ -276,10 +301,14 @@ private class IntIteratorImpl(val collection: IntArray) : IntIterator() {
 
 /**
  * An array of longs.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theLongArrayTypeInfo")
 public final class LongArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -289,6 +318,8 @@ public final class LongArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Long): this(size) {
@@ -341,10 +372,14 @@ private class LongIteratorImpl(val collection: LongArray) : LongIterator() {
 
 /**
  * An array of floats.
- * @constructor Creates a new array of the specified [size], with all elements initialized to zero.
  */
 @ExportTypeInfo("theFloatArrayTypeInfo")
 public final class FloatArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -354,6 +389,8 @@ public final class FloatArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Float): this(size) {
@@ -404,8 +441,16 @@ private class FloatIteratorImpl(val collection: FloatArray) : FloatIterator() {
     }
 }
 
+/**
+ * An array of doubles.
+ */
 @ExportTypeInfo("theDoubleArrayTypeInfo")
 public final class DoubleArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to zero.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -415,6 +460,8 @@ public final class DoubleArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Double): this(size) {
@@ -465,8 +512,16 @@ private class DoubleIteratorImpl(val collection: DoubleArray) : DoubleIterator()
     }
 }
 
+/**
+ * An array of booleans.
+ */
 @ExportTypeInfo("theBooleanArrayTypeInfo")
 public final class BooleanArray {
+    /**
+     * Creates a new array of the specified [size], with all elements initialized to `false`.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
+     */
     // Constructors are handled with the compiler magic.
     public constructor(@Suppress("UNUSED_PARAMETER") size: Int) {}
 
@@ -476,6 +531,8 @@ public final class BooleanArray {
      *
      * The function [init] is called for each array element sequentially starting from the first one.
      * It should return the value for an array element given its index.
+     *
+     * @throws RuntimeException if the specified [size] is negative.
      */
     @Suppress("WRONG_MODIFIER_TARGET")
     public inline constructor(size: Int, init: (Int) -> Boolean): this(size) {