From df6ccbca49a6b3ac29a214e8164cdf024846037f Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Wed, 26 Sep 2018 06:06:20 +0300 Subject: [PATCH] KT-20357 Add samples for `elementAtOrElse` Move samples to Elements nested class. --- .../stdlib/common/src/generated/_Arrays.kt | 54 ++++++++++++------- .../common/src/generated/_Collections.kt | 12 +++-- .../stdlib/common/src/generated/_Sequences.kt | 6 ++- .../stdlib/common/src/generated/_Strings.kt | 6 ++- .../test/samples/collections/collections.kt | 17 ++++-- .../src/templates/Elements.kt | 5 +- 6 files changed, 69 insertions(+), 31 deletions(-) diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index bdf3927ae11..f5b8461404c 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -444,7 +444,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun Array.elementAt(index: Int): T { @@ -454,7 +454,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun ByteArray.elementAt(index: Int): Byte { @@ -464,7 +464,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun ShortArray.elementAt(index: Int): Short { @@ -474,7 +474,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun IntArray.elementAt(index: Int): Int { @@ -484,7 +484,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun LongArray.elementAt(index: Int): Long { @@ -494,7 +494,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun FloatArray.elementAt(index: Int): Float { @@ -504,7 +504,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun DoubleArray.elementAt(index: Int): Double { @@ -514,7 +514,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun BooleanArray.elementAt(index: Int): Boolean { @@ -524,7 +524,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun CharArray.elementAt(index: Int): Char { @@ -533,6 +533,8 @@ public inline fun CharArray.elementAt(index: Int): 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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun Array.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T { @@ -541,6 +543,8 @@ public inline fun Array.elementAtOrElse(index: Int, defaultValue: (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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun ByteArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Byte): Byte { @@ -549,6 +553,8 @@ public inline fun ByteArray.elementAtOrElse(index: Int, defaultValue: (Int) -> B /** * 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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun ShortArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Short): Short { @@ -557,6 +563,8 @@ public inline fun ShortArray.elementAtOrElse(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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun IntArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Int): Int { @@ -565,6 +573,8 @@ public inline fun IntArray.elementAtOrElse(index: Int, defaultValue: (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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun LongArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Long): Long { @@ -573,6 +583,8 @@ public inline fun LongArray.elementAtOrElse(index: Int, defaultValue: (Int) -> L /** * 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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun FloatArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Float): Float { @@ -581,6 +593,8 @@ public inline fun FloatArray.elementAtOrElse(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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun DoubleArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Double): Double { @@ -589,6 +603,8 @@ public inline fun DoubleArray.elementAtOrElse(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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun BooleanArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Boolean): Boolean { @@ -597,6 +613,8 @@ public inline fun BooleanArray.elementAtOrElse(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.Collections.Elements.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun CharArray.elementAtOrElse(index: Int, defaultValue: (Int) -> Char): Char { @@ -606,7 +624,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun Array.elementAtOrNull(index: Int): T? { @@ -616,7 +634,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun ByteArray.elementAtOrNull(index: Int): Byte? { @@ -626,7 +644,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun ShortArray.elementAtOrNull(index: Int): Short? { @@ -636,7 +654,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun IntArray.elementAtOrNull(index: Int): Int? { @@ -646,7 +664,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun LongArray.elementAtOrNull(index: Int): Long? { @@ -656,7 +674,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun FloatArray.elementAtOrNull(index: Int): Float? { @@ -666,7 +684,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun DoubleArray.elementAtOrNull(index: Int): Double? { @@ -676,7 +694,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ @kotlin.internal.InlineOnly public inline fun BooleanArray.elementAtOrNull(index: Int): Boolean? { @@ -686,7 +704,7 @@ 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 + * @sample samples.collections.Collections.Elements.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 56058a4af97..1ddef6f1c1f 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -70,7 +70,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ public fun Iterable.elementAt(index: Int): T { if (this is List) @@ -81,7 +81,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun List.elementAt(index: Int): T { @@ -90,6 +90,8 @@ public inline fun List.elementAt(index: Int): 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 collection. + * + * @sample samples.collections.Collections.Elements.elementAtOrElse */ public fun Iterable.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T { if (this is List) @@ -108,6 +110,8 @@ public fun Iterable.elementAtOrElse(index: Int, defaultValue: (Int) -> 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.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun List.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T { @@ -117,7 +121,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAtOrNull */ public fun Iterable.elementAtOrNull(index: Int): T? { if (this is List) @@ -137,7 +141,7 @@ 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 + * @sample samples.collections.Collections.Elements.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 c038c491fb4..a16c75f7331 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -32,7 +32,7 @@ public operator fun <@kotlin.internal.OnlyInputTypes T> Sequence.contains(ele * * The operation is _terminal_. * - * @sample samples.collections.Collections.Usage.elementAt + * @sample samples.collections.Collections.Elements.elementAt */ public fun Sequence.elementAt(index: Int): T { return elementAtOrElse(index) { throw IndexOutOfBoundsException("Sequence doesn't contain element at index $index.") } @@ -42,6 +42,8 @@ public fun Sequence.elementAt(index: Int): 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 sequence. * * The operation is _terminal_. + * + * @sample samples.collections.Collections.Elements.elementAtOrElse */ public fun Sequence.elementAtOrElse(index: Int, defaultValue: (Int) -> T): T { if (index < 0) @@ -61,7 +63,7 @@ public fun Sequence.elementAtOrElse(index: Int, defaultValue: (Int) -> T) * * The operation is _terminal_. * - * @sample samples.collections.Collections.Usage.elementAtOrNull + * @sample samples.collections.Collections.Elements.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 9777ad82440..26f6b1aa1f4 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -21,7 +21,7 @@ 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 + * @sample samples.collections.Collections.Elements.elementAt */ @kotlin.internal.InlineOnly public inline fun CharSequence.elementAt(index: Int): Char { @@ -30,6 +30,8 @@ public inline fun CharSequence.elementAt(index: Int): 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.elementAtOrElse */ @kotlin.internal.InlineOnly public inline fun CharSequence.elementAtOrElse(index: Int, defaultValue: (Int) -> Char): Char { @@ -39,7 +41,7 @@ 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 + * @sample samples.collections.Collections.Elements.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 72a978d4571..82d2ae99550 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -487,16 +487,16 @@ class Collections { } } - class Usage { + class Elements { @Sample fun elementAt() { val list = listOf(1, 2, 3) assertPrints(list.elementAt(0), "1") assertPrints(list.elementAt(2), "3") - assertFails { list.elementAt(3) } + assertFailsWith { list.elementAt(3) } val emptyList = emptyList() - assertFails { emptyList.elementAt(0) } + assertFailsWith { emptyList.elementAt(0) } } @Sample @@ -509,5 +509,16 @@ class Collections { val emptyList = emptyList() assertPrints(emptyList.elementAtOrNull(0), "null") } + + @Sample + fun elementAtOrElse() { + val list = listOf(1, 2, 3) + assertPrints(list.elementAtOrElse(0) { 42 }, "1") + assertPrints(list.elementAtOrElse(2) { 42 }, "3") + assertPrints(list.elementAtOrElse(3) { 42 }, "42") + + val emptyList = emptyList() + assertPrints(emptyList.elementAtOrElse(0) { "no int" }, "no int") + } } } \ 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 fe63817591c..df526e882b3 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -242,7 +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") + sample("samples.collections.Collections.Elements.elementAt") returns("T") body { """ @@ -269,6 +269,7 @@ object Elements : TemplateGroupBase() { include(CharSequences, Lists) } 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("samples.collections.Collections.Elements.elementAtOrElse") returns("T") body { """ @@ -328,7 +329,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") + sample("samples.collections.Collections.Elements.elementAtOrNull") returns("T?") body { """