diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index 11adb47aa5f..2ef834ca57e 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -443,6 +443,8 @@ public operator fun CharArray.contains(element: Char): Boolean { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun Array.elementAt(index: Int): T { @@ -451,6 +453,8 @@ public inline fun Array.elementAt(index: Int): T { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun ByteArray.elementAt(index: Int): Byte { @@ -459,6 +463,8 @@ public inline fun ByteArray.elementAt(index: Int): Byte { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun ShortArray.elementAt(index: Int): Short { @@ -467,6 +473,8 @@ public inline fun ShortArray.elementAt(index: Int): Short { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun IntArray.elementAt(index: Int): Int { @@ -475,6 +483,8 @@ public inline fun IntArray.elementAt(index: Int): Int { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun LongArray.elementAt(index: Int): Long { @@ -483,6 +493,8 @@ public inline fun LongArray.elementAt(index: Int): Long { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun FloatArray.elementAt(index: Int): Float { @@ -491,6 +503,8 @@ public inline fun FloatArray.elementAt(index: Int): Float { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun DoubleArray.elementAt(index: Int): Double { @@ -499,6 +513,8 @@ public inline fun DoubleArray.elementAt(index: Int): Double { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun BooleanArray.elementAt(index: Int): Boolean { @@ -507,6 +523,8 @@ public inline fun BooleanArray.elementAt(index: Int): Boolean { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this array. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun CharArray.elementAt(index: Int): Char { diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index 984914bad1e..b5f626a2d99 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -69,6 +69,8 @@ public operator fun <@kotlin.internal.OnlyInputTypes T> Iterable.contains(ele /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this collection. + * + * @sample samples.collections.Collections.Usage.elementAt */ public fun Iterable.elementAt(index: Int): T { if (this is List) @@ -78,6 +80,8 @@ public fun Iterable.elementAt(index: Int): T { /** * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this list. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun List.elementAt(index: Int): T { diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index 61350f39de0..34257d012ac 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -31,6 +31,8 @@ public operator fun <@kotlin.internal.OnlyInputTypes T> Sequence.contains(ele * Returns an element at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this sequence. * * The operation is _terminal_. + * + * @sample samples.collections.Collections.Usage.elementAt */ public fun Sequence.elementAt(index: Int): T { return elementAtOrElse(index) { throw IndexOutOfBoundsException("Sequence doesn't contain element at index $index.") } diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 1cc56c9f7dd..2d60e36f3c9 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -20,6 +20,8 @@ import kotlin.random.* /** * Returns a character at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this char sequence. + * + * @sample samples.collections.Collections.Usage.elementAt */ @kotlin.internal.InlineOnly public inline fun CharSequence.elementAt(index: Int): Char { diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt index e644fecb1f0..cd3cde71512 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -487,4 +487,16 @@ class Collections { } } + class Usage { + @Sample + fun elementAt() { + val list = listOf(1, 2, 3) + assertPrints(list.elementAt(0), "1") + assertPrints(list.elementAt(2), "3") + assertFails { list.elementAt(3) } + + val emptyList = emptyList() + assertFails { emptyList.elementAt(0) } + } + } } \ 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 146454d8a83..36380d010f6 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -242,6 +242,7 @@ object Elements : TemplateGroupBase() { } builder { val index = '$' + "index" doc { "Returns ${f.element.prefixWithArticle()} at the given [index] or throws an [IndexOutOfBoundsException] if the [index] is out of bounds of this ${f.collection}." } + sample("samples.collections.Collections.Usage.elementAt") returns("T") body { """