diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index ce10b5ea86477..85267ac01e968 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -1467,6 +1467,8 @@ public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): Char? { /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun Array.getOrElse(index: Int, defaultValue: (Int) -> T): T { @@ -1478,6 +1480,8 @@ public inline fun Array.getOrElse(index: Int, defaultValue: (Int) -> /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun ByteArray.getOrElse(index: Int, defaultValue: (Int) -> Byte): Byte { @@ -1489,6 +1493,8 @@ public inline fun ByteArray.getOrElse(index: Int, defaultValue: (Int) -> Byte): /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun ShortArray.getOrElse(index: Int, defaultValue: (Int) -> Short): Short { @@ -1500,6 +1506,8 @@ public inline fun ShortArray.getOrElse(index: Int, defaultValue: (Int) -> Short) /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun IntArray.getOrElse(index: Int, defaultValue: (Int) -> Int): Int { @@ -1511,6 +1519,8 @@ public inline fun IntArray.getOrElse(index: Int, defaultValue: (Int) -> Int): In /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun LongArray.getOrElse(index: Int, defaultValue: (Int) -> Long): Long { @@ -1522,6 +1532,8 @@ public inline fun LongArray.getOrElse(index: Int, defaultValue: (Int) -> Long): /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun FloatArray.getOrElse(index: Int, defaultValue: (Int) -> Float): Float { @@ -1533,6 +1545,8 @@ public inline fun FloatArray.getOrElse(index: Int, defaultValue: (Int) -> Float) /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun DoubleArray.getOrElse(index: Int, defaultValue: (Int) -> Double): Double { @@ -1544,6 +1558,8 @@ public inline fun DoubleArray.getOrElse(index: Int, defaultValue: (Int) -> Doubl /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun BooleanArray.getOrElse(index: Int, defaultValue: (Int) -> Boolean): Boolean { @@ -1555,6 +1571,8 @@ public inline fun BooleanArray.getOrElse(index: Int, defaultValue: (Int) -> Bool /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @kotlin.internal.InlineOnly public inline fun CharArray.getOrElse(index: Int, defaultValue: (Int) -> Char): Char { diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index 4bde5483acad8..516e5ed290865 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -298,6 +298,8 @@ public inline fun Iterable.firstOrNull(predicate: (T) -> Boolean): T? { /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this list. + * + * @sample samples.collections.Collections.Elements.getOrElse */ @kotlin.internal.InlineOnly public inline fun List.getOrElse(index: Int, defaultValue: (Int) -> T): T { diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 51f62c8416060..c22c1d8bd4251 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -133,6 +133,8 @@ public inline fun CharSequence.firstOrNull(predicate: (Char) -> Boolean): Char? /** * Returns a character at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this char sequence. + * + * @sample samples.collections.Collections.Elements.getOrElse */ @kotlin.internal.InlineOnly public inline fun CharSequence.getOrElse(index: Int, defaultValue: (Int) -> Char): Char { diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 75af868625dbf..14c45c64926b2 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt @@ -737,6 +737,8 @@ public inline fun UShortArray.firstOrNull(predicate: (UShort) -> Boolean): UShor /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -750,6 +752,8 @@ public inline fun UIntArray.getOrElse(index: Int, defaultValue: (Int) -> UInt): /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -763,6 +767,8 @@ public inline fun ULongArray.getOrElse(index: Int, defaultValue: (Int) -> ULong) /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -776,6 +782,8 @@ public inline fun UByteArray.getOrElse(index: Int, defaultValue: (Int) -> UByte) /** * Returns an element at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this array. + * + * @sample samples.collections.Arrays.Usage.getOrElse */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/samples/test/samples/collections/arrays.kt b/libraries/stdlib/samples/test/samples/collections/arrays.kt index 9a5ac6f8ad08e..ca50e96c1def0 100644 --- a/libraries/stdlib/samples/test/samples/collections/arrays.kt +++ b/libraries/stdlib/samples/test/samples/collections/arrays.kt @@ -60,6 +60,36 @@ class Arrays { val sameArray = nonEmptyArray.ifEmpty { arrayOf(2) } assertTrue(nonEmptyArray === sameArray) } + + @Sample + fun getOrElse() { + val emptyArray: Array = emptyArray() + assertPrints(emptyArray.getOrElse(0) { "default" }, "default") + + val array = arrayOf(1) + assertPrints(array.getOrElse(0) { 0 }, "1") + assertPrints(array.getOrElse(-1) { 0 }, "0") + assertPrints(array.getOrElse(0) { "default" }, "1") + assertPrints(array.getOrElse(-1) { "default" }, "default") + + // arrays of primitive types + val intArray = intArrayOf(1, 2, 3) + assertPrints(intArray.getOrElse(0) { 0 }, "1") + assertPrints(intArray.getOrElse(-1) { 0 }, "0") + + val booleanArray = booleanArrayOf(true, false) + assertPrints(booleanArray.getOrElse(0) { false }, "true") + assertPrints(booleanArray.getOrElse(-1) { false }, "false") + + val charArray = charArrayOf('a', 'b', 'c') + assertPrints(charArray.getOrElse(0) { 'z' }, "a") + assertPrints(charArray.getOrElse(-1) { 'z' }, "z") + + // arrays of unsigned types + val uIntArray = uintArrayOf(1u, 2u, 3u) + assertPrints(uIntArray.getOrElse(0) { 10u }, "1") + assertPrints(uIntArray.getOrElse(-1) { 10u }, "10") + } } class Transformations { diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt index 6eb9602b69a97..03fa2b2850bfe 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -1233,6 +1233,18 @@ class Collections { assertPrints(lastEven, "6") } + @Sample + fun getOrElse() { + val list = listOf(1, 2, 3) + assertPrints(list.getOrElse(0) { 42 }, "1") + assertPrints(list.getOrElse(2) { 42 }, "3") + assertPrints(list.getOrElse(3) { 42 }, "42") + assertPrints(list.getOrElse(-1) { 42 }, "42") + + val emptyList = emptyList() + assertPrints(emptyList.getOrElse(0) { "no int" }, "no int") + } + @Sample fun getOrNull() { val list = listOf(1, 2, 3) diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt index 2099f2a8ff21c..f2c759ff2bf17 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -402,6 +402,13 @@ object Elements : TemplateGroupBase() { include(CharSequences, Lists, ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned) } builder { doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or the result of calling the [defaultValue] function if the [index] is out of bounds of this ${f.collection}." } + sample( + when (family) { + CharSequences, Lists -> "samples.collections.Collections.Elements.getOrElse" + ArraysOfObjects, ArraysOfPrimitives, ArraysOfUnsigned -> "samples.collections.Arrays.Usage.getOrElse" + else -> "samples.collections.Collections.Elements.getOrElse" + } + ) returns("T") inlineOnly() val indices = if (family == Lists) "0..