From 96dcafdf3524a867714521d23415b30000c98283 Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Wed, 10 Jul 2019 14:26:50 +0300 Subject: [PATCH] Document order of array elements initialization (KT-32353) --- core/builtins/native/kotlin/Array.kt | 5 ++- core/builtins/native/kotlin/Arrays.kt | 40 +++++++++++++++---- generators/builtins/arrays.kt | 5 ++- generators/builtins/unsignedTypes.kt | 7 ++++ libraries/stdlib/js-ir/builtins/Arrays.kt | 40 +++++++++++++++---- .../src/kotlin/collections/Collections.kt | 12 +++++- .../stdlib/unsigned/src/kotlin/UByteArray.kt | 7 ++++ .../stdlib/unsigned/src/kotlin/UIntArray.kt | 7 ++++ .../stdlib/unsigned/src/kotlin/ULongArray.kt | 7 ++++ .../stdlib/unsigned/src/kotlin/UShortArray.kt | 7 ++++ 10 files changed, 117 insertions(+), 20 deletions(-) diff --git a/core/builtins/native/kotlin/Array.kt b/core/builtins/native/kotlin/Array.kt index 312484f4b01..6bc1992f995 100644 --- a/core/builtins/native/kotlin/Array.kt +++ b/core/builtins/native/kotlin/Array.kt @@ -15,7 +15,10 @@ package kotlin public class Array { /** * Creates a new array with the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> T) diff --git a/core/builtins/native/kotlin/Arrays.kt b/core/builtins/native/kotlin/Arrays.kt index 583f7e50b5e..484d4115374 100644 --- a/core/builtins/native/kotlin/Arrays.kt +++ b/core/builtins/native/kotlin/Arrays.kt @@ -14,7 +14,10 @@ package kotlin public class ByteArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Byte) @@ -48,7 +51,10 @@ public class ByteArray(size: Int) { public class CharArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Char) @@ -82,7 +88,10 @@ public class CharArray(size: Int) { public class ShortArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Short) @@ -116,7 +125,10 @@ public class ShortArray(size: Int) { public class IntArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Int) @@ -150,7 +162,10 @@ public class IntArray(size: Int) { public class LongArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Long) @@ -184,7 +199,10 @@ public class LongArray(size: Int) { public class FloatArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Float) @@ -218,7 +236,10 @@ public class FloatArray(size: Int) { public class DoubleArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Double) @@ -252,7 +273,10 @@ public class DoubleArray(size: Int) { public class BooleanArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Boolean) diff --git a/generators/builtins/arrays.kt b/generators/builtins/arrays.kt index 831a9f02c02..be0b093830f 100644 --- a/generators/builtins/arrays.kt +++ b/generators/builtins/arrays.kt @@ -39,7 +39,10 @@ class GenerateArrays(out: PrintWriter) : BuiltInsSourceGenerator(out) { out.println("public class ${s}Array(size: Int) {") out.println(" /**") out.println(" * Creates a new array of the specified [size], where each element is calculated by calling the specified") - out.println(" * [init] function. The [init] function returns an array element given its index.") + out.println(" * [init] function.") + 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(" public inline constructor(size: Int, init: (Int) -> $s)") out.println() diff --git a/generators/builtins/unsignedTypes.kt b/generators/builtins/unsignedTypes.kt index 72b0ba27b3f..955143fde7c 100644 --- a/generators/builtins/unsignedTypes.kt +++ b/generators/builtins/unsignedTypes.kt @@ -476,6 +476,13 @@ class UnsignedArrayGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIn // TODO: Make inline constructor, like in ByteArray out.println(""" +/** + * Creates a new array of the specified [size], where each element is calculated by calling the specified + * [init] function. + * + * 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. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/js-ir/builtins/Arrays.kt b/libraries/stdlib/js-ir/builtins/Arrays.kt index 4e95d2579f5..6b7c431f812 100644 --- a/libraries/stdlib/js-ir/builtins/Arrays.kt +++ b/libraries/stdlib/js-ir/builtins/Arrays.kt @@ -20,7 +20,10 @@ package kotlin public class ByteArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Byte) @@ -43,7 +46,10 @@ public class ByteArray(size: Int) { public class CharArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Char) @@ -66,7 +72,10 @@ public class CharArray(size: Int) { public class ShortArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Short) @@ -89,7 +98,10 @@ public class ShortArray(size: Int) { public class IntArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Int) @@ -112,7 +124,10 @@ public class IntArray(size: Int) { public class LongArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Long) @@ -135,7 +150,10 @@ public class LongArray(size: Int) { public class FloatArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Float) @@ -158,7 +176,10 @@ public class FloatArray(size: Int) { public class DoubleArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Double) @@ -181,7 +202,10 @@ public class DoubleArray(size: Int) { public class BooleanArray(size: Int) { /** * Creates a new array of the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns an array element given its index. + * [init] function. + * + * 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. */ public inline constructor(size: Int, init: (Int) -> Boolean) diff --git a/libraries/stdlib/src/kotlin/collections/Collections.kt b/libraries/stdlib/src/kotlin/collections/Collections.kt index 142662a9a37..09ca626962a 100644 --- a/libraries/stdlib/src/kotlin/collections/Collections.kt +++ b/libraries/stdlib/src/kotlin/collections/Collections.kt @@ -125,7 +125,11 @@ public fun listOfNotNull(vararg elements: T?): List = elements.filt /** * Creates a new read-only list with the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns a list element given its index. + * [init] function. + * + * The function [init] is called for each list element sequentially starting from the first one. + * It should return the value for a list element given its index. + * * @sample samples.collections.Collections.Lists.readOnlyListFromInitializer */ @SinceKotlin("1.1") @@ -134,7 +138,11 @@ public inline fun List(size: Int, init: (index: Int) -> T): List = Mutabl /** * Creates a new mutable list with the specified [size], where each element is calculated by calling the specified - * [init] function. The [init] function returns a list element given its index. + * [init] function. + * + * The function [init] is called for each list element sequentially starting from the first one. + * It should return the value for a list element given its index. + * * @sample samples.collections.Collections.Lists.mutableListFromInitializer */ @SinceKotlin("1.1") diff --git a/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt b/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt index 8cadd853fb2..3ca96f40c15 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UByteArray.kt @@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: ByteArray) : Collection override fun isEmpty(): Boolean = this.storage.size == 0 } +/** + * Creates a new array of the specified [size], where each element is calculated by calling the specified + * [init] function. + * + * 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. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt b/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt index af65c3add3c..81d703c44a6 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UIntArray.kt @@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: IntArray) : Collection< override fun isEmpty(): Boolean = this.storage.size == 0 } +/** + * Creates a new array of the specified [size], where each element is calculated by calling the specified + * [init] function. + * + * 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. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt b/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt index 1bd31c30493..4068c310256 100644 --- a/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/ULongArray.kt @@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: LongArray) : Collection override fun isEmpty(): Boolean = this.storage.size == 0 } +/** + * Creates a new array of the specified [size], where each element is calculated by calling the specified + * [init] function. + * + * 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. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly diff --git a/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt b/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt index 32f34ca9916..07c82c5a576 100644 --- a/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt +++ b/libraries/stdlib/unsigned/src/kotlin/UShortArray.kt @@ -62,6 +62,13 @@ internal constructor(@PublishedApi internal val storage: ShortArray) : Collectio override fun isEmpty(): Boolean = this.storage.size == 0 } +/** + * Creates a new array of the specified [size], where each element is calculated by calling the specified + * [init] function. + * + * 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. + */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @kotlin.internal.InlineOnly