From 4d7597fa5aadb0093b7b90fa76823271a9336cdc Mon Sep 17 00:00:00 2001 From: Abduqodiri Qurbonzoda Date: Tue, 14 Apr 2020 12:31:25 +0300 Subject: [PATCH] Document 'reduce' operation behavior on empty collections #KT-23322 --- .../stdlib/common/src/generated/_Arrays.kt | 810 ++++++++++++++---- .../common/src/generated/_Collections.kt | 90 +- .../stdlib/common/src/generated/_Sequences.kt | 43 +- .../stdlib/common/src/generated/_Strings.kt | 90 +- .../stdlib/common/src/generated/_UArrays.kt | 360 ++++++-- .../src/templates/Aggregates.kt | 157 ++-- 6 files changed, 1194 insertions(+), 356 deletions(-) diff --git a/libraries/stdlib/common/src/generated/_Arrays.kt b/libraries/stdlib/common/src/generated/_Arrays.kt index edd9ad1e77a..1bb1506a27c 100644 --- a/libraries/stdlib/common/src/generated/_Arrays.kt +++ b/libraries/stdlib/common/src/generated/_Arrays.kt @@ -11793,7 +11793,12 @@ public inline fun CharArray.count(predicate: (Char) -> Boolean): Int { } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun Array.fold(initial: R, operation: (acc: R, T) -> R): R { var accumulator = initial @@ -11802,7 +11807,12 @@ public inline fun Array.fold(initial: R, operation: (acc: R, T) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun ByteArray.fold(initial: R, operation: (acc: R, Byte) -> R): R { var accumulator = initial @@ -11811,7 +11821,12 @@ public inline fun ByteArray.fold(initial: R, operation: (acc: R, Byte) -> R) } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun ShortArray.fold(initial: R, operation: (acc: R, Short) -> R): R { var accumulator = initial @@ -11820,7 +11835,12 @@ public inline fun ShortArray.fold(initial: R, operation: (acc: R, Short) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun IntArray.fold(initial: R, operation: (acc: R, Int) -> R): R { var accumulator = initial @@ -11829,7 +11849,12 @@ public inline fun IntArray.fold(initial: R, operation: (acc: R, Int) -> R): } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun LongArray.fold(initial: R, operation: (acc: R, Long) -> R): R { var accumulator = initial @@ -11838,7 +11863,12 @@ public inline fun LongArray.fold(initial: R, operation: (acc: R, Long) -> R) } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun FloatArray.fold(initial: R, operation: (acc: R, Float) -> R): R { var accumulator = initial @@ -11847,7 +11877,12 @@ public inline fun FloatArray.fold(initial: R, operation: (acc: R, Float) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun DoubleArray.fold(initial: R, operation: (acc: R, Double) -> R): R { var accumulator = initial @@ -11856,7 +11891,12 @@ public inline fun DoubleArray.fold(initial: R, operation: (acc: R, Double) - } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun BooleanArray.fold(initial: R, operation: (acc: R, Boolean) -> R): R { var accumulator = initial @@ -11865,7 +11905,12 @@ public inline fun BooleanArray.fold(initial: R, operation: (acc: R, Boolean) } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun CharArray.fold(initial: R, operation: (acc: R, Char) -> R): R { var accumulator = initial @@ -11876,6 +11921,9 @@ public inline fun CharArray.fold(initial: R, operation: (acc: R, Char) -> R) /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11889,6 +11937,9 @@ public inline fun Array.foldIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11902,6 +11953,9 @@ public inline fun ByteArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11915,6 +11969,9 @@ public inline fun ShortArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11928,6 +11985,9 @@ public inline fun IntArray.foldIndexed(initial: R, operation: (index: Int, a /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11941,6 +12001,9 @@ public inline fun LongArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11954,6 +12017,9 @@ public inline fun FloatArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11967,6 +12033,9 @@ public inline fun DoubleArray.foldIndexed(initial: R, operation: (index: Int /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11980,6 +12049,9 @@ public inline fun BooleanArray.foldIndexed(initial: R, operation: (index: In /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -11991,7 +12063,12 @@ public inline fun CharArray.foldIndexed(initial: R, operation: (index: Int, } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun Array.foldRight(initial: R, operation: (T, acc: R) -> R): R { var index = lastIndex @@ -12003,7 +12080,12 @@ public inline fun Array.foldRight(initial: R, operation: (T, acc: } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun ByteArray.foldRight(initial: R, operation: (Byte, acc: R) -> R): R { var index = lastIndex @@ -12015,7 +12097,12 @@ public inline fun ByteArray.foldRight(initial: R, operation: (Byte, acc: R) } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun ShortArray.foldRight(initial: R, operation: (Short, acc: R) -> R): R { var index = lastIndex @@ -12027,7 +12114,12 @@ public inline fun ShortArray.foldRight(initial: R, operation: (Short, acc: R } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun IntArray.foldRight(initial: R, operation: (Int, acc: R) -> R): R { var index = lastIndex @@ -12039,7 +12131,12 @@ public inline fun IntArray.foldRight(initial: R, operation: (Int, acc: R) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun LongArray.foldRight(initial: R, operation: (Long, acc: R) -> R): R { var index = lastIndex @@ -12051,7 +12148,12 @@ public inline fun LongArray.foldRight(initial: R, operation: (Long, acc: R) } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun FloatArray.foldRight(initial: R, operation: (Float, acc: R) -> R): R { var index = lastIndex @@ -12063,7 +12165,12 @@ public inline fun FloatArray.foldRight(initial: R, operation: (Float, acc: R } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun DoubleArray.foldRight(initial: R, operation: (Double, acc: R) -> R): R { var index = lastIndex @@ -12075,7 +12182,12 @@ public inline fun DoubleArray.foldRight(initial: R, operation: (Double, acc: } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun BooleanArray.foldRight(initial: R, operation: (Boolean, acc: R) -> R): R { var index = lastIndex @@ -12087,7 +12199,12 @@ public inline fun BooleanArray.foldRight(initial: R, operation: (Boolean, ac } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun CharArray.foldRight(initial: R, operation: (Char, acc: R) -> R): R { var index = lastIndex @@ -12101,6 +12218,9 @@ public inline fun CharArray.foldRight(initial: R, operation: (Char, acc: R) /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12117,6 +12237,9 @@ public inline fun Array.foldRightIndexed(initial: R, operation: (i /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12133,6 +12256,9 @@ public inline fun ByteArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12149,6 +12275,9 @@ public inline fun ShortArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12165,6 +12294,9 @@ public inline fun IntArray.foldRightIndexed(initial: R, operation: (index: I /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12181,6 +12313,9 @@ public inline fun LongArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12197,6 +12332,9 @@ public inline fun FloatArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12213,6 +12351,9 @@ public inline fun DoubleArray.foldRightIndexed(initial: R, operation: (index /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -12229,6 +12370,9 @@ public inline fun BooleanArray.foldRightIndexed(initial: R, operation: (inde /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -13682,7 +13826,14 @@ public inline fun CharArray.onEachIndexed(action: (index: Int, Char) -> Unit): C } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13697,7 +13848,14 @@ public inline fun Array.reduce(operation: (acc: S, T) -> S): S } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13712,7 +13870,14 @@ public inline fun ByteArray.reduce(operation: (acc: Byte, Byte) -> Byte): Byte { } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13727,7 +13892,14 @@ public inline fun ShortArray.reduce(operation: (acc: Short, Short) -> Short): Sh } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13742,7 +13914,14 @@ public inline fun IntArray.reduce(operation: (acc: Int, Int) -> Int): Int { } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13757,7 +13936,14 @@ public inline fun LongArray.reduce(operation: (acc: Long, Long) -> Long): Long { } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13772,7 +13958,14 @@ public inline fun FloatArray.reduce(operation: (acc: Float, Float) -> Float): Fl } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13787,7 +13980,14 @@ public inline fun DoubleArray.reduce(operation: (acc: Double, Double) -> Double) } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13802,7 +14002,14 @@ public inline fun BooleanArray.reduce(operation: (acc: Boolean, Boolean) -> Bool } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13819,8 +14026,12 @@ public inline fun CharArray.reduce(operation: (acc: Char, Char) -> Char): Char { /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13837,8 +14048,12 @@ public inline fun Array.reduceIndexed(operation: (index: Int, /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13855,8 +14070,12 @@ public inline fun ByteArray.reduceIndexed(operation: (index: Int, acc: Byte, Byt /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13873,8 +14092,12 @@ public inline fun ShortArray.reduceIndexed(operation: (index: Int, acc: Short, S /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13891,8 +14114,12 @@ public inline fun IntArray.reduceIndexed(operation: (index: Int, acc: Int, Int) /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13909,8 +14136,12 @@ public inline fun LongArray.reduceIndexed(operation: (index: Int, acc: Long, Lon /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13927,8 +14158,12 @@ public inline fun FloatArray.reduceIndexed(operation: (index: Int, acc: Float, F /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13945,8 +14180,12 @@ public inline fun DoubleArray.reduceIndexed(operation: (index: Int, acc: Double, /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13963,8 +14202,12 @@ public inline fun BooleanArray.reduceIndexed(operation: (index: Int, acc: Boolea /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -13981,9 +14224,11 @@ public inline fun CharArray.reduceIndexed(operation: (index: Int, acc: Char, Cha /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14001,9 +14246,11 @@ public inline fun Array.reduceIndexedOrNull(operation: (index: /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14021,9 +14268,11 @@ public inline fun ByteArray.reduceIndexedOrNull(operation: (index: Int, acc: Byt /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14041,9 +14290,11 @@ public inline fun ShortArray.reduceIndexedOrNull(operation: (index: Int, acc: Sh /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14061,9 +14312,11 @@ public inline fun IntArray.reduceIndexedOrNull(operation: (index: Int, acc: Int, /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14081,9 +14334,11 @@ public inline fun LongArray.reduceIndexedOrNull(operation: (index: Int, acc: Lon /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14101,9 +14356,11 @@ public inline fun FloatArray.reduceIndexedOrNull(operation: (index: Int, acc: Fl /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14121,9 +14378,11 @@ public inline fun DoubleArray.reduceIndexedOrNull(operation: (index: Int, acc: D /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14141,9 +14400,11 @@ public inline fun BooleanArray.reduceIndexedOrNull(operation: (index: Int, acc: /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14159,7 +14420,13 @@ public inline fun CharArray.reduceIndexedOrNull(operation: (index: Int, acc: Cha } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14176,7 +14443,13 @@ public inline fun Array.reduceOrNull(operation: (acc: S, T) -> } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14193,7 +14466,13 @@ public inline fun ByteArray.reduceOrNull(operation: (acc: Byte, Byte) -> Byte): } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14210,7 +14489,13 @@ public inline fun ShortArray.reduceOrNull(operation: (acc: Short, Short) -> Shor } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14227,7 +14512,13 @@ public inline fun IntArray.reduceOrNull(operation: (acc: Int, Int) -> Int): Int? } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14244,7 +14535,13 @@ public inline fun LongArray.reduceOrNull(operation: (acc: Long, Long) -> Long): } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14261,7 +14558,13 @@ public inline fun FloatArray.reduceOrNull(operation: (acc: Float, Float) -> Floa } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14278,7 +14581,13 @@ public inline fun DoubleArray.reduceOrNull(operation: (acc: Double, Double) -> D } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14295,7 +14604,13 @@ public inline fun BooleanArray.reduceOrNull(operation: (acc: Boolean, Boolean) - } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -14312,7 +14627,14 @@ public inline fun CharArray.reduceOrNull(operation: (acc: Char, Char) -> Char): } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14327,7 +14649,14 @@ public inline fun Array.reduceRight(operation: (T, acc: S) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14342,7 +14671,14 @@ public inline fun ByteArray.reduceRight(operation: (Byte, acc: Byte) -> Byte): B } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14357,7 +14693,14 @@ public inline fun ShortArray.reduceRight(operation: (Short, acc: Short) -> Short } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14372,7 +14715,14 @@ public inline fun IntArray.reduceRight(operation: (Int, acc: Int) -> Int): Int { } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14387,7 +14737,14 @@ public inline fun LongArray.reduceRight(operation: (Long, acc: Long) -> Long): L } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14402,7 +14759,14 @@ public inline fun FloatArray.reduceRight(operation: (Float, acc: Float) -> Float } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14417,7 +14781,14 @@ public inline fun DoubleArray.reduceRight(operation: (Double, acc: Double) -> Do } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14432,7 +14803,14 @@ public inline fun BooleanArray.reduceRight(operation: (Boolean, acc: Boolean) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14447,10 +14825,14 @@ public inline fun CharArray.reduceRight(operation: (Char, acc: Char) -> Char): C } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14466,10 +14848,14 @@ public inline fun Array.reduceRightIndexed(operation: (index: } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14485,10 +14871,14 @@ public inline fun ByteArray.reduceRightIndexed(operation: (index: Int, Byte, acc } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14504,10 +14894,14 @@ public inline fun ShortArray.reduceRightIndexed(operation: (index: Int, Short, a } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14523,10 +14917,14 @@ public inline fun IntArray.reduceRightIndexed(operation: (index: Int, Int, acc: } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14542,10 +14940,14 @@ public inline fun LongArray.reduceRightIndexed(operation: (index: Int, Long, acc } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14561,10 +14963,14 @@ public inline fun FloatArray.reduceRightIndexed(operation: (index: Int, Float, a } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14580,10 +14986,14 @@ public inline fun DoubleArray.reduceRightIndexed(operation: (index: Int, Double, } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14599,10 +15009,14 @@ public inline fun BooleanArray.reduceRightIndexed(operation: (index: Int, Boolea } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -14618,11 +15032,13 @@ public inline fun CharArray.reduceRightIndexed(operation: (index: Int, Char, acc } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14639,11 +15055,13 @@ public inline fun Array.reduceRightIndexedOrNull(operation: (i } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14660,11 +15078,13 @@ public inline fun ByteArray.reduceRightIndexedOrNull(operation: (index: Int, Byt } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14681,11 +15101,13 @@ public inline fun ShortArray.reduceRightIndexedOrNull(operation: (index: Int, Sh } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14702,11 +15124,13 @@ public inline fun IntArray.reduceRightIndexedOrNull(operation: (index: Int, Int, } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14723,11 +15147,13 @@ public inline fun LongArray.reduceRightIndexedOrNull(operation: (index: Int, Lon } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14744,11 +15170,13 @@ public inline fun FloatArray.reduceRightIndexedOrNull(operation: (index: Int, Fl } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14765,11 +15193,13 @@ public inline fun DoubleArray.reduceRightIndexedOrNull(operation: (index: Int, D } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14786,11 +15216,13 @@ public inline fun BooleanArray.reduceRightIndexedOrNull(operation: (index: Int, } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14807,7 +15239,13 @@ public inline fun CharArray.reduceRightIndexedOrNull(operation: (index: Int, Cha } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14824,7 +15262,13 @@ public inline fun Array.reduceRightOrNull(operation: (T, acc: } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14841,7 +15285,13 @@ public inline fun ByteArray.reduceRightOrNull(operation: (Byte, acc: Byte) -> By } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14858,7 +15308,13 @@ public inline fun ShortArray.reduceRightOrNull(operation: (Short, acc: Short) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14875,7 +15331,13 @@ public inline fun IntArray.reduceRightOrNull(operation: (Int, acc: Int) -> Int): } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14892,7 +15354,13 @@ public inline fun LongArray.reduceRightOrNull(operation: (Long, acc: Long) -> Lo } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14909,7 +15377,13 @@ public inline fun FloatArray.reduceRightOrNull(operation: (Float, acc: Float) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14926,7 +15400,13 @@ public inline fun DoubleArray.reduceRightOrNull(operation: (Double, acc: Double) } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -14943,7 +15423,13 @@ public inline fun BooleanArray.reduceRightOrNull(operation: (Boolean, acc: Boole } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ diff --git a/libraries/stdlib/common/src/generated/_Collections.kt b/libraries/stdlib/common/src/generated/_Collections.kt index 6b57ccf6e1c..e8fb686ebfc 100644 --- a/libraries/stdlib/common/src/generated/_Collections.kt +++ b/libraries/stdlib/common/src/generated/_Collections.kt @@ -1602,7 +1602,12 @@ public inline fun Iterable.count(predicate: (T) -> Boolean): Int { } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the collection is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ public inline fun Iterable.fold(initial: R, operation: (acc: R, T) -> R): R { var accumulator = initial @@ -1613,6 +1618,9 @@ public inline fun Iterable.fold(initial: R, operation: (acc: R, T) -> /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original collection. + * + * Returns the specified [initial] value if the collection is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -1624,7 +1632,12 @@ public inline fun Iterable.foldIndexed(initial: R, operation: (index: } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the list is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ public inline fun List.foldRight(initial: R, operation: (T, acc: R) -> R): R { var accumulator = initial @@ -1640,6 +1653,9 @@ public inline fun List.foldRight(initial: R, operation: (T, acc: R) -> /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original list and current accumulator value. + * + * Returns the specified [initial] value if the list is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -1890,7 +1906,14 @@ public inline fun > C.onEachIndexed(action: (index: Int, T) - } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this collection is empty. If the collection can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -1907,8 +1930,12 @@ public inline fun Iterable.reduce(operation: (acc: S, T) -> S): S /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original collection. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this collection is empty. If the collection can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -1926,9 +1953,11 @@ public inline fun Iterable.reduceIndexed(operation: (index: Int, a /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original collection. - * Returns null if the collection is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the collection is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -1945,7 +1974,13 @@ public inline fun Iterable.reduceIndexedOrNull(operation: (index: } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the collection is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the collection is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -1962,7 +1997,14 @@ public inline fun Iterable.reduceOrNull(operation: (acc: S, T) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this list is empty. If the list can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -1978,10 +2020,14 @@ public inline fun List.reduceRight(operation: (T, acc: S) -> S): S } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original list and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this list is empty. If the list can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -1998,11 +2044,13 @@ public inline fun List.reduceRightIndexed(operation: (index: Int, } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original list and current accumulator value. - * Returns null if the list is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the list is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -2020,7 +2068,13 @@ public inline fun List.reduceRightIndexedOrNull(operation: (index: } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the list is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the list is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ diff --git a/libraries/stdlib/common/src/generated/_Sequences.kt b/libraries/stdlib/common/src/generated/_Sequences.kt index 439819fc978..5f3b32e3687 100644 --- a/libraries/stdlib/common/src/generated/_Sequences.kt +++ b/libraries/stdlib/common/src/generated/_Sequences.kt @@ -1078,7 +1078,12 @@ public inline fun Sequence.count(predicate: (T) -> Boolean): Int { } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the sequence is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. * * The operation is _terminal_. */ @@ -1091,6 +1096,9 @@ public inline fun Sequence.fold(initial: R, operation: (acc: R, T) -> /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original sequence. + * + * Returns the specified [initial] value if the sequence is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. * @@ -1372,7 +1380,14 @@ public fun Sequence.onEachIndexed(action: (index: Int, T) -> Unit): Seque } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this sequence is empty. If the sequence can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * The operation is _terminal_. * @@ -1391,8 +1406,12 @@ public inline fun Sequence.reduce(operation: (acc: S, T) -> S): S /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original sequence. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this sequence is empty. If the sequence can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * The operation is _terminal_. * @@ -1412,9 +1431,11 @@ public inline fun Sequence.reduceIndexed(operation: (index: Int, a /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original sequence. - * Returns null if the sequence is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the sequence is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * The operation is _terminal_. * @@ -1433,7 +1454,13 @@ public inline fun Sequence.reduceIndexedOrNull(operation: (index: } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the sequence is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the sequence is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * The operation is _terminal_. * diff --git a/libraries/stdlib/common/src/generated/_Strings.kt b/libraries/stdlib/common/src/generated/_Strings.kt index c6e06bd9274..8a4a12572c9 100644 --- a/libraries/stdlib/common/src/generated/_Strings.kt +++ b/libraries/stdlib/common/src/generated/_Strings.kt @@ -1006,7 +1006,12 @@ public inline fun CharSequence.count(predicate: (Char) -> Boolean): Int { } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each character. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each character. + * + * Returns the specified [initial] value if the char sequence is empty. + * + * @param [operation] function that takes current accumulator value and a character, and calculates the next accumulator value. */ public inline fun CharSequence.fold(initial: R, operation: (acc: R, Char) -> R): R { var accumulator = initial @@ -1017,6 +1022,9 @@ public inline fun CharSequence.fold(initial: R, operation: (acc: R, Char) -> /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each character with its index in the original char sequence. + * + * Returns the specified [initial] value if the char sequence is empty. + * * @param [operation] function that takes the index of a character, current accumulator value * and the character itself, and calculates the next accumulator value. */ @@ -1028,7 +1036,12 @@ public inline fun CharSequence.foldIndexed(initial: R, operation: (index: In } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each character and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each character and current accumulator value. + * + * Returns the specified [initial] value if the char sequence is empty. + * + * @param [operation] function that takes a character and current accumulator value, and calculates the next accumulator value. */ public inline fun CharSequence.foldRight(initial: R, operation: (Char, acc: R) -> R): R { var index = lastIndex @@ -1042,6 +1055,9 @@ public inline fun CharSequence.foldRight(initial: R, operation: (Char, acc: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each character with its index in the original char sequence and current accumulator value. + * + * Returns the specified [initial] value if the char sequence is empty. + * * @param [operation] function that takes the index of a character, the character itself * and current accumulator value, and calculates the next accumulator value. */ @@ -1207,7 +1223,14 @@ public inline fun S.onEachIndexed(action: (index: Int, Char) } /** - * Accumulates value starting with the first character and applying [operation] from left to right to current accumulator value and each character. + * Accumulates value starting with the first character and applying [operation] from left to right + * to current accumulator value and each character. + * + * Throws an exception if this char sequence is empty. If the char sequence can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and a character, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -1224,8 +1247,12 @@ public inline fun CharSequence.reduce(operation: (acc: Char, Char) -> Char): Cha /** * Accumulates value starting with the first character and applying [operation] from left to right * to current accumulator value and each character with its index in the original char sequence. - * @param [operation] function that takes the index of a character, current accumulator value - * and the character itself and calculates the next accumulator value. + * + * Throws an exception if this char sequence is empty. If the char sequence can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of a character, current accumulator value and the character itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -1242,9 +1269,11 @@ public inline fun CharSequence.reduceIndexed(operation: (index: Int, acc: Char, /** * Accumulates value starting with the first character and applying [operation] from left to right * to current accumulator value and each character with its index in the original char sequence. - * Returns null if the char sequence is empty. - * @param [operation] function that takes the index of a character, current accumulator value - * and the character itself and calculates the next accumulator value. + * + * Returns `null` if the char sequence is empty. + * + * @param [operation] function that takes the index of a character, current accumulator value and the character itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -1260,7 +1289,13 @@ public inline fun CharSequence.reduceIndexedOrNull(operation: (index: Int, acc: } /** - * Accumulates value starting with the first character and applying [operation] from left to right to current accumulator value and each character. Returns null if the char sequence is empty. + * Accumulates value starting with the first character and applying [operation] from left to right + * to current accumulator value and each character. + * + * Returns `null` if the char sequence is empty. + * + * @param [operation] function that takes current accumulator value and a character, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -1277,7 +1312,14 @@ public inline fun CharSequence.reduceOrNull(operation: (acc: Char, Char) -> Char } /** - * Accumulates value starting with last character and applying [operation] from right to left to each character and current accumulator value. + * Accumulates value starting with the last character and applying [operation] from right to left + * to each character and current accumulator value. + * + * Throws an exception if this char sequence is empty. If the char sequence can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes a character and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -1292,10 +1334,14 @@ public inline fun CharSequence.reduceRight(operation: (Char, acc: Char) -> Char) } /** - * Accumulates value starting with last character and applying [operation] from right to left + * Accumulates value starting with the last character and applying [operation] from right to left * to each character with its index in the original char sequence and current accumulator value. - * @param [operation] function that takes the index of a character, the character itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this char sequence is empty. If the char sequence can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of a character, the character itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -1311,11 +1357,13 @@ public inline fun CharSequence.reduceRightIndexed(operation: (index: Int, Char, } /** - * Accumulates value starting with last character and applying [operation] from right to left + * Accumulates value starting with the last character and applying [operation] from right to left * to each character with its index in the original char sequence and current accumulator value. - * Returns null if the char sequence is empty. - * @param [operation] function that takes the index of a character, the character itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the char sequence is empty. + * + * @param [operation] function that takes the index of a character, the character itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -1332,7 +1380,13 @@ public inline fun CharSequence.reduceRightIndexedOrNull(operation: (index: Int, } /** - * Accumulates value starting with last character and applying [operation] from right to left to each character and current accumulator value. Returns null if the char sequence is empty. + * Accumulates value starting with the last character and applying [operation] from right to left + * to each character and current accumulator value. + * + * Returns `null` if the char sequence is empty. + * + * @param [operation] function that takes a character and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ diff --git a/libraries/stdlib/common/src/generated/_UArrays.kt b/libraries/stdlib/common/src/generated/_UArrays.kt index 024f2205d98..1a82b386fef 100644 --- a/libraries/stdlib/common/src/generated/_UArrays.kt +++ b/libraries/stdlib/common/src/generated/_UArrays.kt @@ -5091,7 +5091,12 @@ public inline fun UShortArray.count(predicate: (UShort) -> Boolean): Int { } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5103,7 +5108,12 @@ public inline fun UIntArray.fold(initial: R, operation: (acc: R, UInt) -> R) } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5115,7 +5125,12 @@ public inline fun ULongArray.fold(initial: R, operation: (acc: R, ULong) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5127,7 +5142,12 @@ public inline fun UByteArray.fold(initial: R, operation: (acc: R, UByte) -> } /** - * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with [initial] value and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5141,6 +5161,9 @@ public inline fun UShortArray.fold(initial: R, operation: (acc: R, UShort) - /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -5157,6 +5180,9 @@ public inline fun UIntArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -5173,6 +5199,9 @@ public inline fun ULongArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -5189,6 +5218,9 @@ public inline fun UByteArray.foldIndexed(initial: R, operation: (index: Int, /** * Accumulates value starting with [initial] value and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, current accumulator value * and the element itself, and calculates the next accumulator value. */ @@ -5203,7 +5235,12 @@ public inline fun UShortArray.foldIndexed(initial: R, operation: (index: Int } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5218,7 +5255,12 @@ public inline fun UIntArray.foldRight(initial: R, operation: (UInt, acc: R) } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5233,7 +5275,12 @@ public inline fun ULongArray.foldRight(initial: R, operation: (ULong, acc: R } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5248,7 +5295,12 @@ public inline fun UByteArray.foldRight(initial: R, operation: (UByte, acc: R } /** - * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with [initial] value and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, and calculates the next accumulator value. */ @SinceKotlin("1.3") @ExperimentalUnsignedTypes @@ -5265,6 +5317,9 @@ public inline fun UShortArray.foldRight(initial: R, operation: (UShort, acc: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -5284,6 +5339,9 @@ public inline fun UIntArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -5303,6 +5361,9 @@ public inline fun ULongArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -5322,6 +5383,9 @@ public inline fun UByteArray.foldRightIndexed(initial: R, operation: (index: /** * Accumulates value starting with [initial] value and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. + * + * Returns the specified [initial] value if the array is empty. + * * @param [operation] function that takes the index of an element, the element itself * and current accumulator value, and calculates the next accumulator value. */ @@ -6063,7 +6127,14 @@ public inline fun UShortArray.onEachIndexed(action: (index: Int, UShort) -> Unit } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6081,7 +6152,14 @@ public inline fun UIntArray.reduce(operation: (acc: UInt, UInt) -> UInt): UInt { } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6099,7 +6177,14 @@ public inline fun ULongArray.reduce(operation: (acc: ULong, ULong) -> ULong): UL } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6117,7 +6202,14 @@ public inline fun UByteArray.reduce(operation: (acc: UByte, UByte) -> UByte): UB } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6137,8 +6229,12 @@ public inline fun UShortArray.reduce(operation: (acc: UShort, UShort) -> UShort) /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6158,8 +6254,12 @@ public inline fun UIntArray.reduceIndexed(operation: (index: Int, acc: UInt, UIn /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6179,8 +6279,12 @@ public inline fun ULongArray.reduceIndexed(operation: (index: Int, acc: ULong, U /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6200,8 +6304,12 @@ public inline fun UByteArray.reduceIndexed(operation: (index: Int, acc: UByte, U /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduce */ @@ -6221,9 +6329,11 @@ public inline fun UShortArray.reduceIndexed(operation: (index: Int, acc: UShort, /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6243,9 +6353,11 @@ public inline fun UIntArray.reduceIndexedOrNull(operation: (index: Int, acc: UIn /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6265,9 +6377,11 @@ public inline fun ULongArray.reduceIndexedOrNull(operation: (index: Int, acc: UL /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6287,9 +6401,11 @@ public inline fun UByteArray.reduceIndexedOrNull(operation: (index: Int, acc: UB /** * Accumulates value starting with the first element and applying [operation] from left to right * to current accumulator value and each element with its index in the original array. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, current accumulator value - * and the element itself and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, current accumulator value and the element itself, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6307,7 +6423,13 @@ public inline fun UShortArray.reduceIndexedOrNull(operation: (index: Int, acc: U } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6326,7 +6448,13 @@ public inline fun UIntArray.reduceOrNull(operation: (acc: UInt, UInt) -> UInt): } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6345,7 +6473,13 @@ public inline fun ULongArray.reduceOrNull(operation: (acc: ULong, ULong) -> ULon } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6364,7 +6498,13 @@ public inline fun UByteArray.reduceOrNull(operation: (acc: UByte, UByte) -> UByt } /** - * Accumulates value starting with the first element and applying [operation] from left to right to current accumulator value and each element. Returns null if the array is empty. + * Accumulates value starting with the first element and applying [operation] from left to right + * to current accumulator value and each element. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes current accumulator value and an element, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceOrNull */ @@ -6383,7 +6523,14 @@ public inline fun UShortArray.reduceOrNull(operation: (acc: UShort, UShort) -> U } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6401,7 +6548,14 @@ public inline fun UIntArray.reduceRight(operation: (UInt, acc: UInt) -> UInt): U } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6419,7 +6573,14 @@ public inline fun ULongArray.reduceRight(operation: (ULong, acc: ULong) -> ULong } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6437,7 +6598,14 @@ public inline fun UByteArray.reduceRight(operation: (UByte, acc: UByte) -> UByte } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6455,10 +6623,14 @@ public inline fun UShortArray.reduceRight(operation: (UShort, acc: UShort) -> US } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6477,10 +6649,14 @@ public inline fun UIntArray.reduceRightIndexed(operation: (index: Int, UInt, acc } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6499,10 +6675,14 @@ public inline fun ULongArray.reduceRightIndexed(operation: (index: Int, ULong, a } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6521,10 +6701,14 @@ public inline fun UByteArray.reduceRightIndexed(operation: (index: Int, UByte, a } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Throws an exception if this array is empty. If the array can be empty in an expected way, + * please use [reduceRightIndexedOrNull] instead. It returns `null` when its receiver is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRight */ @@ -6543,11 +6727,13 @@ public inline fun UShortArray.reduceRightIndexed(operation: (index: Int, UShort, } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6566,11 +6752,13 @@ public inline fun UIntArray.reduceRightIndexedOrNull(operation: (index: Int, UIn } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6589,11 +6777,13 @@ public inline fun ULongArray.reduceRightIndexedOrNull(operation: (index: Int, UL } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6612,11 +6802,13 @@ public inline fun UByteArray.reduceRightIndexedOrNull(operation: (index: Int, UB } /** - * Accumulates value starting with last element and applying [operation] from right to left + * Accumulates value starting with the last element and applying [operation] from right to left * to each element with its index in the original array and current accumulator value. - * Returns null if the array is empty. - * @param [operation] function that takes the index of an element, the element itself - * and current accumulator value, and calculates the next accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes the index of an element, the element itself and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6635,7 +6827,13 @@ public inline fun UShortArray.reduceRightIndexedOrNull(operation: (index: Int, U } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6654,7 +6852,13 @@ public inline fun UIntArray.reduceRightOrNull(operation: (UInt, acc: UInt) -> UI } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6673,7 +6877,13 @@ public inline fun ULongArray.reduceRightOrNull(operation: (ULong, acc: ULong) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ @@ -6692,7 +6902,13 @@ public inline fun UByteArray.reduceRightOrNull(operation: (UByte, acc: UByte) -> } /** - * Accumulates value starting with last element and applying [operation] from right to left to each element and current accumulator value. Returns null if the array is empty. + * Accumulates value starting with the last element and applying [operation] from right to left + * to each element and current accumulator value. + * + * Returns `null` if the array is empty. + * + * @param [operation] function that takes an element and current accumulator value, + * and calculates the next accumulator value. * * @sample samples.collections.Collections.Aggregates.reduceRightOrNull */ diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt index fa0d5654e9d..a85db01e23f 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Aggregates.kt @@ -5,7 +5,10 @@ package templates +import templates.DocExtensions.collection +import templates.DocExtensions.element import templates.DocExtensions.mapResult +import templates.DocExtensions.prefixWithArticle import templates.Family.* import templates.SequenceClass.* @@ -521,6 +524,9 @@ object Aggregates : TemplateGroupBase() { """ Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each ${f.element} with its index in the original ${f.collection}. + + Returns the specified [initial] value if the ${f.collection} is empty. + @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, current accumulator value and the ${f.element} itself, and calculates the next accumulator value. """ @@ -548,6 +554,9 @@ object Aggregates : TemplateGroupBase() { """ Accumulates value starting with [initial] value and applying [operation] from right to left to each ${f.element} with its index in the original ${f.collection} and current accumulator value. + + Returns the specified [initial] value if the ${f.collection} is empty. + @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, the ${f.element} itself and current accumulator value, and calculates the next accumulator value. """ @@ -588,7 +597,16 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each ${f.element}." } + doc { + """ + Accumulates value starting with [initial] value and applying [operation] from left to right + to current accumulator value and each ${f.element}. + + Returns the specified [initial] value if the ${f.collection} is empty. + + @param [operation] function that takes current accumulator value and ${f.element.prefixWithArticle()}, and calculates the next accumulator value. + """ + } typeParam("R") returns("R") body { @@ -606,7 +624,16 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with [initial] value and applying [operation] from right to left to each ${f.element} and current accumulator value." } + doc { + """ + Accumulates value starting with [initial] value and applying [operation] from right to left + to each ${f.element} and current accumulator value. + + Returns the specified [initial] value if the ${f.collection} is empty. + + @param [operation] function that takes ${f.element.prefixWithArticle()} and current accumulator value, and calculates the next accumulator value. + """ + } typeParam("R") returns("R") body { @@ -633,20 +660,47 @@ object Aggregates : TemplateGroupBase() { } } + private fun MemberBuilder.reduceDoc(fName: String): String { + fun summaryDoc(isLeftToRight: Boolean, isIndexed: Boolean): String { + val acc = "current accumulator value" + val element = if (isIndexed) "each ${f.element} with its index in the original ${f.collection}" else "each ${f.element}" + val start = if (isLeftToRight) "first" else "last" + val iteration = if (isLeftToRight) "left to right\nto $acc and $element" else "right to left\nto $element and $acc" + return """ + Accumulates value starting with the $start ${f.element} and applying [operation] from $iteration.""" + } + + fun paramDoc(isLeftToRight: Boolean, isIndexed: Boolean): String { + val acc = "current accumulator value" + val element = if (isIndexed) "the ${f.element} itself" else f.element.prefixWithArticle() + val index = if (isIndexed) "the index of ${f.element.prefixWithArticle()}, " else "" + return """ + @param [operation] function that takes $index${if (isLeftToRight) "$acc and $element" else "$element and $acc"}, + and calculates the next accumulator value.""" + } + + fun emptyNote(isThrowing: Boolean): String = if (isThrowing) """ + Throws an exception if this ${f.collection} is empty. If the ${f.collection} can be empty in an expected way, + please use [${fName}OrNull] instead. It returns `null` when its receiver is empty.""" + else """ + Returns `null` if the ${f.collection} is empty.""" + + val isLeftToRight = fName.contains("Right").not() + val isIndexed = fName.contains("Indexed") + val isThrowing = fName.contains("OrNull").not() + return """ + ${summaryDoc(isLeftToRight, isIndexed)} + ${emptyNote(isThrowing)} + ${paramDoc(isLeftToRight, isIndexed)}""" + } + val f_reduceIndexed = fn("reduceIndexed(operation: (index: Int, acc: T, T) -> T)") { include(ArraysOfPrimitives, ArraysOfUnsigned, CharSequences) } builder { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { - """ - Accumulates value starting with the first ${f.element} and applying [operation] from left to right - to current accumulator value and each ${f.element} with its index in the original ${f.collection}. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, current accumulator value - and the ${f.element} itself and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceIndexed") } sample("samples.collections.Collections.Aggregates.reduce") returns("T") body { @@ -668,14 +722,7 @@ object Aggregates : TemplateGroupBase() { } builder { inline() - doc { - """ - Accumulates value starting with the first ${f.element} and applying [operation] from left to right - to current accumulator value and each ${f.element} with its index in the original ${f.collection}. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, current accumulator value - and the ${f.element} itself and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceIndexed") } typeParam("S") typeParam("T : S") sample("samples.collections.Collections.Aggregates.reduce") @@ -715,15 +762,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { - """ - Accumulates value starting with the first ${f.element} and applying [operation] from left to right - to current accumulator value and each ${f.element} with its index in the original ${f.collection}. - Returns null if the ${f.collection} is empty. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, current accumulator value - and the ${f.element} itself and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceIndexedOrNull") } sample("samples.collections.Collections.Aggregates.reduceOrNull") returns("T?") body { @@ -746,15 +785,7 @@ object Aggregates : TemplateGroupBase() { since("1.4") inline() - doc { - """ - Accumulates value starting with the first ${f.element} and applying [operation] from left to right - to current accumulator value and each ${f.element} with its index in the original ${f.collection}. - Returns null if the ${f.collection} is empty. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, current accumulator value - and the ${f.element} itself and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceIndexedOrNull") } typeParam("S") typeParam("T : S") sample("samples.collections.Collections.Aggregates.reduceOrNull") @@ -793,14 +824,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { - """ - Accumulates value starting with last ${f.element} and applying [operation] from right to left - to each ${f.element} with its index in the original ${f.collection} and current accumulator value. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, the ${f.element} itself - and current accumulator value, and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceRightIndexed") } sample("samples.collections.Collections.Aggregates.reduceRight") returns("T") body { @@ -824,14 +848,7 @@ object Aggregates : TemplateGroupBase() { } builder { inline() - doc { - """ - Accumulates value starting with last ${f.element} and applying [operation] from right to left - to each ${f.element} with its index in the original ${f.collection} and current accumulator value. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, the ${f.element} itself - and current accumulator value, and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceRightIndexed") } sample("samples.collections.Collections.Aggregates.reduceRight") typeParam("S") typeParam("T : S") @@ -874,15 +891,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { - """ - Accumulates value starting with last ${f.element} and applying [operation] from right to left - to each ${f.element} with its index in the original ${f.collection} and current accumulator value. - Returns null if the ${f.collection} is empty. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, the ${f.element} itself - and current accumulator value, and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceRightIndexedOrNull") } sample("samples.collections.Collections.Aggregates.reduceRightOrNull") returns("T?") body { @@ -907,15 +916,7 @@ object Aggregates : TemplateGroupBase() { since("1.4") inline() - doc { - """ - Accumulates value starting with last ${f.element} and applying [operation] from right to left - to each ${f.element} with its index in the original ${f.collection} and current accumulator value. - Returns null if the ${f.collection} is empty. - @param [operation] function that takes the index of ${f.element.prefixWithArticle()}, the ${f.element} itself - and current accumulator value, and calculates the next accumulator value. - """ - } + doc { reduceDoc("reduceRightIndexedOrNull") } sample("samples.collections.Collections.Aggregates.reduceRightOrNull") typeParam("S") typeParam("T : S") @@ -957,7 +958,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}." } + doc { reduceDoc("reduce") } sample("samples.collections.Collections.Aggregates.reduce") returns("T") body { @@ -979,7 +980,7 @@ object Aggregates : TemplateGroupBase() { } builder { inline() - doc { "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}." } + doc { reduceDoc("reduce") } sample("samples.collections.Collections.Aggregates.reduce") typeParam("S") typeParam("T : S") @@ -1018,7 +1019,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}. Returns null if the ${f.collection} is empty." } + doc { reduceDoc("reduceOrNull") } sample("samples.collections.Collections.Aggregates.reduceOrNull") returns("T?") body { @@ -1042,7 +1043,7 @@ object Aggregates : TemplateGroupBase() { annotation("@ExperimentalStdlibApi") inline() - doc { "Accumulates value starting with the first ${f.element} and applying [operation] from left to right to current accumulator value and each ${f.element}. Returns null if the ${f.collection} is empty." } + doc { reduceDoc("reduceOrNull") } sample("samples.collections.Collections.Aggregates.reduceOrNull") typeParam("S") typeParam("T : S") @@ -1079,7 +1080,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value." } + doc { reduceDoc("reduceRight") } sample("samples.collections.Collections.Aggregates.reduceRight") returns("T") body { @@ -1101,7 +1102,7 @@ object Aggregates : TemplateGroupBase() { include(Lists, ArraysOfObjects) } builder { inline() - doc { "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value." } + doc { reduceDoc("reduceRight") } sample("samples.collections.Collections.Aggregates.reduceRight") typeParam("S") typeParam("T : S") @@ -1143,7 +1144,7 @@ object Aggregates : TemplateGroupBase() { inline() specialFor(ArraysOfUnsigned) { inlineOnly() } - doc { "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value. Returns null if the ${f.collection} is empty." } + doc { reduceDoc("reduceRightOrNull") } sample("samples.collections.Collections.Aggregates.reduceRightOrNull") returns("T?") body { @@ -1167,7 +1168,7 @@ object Aggregates : TemplateGroupBase() { since("1.3") annotation("@ExperimentalStdlibApi") inline() - doc { "Accumulates value starting with last ${f.element} and applying [operation] from right to left to each ${f.element} and current accumulator value. Returns null if the ${f.collection} is empty." } + doc { reduceDoc("reduceRightOrNull") } sample("samples.collections.Collections.Aggregates.reduceRightOrNull") typeParam("S") typeParam("T : S")