diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index 2ef834ca57e..bdf3927ae11 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -605,6 +605,8 @@ public inline fun CharArray.elementAtOrElse(index: Int, defaultValue: (Int) -> C /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun Array.elementAtOrNull(index: Int): T? { @@ -613,6 +615,8 @@ public inline fun Array.elementAtOrNull(index: Int): T? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun ByteArray.elementAtOrNull(index: Int): Byte? { @@ -621,6 +625,8 @@ public inline fun ByteArray.elementAtOrNull(index: Int): Byte? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun ShortArray.elementAtOrNull(index: Int): Short? { @@ -629,6 +635,8 @@ public inline fun ShortArray.elementAtOrNull(index: Int): Short? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun IntArray.elementAtOrNull(index: Int): Int? { @@ -637,6 +645,8 @@ public inline fun IntArray.elementAtOrNull(index: Int): Int? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun LongArray.elementAtOrNull(index: Int): Long? { @@ -645,6 +655,8 @@ public inline fun LongArray.elementAtOrNull(index: Int): Long? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun FloatArray.elementAtOrNull(index: Int): Float? { @@ -653,6 +665,8 @@ public inline fun FloatArray.elementAtOrNull(index: Int): Float? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun DoubleArray.elementAtOrNull(index: Int): Double? { @@ -661,6 +675,8 @@ public inline fun DoubleArray.elementAtOrNull(index: Int): Double? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun BooleanArray.elementAtOrNull(index: Int): Boolean? { @@ -669,6 +685,8 @@ public inline fun BooleanArray.elementAtOrNull(index: Int): Boolean? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun CharArray.elementAtOrNull(index: Int): Char? { diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index b5f626a2d99..56058a4af97 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -116,6 +116,8 @@ public inline fun List.elementAtOrElse(index: Int, defaultValue: (Int) -> /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this collection. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ public fun Iterable.elementAtOrNull(index: Int): T? { if (this is List) @@ -134,6 +136,8 @@ public fun Iterable.elementAtOrNull(index: Int): T? { /** * Returns an element at the given [index] or `null` if the [index] is out of bounds of this list. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun List.elementAtOrNull(index: Int): T? { diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index 34257d012ac..c038c491fb4 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -60,6 +60,8 @@ public fun Sequence.elementAtOrElse(index: Int, defaultValue: (Int) -> T) * Returns an element at the given [index] or `null` if the [index] is out of bounds of this sequence. * * The operation is _terminal_. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ public fun Sequence.elementAtOrNull(index: Int): T? { if (index < 0) diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 2d60e36f3c9..9777ad82440 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -38,6 +38,8 @@ public inline fun CharSequence.elementAtOrElse(index: Int, defaultValue: (Int) - /** * Returns a character at the given [index] or `null` if the [index] is out of bounds of this char sequence. + * + * @sample samples.collections.Collections.Usage.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun CharSequence.elementAtOrNull(index: Int): Char? { diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt index cd3cde71512..72a978d4571 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -498,5 +498,16 @@ class Collections { val emptyList = emptyList() assertFails { emptyList.elementAt(0) } } + + @Sample + fun elementAtOrNull() { + val list = listOf(1, 2, 3) + assertPrints(list.elementAtOrNull(0), "1") + assertPrints(list.elementAtOrNull(2), "3") + assertPrints(list.elementAtOrNull(3), "null") + + val emptyList = emptyList() + assertPrints(emptyList.elementAtOrNull(0), "null") + } } } \ No newline at end of file diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt index 36380d010f6..fe63817591c 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -328,6 +328,7 @@ object Elements : TemplateGroupBase() { include(CharSequences, Lists) } builder { doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or `null` if the [index] is out of bounds of this ${f.collection}." } + sample("samples.collections.Collections.Usage.elementAtOrNull") returns("T?") body { """