From 7827bbf64ba4a8b120d321bae9c571a19ae6991a Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Wed, 4 Feb 2015 13:53:42 +0100 Subject: [PATCH] Standard library documentation updates. --- core/builtins/native/kotlin/Annotation.kt | 5 + core/builtins/native/kotlin/Any.kt | 24 ++ core/builtins/native/kotlin/Array.kt | 31 ++ core/builtins/native/kotlin/Iterator.kt | 54 +++ core/builtins/native/kotlin/Library.kt | 21 +- core/builtins/native/kotlin/Nothing.kt | 3 +- core/builtins/src/kotlin/Annotations.kt | 20 + core/builtins/src/kotlin/Inline.kt | 12 + core/builtins/src/kotlin/Progression.kt | 15 + core/builtins/src/kotlin/PropertyMetadata.kt | 6 + core/builtins/src/kotlin/Range.kt | 16 + .../src/kotlin/internal/progressionUtil.kt | 12 +- .../editor/quickDoc/MethodFromStdLib.kt | 2 +- libraries/stdlib/src/generated/_Aggregates.kt | 100 ++--- libraries/stdlib/src/generated/_Elements.kt | 372 ++++++++++-------- libraries/stdlib/src/generated/_Filtering.kt | 202 +++++----- libraries/stdlib/src/generated/_Strings.kt | 132 +++---- .../kotlin/collections/AbstractIterator.kt | 14 +- .../src/kotlin/collections/ArraysJVM.kt | 17 +- .../src/kotlin/collections/Iterators.kt | 6 +- .../stdlib/src/kotlin/collections/JUtilJVM.kt | 4 +- .../stdlib/src/kotlin/collections/Maps.kt | 113 ++++-- .../stdlib/src/kotlin/collections/MapsJVM.kt | 14 +- .../kotlin/collections/MutableCollections.kt | 16 +- .../src/kotlin/collections/Operations.kt | 6 +- .../src/kotlin/properties/Delegation.kt | 129 ++++++ libraries/stdlib/src/kotlin/text/Strings.kt | 188 +++++---- .../stdlib/src/kotlin/util/AssertionsJVM.kt | 4 +- libraries/stdlib/src/kotlin/util/Integers.kt | 3 + libraries/stdlib/src/kotlin/util/JLangJVM.kt | 19 +- libraries/stdlib/src/kotlin/util/Numbers.kt | 8 +- libraries/stdlib/src/kotlin/util/Ordering.kt | 10 +- .../stdlib/src/kotlin/util/Preconditions.kt | 32 +- libraries/stdlib/src/kotlin/util/Standard.kt | 10 +- .../stdlib/src/kotlin/util/StandardJVM.kt | 7 +- libraries/stdlib/src/kotlin/util/SystemJVM.kt | 8 +- libraries/stdlib/src/kotlin/util/Tuples.kt | 25 +- .../src/templates/Aggregates.kt | 10 +- .../src/templates/Elements.kt | 48 ++- .../src/templates/Filtering.kt | 39 +- .../src/templates/Strings.kt | 12 +- 41 files changed, 1144 insertions(+), 625 deletions(-) diff --git a/core/builtins/native/kotlin/Annotation.kt b/core/builtins/native/kotlin/Annotation.kt index 48dc4e67bd0..1f6db4aaeed 100644 --- a/core/builtins/native/kotlin/Annotation.kt +++ b/core/builtins/native/kotlin/Annotation.kt @@ -16,4 +16,9 @@ package kotlin +/** + * Base trait implicitly implemented by all annotation interfaces. + * See [Kotlin language documentation](http://kotlinlang.org/docs/reference/annotations.html) for more information + * on annotations. + */ public trait Annotation diff --git a/core/builtins/native/kotlin/Any.kt b/core/builtins/native/kotlin/Any.kt index e8c1f47705d..228b17713d2 100644 --- a/core/builtins/native/kotlin/Any.kt +++ b/core/builtins/native/kotlin/Any.kt @@ -16,10 +16,34 @@ package kotlin +/** + * The root of the Kotlin class hierarchy. Every Kotlin class has [Any] as a superclass. + */ public open class Any { + /** + * Indicates whether some other object is "equal to" this one. Implementations must fulfil the following + * requirements: + * + * * Reflexive: for any non-null reference value x, x.equals(x) should return true. + * * Symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. + * * Transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true + * * Consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified. + * + * Note that the `==` operator in Kotlin code is translated into a call to [equals] when objects on both sides of the + * operator are not null. + */ public open fun equals(other: Any?): Boolean + /** + * Returns a hash code value for the object. The general contract of hashCode is: + * + * * Whenever it is invoked on the same object more than once, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. + * * If two objects are equal according to the equals() method, then calling the hashCode method on each of the two objects must produce the same integer result. + */ public open fun hashCode(): Int + /** + * Returns a string representation of the object. + */ public open fun toString(): String } diff --git a/core/builtins/native/kotlin/Array.kt b/core/builtins/native/kotlin/Array.kt index 6fcb3c5defc..d84ec5c9d4b 100644 --- a/core/builtins/native/kotlin/Array.kt +++ b/core/builtins/native/kotlin/Array.kt @@ -16,13 +16,44 @@ package kotlin +/** + * Represents an array (specifically, a Java array when targeting the JVM platform). + * Array instances can be created using the [array] and [arrayOfNulls] standard + * library functions. + * See [Kotlin language documentation](http://kotlinlang.org/docs/reference/basic-types.html#arrays) + * for more information on arrays. + */ public class Array private (): Cloneable { + /** + * Returns the array element at the specified [index]. This method can be called using the + * index operator: + * ``` + * value = arr[index] + * ``` + */ public fun get(index: Int): T + + /** + * Sets the array element at the specified [index] to the specified [value]. This method can + * be called using the index operator: + * ``` + * arr[index] = value + * ``` + */ public fun set(index: Int, value: T): Unit + /** + * Returns the number of elements in the array. + */ public fun size(): Int + /** + * Creates an iterator for iterating over the elements of the array. + */ public fun iterator(): Iterator + /** + * Creates a shallow copy of the array. + */ public override fun clone(): Array } diff --git a/core/builtins/native/kotlin/Iterator.kt b/core/builtins/native/kotlin/Iterator.kt index 21b003d6a75..c85b955f561 100644 --- a/core/builtins/native/kotlin/Iterator.kt +++ b/core/builtins/native/kotlin/Iterator.kt @@ -16,26 +16,67 @@ package kotlin +/** + * An iterator over a collection or another entity that can be represented as a sequence of elements. + * Allows to sequentially access the elements. + */ public trait Iterator { + /** + * Returns the next element in the iteration. + */ public fun next(): T + + /** + * Returns `true` if the iteration has more elements. + */ public fun hasNext(): Boolean } +/** + * An iterator over a mutable collection. Provides the ability to remove elements while iterating. + * @see MutableCollection.iterator + */ public trait MutableIterator : Iterator { + /** + * Removes from the underlying collection the last element returned by this iterator. + */ public fun remove(): Unit } +/** + * An iterator over a collection that supports indexed access. + * @see List.listIterator + */ public trait ListIterator : Iterator { // Query Operations override fun next(): T override fun hasNext(): Boolean + /** + * Returns `true` if there are elements in the iteration before the current element. + */ public fun hasPrevious(): Boolean + + /** + * Returns the previous element in the iteration and moves the cursor position backwards. + */ public fun previous(): T + + /** + * Returns the index of the element that would be returned by a subsequent call to [next]. + */ public fun nextIndex(): Int + + /** + * Returns the index of the element that would be returned by a subsequent call to [previous]. + */ public fun previousIndex(): Int } +/** + * An iterator over a mutable collection that supports indexed access. Provides the ability + * to add, modify and remove elements while iterating. + */ public trait MutableListIterator : ListIterator, MutableIterator { // Query Operations override fun next(): T @@ -43,6 +84,19 @@ public trait MutableListIterator : ListIterator, MutableIterator { // Modification Operations override fun remove(): Unit + + /** + * Replaces the last element returned by [next] or [previous] with the specified element [e]. + */ public fun set(e: T): Unit + + /** + * Adds the specified element [e] into the underlying collection immediately before the element that would be + * returned by [next], if any, and after the element that would be returned by [previous], if any. + * (If the collection contains no elements, the new element becomes the sole element in the collection.) + * The new element is inserted before the implicit cursor: a subsequent call to [next] would be unaffected, + * and a subsequent call to [previous] would return the new element. (This call increases by one the value \ + * that would be returned by a call to [nextIndex] or [previousIndex].) + */ public fun add(e: T): Unit } diff --git a/core/builtins/native/kotlin/Library.kt b/core/builtins/native/kotlin/Library.kt index 0b421b84e09..2d1a9d4adbe 100644 --- a/core/builtins/native/kotlin/Library.kt +++ b/core/builtins/native/kotlin/Library.kt @@ -16,13 +16,32 @@ package kotlin +/** + * Returns true if the receiver and the [other] object are the same object instance, or if they + * are both null. + */ public fun Any?.identityEquals(other: Any?): Boolean // = this === other +/** + * Returns true if the receiver and the [other] object are "equal" to each other, or if they are + * both null. + * @see Any.equals + */ public fun Any?.equals(other: Any?): Boolean -// Returns "null" for null +/** + * Returns a string representation of the object. Can be called with a null receiver, in which case + * it returns the string "null". + */ public fun Any?.toString(): String +/** + * Concatenates this string with the string representation of the given [other] object. If either the receiver + * or the [other] object are null, they are represented as the string "null". + */ public fun String?.plus(other: Any?): String +/** + * Returns an array of objects of the given type with the given [size], initialized with null values. + */ public fun arrayOfNulls(size: Int): Array diff --git a/core/builtins/native/kotlin/Nothing.kt b/core/builtins/native/kotlin/Nothing.kt index 438d59ea88b..0306fe46fba 100644 --- a/core/builtins/native/kotlin/Nothing.kt +++ b/core/builtins/native/kotlin/Nothing.kt @@ -17,6 +17,7 @@ package kotlin /** - * Nothing has no instances + * Nothing has no instances. You can use Nothing to represent "a value that never exists": for example, + * if a function has the return type of Nothing, it means that it never returns (always throws an exception). */ public class Nothing private () {} diff --git a/core/builtins/src/kotlin/Annotations.kt b/core/builtins/src/kotlin/Annotations.kt index d61cab7e9b5..a189279a794 100644 --- a/core/builtins/src/kotlin/Annotations.kt +++ b/core/builtins/src/kotlin/Annotations.kt @@ -16,10 +16,30 @@ package kotlin +/** + * Marks the annotated class as a data class. The compiler automatically generates + * equals()/hashCode(), toString(), componentN() and copy() functions for data classes. + * See [the Kotlin language documentation](http://kotlinlang.org/docs/reference/data-classes.html) + * for more information. + */ public annotation class data +/** + * Marks the annotated class, function or property as deprecated. + * @param value the message explaining the deprecation and recommending an alternative API to use. + */ public annotation class deprecated(val value: String) +/** + * Suppresses the given compilation warnings in the annotated element. + * @param names names of the compiler diagnostics to suppress. + */ public annotation class suppress(vararg val names: String) +/** + * Enables the tail call optimization for the annotated function. If the annotated function + * calls itself recursively as the last operation it performs, it will be executed without + * growing the stack depth. Tail call optimization is currently only supported by the JVM + * backend. + */ public annotation class tailRecursive diff --git a/core/builtins/src/kotlin/Inline.kt b/core/builtins/src/kotlin/Inline.kt index dde67490901..e162abb9ae4 100644 --- a/core/builtins/src/kotlin/Inline.kt +++ b/core/builtins/src/kotlin/Inline.kt @@ -16,8 +16,20 @@ package kotlin +/** + * Annotates the parameter of a function annotated as [inline] and forbids inlining of + * function literals passed as arguments for this parameter. + */ public annotation class noinline +/** + * Enables inlining of the annotated function and the function literals that it takes as parameters into the + * calling functions. Inline functions can use reified type parameters, and lambdas passed to inline + * functions can contain non-local returns. + * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/inline-functions.html) for more information. + * @see noinline + * @see inlineOptions + */ public annotation class inline(public val strategy: InlineStrategy = InlineStrategy.AS_FUNCTION) public enum class InlineStrategy { diff --git a/core/builtins/src/kotlin/Progression.kt b/core/builtins/src/kotlin/Progression.kt index 58396f3fabc..f912d4ddd48 100644 --- a/core/builtins/src/kotlin/Progression.kt +++ b/core/builtins/src/kotlin/Progression.kt @@ -16,10 +16,25 @@ package kotlin +/** + * Represents a sequence of numbers or characters with a given start value, end value and step. + * This class is intended to be used in 'for' loops, and the JVM backend suggests efficient + * bytecode generation for it. Progressions with a step of -1 can be created through the + * `downTo` method on classes representing primitive types. + */ public trait Progression : Iterable { + /** + * The start value of the progression. + */ public val start: N + /** + * The end value of the progression (inclusive). + */ public val end: N + /** + * The step of the progression. + */ public val increment: Number } diff --git a/core/builtins/src/kotlin/PropertyMetadata.kt b/core/builtins/src/kotlin/PropertyMetadata.kt index 79a48c671b1..8b6174f7873 100644 --- a/core/builtins/src/kotlin/PropertyMetadata.kt +++ b/core/builtins/src/kotlin/PropertyMetadata.kt @@ -16,7 +16,13 @@ package kotlin +/** + * Represents a property in a Kotlin class. + */ public trait PropertyMetadata { + /** + * The name of the property. + */ public val name: String } diff --git a/core/builtins/src/kotlin/Range.kt b/core/builtins/src/kotlin/Range.kt index d538a67fc45..fad08d53c6d 100644 --- a/core/builtins/src/kotlin/Range.kt +++ b/core/builtins/src/kotlin/Range.kt @@ -16,13 +16,29 @@ package kotlin +/** + * Represents a range of values (for example, numbers or characters). + * See the [Kotlin language documentation](http://kotlinlang.org/docs/reference/ranges.html) for more information. + */ public trait Range> { + /** + * The minimum value in the range. + */ public val start: T + /** + * The maximum value in the range (inclusive). + */ public val end: T + /** + * Checks if the specified value belongs to the range. + */ public fun contains(item: T): Boolean + /** + * Checks if the range is empty. + */ public fun isEmpty(): Boolean = start > end override fun toString(): String = "$start..$end" diff --git a/core/builtins/src/kotlin/internal/progressionUtil.kt b/core/builtins/src/kotlin/internal/progressionUtil.kt index c594486f233..76cf7f0ed12 100644 --- a/core/builtins/src/kotlin/internal/progressionUtil.kt +++ b/core/builtins/src/kotlin/internal/progressionUtil.kt @@ -39,11 +39,11 @@ private fun differenceModulo(a: Long, b: Long, c: Long): Long { /** * Calculates the final element of a bounded arithmetic progression, i.e. the last element of the progression which is in the range - * from {@code start} to {@code end} in case of a positive {@code increment}, or from {@code end} to {@code start} in case of a negative + * from [start] to [end] in case of a positive [increment], or from [end] to [start] in case of a negative * increment. * - *

No validation on passed parameters is performed. The given parameters should satisfy the condition: either - * {@code increment > 0} and {@code start <= end}, or {@code increment < 0} and {@code start >= end}. + * No validation on passed parameters is performed. The given parameters should satisfy the condition: either + * `increment > 0` and `start >= end`, or `increment < 0` and`start >= end`. * @param start first element of the progression * @param end ending bound for the progression * @param increment increment, or difference of successive elements in the progression @@ -60,11 +60,11 @@ public fun getProgressionFinalElement(start: Int, end: Int, increment: Int): Int /** * Calculates the final element of a bounded arithmetic progression, i.e. the last element of the progression which is in the range - * from {@code start} to {@code end} in case of a positive {@code increment}, or from {@code end} to {@code start} in case of a negative + * from [start] to [end] in case of a positive [increment], or from [end] to [start] in case of a negative * increment. * - *

No validation on passed parameters is performed. The given parameters should satisfy the condition: either - * {@code increment > 0} and {@code start <= end}, or {@code increment < 0} and {@code start >= end}. + * No validation on passed parameters is performed. The given parameters should satisfy the condition: either + * `increment > 0` and `start >= end`, or `increment < 0` and`start >= end`. * @param start first element of the progression * @param end ending bound for the progression * @param increment increment, or difference of successive elements in the progression diff --git a/idea/testData/editor/quickDoc/MethodFromStdLib.kt b/idea/testData/editor/quickDoc/MethodFromStdLib.kt index eb2bed96877..57fb7c02a15 100644 --- a/idea/testData/editor/quickDoc/MethodFromStdLib.kt +++ b/idea/testData/editor/quickDoc/MethodFromStdLib.kt @@ -2,4 +2,4 @@ fun test() { listOf(1, 2, 4).filter { it > 0 } } -// INFO: inline public fun <T> Iterable<T>.filter(predicate: (T) → Boolean): List<T>

Returns a list containing all elements matching the given *predicate*

+// INFO: inline public fun <T> Iterable<T>.filter(predicate: (T) → Boolean): List<T>

Returns a list containing all elements matching the given [predicate]

diff --git a/libraries/stdlib/src/generated/_Aggregates.kt b/libraries/stdlib/src/generated/_Aggregates.kt index 97998e11a75..adcdb6df42f 100644 --- a/libraries/stdlib/src/generated/_Aggregates.kt +++ b/libraries/stdlib/src/generated/_Aggregates.kt @@ -218,7 +218,7 @@ public fun String.any(): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun Array.any(predicate: (T) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -226,7 +226,7 @@ public inline fun Array.any(predicate: (T) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun BooleanArray.any(predicate: (Boolean) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -234,7 +234,7 @@ public inline fun BooleanArray.any(predicate: (Boolean) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun ByteArray.any(predicate: (Byte) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -242,7 +242,7 @@ public inline fun ByteArray.any(predicate: (Byte) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun CharArray.any(predicate: (Char) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -250,7 +250,7 @@ public inline fun CharArray.any(predicate: (Char) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun DoubleArray.any(predicate: (Double) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -258,7 +258,7 @@ public inline fun DoubleArray.any(predicate: (Double) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun FloatArray.any(predicate: (Float) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -266,7 +266,7 @@ public inline fun FloatArray.any(predicate: (Float) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun IntArray.any(predicate: (Int) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -274,7 +274,7 @@ public inline fun IntArray.any(predicate: (Int) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun LongArray.any(predicate: (Long) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -282,7 +282,7 @@ public inline fun LongArray.any(predicate: (Long) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun ShortArray.any(predicate: (Short) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -290,7 +290,7 @@ public inline fun ShortArray.any(predicate: (Short) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun Iterable.any(predicate: (T) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -298,7 +298,7 @@ public inline fun Iterable.any(predicate: (T) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun Map.any(predicate: (Map.Entry) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -306,7 +306,7 @@ public inline fun Map.any(predicate: (Map.Entry) -> Boolean): } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun Stream.any(predicate: (T) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -314,7 +314,7 @@ public inline fun Stream.any(predicate: (T) -> Boolean): Boolean { } /** - * Returns *true* if any element matches the given *predicate* + * Returns *true* if any element matches the given [predicate] */ public inline fun String.any(predicate: (Char) -> Boolean): Boolean { for (element in this) if (predicate(element)) return true @@ -424,7 +424,7 @@ public fun String.count(): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun Array.count(predicate: (T) -> Boolean): Int { var count = 0 @@ -433,7 +433,7 @@ public inline fun Array.count(predicate: (T) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun BooleanArray.count(predicate: (Boolean) -> Boolean): Int { var count = 0 @@ -442,7 +442,7 @@ public inline fun BooleanArray.count(predicate: (Boolean) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun ByteArray.count(predicate: (Byte) -> Boolean): Int { var count = 0 @@ -451,7 +451,7 @@ public inline fun ByteArray.count(predicate: (Byte) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun CharArray.count(predicate: (Char) -> Boolean): Int { var count = 0 @@ -460,7 +460,7 @@ public inline fun CharArray.count(predicate: (Char) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun DoubleArray.count(predicate: (Double) -> Boolean): Int { var count = 0 @@ -469,7 +469,7 @@ public inline fun DoubleArray.count(predicate: (Double) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun FloatArray.count(predicate: (Float) -> Boolean): Int { var count = 0 @@ -478,7 +478,7 @@ public inline fun FloatArray.count(predicate: (Float) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun IntArray.count(predicate: (Int) -> Boolean): Int { var count = 0 @@ -487,7 +487,7 @@ public inline fun IntArray.count(predicate: (Int) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun LongArray.count(predicate: (Long) -> Boolean): Int { var count = 0 @@ -496,7 +496,7 @@ public inline fun LongArray.count(predicate: (Long) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun ShortArray.count(predicate: (Short) -> Boolean): Int { var count = 0 @@ -505,7 +505,7 @@ public inline fun ShortArray.count(predicate: (Short) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun Iterable.count(predicate: (T) -> Boolean): Int { var count = 0 @@ -514,7 +514,7 @@ public inline fun Iterable.count(predicate: (T) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun Map.count(predicate: (Map.Entry) -> Boolean): Int { var count = 0 @@ -523,7 +523,7 @@ public inline fun Map.count(predicate: (Map.Entry) -> Boolean } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun Stream.count(predicate: (T) -> Boolean): Int { var count = 0 @@ -532,7 +532,7 @@ public inline fun Stream.count(predicate: (T) -> Boolean): Int { } /** - * Returns the number of elements matching the given *predicate* + * Returns the number of elements matching the given [predicate] */ public inline fun String.count(predicate: (Char) -> Boolean): Int { var count = 0 @@ -2243,7 +2243,7 @@ public inline fun String.reduceRight(operation: (Char, Char) -> Char): Char { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Array.sumBy(transform: (T) -> Int): Int { var sum: Int = 0 @@ -2254,7 +2254,7 @@ public inline fun Array.sumBy(transform: (T) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun BooleanArray.sumBy(transform: (Boolean) -> Int): Int { var sum: Int = 0 @@ -2265,7 +2265,7 @@ public inline fun BooleanArray.sumBy(transform: (Boolean) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun ByteArray.sumBy(transform: (Byte) -> Int): Int { var sum: Int = 0 @@ -2276,7 +2276,7 @@ public inline fun ByteArray.sumBy(transform: (Byte) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun CharArray.sumBy(transform: (Char) -> Int): Int { var sum: Int = 0 @@ -2287,7 +2287,7 @@ public inline fun CharArray.sumBy(transform: (Char) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun DoubleArray.sumBy(transform: (Double) -> Int): Int { var sum: Int = 0 @@ -2298,7 +2298,7 @@ public inline fun DoubleArray.sumBy(transform: (Double) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun FloatArray.sumBy(transform: (Float) -> Int): Int { var sum: Int = 0 @@ -2309,7 +2309,7 @@ public inline fun FloatArray.sumBy(transform: (Float) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun IntArray.sumBy(transform: (Int) -> Int): Int { var sum: Int = 0 @@ -2320,7 +2320,7 @@ public inline fun IntArray.sumBy(transform: (Int) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun LongArray.sumBy(transform: (Long) -> Int): Int { var sum: Int = 0 @@ -2331,7 +2331,7 @@ public inline fun LongArray.sumBy(transform: (Long) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun ShortArray.sumBy(transform: (Short) -> Int): Int { var sum: Int = 0 @@ -2342,7 +2342,7 @@ public inline fun ShortArray.sumBy(transform: (Short) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Iterable.sumBy(transform: (T) -> Int): Int { var sum: Int = 0 @@ -2353,7 +2353,7 @@ public inline fun Iterable.sumBy(transform: (T) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Stream.sumBy(transform: (T) -> Int): Int { var sum: Int = 0 @@ -2364,7 +2364,7 @@ public inline fun Stream.sumBy(transform: (T) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from characters in the string */ public inline fun String.sumBy(transform: (Char) -> Int): Int { var sum: Int = 0 @@ -2375,7 +2375,7 @@ public inline fun String.sumBy(transform: (Char) -> Int): Int { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Array.sumByDouble(transform: (T) -> Double): Double { var sum: Double = 0.0 @@ -2386,7 +2386,7 @@ public inline fun Array.sumByDouble(transform: (T) -> Double): Double } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun BooleanArray.sumByDouble(transform: (Boolean) -> Double): Double { var sum: Double = 0.0 @@ -2397,7 +2397,7 @@ public inline fun BooleanArray.sumByDouble(transform: (Boolean) -> Double): Doub } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun ByteArray.sumByDouble(transform: (Byte) -> Double): Double { var sum: Double = 0.0 @@ -2408,7 +2408,7 @@ public inline fun ByteArray.sumByDouble(transform: (Byte) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun CharArray.sumByDouble(transform: (Char) -> Double): Double { var sum: Double = 0.0 @@ -2419,7 +2419,7 @@ public inline fun CharArray.sumByDouble(transform: (Char) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun DoubleArray.sumByDouble(transform: (Double) -> Double): Double { var sum: Double = 0.0 @@ -2430,7 +2430,7 @@ public inline fun DoubleArray.sumByDouble(transform: (Double) -> Double): Double } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun FloatArray.sumByDouble(transform: (Float) -> Double): Double { var sum: Double = 0.0 @@ -2441,7 +2441,7 @@ public inline fun FloatArray.sumByDouble(transform: (Float) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun IntArray.sumByDouble(transform: (Int) -> Double): Double { var sum: Double = 0.0 @@ -2452,7 +2452,7 @@ public inline fun IntArray.sumByDouble(transform: (Int) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun LongArray.sumByDouble(transform: (Long) -> Double): Double { var sum: Double = 0.0 @@ -2463,7 +2463,7 @@ public inline fun LongArray.sumByDouble(transform: (Long) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun ShortArray.sumByDouble(transform: (Short) -> Double): Double { var sum: Double = 0.0 @@ -2474,7 +2474,7 @@ public inline fun ShortArray.sumByDouble(transform: (Short) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Iterable.sumByDouble(transform: (T) -> Double): Double { var sum: Double = 0.0 @@ -2485,7 +2485,7 @@ public inline fun Iterable.sumByDouble(transform: (T) -> Double): Double } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from elements in the collection */ public inline fun Stream.sumByDouble(transform: (T) -> Double): Double { var sum: Double = 0.0 @@ -2496,7 +2496,7 @@ public inline fun Stream.sumByDouble(transform: (T) -> Double): Double { } /** - * Returns the sum of all values produced by `transform` function from elements in the collection + * Returns the sum of all values produced by [transform] function from characters in the string */ public inline fun String.sumByDouble(transform: (Char) -> Double): Double { var sum: Double = 0.0 diff --git a/libraries/stdlib/src/generated/_Elements.kt b/libraries/stdlib/src/generated/_Elements.kt index 77500227154..80c0d3dc818 100644 --- a/libraries/stdlib/src/generated/_Elements.kt +++ b/libraries/stdlib/src/generated/_Elements.kt @@ -548,7 +548,8 @@ public fun String.elementAt(index: Int): Char { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun Array.first(): T { if (isEmpty()) @@ -557,7 +558,8 @@ public fun Array.first(): T { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun BooleanArray.first(): Boolean { if (isEmpty()) @@ -566,7 +568,8 @@ public fun BooleanArray.first(): Boolean { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun ByteArray.first(): Byte { if (isEmpty()) @@ -575,7 +578,8 @@ public fun ByteArray.first(): Byte { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun CharArray.first(): Char { if (isEmpty()) @@ -584,7 +588,8 @@ public fun CharArray.first(): Char { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun DoubleArray.first(): Double { if (isEmpty()) @@ -593,7 +598,8 @@ public fun DoubleArray.first(): Double { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun FloatArray.first(): Float { if (isEmpty()) @@ -602,7 +608,8 @@ public fun FloatArray.first(): Float { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun IntArray.first(): Int { if (isEmpty()) @@ -611,7 +618,8 @@ public fun IntArray.first(): Int { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun LongArray.first(): Long { if (isEmpty()) @@ -620,7 +628,8 @@ public fun LongArray.first(): Long { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun ShortArray.first(): Short { if (isEmpty()) @@ -629,7 +638,8 @@ public fun ShortArray.first(): Short { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun Iterable.first(): T { when (this) { @@ -649,7 +659,8 @@ public fun Iterable.first(): T { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun List.first(): T { if (isEmpty()) @@ -658,7 +669,8 @@ public fun List.first(): T { } /** - * Returns first element + * Returns first element. + * @throws NoSuchElementException if the collection is empty. */ public fun Stream.first(): T { when (this) { @@ -678,7 +690,8 @@ public fun Stream.first(): T { } /** - * Returns first element + * Returns first character. + * @throws NoSuchElementException if the string is empty. */ public fun String.first(): Char { if (isEmpty()) @@ -687,7 +700,8 @@ public fun String.first(): Char { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Array.first(predicate: (T) -> Boolean): T { for (element in this) if (predicate(element)) return element @@ -695,7 +709,8 @@ public inline fun Array.first(predicate: (T) -> Boolean): T { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun BooleanArray.first(predicate: (Boolean) -> Boolean): Boolean { for (element in this) if (predicate(element)) return element @@ -703,7 +718,8 @@ public inline fun BooleanArray.first(predicate: (Boolean) -> Boolean): Boolean { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun ByteArray.first(predicate: (Byte) -> Boolean): Byte { for (element in this) if (predicate(element)) return element @@ -711,7 +727,8 @@ public inline fun ByteArray.first(predicate: (Byte) -> Boolean): Byte { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun CharArray.first(predicate: (Char) -> Boolean): Char { for (element in this) if (predicate(element)) return element @@ -719,7 +736,8 @@ public inline fun CharArray.first(predicate: (Char) -> Boolean): Char { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun DoubleArray.first(predicate: (Double) -> Boolean): Double { for (element in this) if (predicate(element)) return element @@ -727,7 +745,8 @@ public inline fun DoubleArray.first(predicate: (Double) -> Boolean): Double { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun FloatArray.first(predicate: (Float) -> Boolean): Float { for (element in this) if (predicate(element)) return element @@ -735,7 +754,8 @@ public inline fun FloatArray.first(predicate: (Float) -> Boolean): Float { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun IntArray.first(predicate: (Int) -> Boolean): Int { for (element in this) if (predicate(element)) return element @@ -743,7 +763,8 @@ public inline fun IntArray.first(predicate: (Int) -> Boolean): Int { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun LongArray.first(predicate: (Long) -> Boolean): Long { for (element in this) if (predicate(element)) return element @@ -751,7 +772,8 @@ public inline fun LongArray.first(predicate: (Long) -> Boolean): Long { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun ShortArray.first(predicate: (Short) -> Boolean): Short { for (element in this) if (predicate(element)) return element @@ -759,7 +781,8 @@ public inline fun ShortArray.first(predicate: (Short) -> Boolean): Short { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Iterable.first(predicate: (T) -> Boolean): T { for (element in this) if (predicate(element)) return element @@ -767,7 +790,8 @@ public inline fun Iterable.first(predicate: (T) -> Boolean): T { } /** - * Returns first element matching the given *predicate* + * "Returns the first element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Stream.first(predicate: (T) -> Boolean): T { for (element in this) if (predicate(element)) return element @@ -775,7 +799,8 @@ public inline fun Stream.first(predicate: (T) -> Boolean): T { } /** - * Returns first element matching the given *predicate* + * Returns the first character matching the given [predicate]. + * @throws NoSuchElementException if no such character is found. */ public inline fun String.first(predicate: (Char) -> Boolean): Char { for (element in this) if (predicate(element)) return element @@ -783,70 +808,70 @@ public inline fun String.first(predicate: (Char) -> Boolean): Char { } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun Array.firstOrNull(): T? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun BooleanArray.firstOrNull(): Boolean? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun ByteArray.firstOrNull(): Byte? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun CharArray.firstOrNull(): Char? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun DoubleArray.firstOrNull(): Double? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun FloatArray.firstOrNull(): Float? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun IntArray.firstOrNull(): Int? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun LongArray.firstOrNull(): Long? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun ShortArray.firstOrNull(): Short? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun Iterable.firstOrNull(): T? { when (this) { @@ -866,14 +891,14 @@ public fun Iterable.firstOrNull(): T? { } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun List.firstOrNull(): T? { return if (isEmpty()) null else this[0] } /** - * Returns first element, or null if collection is empty + * Returns the first element, or null if the collection is empty. */ public fun Stream.firstOrNull(): T? { when (this) { @@ -893,14 +918,14 @@ public fun Stream.firstOrNull(): T? { } /** - * Returns first element, or null if collection is empty + * Returns the first character, or null if string is empty. */ public fun String.firstOrNull(): Char? { return if (isEmpty()) null else this[0] } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun Array.firstOrNull(predicate: (T) -> Boolean): T? { for (element in this) if (predicate(element)) return element @@ -908,7 +933,7 @@ public inline fun Array.firstOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun BooleanArray.firstOrNull(predicate: (Boolean) -> Boolean): Boolean? { for (element in this) if (predicate(element)) return element @@ -916,7 +941,7 @@ public inline fun BooleanArray.firstOrNull(predicate: (Boolean) -> Boolean): Boo } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun ByteArray.firstOrNull(predicate: (Byte) -> Boolean): Byte? { for (element in this) if (predicate(element)) return element @@ -924,7 +949,7 @@ public inline fun ByteArray.firstOrNull(predicate: (Byte) -> Boolean): Byte? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): Char? { for (element in this) if (predicate(element)) return element @@ -932,7 +957,7 @@ public inline fun CharArray.firstOrNull(predicate: (Char) -> Boolean): Char? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun DoubleArray.firstOrNull(predicate: (Double) -> Boolean): Double? { for (element in this) if (predicate(element)) return element @@ -940,7 +965,7 @@ public inline fun DoubleArray.firstOrNull(predicate: (Double) -> Boolean): Doubl } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun FloatArray.firstOrNull(predicate: (Float) -> Boolean): Float? { for (element in this) if (predicate(element)) return element @@ -948,7 +973,7 @@ public inline fun FloatArray.firstOrNull(predicate: (Float) -> Boolean): Float? } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun IntArray.firstOrNull(predicate: (Int) -> Boolean): Int? { for (element in this) if (predicate(element)) return element @@ -956,7 +981,7 @@ public inline fun IntArray.firstOrNull(predicate: (Int) -> Boolean): Int? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun LongArray.firstOrNull(predicate: (Long) -> Boolean): Long? { for (element in this) if (predicate(element)) return element @@ -964,7 +989,7 @@ public inline fun LongArray.firstOrNull(predicate: (Long) -> Boolean): Long? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun ShortArray.firstOrNull(predicate: (Short) -> Boolean): Short? { for (element in this) if (predicate(element)) return element @@ -972,7 +997,7 @@ public inline fun ShortArray.firstOrNull(predicate: (Short) -> Boolean): Short? } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun Iterable.firstOrNull(predicate: (T) -> Boolean): T? { for (element in this) if (predicate(element)) return element @@ -980,7 +1005,7 @@ public inline fun Iterable.firstOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first element matching the given [predicate], or `null` if element was not found */ public inline fun Stream.firstOrNull(predicate: (T) -> Boolean): T? { for (element in this) if (predicate(element)) return element @@ -988,7 +1013,7 @@ public inline fun Stream.firstOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns first element matching the given *predicate*, or *null* if element was not found + * Returns first character matching the given [predicate], or `null` if character was not found */ public inline fun String.firstOrNull(predicate: (Char) -> Boolean): Char? { for (element in this) if (predicate(element)) return element @@ -996,7 +1021,7 @@ public inline fun String.firstOrNull(predicate: (Char) -> Boolean): Char? { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun Array.indexOf(element: T): Int { if (element == null) { @@ -1016,7 +1041,7 @@ public fun Array.indexOf(element: T): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun BooleanArray.indexOf(element: Boolean): Int { for (index in indices) { @@ -1028,7 +1053,7 @@ public fun BooleanArray.indexOf(element: Boolean): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun ByteArray.indexOf(element: Byte): Int { for (index in indices) { @@ -1040,7 +1065,7 @@ public fun ByteArray.indexOf(element: Byte): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun CharArray.indexOf(element: Char): Int { for (index in indices) { @@ -1052,7 +1077,7 @@ public fun CharArray.indexOf(element: Char): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun DoubleArray.indexOf(element: Double): Int { for (index in indices) { @@ -1064,7 +1089,7 @@ public fun DoubleArray.indexOf(element: Double): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun FloatArray.indexOf(element: Float): Int { for (index in indices) { @@ -1076,7 +1101,7 @@ public fun FloatArray.indexOf(element: Float): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun IntArray.indexOf(element: Int): Int { for (index in indices) { @@ -1088,7 +1113,7 @@ public fun IntArray.indexOf(element: Int): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun LongArray.indexOf(element: Long): Int { for (index in indices) { @@ -1100,7 +1125,7 @@ public fun LongArray.indexOf(element: Long): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun ShortArray.indexOf(element: Short): Int { for (index in indices) { @@ -1112,7 +1137,7 @@ public fun ShortArray.indexOf(element: Short): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun Iterable.indexOf(element: T): Int { var index = 0 @@ -1125,7 +1150,7 @@ public fun Iterable.indexOf(element: T): Int { } /** - * Returns first index of *element*, or -1 if the collection does not contain element + * Returns first index of [element], or -1 if the collection does not contain element */ public fun Stream.indexOf(element: T): Int { var index = 0 @@ -1138,7 +1163,8 @@ public fun Stream.indexOf(element: T): Int { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun Array.last(): T { if (isEmpty()) @@ -1147,7 +1173,8 @@ public fun Array.last(): T { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun BooleanArray.last(): Boolean { if (isEmpty()) @@ -1156,7 +1183,8 @@ public fun BooleanArray.last(): Boolean { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun ByteArray.last(): Byte { if (isEmpty()) @@ -1165,7 +1193,8 @@ public fun ByteArray.last(): Byte { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun CharArray.last(): Char { if (isEmpty()) @@ -1174,7 +1203,8 @@ public fun CharArray.last(): Char { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun DoubleArray.last(): Double { if (isEmpty()) @@ -1183,7 +1213,8 @@ public fun DoubleArray.last(): Double { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun FloatArray.last(): Float { if (isEmpty()) @@ -1192,7 +1223,8 @@ public fun FloatArray.last(): Float { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun IntArray.last(): Int { if (isEmpty()) @@ -1201,7 +1233,8 @@ public fun IntArray.last(): Int { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun LongArray.last(): Long { if (isEmpty()) @@ -1210,7 +1243,8 @@ public fun LongArray.last(): Long { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun ShortArray.last(): Short { if (isEmpty()) @@ -1219,7 +1253,8 @@ public fun ShortArray.last(): Short { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun Iterable.last(): T { when (this) { @@ -1242,7 +1277,8 @@ public fun Iterable.last(): T { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun List.last(): T { if (isEmpty()) @@ -1251,7 +1287,8 @@ public fun List.last(): T { } /** - * Returns last element + * Returns the last element. + * @throws NoSuchElementException if the collection is empty. */ public fun Stream.last(): T { val iterator = iterator() @@ -1264,7 +1301,8 @@ public fun Stream.last(): T { } /** - * Returns last element + * "Returns the last character. + * @throws NoSuchElementException if the string is empty. */ public fun String.last(): Char { if (isEmpty()) @@ -1273,7 +1311,8 @@ public fun String.last(): Char { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Array.last(predicate: (T) -> Boolean): T { var last: T? = null @@ -1289,7 +1328,8 @@ public inline fun Array.last(predicate: (T) -> Boolean): T { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun BooleanArray.last(predicate: (Boolean) -> Boolean): Boolean { var last: Boolean? = null @@ -1305,7 +1345,8 @@ public inline fun BooleanArray.last(predicate: (Boolean) -> Boolean): Boolean { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun ByteArray.last(predicate: (Byte) -> Boolean): Byte { var last: Byte? = null @@ -1321,7 +1362,8 @@ public inline fun ByteArray.last(predicate: (Byte) -> Boolean): Byte { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun CharArray.last(predicate: (Char) -> Boolean): Char { var last: Char? = null @@ -1337,7 +1379,8 @@ public inline fun CharArray.last(predicate: (Char) -> Boolean): Char { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun DoubleArray.last(predicate: (Double) -> Boolean): Double { var last: Double? = null @@ -1353,7 +1396,8 @@ public inline fun DoubleArray.last(predicate: (Double) -> Boolean): Double { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun FloatArray.last(predicate: (Float) -> Boolean): Float { var last: Float? = null @@ -1369,7 +1413,8 @@ public inline fun FloatArray.last(predicate: (Float) -> Boolean): Float { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun IntArray.last(predicate: (Int) -> Boolean): Int { var last: Int? = null @@ -1385,7 +1430,8 @@ public inline fun IntArray.last(predicate: (Int) -> Boolean): Int { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun LongArray.last(predicate: (Long) -> Boolean): Long { var last: Long? = null @@ -1401,7 +1447,8 @@ public inline fun LongArray.last(predicate: (Long) -> Boolean): Long { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun ShortArray.last(predicate: (Short) -> Boolean): Short { var last: Short? = null @@ -1417,7 +1464,8 @@ public inline fun ShortArray.last(predicate: (Short) -> Boolean): Short { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Iterable.last(predicate: (T) -> Boolean): T { var last: T? = null @@ -1433,7 +1481,8 @@ public inline fun Iterable.last(predicate: (T) -> Boolean): T { } /** - * Returns last element matching the given *predicate* + * Returns the last element matching the given [predicate]. + * @throws NoSuchElementException if no such element is found. */ public inline fun Stream.last(predicate: (T) -> Boolean): T { var last: T? = null @@ -1449,7 +1498,8 @@ public inline fun Stream.last(predicate: (T) -> Boolean): T { } /** - * Returns last element matching the given *predicate* + * "Returns the last character matching the given [predicate]. + * @throws NoSuchElementException if no such character is found. */ public inline fun String.last(predicate: (Char) -> Boolean): Char { var last: Char? = null @@ -1629,70 +1679,70 @@ public fun Stream.lastIndexOf(element: T): Int { } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun Array.lastOrNull(): T? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun BooleanArray.lastOrNull(): Boolean? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun ByteArray.lastOrNull(): Byte? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun CharArray.lastOrNull(): Char? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun DoubleArray.lastOrNull(): Double? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun FloatArray.lastOrNull(): Float? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun IntArray.lastOrNull(): Int? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun LongArray.lastOrNull(): Long? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun ShortArray.lastOrNull(): Short? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun Iterable.lastOrNull(): T? { when (this) { @@ -1710,14 +1760,14 @@ public fun Iterable.lastOrNull(): T? { } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun List.lastOrNull(): T? { return if (isEmpty()) null else this[size() - 1] } /** - * Returns last element, or null if collection is empty + * Returns the last element, or `null` if the collection is empty */ public fun Stream.lastOrNull(): T? { val iterator = iterator() @@ -1730,14 +1780,14 @@ public fun Stream.lastOrNull(): T? { } /** - * Returns last element, or null if collection is empty + * Returns the last character, or `null` if the string is empty */ public fun String.lastOrNull(): Char? { return if (isEmpty()) null else this[length() - 1] } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun Array.lastOrNull(predicate: (T) -> Boolean): T? { var last: T? = null @@ -1750,7 +1800,7 @@ public inline fun Array.lastOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun BooleanArray.lastOrNull(predicate: (Boolean) -> Boolean): Boolean? { var last: Boolean? = null @@ -1763,7 +1813,7 @@ public inline fun BooleanArray.lastOrNull(predicate: (Boolean) -> Boolean): Bool } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun ByteArray.lastOrNull(predicate: (Byte) -> Boolean): Byte? { var last: Byte? = null @@ -1776,7 +1826,7 @@ public inline fun ByteArray.lastOrNull(predicate: (Byte) -> Boolean): Byte? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun CharArray.lastOrNull(predicate: (Char) -> Boolean): Char? { var last: Char? = null @@ -1789,7 +1839,7 @@ public inline fun CharArray.lastOrNull(predicate: (Char) -> Boolean): Char? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun DoubleArray.lastOrNull(predicate: (Double) -> Boolean): Double? { var last: Double? = null @@ -1802,7 +1852,7 @@ public inline fun DoubleArray.lastOrNull(predicate: (Double) -> Boolean): Double } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun FloatArray.lastOrNull(predicate: (Float) -> Boolean): Float? { var last: Float? = null @@ -1815,7 +1865,7 @@ public inline fun FloatArray.lastOrNull(predicate: (Float) -> Boolean): Float? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun IntArray.lastOrNull(predicate: (Int) -> Boolean): Int? { var last: Int? = null @@ -1828,7 +1878,7 @@ public inline fun IntArray.lastOrNull(predicate: (Int) -> Boolean): Int? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun LongArray.lastOrNull(predicate: (Long) -> Boolean): Long? { var last: Long? = null @@ -1841,7 +1891,7 @@ public inline fun LongArray.lastOrNull(predicate: (Long) -> Boolean): Long? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun ShortArray.lastOrNull(predicate: (Short) -> Boolean): Short? { var last: Short? = null @@ -1854,7 +1904,7 @@ public inline fun ShortArray.lastOrNull(predicate: (Short) -> Boolean): Short? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun Iterable.lastOrNull(predicate: (T) -> Boolean): T? { var last: T? = null @@ -1867,7 +1917,7 @@ public inline fun Iterable.lastOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last element matching the given [predicate], or `null` if no such element was found. */ public inline fun Stream.lastOrNull(predicate: (T) -> Boolean): T? { var last: T? = null @@ -1880,7 +1930,7 @@ public inline fun Stream.lastOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns last element matching the given *predicate*, or null if element was not found + * Returns the last character matching the given [predicate], or `null` if no such character was found. */ public inline fun String.lastOrNull(predicate: (Char) -> Boolean): Char? { var last: Char? = null @@ -1893,7 +1943,7 @@ public inline fun String.lastOrNull(predicate: (Char) -> Boolean): Char? { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun Array.single(): T { return when (size()) { @@ -1904,7 +1954,7 @@ public fun Array.single(): T { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun BooleanArray.single(): Boolean { return when (size()) { @@ -1915,7 +1965,7 @@ public fun BooleanArray.single(): Boolean { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun ByteArray.single(): Byte { return when (size()) { @@ -1926,7 +1976,7 @@ public fun ByteArray.single(): Byte { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun CharArray.single(): Char { return when (size()) { @@ -1937,7 +1987,7 @@ public fun CharArray.single(): Char { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun DoubleArray.single(): Double { return when (size()) { @@ -1948,7 +1998,7 @@ public fun DoubleArray.single(): Double { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun FloatArray.single(): Float { return when (size()) { @@ -1959,7 +2009,7 @@ public fun FloatArray.single(): Float { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun IntArray.single(): Int { return when (size()) { @@ -1970,7 +2020,7 @@ public fun IntArray.single(): Int { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun LongArray.single(): Long { return when (size()) { @@ -1981,7 +2031,7 @@ public fun LongArray.single(): Long { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun ShortArray.single(): Short { return when (size()) { @@ -1992,7 +2042,7 @@ public fun ShortArray.single(): Short { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun Iterable.single(): T { when (this) { @@ -2014,7 +2064,7 @@ public fun Iterable.single(): T { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun List.single(): T { return when (size()) { @@ -2025,7 +2075,7 @@ public fun List.single(): T { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single element, or throws an exception if the collection is empty or has more than one element. */ public fun Stream.single(): T { when (this) { @@ -2047,7 +2097,7 @@ public fun Stream.single(): T { } /** - * Returns single element, or throws exception if there is no or more than one element + * Returns the single character, or throws an exception if the string is empty or has more than one character. */ public fun String.single(): Char { return when (length()) { @@ -2058,7 +2108,7 @@ public fun String.single(): Char { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun Array.single(predicate: (T) -> Boolean): T { var single: T? = null @@ -2075,7 +2125,7 @@ public inline fun Array.single(predicate: (T) -> Boolean): T { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun BooleanArray.single(predicate: (Boolean) -> Boolean): Boolean { var single: Boolean? = null @@ -2092,7 +2142,7 @@ public inline fun BooleanArray.single(predicate: (Boolean) -> Boolean): Boolean } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun ByteArray.single(predicate: (Byte) -> Boolean): Byte { var single: Byte? = null @@ -2109,7 +2159,7 @@ public inline fun ByteArray.single(predicate: (Byte) -> Boolean): Byte { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun CharArray.single(predicate: (Char) -> Boolean): Char { var single: Char? = null @@ -2126,7 +2176,7 @@ public inline fun CharArray.single(predicate: (Char) -> Boolean): Char { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun DoubleArray.single(predicate: (Double) -> Boolean): Double { var single: Double? = null @@ -2143,7 +2193,7 @@ public inline fun DoubleArray.single(predicate: (Double) -> Boolean): Double { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun FloatArray.single(predicate: (Float) -> Boolean): Float { var single: Float? = null @@ -2160,7 +2210,7 @@ public inline fun FloatArray.single(predicate: (Float) -> Boolean): Float { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun IntArray.single(predicate: (Int) -> Boolean): Int { var single: Int? = null @@ -2177,7 +2227,7 @@ public inline fun IntArray.single(predicate: (Int) -> Boolean): Int { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun LongArray.single(predicate: (Long) -> Boolean): Long { var single: Long? = null @@ -2194,7 +2244,7 @@ public inline fun LongArray.single(predicate: (Long) -> Boolean): Long { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun ShortArray.single(predicate: (Short) -> Boolean): Short { var single: Short? = null @@ -2211,7 +2261,7 @@ public inline fun ShortArray.single(predicate: (Short) -> Boolean): Short { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun Iterable.single(predicate: (T) -> Boolean): T { var single: T? = null @@ -2228,7 +2278,7 @@ public inline fun Iterable.single(predicate: (T) -> Boolean): T { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element */ public inline fun Stream.single(predicate: (T) -> Boolean): T { var single: T? = null @@ -2245,7 +2295,7 @@ public inline fun Stream.single(predicate: (T) -> Boolean): T { } /** - * Returns single element matching the given *predicate*, or throws exception if there is no or more than one element + * Returns the single character matching the given [predicate], or throws exception if there is no or more than one matching character */ public inline fun String.single(predicate: (Char) -> Boolean): Char { var single: Char? = null @@ -2262,70 +2312,70 @@ public inline fun String.single(predicate: (Char) -> Boolean): Char { } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun Array.singleOrNull(): T? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun BooleanArray.singleOrNull(): Boolean? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun ByteArray.singleOrNull(): Byte? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun CharArray.singleOrNull(): Char? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun DoubleArray.singleOrNull(): Double? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun FloatArray.singleOrNull(): Float? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun IntArray.singleOrNull(): Int? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun LongArray.singleOrNull(): Long? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun ShortArray.singleOrNull(): Short? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun Iterable.singleOrNull(): T? { when (this) { @@ -2343,14 +2393,14 @@ public fun Iterable.singleOrNull(): T? { } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun List.singleOrNull(): T? { return if (size() == 1) this[0] else null } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns single element, or `null` if the collection is empty or has more than one element. */ public fun Stream.singleOrNull(): T? { when (this) { @@ -2368,14 +2418,14 @@ public fun Stream.singleOrNull(): T? { } /** - * Returns single element, or null if collection is empty, or throws exception if there is more than one element + * Returns the single character, or `null` if the string is empty or has more than one character. */ public fun String.singleOrNull(): Char? { return if (length() == 1) this[0] else null } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun Array.singleOrNull(predicate: (T) -> Boolean): T? { var single: T? = null @@ -2392,7 +2442,7 @@ public inline fun Array.singleOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun BooleanArray.singleOrNull(predicate: (Boolean) -> Boolean): Boolean? { var single: Boolean? = null @@ -2409,7 +2459,7 @@ public inline fun BooleanArray.singleOrNull(predicate: (Boolean) -> Boolean): Bo } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun ByteArray.singleOrNull(predicate: (Byte) -> Boolean): Byte? { var single: Byte? = null @@ -2426,7 +2476,7 @@ public inline fun ByteArray.singleOrNull(predicate: (Byte) -> Boolean): Byte? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun CharArray.singleOrNull(predicate: (Char) -> Boolean): Char? { var single: Char? = null @@ -2443,7 +2493,7 @@ public inline fun CharArray.singleOrNull(predicate: (Char) -> Boolean): Char? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun DoubleArray.singleOrNull(predicate: (Double) -> Boolean): Double? { var single: Double? = null @@ -2460,7 +2510,7 @@ public inline fun DoubleArray.singleOrNull(predicate: (Double) -> Boolean): Doub } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun FloatArray.singleOrNull(predicate: (Float) -> Boolean): Float? { var single: Float? = null @@ -2477,7 +2527,7 @@ public inline fun FloatArray.singleOrNull(predicate: (Float) -> Boolean): Float? } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun IntArray.singleOrNull(predicate: (Int) -> Boolean): Int? { var single: Int? = null @@ -2494,7 +2544,7 @@ public inline fun IntArray.singleOrNull(predicate: (Int) -> Boolean): Int? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun LongArray.singleOrNull(predicate: (Long) -> Boolean): Long? { var single: Long? = null @@ -2511,7 +2561,7 @@ public inline fun LongArray.singleOrNull(predicate: (Long) -> Boolean): Long? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun ShortArray.singleOrNull(predicate: (Short) -> Boolean): Short? { var single: Short? = null @@ -2528,7 +2578,7 @@ public inline fun ShortArray.singleOrNull(predicate: (Short) -> Boolean): Short? } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun Iterable.singleOrNull(predicate: (T) -> Boolean): T? { var single: T? = null @@ -2545,7 +2595,7 @@ public inline fun Iterable.singleOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found */ public inline fun Stream.singleOrNull(predicate: (T) -> Boolean): T? { var single: T? = null @@ -2562,7 +2612,7 @@ public inline fun Stream.singleOrNull(predicate: (T) -> Boolean): T? { } /** - * Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found + * Returns the single character matching the given [predicate], or `null` if character was not found or more than one character was found */ public inline fun String.singleOrNull(predicate: (Char) -> Boolean): Char? { var single: Char? = null diff --git a/libraries/stdlib/src/generated/_Filtering.kt b/libraries/stdlib/src/generated/_Filtering.kt index 139941471b6..80cae797157 100644 --- a/libraries/stdlib/src/generated/_Filtering.kt +++ b/libraries/stdlib/src/generated/_Filtering.kt @@ -10,7 +10,7 @@ import java.util.* import java.util.Collections // TODO: it's temporary while we have java.util.Collections in js /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun Array.drop(n: Int): List { if (n >= size()) @@ -24,7 +24,7 @@ public fun Array.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun BooleanArray.drop(n: Int): List { if (n >= size()) @@ -38,7 +38,7 @@ public fun BooleanArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun ByteArray.drop(n: Int): List { if (n >= size()) @@ -52,7 +52,7 @@ public fun ByteArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun CharArray.drop(n: Int): List { if (n >= size()) @@ -66,7 +66,7 @@ public fun CharArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun DoubleArray.drop(n: Int): List { if (n >= size()) @@ -80,7 +80,7 @@ public fun DoubleArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun FloatArray.drop(n: Int): List { if (n >= size()) @@ -94,7 +94,7 @@ public fun FloatArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun IntArray.drop(n: Int): List { if (n >= size()) @@ -108,7 +108,7 @@ public fun IntArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun LongArray.drop(n: Int): List { if (n >= size()) @@ -122,7 +122,7 @@ public fun LongArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun ShortArray.drop(n: Int): List { if (n >= size()) @@ -136,7 +136,7 @@ public fun ShortArray.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun Collection.drop(n: Int): List { if (n >= size()) @@ -150,7 +150,7 @@ public fun Collection.drop(n: Int): List { } /** - * Returns a list containing all elements except first *n* elements + * Returns a list containing all elements except first [n] elements */ public fun Iterable.drop(n: Int): List { var count = 0 @@ -162,21 +162,21 @@ public fun Iterable.drop(n: Int): List { } /** - * Returns a stream containing all elements except first *n* elements + * Returns a stream containing all elements except first [n] elements */ public fun Stream.drop(n: Int): Stream { return DropStream(this, n) } /** - * Returns a list containing all elements except first *n* elements + * Returns a string with the first [n] characters removed */ public fun String.drop(n: Int): String { return substring(Math.min(n, length())) } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun Array.dropWhile(predicate: (T) -> Boolean): List { var yielding = false @@ -192,7 +192,7 @@ public inline fun Array.dropWhile(predicate: (T) -> Boolean): List } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun BooleanArray.dropWhile(predicate: (Boolean) -> Boolean): List { var yielding = false @@ -208,7 +208,7 @@ public inline fun BooleanArray.dropWhile(predicate: (Boolean) -> Boolean): List< } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun ByteArray.dropWhile(predicate: (Byte) -> Boolean): List { var yielding = false @@ -224,7 +224,7 @@ public inline fun ByteArray.dropWhile(predicate: (Byte) -> Boolean): List } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun CharArray.dropWhile(predicate: (Char) -> Boolean): List { var yielding = false @@ -240,7 +240,7 @@ public inline fun CharArray.dropWhile(predicate: (Char) -> Boolean): List } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun DoubleArray.dropWhile(predicate: (Double) -> Boolean): List { var yielding = false @@ -256,7 +256,7 @@ public inline fun DoubleArray.dropWhile(predicate: (Double) -> Boolean): List Boolean): List { var yielding = false @@ -272,7 +272,7 @@ public inline fun FloatArray.dropWhile(predicate: (Float) -> Boolean): List Boolean): List { var yielding = false @@ -288,7 +288,7 @@ public inline fun IntArray.dropWhile(predicate: (Int) -> Boolean): List { } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun LongArray.dropWhile(predicate: (Long) -> Boolean): List { var yielding = false @@ -304,7 +304,7 @@ public inline fun LongArray.dropWhile(predicate: (Long) -> Boolean): List } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a list containing all elements except first elements that satisfy the given [predicate] */ public inline fun ShortArray.dropWhile(predicate: (Short) -> Boolean): List { var yielding = false @@ -320,7 +320,7 @@ public inline fun ShortArray.dropWhile(predicate: (Short) -> Boolean): List Iterable.dropWhile(predicate: (T) -> Boolean): List { var yielding = false @@ -336,14 +336,14 @@ public inline fun Iterable.dropWhile(predicate: (T) -> Boolean): List } /** - * Returns a stream containing all elements except first elements that satisfy the given *predicate* + * Returns a stream containing all elements except first elements that satisfy the given [predicate] */ public fun Stream.dropWhile(predicate: (T) -> Boolean): Stream { return DropWhileStream(this, predicate) } /** - * Returns a list containing all elements except first elements that satisfy the given *predicate* + * Returns a string containing all characters except first characters that satisfy the given [predicate] */ public inline fun String.dropWhile(predicate: (Char) -> Boolean): String { for (index in 0..length - 1) @@ -354,168 +354,168 @@ public inline fun String.dropWhile(predicate: (Char) -> Boolean): String { } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun Array.filter(predicate: (T) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun BooleanArray.filter(predicate: (Boolean) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun ByteArray.filter(predicate: (Byte) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun CharArray.filter(predicate: (Char) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun DoubleArray.filter(predicate: (Double) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun FloatArray.filter(predicate: (Float) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun IntArray.filter(predicate: (Int) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun LongArray.filter(predicate: (Long) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun ShortArray.filter(predicate: (Short) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a list containing all elements matching the given [predicate] */ public inline fun Iterable.filter(predicate: (T) -> Boolean): List { return filterTo(ArrayList(), predicate) } /** - * Returns a stream containing all elements matching the given *predicate* + * Returns a stream containing all elements matching the given [predicate] */ public fun Stream.filter(predicate: (T) -> Boolean): Stream { return FilteringStream(this, true, predicate) } /** - * Returns a list containing all elements matching the given *predicate* + * Returns a string containing only those characters from the original string that match the given [predicate] */ public inline fun String.filter(predicate: (Char) -> Boolean): String { return filterTo(StringBuilder(), predicate).toString() } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun Array.filterNot(predicate: (T) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun BooleanArray.filterNot(predicate: (Boolean) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun ByteArray.filterNot(predicate: (Byte) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun CharArray.filterNot(predicate: (Char) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun DoubleArray.filterNot(predicate: (Double) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun FloatArray.filterNot(predicate: (Float) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun IntArray.filterNot(predicate: (Int) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun LongArray.filterNot(predicate: (Long) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun ShortArray.filterNot(predicate: (Short) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a list containing all elements not matching the given [predicate] */ public inline fun Iterable.filterNot(predicate: (T) -> Boolean): List { return filterNotTo(ArrayList(), predicate) } /** - * Returns a stream containing all elements not matching the given *predicate* + * Returns a stream containing all elements not matching the given [predicate] */ public fun Stream.filterNot(predicate: (T) -> Boolean): Stream { return FilteringStream(this, false, predicate) } /** - * Returns a list containing all elements not matching the given *predicate* + * Returns a string containing only those characters from the original string that do not match the given [predicate] */ public inline fun String.filterNot(predicate: (Char) -> Boolean): String { return filterNotTo(StringBuilder(), predicate).toString() @@ -543,7 +543,7 @@ public fun Stream.filterNotNull(): Stream { } /** - * Appends all elements that are not null to the given *destination* + * Appends all elements that are not null to the given [destination] */ public fun , T : Any> Array.filterNotNullTo(destination: C): C { for (element in this) if (element != null) destination.add(element) @@ -551,7 +551,7 @@ public fun , T : Any> Array.filterNotNullTo( } /** - * Appends all elements that are not null to the given *destination* + * Appends all elements that are not null to the given [destination] */ public fun , T : Any> Iterable.filterNotNullTo(destination: C): C { for (element in this) if (element != null) destination.add(element) @@ -559,7 +559,7 @@ public fun , T : Any> Iterable.filterNotNullTo(d } /** - * Appends all elements that are not null to the given *destination* + * Appends all elements that are not null to the given [destination] */ public fun , T : Any> Stream.filterNotNullTo(destination: C): C { for (element in this) if (element != null) destination.add(element) @@ -567,7 +567,7 @@ public fun , T : Any> Stream.filterNotNullTo(des } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > Array.filterNotTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -575,7 +575,7 @@ public inline fun > Array.filterNotTo(dest } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > BooleanArray.filterNotTo(destination: C, predicate: (Boolean) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -583,7 +583,7 @@ public inline fun > BooleanArray.filterNotTo(d } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > ByteArray.filterNotTo(destination: C, predicate: (Byte) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -591,7 +591,7 @@ public inline fun > ByteArray.filterNotTo(destina } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > CharArray.filterNotTo(destination: C, predicate: (Char) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -599,7 +599,7 @@ public inline fun > CharArray.filterNotTo(destina } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > DoubleArray.filterNotTo(destination: C, predicate: (Double) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -607,7 +607,7 @@ public inline fun > DoubleArray.filterNotTo(des } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > FloatArray.filterNotTo(destination: C, predicate: (Float) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -615,7 +615,7 @@ public inline fun > FloatArray.filterNotTo(desti } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > IntArray.filterNotTo(destination: C, predicate: (Int) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -623,7 +623,7 @@ public inline fun > IntArray.filterNotTo(destinati } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > LongArray.filterNotTo(destination: C, predicate: (Long) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -631,7 +631,7 @@ public inline fun > LongArray.filterNotTo(destina } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > ShortArray.filterNotTo(destination: C, predicate: (Short) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -639,7 +639,7 @@ public inline fun > ShortArray.filterNotTo(desti } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > Iterable.filterNotTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -647,7 +647,7 @@ public inline fun > Iterable.filterNotTo(desti } /** - * Appends all elements not matching the given *predicate* to the given *destination* + * Appends all elements not matching the given [predicate] to the given [destination] */ public inline fun > Stream.filterNotTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (!predicate(element)) destination.add(element) @@ -655,7 +655,7 @@ public inline fun > Stream.filterNotTo(destina } /** - * Appends all characters not matching the given *predicate* to the given *destination* + * Appends all characters not matching the given [predicate] to the given [destination] */ public inline fun String.filterNotTo(destination: C, predicate: (Char) -> Boolean): C { for (element in this) if (!predicate(element)) destination.append(element) @@ -663,7 +663,7 @@ public inline fun String.filterNotTo(destination: C, predicate: } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > Array.filterTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -671,7 +671,7 @@ public inline fun > Array.filterTo(destina } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > BooleanArray.filterTo(destination: C, predicate: (Boolean) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -679,7 +679,7 @@ public inline fun > BooleanArray.filterTo(dest } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > ByteArray.filterTo(destination: C, predicate: (Byte) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -687,7 +687,7 @@ public inline fun > ByteArray.filterTo(destinatio } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > CharArray.filterTo(destination: C, predicate: (Char) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -695,7 +695,7 @@ public inline fun > CharArray.filterTo(destinatio } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > DoubleArray.filterTo(destination: C, predicate: (Double) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -703,7 +703,7 @@ public inline fun > DoubleArray.filterTo(destin } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > FloatArray.filterTo(destination: C, predicate: (Float) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -711,7 +711,7 @@ public inline fun > FloatArray.filterTo(destinat } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > IntArray.filterTo(destination: C, predicate: (Int) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -719,7 +719,7 @@ public inline fun > IntArray.filterTo(destination: } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > LongArray.filterTo(destination: C, predicate: (Long) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -727,7 +727,7 @@ public inline fun > LongArray.filterTo(destinatio } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > ShortArray.filterTo(destination: C, predicate: (Short) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -735,7 +735,7 @@ public inline fun > ShortArray.filterTo(destinat } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > Iterable.filterTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -743,7 +743,7 @@ public inline fun > Iterable.filterTo(destinat } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all elements matching the given [predicate] into the given [destination] */ public inline fun > Stream.filterTo(destination: C, predicate: (T) -> Boolean): C { for (element in this) if (predicate(element)) destination.add(element) @@ -751,7 +751,7 @@ public inline fun > Stream.filterTo(destinatio } /** - * Appends all characters matching the given *predicate* to the given *destination* + * Appends all characters matching the given [predicate] to the given [destination] */ public inline fun String.filterTo(destination: C, predicate: (Char) -> Boolean): C { for (index in 0..length - 1) { @@ -872,7 +872,7 @@ public fun List.slice(indices: Iterable): List { } /** - * Returns a list containing elements at specified positions + * Returns a string containing characters at specified positions */ public fun String.slice(indices: Iterable): String { val result = StringBuilder() @@ -883,7 +883,7 @@ public fun String.slice(indices: Iterable): String { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun Array.take(n: Int): List { var count = 0 @@ -898,7 +898,7 @@ public fun Array.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun BooleanArray.take(n: Int): List { var count = 0 @@ -913,7 +913,7 @@ public fun BooleanArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun ByteArray.take(n: Int): List { var count = 0 @@ -928,7 +928,7 @@ public fun ByteArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun CharArray.take(n: Int): List { var count = 0 @@ -943,7 +943,7 @@ public fun CharArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun DoubleArray.take(n: Int): List { var count = 0 @@ -958,7 +958,7 @@ public fun DoubleArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun FloatArray.take(n: Int): List { var count = 0 @@ -973,7 +973,7 @@ public fun FloatArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun IntArray.take(n: Int): List { var count = 0 @@ -988,7 +988,7 @@ public fun IntArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun LongArray.take(n: Int): List { var count = 0 @@ -1003,7 +1003,7 @@ public fun LongArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun ShortArray.take(n: Int): List { var count = 0 @@ -1018,7 +1018,7 @@ public fun ShortArray.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun Collection.take(n: Int): List { var count = 0 @@ -1033,7 +1033,7 @@ public fun Collection.take(n: Int): List { } /** - * Returns a list containing first *n* elements + * Returns a list containing first [n] elements */ public fun Iterable.take(n: Int): List { var count = 0 @@ -1054,14 +1054,14 @@ public fun Stream.take(n: Int): Stream { } /** - * Returns a list containing first *n* elements + * Returns a string containing the first [n] characters from this string, or the entire string if this string is shorter */ public fun String.take(n: Int): String { return substring(0, Math.min(n, length())) } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun Array.takeWhile(predicate: (T) -> Boolean): List { val list = ArrayList() @@ -1074,7 +1074,7 @@ public inline fun Array.takeWhile(predicate: (T) -> Boolean): List } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun BooleanArray.takeWhile(predicate: (Boolean) -> Boolean): List { val list = ArrayList() @@ -1087,7 +1087,7 @@ public inline fun BooleanArray.takeWhile(predicate: (Boolean) -> Boolean): List< } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun ByteArray.takeWhile(predicate: (Byte) -> Boolean): List { val list = ArrayList() @@ -1100,7 +1100,7 @@ public inline fun ByteArray.takeWhile(predicate: (Byte) -> Boolean): List } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun CharArray.takeWhile(predicate: (Char) -> Boolean): List { val list = ArrayList() @@ -1113,7 +1113,7 @@ public inline fun CharArray.takeWhile(predicate: (Char) -> Boolean): List } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun DoubleArray.takeWhile(predicate: (Double) -> Boolean): List { val list = ArrayList() @@ -1126,7 +1126,7 @@ public inline fun DoubleArray.takeWhile(predicate: (Double) -> Boolean): List Boolean): List { val list = ArrayList() @@ -1139,7 +1139,7 @@ public inline fun FloatArray.takeWhile(predicate: (Float) -> Boolean): List Boolean): List { val list = ArrayList() @@ -1152,7 +1152,7 @@ public inline fun IntArray.takeWhile(predicate: (Int) -> Boolean): List { } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun LongArray.takeWhile(predicate: (Long) -> Boolean): List { val list = ArrayList() @@ -1165,7 +1165,7 @@ public inline fun LongArray.takeWhile(predicate: (Long) -> Boolean): List } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a list containing first elements satisfying the given [predicate] */ public inline fun ShortArray.takeWhile(predicate: (Short) -> Boolean): List { val list = ArrayList() @@ -1178,7 +1178,7 @@ public inline fun ShortArray.takeWhile(predicate: (Short) -> Boolean): List Iterable.takeWhile(predicate: (T) -> Boolean): List { val list = ArrayList() @@ -1191,14 +1191,14 @@ public inline fun Iterable.takeWhile(predicate: (T) -> Boolean): List } /** - * Returns a stream containing first elements satisfying the given *predicate* + * Returns a stream containing first elements satisfying the given [predicate] */ public fun Stream.takeWhile(predicate: (T) -> Boolean): Stream { return TakeWhileStream(this, predicate) } /** - * Returns a list containing first elements satisfying the given *predicate* + * Returns a string containing the first characters that satisfy the given [predicate] */ public inline fun String.takeWhile(predicate: (Char) -> Boolean): String { for (index in 0..length - 1) diff --git a/libraries/stdlib/src/generated/_Strings.kt b/libraries/stdlib/src/generated/_Strings.kt index 417dabdd434..42153975b4f 100644 --- a/libraries/stdlib/src/generated/_Strings.kt +++ b/libraries/stdlib/src/generated/_Strings.kt @@ -10,9 +10,9 @@ import java.util.* import java.util.Collections // TODO: it's temporary while we have java.util.Collections in js /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Array.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -30,9 +30,9 @@ public fun Array.joinTo(buffer: A, separator: String } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun BooleanArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -50,9 +50,9 @@ public fun BooleanArray.joinTo(buffer: A, separator: String = " } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun ByteArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -70,9 +70,9 @@ public fun ByteArray.joinTo(buffer: A, separator: String = ", " } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun CharArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -90,9 +90,9 @@ public fun CharArray.joinTo(buffer: A, separator: String = ", " } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun DoubleArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -110,9 +110,9 @@ public fun DoubleArray.joinTo(buffer: A, separator: String = ", } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun FloatArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -130,9 +130,9 @@ public fun FloatArray.joinTo(buffer: A, separator: String = ", } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun IntArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -150,9 +150,9 @@ public fun IntArray.joinTo(buffer: A, separator: String = ", ", } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun LongArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -170,9 +170,9 @@ public fun LongArray.joinTo(buffer: A, separator: String = ", " } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun ShortArray.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -190,9 +190,9 @@ public fun ShortArray.joinTo(buffer: A, separator: String = ", } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Iterable.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -210,9 +210,9 @@ public fun Iterable.joinTo(buffer: A, separator: String = } /** - * Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Stream.joinTo(buffer: A, separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): A { buffer.append(prefix) @@ -230,99 +230,99 @@ public fun Stream.joinTo(buffer: A, separator: String = " } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Array.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun BooleanArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun ByteArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun CharArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun DoubleArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun FloatArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun IntArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun LongArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun ShortArray.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Iterable.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "..." + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Stream.joinToString(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinTo(StringBuilder(), separator, prefix, postfix, limit, truncated).toString() diff --git a/libraries/stdlib/src/kotlin/collections/AbstractIterator.kt b/libraries/stdlib/src/kotlin/collections/AbstractIterator.kt index 40752e3634d..d0692015fd2 100644 --- a/libraries/stdlib/src/kotlin/collections/AbstractIterator.kt +++ b/libraries/stdlib/src/kotlin/collections/AbstractIterator.kt @@ -13,8 +13,8 @@ private enum class State { } /** - * A base class to simplify implementing iterators so that implementations only have to implement [[computeNext()]] - * to implement the iterator, calling [[done()]] when the iteration is complete. + * A base class to simplify implementing iterators so that implementations only have to implement [computeNext] + * to implement the iterator, calling [done] when the iteration is complete. */ public abstract class AbstractIterator: Iterator { private var state = State.NotReady @@ -44,17 +44,17 @@ public abstract class AbstractIterator: Iterator { /** * Computes the next item in the iterator. * - * This callback method should call one of these two methods + * This callback method should call one of these two methods: * - * * [[setNext(T)]] with the next value of the iteration - * * [[done()]] to indicate there are no more elements + * * [setNext] with the next value of the iteration + * * [done] to indicate there are no more elements * * Failure to call either method will result in the iteration terminating with a failed state */ abstract protected fun computeNext(): Unit /** - * Sets the next value in the iteration, called from the [[computeNext()]] function + * Sets the next value in the iteration, called from the [computeNext] function */ protected fun setNext(value: T): Unit { nextValue = value @@ -62,7 +62,7 @@ public abstract class AbstractIterator: Iterator { } /** - * Sets the state to done so that the iteration terminates + * Sets the state to done so that the iteration terminates. */ protected fun done() { state = State.Done diff --git a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt index 6c360a8a5d2..5ece4010bfc 100644 --- a/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/ArraysJVM.kt @@ -25,16 +25,31 @@ import kotlin.jvm.internal.Intrinsic [Intrinsic("kotlin.arrays.array")] public fun booleanArray(vararg content : Boolean) : BooleanArray = content +/** + * Creates an input stream for reading data from this byte array. + */ public val ByteArray.inputStream : ByteArrayInputStream get() = ByteArrayInputStream(this) +/** + * Creates an input stream for reading data from the specified portion of this byte array. + * @param offset the start offset of the portion of the array to read. + * @param length the length of the portion of the array to read. + */ public fun ByteArray.inputStream(offset: Int, length: Int) : ByteArrayInputStream = ByteArrayInputStream(this, offset, length) +/** + * Converts the contents of this byte array to a string using the specified [charset]. + */ public fun ByteArray.toString(charset: String): String = String(this, charset) + +/** + * Converts the contents of this byte array to a string using the specified [charset]. + */ public fun ByteArray.toString(charset: Charset): String = String(this, charset) [Intrinsic("kotlin.collections.copyToArray")] public fun Collection.copyToArray(): Array = throw UnsupportedOperationException() -/** Returns the List if its not null otherwise returns the empty list */ +/** Returns the array if it's not null, or an empty array otherwise. */ public inline fun Array?.orEmpty(): Array = this ?: array() diff --git a/libraries/stdlib/src/kotlin/collections/Iterators.kt b/libraries/stdlib/src/kotlin/collections/Iterators.kt index ad43902134b..6f977c027a0 100644 --- a/libraries/stdlib/src/kotlin/collections/Iterators.kt +++ b/libraries/stdlib/src/kotlin/collections/Iterators.kt @@ -3,7 +3,7 @@ package kotlin import java.util.Enumeration /** - * Helper to make java.util.Enumeration usable in for + * Creates an [Iterator] for an [Enumeration], allowing to use it in `for` loops. */ public fun Enumeration.iterator(): Iterator = object : Iterator { override fun hasNext(): Boolean = hasMoreElements() @@ -12,7 +12,7 @@ public fun Enumeration.iterator(): Iterator = object : Iterator { } /** - * Returns the given iterator itself. This allows to use an instance of iterator in a ranged for-loop + * Returns the given iterator itself. This allows to use an instance of iterator in a `for` loop. */ public fun Iterator.iterator(): Iterator = this @@ -26,7 +26,7 @@ public class IndexingIterable(private val iteratorFactory: () -> Iterator } /** - * Iterator transforming original *iterator* into iterator of [IndexedValue], counting index from zero. + * Iterator transforming original `iterator` into iterator of [IndexedValue], counting index from zero. */ public class IndexingIterator(private val iterator: Iterator) : Iterator> { private var index = 0 diff --git a/libraries/stdlib/src/kotlin/collections/JUtilJVM.kt b/libraries/stdlib/src/kotlin/collections/JUtilJVM.kt index 9a235628fef..b840ed433af 100644 --- a/libraries/stdlib/src/kotlin/collections/JUtilJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/JUtilJVM.kt @@ -3,12 +3,12 @@ package kotlin import java.util.* /** - * Returns a new [[SortedSet]] with the initial elements + * Returns a new [SortedSet] with the given elements. */ public fun sortedSetOf(vararg values: T): TreeSet = values.toCollection(TreeSet()) /** - * Returns a new [[SortedSet]] with the given *comparator* and the initial elements + * Returns a new [SortedSet] with the given [comparator] and elements. */ public fun sortedSetOf(comparator: Comparator, vararg values: T): TreeSet = values.toCollection(TreeSet(comparator)) diff --git a/libraries/stdlib/src/kotlin/collections/Maps.kt b/libraries/stdlib/src/kotlin/collections/Maps.kt index 5e60312bba3..17ab9f16324 100644 --- a/libraries/stdlib/src/kotlin/collections/Maps.kt +++ b/libraries/stdlib/src/kotlin/collections/Maps.kt @@ -21,17 +21,21 @@ private object EmptyMap : Map { /** Returns an empty read-only map of specified type */ public fun emptyMap(): Map = EmptyMap as Map -/** Returns a new read-only map of given pairs, where the first value is the key, and the second is value */ +/** + * Returns a new read-only map with the specified contents, given as a list of pairs + * where the first value is the key and the second is the value. If multiple pairs have + * the same key, the resulting map will contain the value from the last of those pairs. + */ public fun mapOf(vararg values: Pair): Map = if (values.size() == 0) emptyMap() else linkedMapOf(*values) /** Returns an empty read-only map */ public fun mapOf(): Map = emptyMap() /** - * Returns a new [[HashMap]] populated with the given pairs where the first value in each pair - * is the key and the second value is the value + * Returns a new [HashMap] with the specified contents, given as a list of pairs + * where the first component is the key and the second is the value. * - * @includeFunctionBody ../../test/collections/MapTest.kt createUsingPairs + * @sample test.collections.MapTest.createUsingPairs */ public fun hashMapOf(vararg values: Pair): HashMap { val answer = HashMap(values.size()) @@ -40,11 +44,11 @@ public fun hashMapOf(vararg values: Pair): HashMap { } /** - * Returns a new [[LinkedHashMap]] populated with the given pairs where the first value in each pair - * is the key and the second value is the value. This map preserves insertion order so iterating through - * the map's entries will be in the same order + * Returns a new [LinkedHashMap] with the specified contents, given as a list of pairs + * where the first component is the key and the second is the value. + * This map preserves insertion order so iterating through the map's entries will be in the same order. * - * @includeFunctionBody ../../test/collections/MapTest.kt createLinkedMap + * @sample test.collections.MapTest.createLinkedMap */ public fun linkedMapOf(vararg values: Pair): LinkedHashMap { val answer = LinkedHashMap(values.size()) @@ -52,39 +56,67 @@ public fun linkedMapOf(vararg values: Pair): LinkedHashMap { return answer } -/** Returns the [[Map]] if its not null otherwise it returns the empty [[Map]] */ +/** + * Returns the [Map] if its not null, or the empty [Map] otherwise. + */ public fun Map?.orEmpty() : Map = if (this != null) this else emptyMap() +/** + * Checks if the map contains the given key. This method allows to use the `x in map` syntax for checking + * whether an object is contained in the map. + */ public fun Map.contains(key : K) : Boolean = containsKey(key) -/** Returns the key of the entry */ +/** + * Allows to access the key of a map entry as a property. Equivalent to `getKey()`. + */ public val Map.Entry.key: K get() = getKey() -/** Returns the value of the entry */ +/** + * Allows to access the value of a map entry as a property. Equivalent to `getValue()`. + */ public val Map.Entry.value: V get() = getValue() -/** Returns the key of the entry */ +/** + * Returns the key component of the map entry. This method allows to use multi-declarations when working with maps, + * for example: + * ``` + * for ((key, value) in map) { + * // do something with the key and the value + * } + * ``` + */ public fun Map.Entry.component1(): K { return getKey() } -/** Returns the value of the entry */ +/** + * Returns the value component of the map entry. This method allows to use multi-declarations when working with maps, + * for example: + * ``` + * for ((key, value) in map) { + * // do something with the key and the value + * } + * ``` + */ public fun Map.Entry.component2(): V { return getValue() } -/** Converts entry to Pair with key being first component and value being second */ +/** + * Converts entry to [Pair] with key being first component and value being second. + */ public fun Map.Entry.toPair(): Pair { return Pair(getKey(), getValue()) } /** - * Returns the value for the given key or returns the result of the defaultValue function if there was no entry for the given key + * Returns the value for the given key, or the result of the [defaultValue] function if there was no entry for the given key. * - * @includeFunctionBody ../../test/collections/MapTest.kt getOrElse + * @sample test.collections.MapTest.getOrElse */ public inline fun Map.getOrElse(key: K, defaultValue: () -> V): V { if (containsKey(key)) { @@ -95,9 +127,10 @@ public inline fun Map.getOrElse(key: K, defaultValue: () -> V): V { } /** - * Returns the value for the given key or the result of the defaultValue function is put into the map for the given value and returned + * Returns the value for the given key. If the key is not found in the map, calls the [defaultValue] function, + * puts its result into the map under the given key and returns it. * - * @includeFunctionBody ../../test/collections/MapTest.kt getOrPut + * @sample test.collections.MapTest.getOrPut */ public inline fun MutableMap.getOrPut(key: K, defaultValue: () -> V): V { if (containsKey(key)) { @@ -110,9 +143,9 @@ public inline fun MutableMap.getOrPut(key: K, defaultValue: () -> V } /** - * Returns an [[Iterator]] over the entries in the [[Map]] + * Returns an [Iterator] over the entries in the [Map]. * - * @includeFunctionBody ../../test/collections/MapTest.kt iterateWithProperties + * @sample test.collections.MapTest.iterateWithProperties */ public fun Map.iterator(): Iterator> { val entrySet = entrySet() @@ -120,7 +153,8 @@ public fun Map.iterator(): Iterator> { } /** - * Populates the given *destination* [[Map]] with the value returned by applying the *transform* function on each [[Map.Entry]] in this [[Map]] + * Populates the given `destination` [Map] with entries having the keys of this map and the values obtained + * by applying the `transform` function to each entry in this [Map]. */ public inline fun > Map.mapValuesTo(destination: C, transform: (Map.Entry) -> R): C { for (e in this) { @@ -131,7 +165,8 @@ public inline fun > Map.mapValuesTo(destinat } /** - * Populates the given *destination* [[Map]] with the value returned by applying the *transform* function on each [[Map.Entry]] in this [[Map]] + * Populates the given `destination` [Map] with entries having the keys obtained + * by applying the `transform` function to each entry in this [Map] and the values of this map. */ public inline fun > Map.mapKeysTo(destination: C, transform: (Map.Entry) -> R): C { for (e in this) { @@ -142,7 +177,7 @@ public inline fun > Map.mapKeysTo(destinatio } /** - * Puts all the entries into this [[MutableMap]] with the first value in the pair being the key and the second the value + * Puts all the given [values] into this [MutableMap] with the first component in the pair being the key and the second the value. */ public fun MutableMap.putAll(vararg values: Pair): Unit { for ((key, value) in values) { @@ -151,7 +186,7 @@ public fun MutableMap.putAll(vararg values: Pair): Unit { } /** - * Puts all the entries into this [[MutableMap]] with the first value in the pair being the key and the second the value + * Puts all the elements of the given collection into this [MutableMap] with the first component in the pair being the key and the second the value. */ public fun MutableMap.putAll(values: Iterable>): Unit { for ((key, value) in values) { @@ -160,25 +195,27 @@ public fun MutableMap.putAll(values: Iterable>): Unit { } /** - * Returns a new Map containing the results of applying the given *transform* function to each [[Map.Entry]] in this [[Map]] + * Returns a new map with entries having the keys of this map and the values obtained by applying the `transform` + * function to each entry in this [Map]. * - * @includeFunctionBody ../../test/collections/MapTest.kt mapValues + * @sample test.collections.MapTest.mapValues */ public inline fun Map.mapValues(transform: (Map.Entry) -> R): Map { return mapValuesTo(LinkedHashMap(size()), transform) } /** - * Returns a new Map containing the results of applying the given *transform* function to each [[Map.Entry]] in this [[Map]] + * Returns a new Map with entries having the keys obtained by applying the `transform` function to each entry in this + * [Map] and the values of this map. * - * @includeFunctionBody ../../test/collections/MapTest.kt mapKeys + * @sample test.collections.MapTest.mapKeys */ public inline fun Map.mapKeys(transform: (Map.Entry) -> R): Map { return mapKeysTo(LinkedHashMap(size()), transform) } /** - * Returns a map containing all key-value pairs matching keys with the given *predicate* + * Returns a map containing all key-value pairs with keys matching the given [predicate]. */ public inline fun Map.filterKeys(predicate: (K) -> Boolean): Map { val result = LinkedHashMap() @@ -191,7 +228,7 @@ public inline fun Map.filterKeys(predicate: (K) -> Boolean): Map Map.filterValues(predicate: (V) -> Boolean): Map { val result = LinkedHashMap() @@ -205,7 +242,9 @@ public inline fun Map.filterValues(predicate: (V) -> Boolean): Map< /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all entries matching the given [predicate] into the mutable map given as [destination] parameter. + * + * @return the destination map. */ public inline fun > Map.filterTo(destination: C, predicate: (Map.Entry) -> Boolean): C { for (element in this) { @@ -217,14 +256,16 @@ public inline fun > Map.filterTo(destination: C } /** - * Returns a map containing all key-value pairs matching the given *predicate* + * Returns a new map containing all key-value pairs matching the given [predicate]. */ public inline fun Map.filter(predicate: (Map.Entry) -> Boolean): Map { return filterTo(LinkedHashMap(), predicate) } /** - * Appends all elements matching the given *predicate* into the given *destination* + * Appends all entries not matching the given [predicate] into the given [destination]. + * + * @return the destination map. */ public inline fun > Map.filterNotTo(destination: C, predicate: (Map.Entry) -> Boolean): C { for (element in this) { @@ -236,7 +277,7 @@ public inline fun > Map.filterNotTo(destination } /** - * Returns a map containing all key-value pairs matching the given *predicate* + * Returns a new map containing all key-value pairs not matching the given [predicate]. */ public inline fun Map.filterNot(predicate: (Map.Entry) -> Boolean): Map { return filterNotTo(LinkedHashMap(), predicate) @@ -250,7 +291,7 @@ public fun MutableMap.plusAssign(pair: Pair) { } /** - * Returns a map containing all key-value pairs from the given collection + * Returns a new map containing all key-value pairs from the given collection of pairs. */ public fun Iterable>.toMap(): Map { val result = LinkedHashMap() @@ -261,6 +302,6 @@ public fun Iterable>.toMap(): Map { } /** - * Converts this [Map] to a [LinkedHashMap] so future insertion orders are maintained + * Converts this [Map] to a [LinkedHashMap], maintaining the insertion order of elements added to that map afterwards. */ public fun Map.toLinkedMap(): MutableMap = LinkedHashMap(this) diff --git a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt index 33f01fd967d..8c9e91bc928 100644 --- a/libraries/stdlib/src/kotlin/collections/MapsJVM.kt +++ b/libraries/stdlib/src/kotlin/collections/MapsJVM.kt @@ -11,17 +11,17 @@ import java.util.Properties public fun MutableMap.set(key: K, value: V): V? = put(key, value) /** - * Converts this [[Map]] to a [[SortedMap]] so iteration order will be in key order + * Converts this [Map] to a [SortedMap] so iteration order will be in key order * * @includeFunctionBody ../../test/collections/MapTest.kt toSortedMap */ public fun Map.toSortedMap(): SortedMap = TreeMap(this) /** - * Converts this [[Map]] to a [[SortedMap]] using the given *comparator* so that iteration order will be in the order + * Converts this [Map] to a [SortedMap] using the given [comparator] so that iteration order will be in the order * defined by the comparator * - * @includeFunctionBody ../../test/collections/MapTest.kt toSortedMapWithComparator + * @sample test.collections.MapJVMTest.toSortedMapWithComparator */ public fun Map.toSortedMap(comparator: Comparator): SortedMap { val result = TreeMap(comparator) @@ -30,10 +30,10 @@ public fun Map.toSortedMap(comparator: Comparator): SortedMap sortedMapOf(vararg values: Pair): SortedMap { val answer = TreeMap() @@ -49,7 +49,7 @@ public fun sortedMapOf(vararg values: Pair): SortedMap { /** - * Converts this [[Map]] to a [[Properties]] object + * Converts this [Map] to a [Properties] object * * @includeFunctionBody ../../test/collections/MapTest.kt toProperties */ diff --git a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt index 3cc6e0aebae..f34c31ee605 100644 --- a/libraries/stdlib/src/kotlin/collections/MutableCollections.kt +++ b/libraries/stdlib/src/kotlin/collections/MutableCollections.kt @@ -1,7 +1,7 @@ package kotlin /** - * Adds all elements of the given *iterable* to this [[MutableCollection]] + * Adds all elements of the given [iterable] to this [MutableCollection]. */ public fun MutableCollection.addAll(iterable: Iterable) { when (iterable) { @@ -11,21 +11,21 @@ public fun MutableCollection.addAll(iterable: Iterable) { } /** - * Adds all elements of the given *stream* to this [[MutableCollection]] + * Adds all elements of the given [stream] to this [MutableCollection]. */ public fun MutableCollection.addAll(stream: Stream) { for (item in stream) add(item) } /** - * Adds all elements of the given *array* to this [[MutableCollection]] + * Adds all elements of the given [array] to this [MutableCollection]. */ public fun MutableCollection.addAll(array: Array) { for (item in array) add(item) } /** - * Removes all elements of the given *iterable* from this [[MutableCollection]] + * Removes all elements of the given [iterable] from this [MutableCollection]. */ public fun MutableCollection.removeAll(iterable: Iterable) { when (iterable) { @@ -35,21 +35,21 @@ public fun MutableCollection.removeAll(iterable: Iterable) { } /** - * Removes all elements of the given *stream* from this [[MutableCollection]] + * Removes all elements of the given [stream] from this [MutableCollection]. */ public fun MutableCollection.removeAll(stream: Stream) { for (item in stream) remove(item) } /** - * Removes all elements of the given *array* from this [[MutableCollection]] + * Removes all elements of the given [array] from this [MutableCollection]. */ public fun MutableCollection.removeAll(array: Array) { for (item in array) remove(item) } /** - * Retains only elements of the given *iterable* in this [[MutableCollection]] + * Retains only elements of the given [iterable] in this [MutableCollection]. */ public fun MutableCollection.retainAll(iterable: Iterable) { when (iterable) { @@ -59,7 +59,7 @@ public fun MutableCollection.retainAll(iterable: Iterable) { } /** - * Retains only elements of the given *array* in this [[MutableCollection]] + * Retains only elements of the given [array] in this [MutableCollection]. */ public fun MutableCollection.retainAll(array: Array) { retainAll(array.toSet()) diff --git a/libraries/stdlib/src/kotlin/collections/Operations.kt b/libraries/stdlib/src/kotlin/collections/Operations.kt index 44b0a29dd06..676e092b4e5 100644 --- a/libraries/stdlib/src/kotlin/collections/Operations.kt +++ b/libraries/stdlib/src/kotlin/collections/Operations.kt @@ -4,7 +4,7 @@ import java.util.ArrayList import kotlin.platform.platformName /** - * Returns a single list of all elements from all collections in original collection + * Returns a single list of all elements from all collections in the given collection. */ public fun Iterable>.flatten(): List { val result = ArrayList() @@ -15,14 +15,14 @@ public fun Iterable>.flatten(): List { } /** - * Returns a stream of all elements from all streams in original stream + * Returns a stream of all elements from all streams in the given stream. */ public fun Stream>.flatten(): Stream { return FlatteningStream(this, { it }) } /** - * Returns a single list of all elements from all collections in original collection + * Returns a single list of all elements from all arrays in the given array. */ public fun Array>.flatten(): List { val result = ArrayList(sumBy { it.size() }) diff --git a/libraries/stdlib/src/kotlin/properties/Delegation.kt b/libraries/stdlib/src/kotlin/properties/Delegation.kt index f32b9a49dd9..5877fe43622 100644 --- a/libraries/stdlib/src/kotlin/properties/Delegation.kt +++ b/libraries/stdlib/src/kotlin/properties/Delegation.kt @@ -1,20 +1,80 @@ package kotlin.properties +/** + * Base trait that can be used for implementing property delegates of read-only properties. This is provided only for + * convenience; you don't have to extend this trait as long as your property delegate has methods with the same + * signatures. + * @param R the type of object which owns the delegated property. + * @param T the type of the property value. + */ public trait ReadOnlyProperty { + /** + * Returns the value of the property for the given object. + * @param thisRef the object for which the value is requested. + * @param desc the metadata for the property. + * @return the property value. + */ public fun get(thisRef: R, desc: PropertyMetadata): T } +/** + * Base trait that can be used for implementing property delegates of read-only properties. This is provided only for + * convenience; you don't have to extend this trait as long as your property delegate has methods with the same + * signatures. + * @param R the type of object which owns the delegated property. + * @param T the type of the property value. + */ public trait ReadWriteProperty { + /** + * Returns the value of the property for the given object. + * @param thisRef the object for which the value is requested. + * @param desc the metadata for the property. + * @return the property value. + */ public fun get(thisRef: R, desc: PropertyMetadata): T + + /** + * Sets the value of the property for the given object. + * @param thisRef the object for which the value is requested. + * @param desc the metadata for the property. + * @param value the value to set. + */ public fun set(thisRef: R, desc: PropertyMetadata, value: T) } +/** + * Standard property delegates. + */ public object Delegates { + /** + * Returns a property delegate for a read/write property with a non-null value that is initialized not during + * object construction time but at a later time. Trying to read the property before the initial value has been + * assigned results in an exception. + */ public fun notNull(): ReadWriteProperty = NotNullVar() + /** + * Returns a property delegate for a read-only property that is initialized on first access by calling the + * specified block of code. Supports lazy initialization semantics for properties. + * @param initializer the function that returns the value of the property. + */ public fun lazy(initializer: () -> T): ReadOnlyProperty = LazyVal(initializer) + + /** + * Returns a property delegate for a read-only property that is initialized on first access by calling the + * specified block of code under a specified lock. Supports lazy initialization semantics for properties and + * concurrent access. + * @param lock the object the monitor of which is locked before calling the initializer block. If not specified, + * the property delegate object itself is used as a lock. + * @param initializer the function that returns the value of the property. + */ public fun blockingLazy(lock: Any? = null, initializer: () -> T): ReadOnlyProperty = BlockingLazyVal(lock, initializer) + /** + * Returns a property delegate for a read/write property that calls a specified callback function when changed. + * @param initial the initial value of the property. + * @param onChange the callback which is called when the property value is changed. + */ public fun observable(initial: T, onChange: (desc: PropertyMetadata, oldValue: T, newValue: T) -> Unit): ReadWriteProperty { return ObservableProperty(initial) { (desc, old, new) -> onChange(desc, old, new) @@ -22,15 +82,34 @@ public object Delegates { } } + /** + * Returns a property delegate for a read/write property that calls a specified callback function when changed, + * allowing the callback to veto the modification. + * @param initial the initial value of the property. + * @param onChange the callback which is called when a change to the property value is attempted. The new value + * is saved if the callback returns true and discarded if the callback returns false. + */ public fun vetoable(initial: T, onChange: (desc: PropertyMetadata, oldValue: T, newValue: T) -> Boolean): ReadWriteProperty { return ObservableProperty(initial, onChange) } + /** + * Returns a property delegate for a read/write property that stores its value in a map, using the property name + * as a key. + * @param map the map where the property values are stored. + * @param default the function returning the value of the property for a given object if it's missing from the given map. + */ public fun mapVar(map: MutableMap, default: (thisRef: Any?, desc: String) -> T = defaultValueProvider): ReadWriteProperty { return FixedMapVar(map, defaultKeyProvider, default) } + /** + * Returns a property delegate for a read-only property that takes its value from a map, using the property name + * as a key. + * @param map the map where the property values are stored. + * @param default the function returning the value of the property for a given object if it's missing from the given map. + */ public fun mapVal(map: Map, default: (thisRef: Any?, desc: String) -> T = defaultValueProvider): ReadOnlyProperty { return FixedMapVal(map, defaultKeyProvider, default) @@ -50,6 +129,12 @@ private class NotNullVar() : ReadWriteProperty { } } +/** + * Implements a property delegate for a read/write property that calls a specified callback function when changed. + * @param initialValue the initial value of the property. + * @param onChange the callback which is called when a change to the property value is attempted. The new value +* is saved if the callback returns true and discarded if the callback returns false. + */ public class ObservableProperty( initialValue: T, private val onChange: (name: PropertyMetadata, oldValue: T, newValue: T) -> Boolean ) : ReadWriteProperty { @@ -111,12 +196,36 @@ private class BlockingLazyVal(lock: Any?, private val initializer: () -> T) : } } +/** + * Exception thrown by the default implementation of property delegates which store values in a map + * when the map does not contain the corresponding key. + */ public class KeyMissingException(message: String): RuntimeException(message) +/** + * Implements the core logic for a property delegate that stores property values in a map. + * @param T the type of the object that owns the delegated property. + * @param K the type of key in the map. + * @param V the type of the property value. + */ public abstract class MapVal() : ReadOnlyProperty { + /** + * Returns the map used to store the values of the properties of the given object instance. + * @param ref the object instance for which the map is requested. + */ protected abstract fun map(ref: T): Map + + /** + * Returns the map key used to store the values of the given property. + * @param desc the property for which the key is requested. + */ protected abstract fun key(desc: PropertyMetadata): K + /** + * Returns the property value to be used when the map does not contain the corresponding key. + * @param ref the object instance for which the value was requested. + * @param desc the property for which the value was requested. + */ protected open fun default(ref: T, desc: PropertyMetadata): V { throw KeyMissingException("Key $desc is missing in $ref") } @@ -132,6 +241,12 @@ public abstract class MapVal() : ReadOnlyProperty { } } +/** + * Implements the core logic for a read/write property delegate that stores property values in a map. + * @param T the type of the object that owns the delegated property. + * @param K the type of key in the map. + * @param V the type of the property value. + */ public abstract class MapVar() : MapVal(), ReadWriteProperty { protected abstract override fun map(ref: T): MutableMap @@ -144,6 +259,13 @@ public abstract class MapVar() : MapVal(), ReadWriteProperty String = {it.name} private val defaultValueProvider:(Any?, Any?) -> Nothing = {(thisRef, key) -> throw KeyMissingException("$key is missing from $thisRef")} +/** + * Implements a read-only property delegate that stores the property values in a given map instance and uses the given + * callback functions for calculating the key and the default value for each property. + * @param map the map used to store the values. + * @param key the function to calculate the map key from a property metadata object. + * @param default the function returning the value of the property for a given object if it's missing from the given map. + */ public open class FixedMapVal(private val map: Map, private val key: (PropertyMetadata) -> K, private val default: (ref: T, key: K) -> V = defaultValueProvider) : MapVal() { @@ -160,6 +282,13 @@ public open class FixedMapVal(private val map: Map, } } +/** + * Implements a read/write property delegate that stores the property values in a given map instance and uses the given + * callback functions for calculating the key and the default value for each property. + * @param map the map used to store the values. + * @param key the function to calculate the map key from a property metadata object. + * @param default the function returning the value of the property for a given object if it's missing from the given map. + */ public open class FixedMapVar(private val map: MutableMap, private val key: (PropertyMetadata) -> K, private val default: (ref: T, key: K) -> V = defaultValueProvider) : MapVar() { diff --git a/libraries/stdlib/src/kotlin/text/Strings.kt b/libraries/stdlib/src/kotlin/text/Strings.kt index e94d9cdd059..9ea5752f8e6 100644 --- a/libraries/stdlib/src/kotlin/text/Strings.kt +++ b/libraries/stdlib/src/kotlin/text/Strings.kt @@ -6,7 +6,10 @@ public fun String.trim(text: String): String = trimLeading(text).trimTrailing(te /** Returns the string with the prefix and postfix text trimmed */ public fun String.trim(prefix: String, postfix: String): String = trimLeading(prefix).trimTrailing(postfix) -/** Returns the string with the leading prefix of this string removed */ +/** + * If this string starts with the given [prefix], returns a copy of this string + * with the prefix removed. Otherwise, returns this string. + */ public fun String.trimLeading(prefix: String): String { var answer = this if (answer.startsWith(prefix)) { @@ -15,7 +18,10 @@ public fun String.trimLeading(prefix: String): String { return answer } -/** Returns the string with the trailing postfix of this string removed */ +/** + * If this string ends with the given [postfix], returns a copy of this string + * with the postfix removed. Otherwise, returns this string. + */ public fun String.trimTrailing(postfix: String): String { var answer = this if (answer.endsWith(postfix)) { @@ -24,7 +30,9 @@ public fun String.trimTrailing(postfix: String): String { return answer } -/** Returns a new String containing the everything but the leading whitespace characters */ +/** + * Returns a copy of this String with leading whitespace removed. + */ public fun String.trimLeading(): String { var count = 0 @@ -34,7 +42,9 @@ public fun String.trimLeading(): String { return if (count > 0) substring(count) else this } -/** Returns a new String containing the everything but the trailing whitespace characters */ +/** + * Returns a copy of this String with trailing whitespace removed. + */ public fun String.trimTrailing(): String { var count = this.length @@ -58,12 +68,22 @@ public fun CharSequence.iterator(): CharIterator = object : CharIterator() { public override fun hasNext(): Boolean = index < length } -/** Returns the string if it is not null or the empty string if its null */ +/** Returns the string if it is not null, or the empty string otherwise. */ public fun String?.orEmpty(): String = this ?: "" +/** + * Returns the range of valid character indices for this string. + */ public val String.indices: IntRange get() = 0..length() - 1 +/** + * Returns a character at the given index in a [CharSequence]. Allows to use the + * index operator for working with character sequences: + * ``` + * val c = charSequence[5] + * ``` + */ public fun CharSequence.get(index: Int): Char = this.charAt(index) /** @@ -73,7 +93,7 @@ public val String.lastIndex: Int get() = this.length() - 1 /** - * Returns a subsequence specified by given set of indices. + * Returns a subsequence obtained by taking the characters at the given [indices] in this sequence. */ public fun CharSequence.slice(indices: Iterable): CharSequence { val sb = StringBuilder() @@ -84,109 +104,113 @@ public fun CharSequence.slice(indices: Iterable): CharSequence { } /** - * Returns a substring specified by given range + * Returns a substring specified by the given [range]. */ public fun String.substring(range: IntRange): String = substring(range.start, range.end + 1) /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - * a special *truncated* separator (which defaults to "...") + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Iterable.join(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinToString(separator, prefix, postfix, limit, truncated) } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If an array could be huge you can specify a non-negative value of *limit* which will only show a subset of the array then it will - * a special *truncated* separator (which defaults to "...") + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the array could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Array.join(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinToString(separator, prefix, postfix, limit, truncated) } /** - * Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. - * If a stream could be huge you can specify a non-negative value of *limit* which will only show a subset of the stream then it will - * a special *truncated* separator (which defaults to "...") + * Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. + * If the stream could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + * elements will be appended, followed by the [truncated] string (which defaults to "..."). */ public fun Stream.join(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int = -1, truncated: String = "..."): String { return joinToString(separator, prefix, postfix, limit, truncated) } + /** - * Returns a substring before first occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring before the first occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringBefore(delimiter: Char, missingSeparatorValue : String = this): String { +public fun String.substringBefore(delimiter: Char, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(0, index) + return if (index == -1) missingDelimiterValue else substring(0, index) } /** - * Returns a substring before first occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring before the first occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringBefore(delimiter: String, missingSeparatorValue : String = this): String { +public fun String.substringBefore(delimiter: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(0, index) + return if (index == -1) missingDelimiterValue else substring(0, index) } + /** - * Returns a substring after first occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring after the first occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringAfter(delimiter: Char, missingSeparatorValue : String = this): String { +public fun String.substringAfter(delimiter: Char, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(index + 1, length) + return if (index == -1) missingDelimiterValue else substring(index + 1, length) } /** - * Returns a substring after first occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring after the first occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringAfter(delimiter: String, missingSeparatorValue : String = this): String { +public fun String.substringAfter(delimiter: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(index + delimiter.length, length) + return if (index == -1) missingDelimiterValue else substring(index + delimiter.length, length) } /** - * Returns a substring before last occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring before the last occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringBeforeLast(delimiter: Char, missingSeparatorValue : String = this): String { +public fun String.substringBeforeLast(delimiter: Char, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(0, index) + return if (index == -1) missingDelimiterValue else substring(0, index) } /** - * Returns a substring before last occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring before the last occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringBeforeLast(delimiter: String, missingSeparatorValue : String = this): String { +public fun String.substringBeforeLast(delimiter: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(0, index) + return if (index == -1) missingDelimiterValue else substring(0, index) } /** - * Returns a substring after last occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring after the last occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringAfterLast(delimiter: Char, missingSeparatorValue : String = this): String { +public fun String.substringAfterLast(delimiter: Char, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(index + 1, length) + return if (index == -1) missingDelimiterValue else substring(index + 1, length) } /** - * Returns a substring after last occurrence of delimiter. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Returns a substring after the last occurrence of [delimiter]. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.substringAfterLast(delimiter: String, missingSeparatorValue : String = this): String { +public fun String.substringAfterLast(delimiter: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else substring(index + delimiter.length, length) + return if (index == -1) missingDelimiterValue else substring(index + delimiter.length, length) } /** - * Replace part of string at given range with replacement string + * Replaces the part of the string at the given range with the [replacement] string. + * @param firstIndex the index of the first character to be replaced. + * @param lastIndex the index of the first character after the replacement to keep in the string. */ public fun String.replaceRange(firstIndex: Int, lastIndex: Int, replacement: String): String { if (lastIndex < firstIndex) @@ -199,7 +223,7 @@ public fun String.replaceRange(firstIndex: Int, lastIndex: Int, replacement: Str } /** - * Replace part of string at given range with replacement string + * Replace the part of string at the given [range] with the [replacement] string. */ public fun String.replaceRange(range: IntRange, replacement: String): String { if (range.end < range.start) @@ -212,73 +236,73 @@ public fun String.replaceRange(range: IntRange, replacement: String): String { } /** - * Replace part of string before first occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string before the first occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceBefore(delimiter: Char, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceBefore(delimiter: Char, replacement: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(0, index, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(0, index, replacement) } /** - * Replace part of string before first occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string before the first occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceBefore(delimiter: String, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceBefore(delimiter: String, replacement: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(0, index, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(0, index, replacement) } /** - * Replace part of string after first occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string after the first occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceAfter(delimiter: Char, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceAfter(delimiter: Char, replacement: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(index + 1, length, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(index + 1, length, replacement) } /** - * Replace part of string after first occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string after the first occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceAfter(delimiter: String, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceAfter(delimiter: String, replacement: String, missingDelimiterValue: String = this): String { val index = indexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(index + delimiter.length, length, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(index + delimiter.length, length, replacement) } /** - * Replace part of string after last occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string after the last occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceAfterLast(delimiter: String, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceAfterLast(delimiter: String, replacement: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(index + delimiter.length, length, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(index + delimiter.length, length, replacement) } /** - * Replace part of string after last occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string after the last occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceAfterLast(delimiter: Char, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceAfterLast(delimiter: Char, replacement: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(index + 1, length, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(index + 1, length, replacement) } /** - * Replace part of string before last occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string before the last occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceBeforeLast(delimiter: Char, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceBeforeLast(delimiter: Char, replacement: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(0, index, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(0, index, replacement) } /** - * Replace part of string before last occurrence of given delimiter with replacement string. - * In case of no delimiter, returns the value of missingSeparatorValue which defaults to original string. + * Replace part of string before the last occurrence of given delimiter with the [replacement] string. + * If the string does not contain the delimiter, returns [missingDelimiterValue] which defaults to the original string. */ -public fun String.replaceBeforeLast(delimiter: String, replacement: String, missingSeparatorValue : String = this): String { +public fun String.replaceBeforeLast(delimiter: String, replacement: String, missingDelimiterValue: String = this): String { val index = lastIndexOf(delimiter) - return if (index == -1) missingSeparatorValue else replaceRange(0, index, replacement) + return if (index == -1) missingDelimiterValue else replaceRange(0, index, replacement) } diff --git a/libraries/stdlib/src/kotlin/util/AssertionsJVM.kt b/libraries/stdlib/src/kotlin/util/AssertionsJVM.kt index c974cbf8654..e4210cb2404 100644 --- a/libraries/stdlib/src/kotlin/util/AssertionsJVM.kt +++ b/libraries/stdlib/src/kotlin/util/AssertionsJVM.kt @@ -7,7 +7,7 @@ deprecated("Must be public to make assert() inlinable") public val ASSERTIONS_ENABLED: Boolean = _Assertions.javaClass.desiredAssertionStatus() /** -* Throws an [AssertionError] with an optional *message* if the *value* is false +* Throws an [AssertionError] with an optional [message] if the [value] is false * and runtime assertions have been enabled on the JVM using the *-ea* JVM option. */ public fun assert(value: Boolean, message: Any = "Assertion failed") { @@ -19,7 +19,7 @@ public fun assert(value: Boolean, message: Any = "Assertion failed") { } /** - * Throws an [AssertionError] calculated by *lazyMessage* if the *value* is false + * Throws an [AssertionError] calculated by [lazyMessage] if the [value] is false * and runtime assertions have been enabled on the JVM using the *-ea* JVM option. */ public inline fun assert(value: Boolean, lazyMessage: () -> Any) { diff --git a/libraries/stdlib/src/kotlin/util/Integers.kt b/libraries/stdlib/src/kotlin/util/Integers.kt index 4637bcaa201..f56b0b67fcd 100644 --- a/libraries/stdlib/src/kotlin/util/Integers.kt +++ b/libraries/stdlib/src/kotlin/util/Integers.kt @@ -1,5 +1,8 @@ package kotlin +/** + * Executes the given function [body] the number of times equal to the value of this integer. + */ public inline fun Int.times(body : () -> Unit) { var count = this; while (count > 0) { diff --git a/libraries/stdlib/src/kotlin/util/JLangJVM.kt b/libraries/stdlib/src/kotlin/util/JLangJVM.kt index d8476831a69..cffea84c401 100644 --- a/libraries/stdlib/src/kotlin/util/JLangJVM.kt +++ b/libraries/stdlib/src/kotlin/util/JLangJVM.kt @@ -10,21 +10,34 @@ import kotlin.jvm.internal.Intrinsic * * Example: * - * throws(javaClass()) - * fun readFile(name: String): String {...} + * ``` + * throws(javaClass()) + * fun readFile(name: String): String {...} + * ``` * * will be translated to * - * String readFile(String name) throws IOException {...} + * ``` + * String readFile(String name) throws IOException {...} + * ``` */ Retention(RetentionPolicy.SOURCE) public annotation class throws(public vararg val exceptionClasses: Class) +/** + * Returns the runtime Java class of this object. + */ [Intrinsic("kotlin.javaClass.property")] public val T.javaClass : Class get() = (this as java.lang.Object).getClass() as Class +/** + * Returns the Java class for the specified type. + */ [Intrinsic("kotlin.javaClass.function")] public fun javaClass(): Class = null as Class +/** + * Executes the given function [block] while holding the monitor of the given object [lock]. + */ public inline fun synchronized(lock: Any, block: () -> R): R { monitorEnter(lock) try { diff --git a/libraries/stdlib/src/kotlin/util/Numbers.kt b/libraries/stdlib/src/kotlin/util/Numbers.kt index ddc3aa1ef5d..bb80c7ad588 100644 --- a/libraries/stdlib/src/kotlin/util/Numbers.kt +++ b/libraries/stdlib/src/kotlin/util/Numbers.kt @@ -1,13 +1,13 @@ package kotlin /** - * Returns {@code true} if the specified number is a - * Not-a-Number (NaN) value, {@code false} otherwise. + * Returns `true` if the specified number is a + * Not-a-Number (NaN) value, `false` otherwise. */ public fun Double.isNaN(): Boolean = this != this /** - * Returns {@code true} if the specified number is a - * Not-a-Number (NaN) value, {@code false} otherwise. + * Returns `true` if the specified number is a + * Not-a-Number (NaN) value, `false` otherwise. */ public fun Float.isNaN(): Boolean = this != this \ No newline at end of file diff --git a/libraries/stdlib/src/kotlin/util/Ordering.kt b/libraries/stdlib/src/kotlin/util/Ordering.kt index 4a3bc01e288..d621e8ec8c6 100644 --- a/libraries/stdlib/src/kotlin/util/Ordering.kt +++ b/libraries/stdlib/src/kotlin/util/Ordering.kt @@ -19,7 +19,10 @@ package kotlin import java.util.Comparator /** - * Compares two values using the sequence of functions to calculate a result of comparison. + * Compares two values using the specified sequence of functions to calculate the result of the comparison. + * The functions are called sequentially, receive the given values [a] and [b] and return [Comparable] + * objects. As soon as the [Comparable] instances returned by a function for [a] and [b] values do not + * compare as equal, the result of that comparison is returned. */ public fun compareValuesBy(a: T?, b: T?, vararg functions: (T) -> Comparable<*>?): Int { require(functions.size() > 0) @@ -36,7 +39,7 @@ public fun compareValuesBy(a: T?, b: T?, vararg functions: (T) -> Comp } /** - * Compares two [Comparable] nullable values, null is considered less than any value. + * Compares two nullable [Comparable] values. Null is considered less than any value. */ public fun > compareValues(a: T?, b: T?): Int { if (a identityEquals b) return 0 @@ -48,6 +51,9 @@ public fun > compareValues(a: T?, b: T?): Int { /** * Creates a comparator using the sequence of functions to calculate a result of comparison. + * The functions are called sequentially, receive the given values [a] and [b] and return [Comparable] + * objects. As soon as the [Comparable] instances returned by a function for [a] and [b] values do not + * compare as equal, the result of that comparison is returned from the [Comparator]. */ public fun compareBy(vararg functions: (T) -> Comparable<*>?): Comparator { return object : Comparator { diff --git a/libraries/stdlib/src/kotlin/util/Preconditions.kt b/libraries/stdlib/src/kotlin/util/Preconditions.kt index 8646dcf21c9..bb28bcb9303 100644 --- a/libraries/stdlib/src/kotlin/util/Preconditions.kt +++ b/libraries/stdlib/src/kotlin/util/Preconditions.kt @@ -5,9 +5,9 @@ import java.lang.IllegalArgumentException import java.lang.IllegalStateException /** - * Throws an [IllegalArgumentException] with an optional *message* if the *value* is false. + * Throws an [IllegalArgumentException] with an optional [message] if the [value] is false. * - * ${code test.collections.PreconditionsTest.failingRequireWithMessage} + * @sample test.collections.PreconditionsTest.failingRequireWithMessage */ public fun require(value: Boolean, message: Any = "Failed requirement"): Unit { if (!value) { @@ -16,9 +16,9 @@ public fun require(value: Boolean, message: Any = "Failed requirement"): Unit { } /** - * Throws an [IllegalArgumentException] with the *lazyMessage* if the *value* is false. + * Throws an [IllegalArgumentException] with the result of calling [lazyMessage] if the [value] is false. * - * ${code test.collections.PreconditionsTest.failingRequireWithLazyMessage} + * @sample test.collections.PreconditionsTest.failingRequireWithLazyMessage */ public inline fun require(value: Boolean, lazyMessage: () -> Any): Unit { if (!value) { @@ -28,10 +28,10 @@ public inline fun require(value: Boolean, lazyMessage: () -> Any): Unit { } /** - * Throws an [IllegalArgumentException] with the given *message* if the *value* is null otherwise - * the not null value is returned. + * Throws an [IllegalArgumentException] with the given [message] if the [value] is null. Otherwise + * returns the not null value. * - * ${code test.collections.PreconditionsTest.requireNotNull} + * @sample test.collections.PreconditionsTest.requireNotNull */ public fun requireNotNull(value: T?, message: Any = "Required value was null"): T { if (value == null) { @@ -42,9 +42,9 @@ public fun requireNotNull(value: T?, message: Any = "Required value was } /** - * Throws an [IllegalStateException] with an optional *message* if the *value* is false. + * Throws an [IllegalStateException] with an optional [message] if the [value] is false. * - * ${code test.collections.PreconditionsTest.failingCheckWithMessage} + * @sample test.collections.PreconditionsTest.failingCheckWithMessage */ public fun check(value: Boolean, message: Any = "Check failed"): Unit { if (!value) { @@ -53,9 +53,9 @@ public fun check(value: Boolean, message: Any = "Check failed"): Unit { } /** - * Throws an [IllegalStateException] with the *lazyMessage* if the *value* is false. + * Throws an [IllegalStateException] with the result of calling [lazyMessage] if the [value] is false. * - * ${code test.collections.PreconditionsTest.failingCheckWithLazyMessage} + * @sample test.collections.PreconditionsTest.failingCheckWithLazyMessage */ public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit { if (!value) { @@ -65,10 +65,10 @@ public inline fun check(value: Boolean, lazyMessage: () -> Any): Unit { } /** - * Throws an [IllegalStateException] with the given *message* if the *value* is null otherwise - * the not null value is returned. + * Throws an [IllegalArgumentException] with the given [message] if the [value] is null. Otherwise + * returns the not null value. * - * ${code test.collections.PreconditionsTest.checkNotNull} + * @sample test.collections.PreconditionsTest.checkNotNull */ public fun checkNotNull(value: T?, message: Any = "Required value was null"): T { if (value == null) { @@ -79,8 +79,8 @@ public fun checkNotNull(value: T?, message: Any = "Required value was nu } /** - * Throws an [IllegalStateException] with the given *message* + * Throws an [IllegalStateException] with the given [message] * - * ${code test.collections.PreconditionsTest.error} + * @sample test.collections.PreconditionsTest.error */ public fun error(message: Any): Nothing = throw IllegalStateException(message.toString()) diff --git a/libraries/stdlib/src/kotlin/util/Standard.kt b/libraries/stdlib/src/kotlin/util/Standard.kt index 975dc425c30..12dc78a209d 100644 --- a/libraries/stdlib/src/kotlin/util/Standard.kt +++ b/libraries/stdlib/src/kotlin/util/Standard.kt @@ -1,15 +1,15 @@ package kotlin /** - * Creates a tuple of type [[Pair]] from this and *that* which can be useful for creating [[Map]] literals - * with less noise, for example - - * @includeFunctionBody ../../test/collections/MapTest.kt createUsingTo + * Creates a tuple of type [Pair] from this and [that]. + * + * This can be useful for creating [Map] literals with less noise, for example: + * @sample test.collections.MapTest.createUsingTo */ public fun A.to(that: B): Pair = Pair(this, that) /** -Run function f + * Calls the specified function. */ public inline fun run(f: () -> T): T = f() diff --git a/libraries/stdlib/src/kotlin/util/StandardJVM.kt b/libraries/stdlib/src/kotlin/util/StandardJVM.kt index b43ef508e83..77b51232f0d 100644 --- a/libraries/stdlib/src/kotlin/util/StandardJVM.kt +++ b/libraries/stdlib/src/kotlin/util/StandardJVM.kt @@ -4,7 +4,7 @@ import java.io.PrintWriter import java.io.PrintStream /** - * Allows a stack trace to be printed from Kotlin's [[Throwable]] + * Allows a stack trace to be printed from Kotlin's [Throwable]. */ public fun Throwable.printStackTrace(writer: PrintWriter): Unit { val jlt = this as java.lang.Throwable @@ -12,7 +12,7 @@ public fun Throwable.printStackTrace(writer: PrintWriter): Unit { } /** - * Allows a stack trace to be printed from Kotlin's [[Throwable]] + * Allows a stack trace to be printed from Kotlin's [Throwable] */ public fun Throwable.printStackTrace(stream: PrintStream): Unit { val jlt = this as java.lang.Throwable @@ -20,9 +20,8 @@ public fun Throwable.printStackTrace(stream: PrintStream): Unit { } /** - * Returns the stack trace + * Returns the list of stack trace elements in a Kotlin stack trace. */ - public fun Throwable.getStackTrace(): Array { val jlt = this as java.lang.Throwable return jlt.getStackTrace()!! diff --git a/libraries/stdlib/src/kotlin/util/SystemJVM.kt b/libraries/stdlib/src/kotlin/util/SystemJVM.kt index d2f9dfc5a10..bb5b8909191 100644 --- a/libraries/stdlib/src/kotlin/util/SystemJVM.kt +++ b/libraries/stdlib/src/kotlin/util/SystemJVM.kt @@ -1,8 +1,8 @@ package kotlin.util /** -Executes current block and returns elapsed time in milliseconds -*/ + * Executes the given block and returns elapsed time in milliseconds. + */ public fun measureTimeMillis(block: () -> Unit) : Long { val start = System.currentTimeMillis() block() @@ -10,8 +10,8 @@ public fun measureTimeMillis(block: () -> Unit) : Long { } /** -Executes current block and returns elapsed time in nanoseconds -*/ + * Executes the given block and returns elapsed time in nanoseconds. + */ public fun measureTimeNano(block: () -> Unit) : Long { val start = System.nanoTime() block() diff --git a/libraries/stdlib/src/kotlin/util/Tuples.kt b/libraries/stdlib/src/kotlin/util/Tuples.kt index 480cb47a12b..1960bbd2ec9 100644 --- a/libraries/stdlib/src/kotlin/util/Tuples.kt +++ b/libraries/stdlib/src/kotlin/util/Tuples.kt @@ -9,11 +9,13 @@ import java.io.Serializable * Pair exhibits value semantics, i.e. two pairs are equal if both components are equal. * * An example of decomposing it into values: - * ${code test.tuples.PairTest.pairMultiAssignment} + * @sample test.tuples.PairTest.pairMultiAssignment * - * $constructor: Creates new instance of [Pair] - * $first: First value - * $second: Second value + * @param A type of the first value + * @param B type of the second value + * @param first First value + * @param second Second value + * @constructor Creates a new instance of Pair. */ public data class Pair( public val first: A, @@ -27,7 +29,7 @@ public data class Pair( } /** - * Converts pair into a list + * Converts a pair into a list. */ public fun Pair.toList(): List = listOf(first, second) @@ -37,11 +39,14 @@ public fun Pair.toList(): List = listOf(first, second) * There is no meaning attached to values in this class, it can be used for any purpose. * Triple exhibits value semantics, i.e. two triples are equal if all three components are equal. * An example of decomposing it into values: - * {code test.tuples.PairTest.pairMultiAssignment} + * @sample test.tuples.TripleTest.tripleMultiAssignment * - * $first: First value - * $second: Second value - * $third: Third value + * @param A type of the first value + * @param B type of the second value + * @param C type of the third value + * @param first First value + * @param second Second value + * @param third Third value */ public data class Triple( public val first: A, @@ -50,7 +55,7 @@ public data class Triple( ) : Serializable { /** - * Returns string representation of the [Triple] including its [first] and [second] values. + * Returns string representation of the [Triple] including its [first], [second] and [third] values. */ public override fun toString(): String = "($first, $second, $third)" } diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt index e3484a10d1f..eff616a1f16 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt @@ -47,7 +47,7 @@ fun aggregates(): List { templates add f("any(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns *true* if any element matches the given *predicate*" } + doc { "Returns *true* if any element matches the given [predicate]" } returns("Boolean") body { """ @@ -73,7 +73,7 @@ fun aggregates(): List { templates add f("count(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns the number of elements matching the given *predicate*" } + doc { "Returns the number of elements matching the given [predicate]" } returns("Int") body { """ @@ -105,7 +105,8 @@ fun aggregates(): List { templates add f("sumBy(transform: (T) -> Int)") { inline(true) - doc { "Returns the sum of all values produced by `transform` function from elements in the collection" } + doc { "Returns the sum of all values produced by [transform] function from elements in the collection" } + doc(Strings) { "Returns the sum of all values produced by [transform] function from characters in the string" } returns("Int") body { """ @@ -120,7 +121,8 @@ fun aggregates(): List { templates add f("sumByDouble(transform: (T) -> Double)") { inline(true) - doc { "Returns the sum of all values produced by `transform` function from elements in the collection" } + doc { "Returns the sum of all values produced by [transform] function from elements in the collection" } + doc(Strings) { "Returns the sum of all values produced by [transform] function from characters in the string" } returns("Double") body { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt index b8afcdde231..259e1b2b5a7 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Elements.kt @@ -25,7 +25,7 @@ fun elements(): List { templates add f("indexOf(element: T)") { exclude(Strings) - doc { "Returns first index of *element*, or -1 if the collection does not contain element" } + doc { "Returns first index of [element], or -1 if the collection does not contain element" } returns("Int") body { """ @@ -153,7 +153,12 @@ fun elements(): List { } templates add f("first()") { - doc { "Returns first element" } + doc { """Returns first element. + @throws NoSuchElementException if the collection is empty. + """ } + doc(Strings) { """Returns first character. + @throws NoSuchElementException if the string is empty. + """ } returns("T") body { """ @@ -182,7 +187,8 @@ fun elements(): List { } } templates add f("firstOrNull()") { - doc { "Returns first element, or null if collection is empty" } + doc { "Returns the first element, or null if the collection is empty." } + doc(Strings) { "Returns the first character, or null if string is empty." } returns("T?") body { """ @@ -212,7 +218,10 @@ fun elements(): List { templates add f("first(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns first element matching the given *predicate*" } + doc { """"Returns the first element matching the given [predicate]. + @throws NoSuchElementException if no such element is found.""" } + doc(Strings) { """Returns the first character matching the given [predicate]. + @throws NoSuchElementException if no such character is found.""" } returns("T") body { """ @@ -225,7 +234,8 @@ fun elements(): List { templates add f("firstOrNull(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns first element matching the given *predicate*, or *null* if element was not found" } + doc { "Returns first element matching the given [predicate], or `null` if element was not found" } + doc(Strings) { "Returns first character matching the given [predicate], or `null` if character was not found" } returns("T?") body { """ @@ -236,7 +246,10 @@ fun elements(): List { } templates add f("last()") { - doc { "Returns last element" } + doc { """Returns the last element. + @throws NoSuchElementException if the collection is empty.""" } + doc(Strings) { """"Returns the last character. + @throws NoSuchElementException if the string is empty.""" } returns("T") body { """ @@ -280,7 +293,8 @@ fun elements(): List { } templates add f("lastOrNull()") { - doc { "Returns last element, or null if collection is empty" } + doc { "Returns the last element, or `null` if the collection is empty" } + doc(Strings) { "Returns the last character, or `null` if the string is empty" } returns("T?") body { """ @@ -323,7 +337,10 @@ fun elements(): List { templates add f("last(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns last element matching the given *predicate*" } + doc { """Returns the last element matching the given [predicate]. + @throws NoSuchElementException if no such element is found.""" } + doc(Strings) { """"Returns the last character matching the given [predicate]. + @throws NoSuchElementException if no such character is found.""" } returns("T") body { """ @@ -343,7 +360,8 @@ fun elements(): List { templates add f("lastOrNull(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns last element matching the given *predicate*, or null if element was not found" } + doc { "Returns the last element matching the given [predicate], or `null` if no such element was found." } + doc(Strings) { "Returns the last character matching the given [predicate], or `null` if no such character was found." } returns("T?") body { """ @@ -359,7 +377,8 @@ fun elements(): List { } templates add f("single()") { - doc { "Returns single element, or throws exception if there is no or more than one element" } + doc { "Returns the single element, or throws an exception if the collection is empty or has more than one element." } + doc(Strings) { "Returns the single character, or throws an exception if the string is empty or has more than one character." } returns("T") body { """ @@ -402,7 +421,8 @@ fun elements(): List { } templates add f("singleOrNull()") { - doc { "Returns single element, or null if collection is empty, or throws exception if there is more than one element" } + doc { "Returns single element, or `null` if the collection is empty or has more than one element." } + doc(Strings) { "Returns the single character, or `null` if the string is empty or has more than one character." } returns("T?") body { """ @@ -434,7 +454,8 @@ fun elements(): List { templates add f("single(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns single element matching the given *predicate*, or throws exception if there is no or more than one element" } + doc { "Returns the single element matching the given [predicate], or throws exception if there is no or more than one matching element" } + doc(Strings) { "Returns the single character matching the given [predicate], or throws exception if there is no or more than one matching character" } returns("T") body { """ @@ -455,7 +476,8 @@ fun elements(): List { templates add f("singleOrNull(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns single element matching the given *predicate*, or null if element was not found or more than one elements were found" } + doc { "Returns the single element matching the given [predicate], or `null` if element was not found or more than one element was found" } + doc(Strings) { "Returns the single character matching the given [predicate], or `null` if character was not found or more than one character was found" } returns("T?") body { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt index b484c886bab..74559ac161d 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Filtering.kt @@ -6,7 +6,7 @@ fun filtering(): List { val templates = arrayListOf() templates add f("drop(n: Int)") { - doc { "Returns a list containing all elements except first *n* elements" } + doc { "Returns a list containing all elements except first [n] elements" } returns("List") body { """ @@ -19,7 +19,7 @@ fun filtering(): List { """ } - doc(Streams) { "Returns a stream containing all elements except first *n* elements" } + doc(Streams) { "Returns a stream containing all elements except first [n] elements" } returns(Streams) { "Stream" } body(Streams) { """ @@ -27,6 +27,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string with the first [n] characters removed"} body(Strings) { "return substring(Math.min(n, length()))" } returns(Strings) { "String" } @@ -46,7 +47,7 @@ fun filtering(): List { } templates add f("take(n: Int)") { - doc { "Returns a list containing first *n* elements" } + doc { "Returns a list containing first [n] elements" } returns("List") body { """ @@ -61,6 +62,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing the first [n] characters from this string, or the entire string if this string is shorter"} body(Strings) { "return substring(0, Math.min(n, length()))" } returns(Strings) { "String" } @@ -91,7 +93,7 @@ fun filtering(): List { templates add f("dropWhile(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns a list containing all elements except first elements that satisfy the given *predicate*" } + doc { "Returns a list containing all elements except first elements that satisfy the given [predicate]" } returns("List") body { """ @@ -108,6 +110,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing all characters except first characters that satisfy the given [predicate]" } returns(Strings) { "String" } body(Strings) { """ @@ -120,7 +123,7 @@ fun filtering(): List { } inline(false, Streams) - doc(Streams) { "Returns a stream containing all elements except first elements that satisfy the given *predicate*" } + doc(Streams) { "Returns a stream containing all elements except first elements that satisfy the given [predicate]" } returns(Streams) { "Stream" } body(Streams) { """ @@ -133,7 +136,7 @@ fun filtering(): List { templates add f("takeWhile(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns a list containing first elements satisfying the given *predicate*" } + doc { "Returns a list containing first elements satisfying the given [predicate]" } returns("List") body { """ @@ -147,6 +150,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing the first characters that satisfy the given [predicate]"} returns(Strings) { "String" } body(Strings) { """ @@ -159,7 +163,7 @@ fun filtering(): List { } inline(false, Streams) - doc(Streams) { "Returns a stream containing first elements satisfying the given *predicate*" } + doc(Streams) { "Returns a stream containing first elements satisfying the given [predicate]" } returns(Streams) { "Stream" } body(Streams) { """ @@ -171,7 +175,7 @@ fun filtering(): List { templates add f("filter(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns a list containing all elements matching the given *predicate*" } + doc { "Returns a list containing all elements matching the given [predicate]" } returns("List") body { """ @@ -179,6 +183,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing only those characters from the original string that match the given [predicate]" } returns(Strings) { "String" } body(Strings) { """ @@ -187,7 +192,7 @@ fun filtering(): List { } inline(false, Streams) - doc(Streams) { "Returns a stream containing all elements matching the given *predicate*" } + doc(Streams) { "Returns a stream containing all elements matching the given [predicate]" } returns(Streams) { "Stream" } body(Streams) { """ @@ -199,7 +204,7 @@ fun filtering(): List { templates add f("filterTo(destination: C, predicate: (T) -> Boolean)") { inline(true) - doc { "Appends all elements matching the given *predicate* into the given *destination*" } + doc { "Appends all elements matching the given [predicate] into the given [destination]" } typeParam("C : TCollection") returns("C") @@ -210,7 +215,7 @@ fun filtering(): List { """ } - doc(Strings) { "Appends all characters matching the given *predicate* to the given *destination*" } + doc(Strings) { "Appends all characters matching the given [predicate] to the given [destination]" } body(Strings) { """ for (index in 0..length - 1) { @@ -225,7 +230,7 @@ fun filtering(): List { templates add f("filterNot(predicate: (T) -> Boolean)") { inline(true) - doc { "Returns a list containing all elements not matching the given *predicate*" } + doc { "Returns a list containing all elements not matching the given [predicate]" } returns("List") body { """ @@ -233,6 +238,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing only those characters from the original string that do not match the given [predicate]" } returns(Strings) { "String" } body(Strings) { """ @@ -241,7 +247,7 @@ fun filtering(): List { } inline(false, Streams) - doc(Streams) { "Returns a stream containing all elements not matching the given *predicate*" } + doc(Streams) { "Returns a stream containing all elements not matching the given [predicate]" } returns(Streams) { "Stream" } body(Streams) { """ @@ -253,7 +259,7 @@ fun filtering(): List { templates add f("filterNotTo(destination: C, predicate: (T) -> Boolean)") { inline(true) - doc { "Appends all elements not matching the given *predicate* to the given *destination*" } + doc { "Appends all elements not matching the given [predicate] to the given [destination]" } typeParam("C : TCollection") returns("C") @@ -264,7 +270,7 @@ fun filtering(): List { """ } - doc(Strings) { "Appends all characters not matching the given *predicate* to the given *destination*" } + doc(Strings) { "Appends all characters not matching the given [predicate] to the given [destination]" } body(Strings) { """ for (element in this) if (!predicate(element)) destination.append(element) @@ -296,7 +302,7 @@ fun filtering(): List { templates add f("filterNotNullTo(destination: C)") { exclude(ArraysOfPrimitives, Strings) - doc { "Appends all elements that are not null to the given *destination*" } + doc { "Appends all elements that are not null to the given [destination]" } returns("C") typeParam("C : TCollection") typeParam("T : Any") @@ -323,6 +329,7 @@ fun filtering(): List { """ } + doc(Strings) { "Returns a string containing characters at specified positions" } returns(Strings) { "String" } body(Strings) { """ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt index df044289994..fee3eadf543 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Strings.kt @@ -8,10 +8,10 @@ fun strings(): List { templates add f("joinTo(buffer: A, separator: String = \", \", prefix: String = \"\", postfix: String = \"\", limit: Int = -1, truncated: String = \"...\")") { doc { """ - Appends the string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied + Appends the string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. - If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - a special *truncated* separator (which defaults to "...") + If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + elements will be appended, followed by the [truncated] string (which defaults to "..."). """ } typeParam("A : Appendable") @@ -54,10 +54,10 @@ fun strings(): List { templates add f("joinToString(separator: String = \", \", prefix: String = \"\", postfix: String = \"\", limit: Int = -1, truncated: String = \"...\")") { doc { """ - Creates a string from all the elements separated using the *separator* and using the given *prefix* and *postfix* if supplied. + Creates a string from all the elements separated using [separator] and using the given [prefix] and [postfix] if supplied. - If a collection could be huge you can specify a non-negative value of *limit* which will only show a subset of the collection then it will - a special *truncated* separator (which defaults to "..." + If the collection could be huge, you can specify a non-negative value of [limit], in which case only the first [limit] + elements will be appended, followed by the [truncated] string (which defaults to "..."). """ }