diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index 16a879f12d9..59161d9aed6 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -1801,7 +1801,10 @@ public inline fun CharArray.indexOfLast(predicate: (Char) -> Boolean): Int { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun Array.last(): T { if (isEmpty()) @@ -1811,7 +1814,10 @@ public fun Array.last(): T { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun ByteArray.last(): Byte { if (isEmpty()) @@ -1821,7 +1827,10 @@ public fun ByteArray.last(): Byte { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun ShortArray.last(): Short { if (isEmpty()) @@ -1831,7 +1840,10 @@ public fun ShortArray.last(): Short { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun IntArray.last(): Int { if (isEmpty()) @@ -1841,7 +1853,10 @@ public fun IntArray.last(): Int { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun LongArray.last(): Long { if (isEmpty()) @@ -1851,7 +1866,10 @@ public fun LongArray.last(): Long { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun FloatArray.last(): Float { if (isEmpty()) @@ -1861,7 +1879,10 @@ public fun FloatArray.last(): Float { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun DoubleArray.last(): Double { if (isEmpty()) @@ -1871,7 +1892,10 @@ public fun DoubleArray.last(): Double { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun BooleanArray.last(): Boolean { if (isEmpty()) @@ -1881,7 +1905,10 @@ public fun BooleanArray.last(): Boolean { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun CharArray.last(): Char { if (isEmpty()) @@ -1891,7 +1918,10 @@ public fun CharArray.last(): Char { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Array.last(predicate: (T) -> Boolean): T { for (index in this.indices.reversed()) { @@ -1903,7 +1933,10 @@ public inline fun Array.last(predicate: (T) -> Boolean): T { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun ByteArray.last(predicate: (Byte) -> Boolean): Byte { for (index in this.indices.reversed()) { @@ -1915,7 +1948,10 @@ public inline fun ByteArray.last(predicate: (Byte) -> Boolean): Byte { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun ShortArray.last(predicate: (Short) -> Boolean): Short { for (index in this.indices.reversed()) { @@ -1927,7 +1963,10 @@ public inline fun ShortArray.last(predicate: (Short) -> Boolean): Short { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun IntArray.last(predicate: (Int) -> Boolean): Int { for (index in this.indices.reversed()) { @@ -1939,7 +1978,10 @@ public inline fun IntArray.last(predicate: (Int) -> Boolean): Int { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun LongArray.last(predicate: (Long) -> Boolean): Long { for (index in this.indices.reversed()) { @@ -1951,7 +1993,10 @@ public inline fun LongArray.last(predicate: (Long) -> Boolean): Long { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun FloatArray.last(predicate: (Float) -> Boolean): Float { for (index in this.indices.reversed()) { @@ -1963,7 +2008,10 @@ public inline fun FloatArray.last(predicate: (Float) -> Boolean): Float { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun DoubleArray.last(predicate: (Double) -> Boolean): Double { for (index in this.indices.reversed()) { @@ -1975,7 +2023,10 @@ public inline fun DoubleArray.last(predicate: (Double) -> Boolean): Double { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun BooleanArray.last(predicate: (Boolean) -> Boolean): Boolean { for (index in this.indices.reversed()) { @@ -1987,7 +2038,10 @@ public inline fun BooleanArray.last(predicate: (Boolean) -> Boolean): Boolean { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun CharArray.last(predicate: (Char) -> Boolean): Char { for (index in this.indices.reversed()) { @@ -2119,6 +2173,8 @@ public fun CharArray.lastIndexOf(element: Char): Int { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun Array.lastOrNull(): T? { return if (isEmpty()) null else this[size - 1] @@ -2126,6 +2182,8 @@ public fun Array.lastOrNull(): T? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun ByteArray.lastOrNull(): Byte? { return if (isEmpty()) null else this[size - 1] @@ -2133,6 +2191,8 @@ public fun ByteArray.lastOrNull(): Byte? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun ShortArray.lastOrNull(): Short? { return if (isEmpty()) null else this[size - 1] @@ -2140,6 +2200,8 @@ public fun ShortArray.lastOrNull(): Short? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun IntArray.lastOrNull(): Int? { return if (isEmpty()) null else this[size - 1] @@ -2147,6 +2209,8 @@ public fun IntArray.lastOrNull(): Int? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun LongArray.lastOrNull(): Long? { return if (isEmpty()) null else this[size - 1] @@ -2154,6 +2218,8 @@ public fun LongArray.lastOrNull(): Long? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun FloatArray.lastOrNull(): Float? { return if (isEmpty()) null else this[size - 1] @@ -2161,6 +2227,8 @@ public fun FloatArray.lastOrNull(): Float? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun DoubleArray.lastOrNull(): Double? { return if (isEmpty()) null else this[size - 1] @@ -2168,6 +2236,8 @@ public fun DoubleArray.lastOrNull(): Double? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun BooleanArray.lastOrNull(): Boolean? { return if (isEmpty()) null else this[size - 1] @@ -2175,6 +2245,8 @@ public fun BooleanArray.lastOrNull(): Boolean? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun CharArray.lastOrNull(): Char? { return if (isEmpty()) null else this[size - 1] @@ -2182,6 +2254,8 @@ public fun CharArray.lastOrNull(): Char? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Array.lastOrNull(predicate: (T) -> Boolean): T? { for (index in this.indices.reversed()) { @@ -2193,6 +2267,8 @@ public inline fun Array.lastOrNull(predicate: (T) -> Boolean): T? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun ByteArray.lastOrNull(predicate: (Byte) -> Boolean): Byte? { for (index in this.indices.reversed()) { @@ -2204,6 +2280,8 @@ public inline fun ByteArray.lastOrNull(predicate: (Byte) -> Boolean): Byte? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun ShortArray.lastOrNull(predicate: (Short) -> Boolean): Short? { for (index in this.indices.reversed()) { @@ -2215,6 +2293,8 @@ public inline fun ShortArray.lastOrNull(predicate: (Short) -> Boolean): Short? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun IntArray.lastOrNull(predicate: (Int) -> Boolean): Int? { for (index in this.indices.reversed()) { @@ -2226,6 +2306,8 @@ public inline fun IntArray.lastOrNull(predicate: (Int) -> Boolean): Int? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun LongArray.lastOrNull(predicate: (Long) -> Boolean): Long? { for (index in this.indices.reversed()) { @@ -2237,6 +2319,8 @@ public inline fun LongArray.lastOrNull(predicate: (Long) -> Boolean): Long? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun FloatArray.lastOrNull(predicate: (Float) -> Boolean): Float? { for (index in this.indices.reversed()) { @@ -2248,6 +2332,8 @@ public inline fun FloatArray.lastOrNull(predicate: (Float) -> Boolean): Float? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun DoubleArray.lastOrNull(predicate: (Double) -> Boolean): Double? { for (index in this.indices.reversed()) { @@ -2259,6 +2345,8 @@ public inline fun DoubleArray.lastOrNull(predicate: (Double) -> Boolean): Double /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun BooleanArray.lastOrNull(predicate: (Boolean) -> Boolean): Boolean? { for (index in this.indices.reversed()) { @@ -2270,6 +2358,8 @@ public inline fun BooleanArray.lastOrNull(predicate: (Boolean) -> Boolean): Bool /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun CharArray.lastOrNull(predicate: (Char) -> Boolean): Char? { for (index in this.indices.reversed()) { diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index 5ad7c4a5e41..9cd65896550 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -354,7 +354,10 @@ public inline fun List.indexOfLast(predicate: (T) -> Boolean): Int { /** * Returns the last element. - * @throws [NoSuchElementException] if the collection is empty. + * + * @throws NoSuchElementException if the collection is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun Iterable.last(): T { when (this) { @@ -373,7 +376,10 @@ public fun Iterable.last(): T { /** * Returns the last element. - * @throws [NoSuchElementException] if the list is empty. + * + * @throws NoSuchElementException if the list is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun List.last(): T { if (isEmpty()) @@ -383,7 +389,10 @@ public fun List.last(): T { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Iterable.last(predicate: (T) -> Boolean): T { var last: T? = null @@ -401,7 +410,10 @@ public inline fun Iterable.last(predicate: (T) -> Boolean): T { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun List.last(predicate: (T) -> Boolean): T { val iterator = this.listIterator(size) @@ -438,6 +450,8 @@ public fun <@kotlin.internal.OnlyInputTypes T> List.lastIndexOf(element: T): /** * Returns the last element, or `null` if the collection is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun Iterable.lastOrNull(): T? { when (this) { @@ -456,6 +470,8 @@ public fun Iterable.lastOrNull(): T? { /** * Returns the last element, or `null` if the list is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun List.lastOrNull(): T? { return if (isEmpty()) null else this[size - 1] @@ -463,6 +479,8 @@ public fun List.lastOrNull(): T? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Iterable.lastOrNull(predicate: (T) -> Boolean): T? { var last: T? = null @@ -476,6 +494,8 @@ public inline fun Iterable.lastOrNull(predicate: (T) -> Boolean): T? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun List.lastOrNull(predicate: (T) -> Boolean): T? { val iterator = this.listIterator(size) diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index b002457d390..649b97e7d39 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -196,9 +196,12 @@ public inline fun Sequence.indexOfLast(predicate: (T) -> Boolean): Int { /** * Returns the last element. - * @throws [NoSuchElementException] if the sequence is empty. * * The operation is _terminal_. + * + * @throws NoSuchElementException if the sequence is empty. + * + * @sample samples.collections.Collections.Elements.last */ public fun Sequence.last(): T { val iterator = iterator() @@ -212,9 +215,12 @@ public fun Sequence.last(): T { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. * * The operation is _terminal_. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Sequence.last(predicate: (T) -> Boolean): T { var last: T? = null @@ -251,6 +257,8 @@ public fun <@kotlin.internal.OnlyInputTypes T> Sequence.lastIndexOf(element: * Returns the last element, or `null` if the sequence is empty. * * The operation is _terminal_. + * + * @sample samples.collections.Collections.Elements.last */ public fun Sequence.lastOrNull(): T? { val iterator = iterator() @@ -266,6 +274,8 @@ public fun Sequence.lastOrNull(): T? { * Returns the last element matching the given [predicate], or `null` if no such element was found. * * The operation is _terminal_. + * + * @sample samples.collections.Collections.Elements.last */ public inline fun Sequence.lastOrNull(predicate: (T) -> Boolean): T? { var last: T? = null diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index 90a0eee90f5..81b950b8020 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -139,7 +139,10 @@ public inline fun CharSequence.indexOfLast(predicate: (Char) -> Boolean): Int { /** * Returns the last character. - * @throws [NoSuchElementException] if the char sequence is empty. + * + * @throws NoSuchElementException if the char sequence is empty. + * + * @sample samples.text.Strings.last */ public fun CharSequence.last(): Char { if (isEmpty()) @@ -149,7 +152,10 @@ public fun CharSequence.last(): Char { /** * Returns the last character matching the given [predicate]. - * @throws [NoSuchElementException] if no such character is found. + * + * @throws NoSuchElementException if no such character is found. + * + * @sample samples.text.Strings.last */ public inline fun CharSequence.last(predicate: (Char) -> Boolean): Char { for (index in this.indices.reversed()) { @@ -161,6 +167,8 @@ public inline fun CharSequence.last(predicate: (Char) -> Boolean): Char { /** * Returns the last character, or `null` if the char sequence is empty. + * + * @sample samples.text.Strings.last */ public fun CharSequence.lastOrNull(): Char? { return if (isEmpty()) null else this[length - 1] @@ -168,6 +176,8 @@ public fun CharSequence.lastOrNull(): Char? { /** * Returns the last character matching the given [predicate], or `null` if no such character was found. + * + * @sample samples.text.Strings.last */ public inline fun CharSequence.lastOrNull(predicate: (Char) -> Boolean): Char? { for (index in this.indices.reversed()) { diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 271977e22e7..e9cbaf2f54f 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt @@ -884,7 +884,10 @@ public inline fun UShortArray.indexOfLast(predicate: (UShort) -> Boolean): Int { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -895,7 +898,10 @@ public inline fun UIntArray.last(): UInt { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -906,7 +912,10 @@ public inline fun ULongArray.last(): ULong { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -917,7 +926,10 @@ public inline fun UByteArray.last(): UByte { /** * Returns the last element. - * @throws [NoSuchElementException] if the array is empty. + * + * @throws NoSuchElementException if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -928,7 +940,10 @@ public inline fun UShortArray.last(): UShort { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -943,7 +958,10 @@ public inline fun UIntArray.last(predicate: (UInt) -> Boolean): UInt { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -958,7 +976,10 @@ public inline fun ULongArray.last(predicate: (ULong) -> Boolean): ULong { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -973,7 +994,10 @@ public inline fun UByteArray.last(predicate: (UByte) -> Boolean): UByte { /** * Returns the last element matching the given [predicate]. - * @throws [NoSuchElementException] if no such element is found. + * + * @throws NoSuchElementException if no such element is found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1028,6 +1052,8 @@ public inline fun UShortArray.lastIndexOf(element: UShort): Int { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1037,6 +1063,8 @@ public fun UIntArray.lastOrNull(): UInt? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1046,6 +1074,8 @@ public fun ULongArray.lastOrNull(): ULong? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1055,6 +1085,8 @@ public fun UByteArray.lastOrNull(): UByte? { /** * Returns the last element, or `null` if the array is empty. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1064,6 +1096,8 @@ public fun UShortArray.lastOrNull(): UShort? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1078,6 +1112,8 @@ public inline fun UIntArray.lastOrNull(predicate: (UInt) -> Boolean): UInt? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1092,6 +1128,8 @@ public inline fun ULongArray.lastOrNull(predicate: (ULong) -> Boolean): ULong? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -1106,6 +1144,8 @@ public inline fun UByteArray.lastOrNull(predicate: (UByte) -> Boolean): UByte? { /** * Returns the last element matching the given [predicate], or `null` if no such element was found. + * + * @sample samples.collections.Collections.Elements.last */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt index 0c7d7fc7be3..509680a3027 100644 --- a/libraries/stdlib/samples/test/samples/collections/collections.kt +++ b/libraries/stdlib/samples/test/samples/collections/collections.kt @@ -800,6 +800,19 @@ class Collections { val emptyList = emptyList() assertPrints(emptyList.getOrNull(0), "null") } + + @Sample + fun last() { + val list = listOf(1, 2, 3, 4) + assertPrints(list.last(), "4") + assertPrints(list.last { it % 2 == 1 }, "3") + assertPrints(list.lastOrNull { it < 0 }, "null") + assertFails { list.last { it < 0 } } + + val emptyList = emptyList() + assertPrints(emptyList.lastOrNull(), "null") + assertFails { emptyList.last() } + } } class Sorting { diff --git a/libraries/stdlib/samples/test/samples/text/strings.kt b/libraries/stdlib/samples/test/samples/text/strings.kt index 1c3e0ff6086..a30b571ce47 100644 --- a/libraries/stdlib/samples/test/samples/text/strings.kt +++ b/libraries/stdlib/samples/test/samples/text/strings.kt @@ -408,4 +408,17 @@ class Strings { assertPrints(matchDetails(inputString, toFind, 2), "Searching for 'ever' in 'Never ever give up' starting at position 2: Found at 6") assertPrints(matchDetails(inputString, toFind, 10), "Searching for 'ever' in 'Never ever give up' starting at position 10: Not found") } + + @Sample + fun last() { + val string = "Kotlin 1.4.0" + assertPrints(string.last(), "0") + assertPrints(string.last { it.isLetter() }, "n") + assertPrints(string.lastOrNull { it > 'z' }, "null") + assertFails { string.last { it > 'z' } } + + val emptyString = "" + assertPrints(emptyString.lastOrNull(), "null") + assertFails { emptyString.last() } + } } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt index 79050071b25..4fc603b84af 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -5,6 +5,8 @@ package templates +import templates.DocExtensions.collection +import templates.DocExtensions.element import templates.Family.* import templates.SequenceClass.* @@ -567,13 +569,19 @@ object Elements : TemplateGroupBase() { body { "return firstOrNull(predicate)"} } + private val Family.sampleClass: String + get() = when (this) { + Strings, CharSequences -> "samples.text.Strings" + else -> "samples.collections.Collections.Elements" + } val f_last = fn("last()") { includeDefault() include(CharSequences, Lists, ArraysOfUnsigned) } builder { - doc { """Returns the last ${f.element}. - @throws [NoSuchElementException] if the ${f.collection} is empty.""" } + doc { "Returns the last ${f.element}." } + throws("NoSuchElementException", "if the ${f.collection} is empty.") + sample("${f.sampleClass}.last") returns("T") body { """ @@ -621,6 +629,7 @@ object Elements : TemplateGroupBase() { include(Lists, CharSequences, ArraysOfUnsigned) } builder { doc { "Returns the last ${f.element}, or `null` if the ${f.collection} is empty." } + sample("${f.sampleClass}.last") returns("T?") body { """ @@ -668,8 +677,9 @@ object Elements : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { """Returns the last ${f.element} matching the given [predicate]. - @throws [NoSuchElementException] if no such ${f.element} is found.""" } + doc { "Returns the last ${f.element} matching the given [predicate]." } + throws("NoSuchElementException", "if no such ${f.element} is found.") + sample("${f.sampleClass}.last") returns("T") body { """ @@ -716,6 +726,7 @@ object Elements : TemplateGroupBase() { specialFor(ArraysOfUnsigned) { inlineOnly() } doc { "Returns the last ${f.element} matching the given [predicate], or `null` if no such ${f.element} was found." } + sample("${f.sampleClass}.last") returns("T?") body { """