Skip to content

Commit 9cb1738

Browse files
Abduqodiri QurbonzodaSpace Team
Abduqodiri Qurbonzoda
authored and
Space Team
committed
Improve docs of max() and min() functions on collections #KT-36863
Also for: * maxOf() and minOf() * maxOfWith() and minOfWith() Specify which element is returned from the functions if multiple elements are equally maximal or minimal. Add samples.
1 parent 1995883 commit 9cb1738

File tree

8 files changed

+1433
-217
lines changed

8 files changed

+1433
-217
lines changed

‎libraries/stdlib/common/src/generated/_Arrays.kt‎

Lines changed: 628 additions & 108 deletions
Large diffs are not rendered by default.

‎libraries/stdlib/common/src/generated/_Collections.kt‎

Lines changed: 102 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1876,9 +1876,11 @@ public inline fun <T> Iterable<T>.forEachIndexed(action: (index: Int, T) -> Unit
18761876
/**
18771877
* Returns the largest element.
18781878
*
1879-
* If any of elements is `NaN` returns `NaN`.
1879+
* If any of elements is `NaN`, this function returns `NaN`.
18801880
*
18811881
* @throws NoSuchElementException if the collection is empty.
1882+
*
1883+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
18821884
*/
18831885
@SinceKotlin("1.7")
18841886
@kotlin.jvm.JvmName("maxOrThrow")
@@ -1897,9 +1899,11 @@ public fun Iterable<Double>.max(): Double {
18971899
/**
18981900
* Returns the largest element.
18991901
*
1900-
* If any of elements is `NaN` returns `NaN`.
1902+
* If any of elements is `NaN`, this function returns `NaN`.
19011903
*
19021904
* @throws NoSuchElementException if the collection is empty.
1905+
*
1906+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
19031907
*/
19041908
@SinceKotlin("1.7")
19051909
@kotlin.jvm.JvmName("maxOrThrow")
@@ -1918,7 +1922,11 @@ public fun Iterable<Float>.max(): Float {
19181922
/**
19191923
* Returns the largest element.
19201924
*
1925+
* If there are multiple equal maximal elements, this function returns the first of those elements.
1926+
*
19211927
* @throws NoSuchElementException if the collection is empty.
1928+
*
1929+
* @sample samples.collections.Collections.Aggregates.maxMinGeneric
19221930
*/
19231931
@SinceKotlin("1.7")
19241932
@kotlin.jvm.JvmName("maxOrThrow")
@@ -1991,6 +1999,8 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.maxByOrNull(selector: (T) -
19911999
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
19922000
*
19932001
* @throws NoSuchElementException if the collection is empty.
2002+
*
2003+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
19942004
*/
19952005
@SinceKotlin("1.4")
19962006
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2014,6 +2024,8 @@ public inline fun <T> Iterable<T>.maxOf(selector: (T) -> Double): Double {
20142024
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
20152025
*
20162026
* @throws NoSuchElementException if the collection is empty.
2027+
*
2028+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
20172029
*/
20182030
@SinceKotlin("1.4")
20192031
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2034,7 +2046,11 @@ public inline fun <T> Iterable<T>.maxOf(selector: (T) -> Float): Float {
20342046
* Returns the largest value among all values produced by [selector] function
20352047
* applied to each element in the collection.
20362048
*
2049+
* If multiple elements produce the maximal value, this function returns the first of those values.
2050+
*
20372051
* @throws NoSuchElementException if the collection is empty.
2052+
*
2053+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfGeneric
20382054
*/
20392055
@SinceKotlin("1.4")
20402056
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2055,9 +2071,11 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.maxOf(selector: (T) -> R):
20552071

20562072
/**
20572073
* Returns the largest value among all values produced by [selector] function
2058-
* applied to each element in the collection or `null` if there are no elements.
2074+
* applied to each element in the collection or `null` if the collection is empty.
20592075
*
20602076
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
2077+
*
2078+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
20612079
*/
20622080
@SinceKotlin("1.4")
20632081
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2076,9 +2094,11 @@ public inline fun <T> Iterable<T>.maxOfOrNull(selector: (T) -> Double): Double?
20762094

20772095
/**
20782096
* Returns the largest value among all values produced by [selector] function
2079-
* applied to each element in the collection or `null` if there are no elements.
2097+
* applied to each element in the collection or `null` if the collection is empty.
20802098
*
20812099
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
2100+
*
2101+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
20822102
*/
20832103
@SinceKotlin("1.4")
20842104
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2097,7 +2117,11 @@ public inline fun <T> Iterable<T>.maxOfOrNull(selector: (T) -> Float): Float? {
20972117

20982118
/**
20992119
* Returns the largest value among all values produced by [selector] function
2100-
* applied to each element in the collection or `null` if there are no elements.
2120+
* applied to each element in the collection or `null` if the collection is empty.
2121+
*
2122+
* If multiple elements produce the maximal value, this function returns the first of those values.
2123+
*
2124+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfGeneric
21012125
*/
21022126
@SinceKotlin("1.4")
21032127
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2120,7 +2144,11 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.maxOfOrNull(selector: (T) -
21202144
* Returns the largest value according to the provided [comparator]
21212145
* among all values produced by [selector] function applied to each element in the collection.
21222146
*
2147+
* If multiple elements produce the maximal value, this function returns the first of those values.
2148+
*
21232149
* @throws NoSuchElementException if the collection is empty.
2150+
*
2151+
* @sample samples.collections.Collections.Aggregates.maxOfWithMinOfWithGeneric
21242152
*/
21252153
@SinceKotlin("1.4")
21262154
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2141,7 +2169,11 @@ public inline fun <T, R> Iterable<T>.maxOfWith(comparator: Comparator<in R>, sel
21412169

21422170
/**
21432171
* Returns the largest value according to the provided [comparator]
2144-
* among all values produced by [selector] function applied to each element in the collection or `null` if there are no elements.
2172+
* among all values produced by [selector] function applied to each element in the collection or `null` if the collection is empty.
2173+
*
2174+
* If multiple elements produce the maximal value, this function returns the first of those values.
2175+
*
2176+
* @sample samples.collections.Collections.Aggregates.maxOfWithMinOfWithGeneric
21452177
*/
21462178
@SinceKotlin("1.4")
21472179
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2161,9 +2193,11 @@ public inline fun <T, R> Iterable<T>.maxOfWithOrNull(comparator: Comparator<in R
21612193
}
21622194

21632195
/**
2164-
* Returns the largest element or `null` if there are no elements.
2196+
* Returns the largest element or `null` if the collection is empty.
2197+
*
2198+
* If any of elements is `NaN`, this function returns `NaN`.
21652199
*
2166-
* If any of elements is `NaN` returns `NaN`.
2200+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
21672201
*/
21682202
@SinceKotlin("1.4")
21692203
public fun Iterable<Double>.maxOrNull(): Double? {
@@ -2178,9 +2212,11 @@ public fun Iterable<Double>.maxOrNull(): Double? {
21782212
}
21792213

21802214
/**
2181-
* Returns the largest element or `null` if there are no elements.
2215+
* Returns the largest element or `null` if the collection is empty.
2216+
*
2217+
* If any of elements is `NaN`, this function returns `NaN`.
21822218
*
2183-
* If any of elements is `NaN` returns `NaN`.
2219+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
21842220
*/
21852221
@SinceKotlin("1.4")
21862222
public fun Iterable<Float>.maxOrNull(): Float? {
@@ -2195,7 +2231,11 @@ public fun Iterable<Float>.maxOrNull(): Float? {
21952231
}
21962232

21972233
/**
2198-
* Returns the largest element or `null` if there are no elements.
2234+
* Returns the largest element or `null` if the collection is empty.
2235+
*
2236+
* If there are multiple equal maximal elements, this function returns the first of those elements.
2237+
*
2238+
* @sample samples.collections.Collections.Aggregates.maxMinGeneric
21992239
*/
22002240
@SinceKotlin("1.4")
22012241
public fun <T : Comparable<T>> Iterable<T>.maxOrNull(): T? {
@@ -2246,9 +2286,11 @@ public fun <T> Iterable<T>.maxWithOrNull(comparator: Comparator<in T>): T? {
22462286
/**
22472287
* Returns the smallest element.
22482288
*
2249-
* If any of elements is `NaN` returns `NaN`.
2289+
* If any of elements is `NaN`, this function returns `NaN`.
22502290
*
22512291
* @throws NoSuchElementException if the collection is empty.
2292+
*
2293+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
22522294
*/
22532295
@SinceKotlin("1.7")
22542296
@kotlin.jvm.JvmName("minOrThrow")
@@ -2267,9 +2309,11 @@ public fun Iterable<Double>.min(): Double {
22672309
/**
22682310
* Returns the smallest element.
22692311
*
2270-
* If any of elements is `NaN` returns `NaN`.
2312+
* If any of elements is `NaN`, this function returns `NaN`.
22712313
*
22722314
* @throws NoSuchElementException if the collection is empty.
2315+
*
2316+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
22732317
*/
22742318
@SinceKotlin("1.7")
22752319
@kotlin.jvm.JvmName("minOrThrow")
@@ -2288,7 +2332,11 @@ public fun Iterable<Float>.min(): Float {
22882332
/**
22892333
* Returns the smallest element.
22902334
*
2335+
* If there are multiple equal minimal elements, this function returns the first of those elements.
2336+
*
22912337
* @throws NoSuchElementException if the collection is empty.
2338+
*
2339+
* @sample samples.collections.Collections.Aggregates.maxMinGeneric
22922340
*/
22932341
@SinceKotlin("1.7")
22942342
@kotlin.jvm.JvmName("minOrThrow")
@@ -2361,6 +2409,8 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.minByOrNull(selector: (T) -
23612409
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
23622410
*
23632411
* @throws NoSuchElementException if the collection is empty.
2412+
*
2413+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
23642414
*/
23652415
@SinceKotlin("1.4")
23662416
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2384,6 +2434,8 @@ public inline fun <T> Iterable<T>.minOf(selector: (T) -> Double): Double {
23842434
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
23852435
*
23862436
* @throws NoSuchElementException if the collection is empty.
2437+
*
2438+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
23872439
*/
23882440
@SinceKotlin("1.4")
23892441
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2404,7 +2456,11 @@ public inline fun <T> Iterable<T>.minOf(selector: (T) -> Float): Float {
24042456
* Returns the smallest value among all values produced by [selector] function
24052457
* applied to each element in the collection.
24062458
*
2459+
* If multiple elements produce the minimal value, this function returns the first of those values.
2460+
*
24072461
* @throws NoSuchElementException if the collection is empty.
2462+
*
2463+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfGeneric
24082464
*/
24092465
@SinceKotlin("1.4")
24102466
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2425,9 +2481,11 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.minOf(selector: (T) -> R):
24252481

24262482
/**
24272483
* Returns the smallest value among all values produced by [selector] function
2428-
* applied to each element in the collection or `null` if there are no elements.
2484+
* applied to each element in the collection or `null` if the collection is empty.
24292485
*
24302486
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
2487+
*
2488+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
24312489
*/
24322490
@SinceKotlin("1.4")
24332491
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2446,9 +2504,11 @@ public inline fun <T> Iterable<T>.minOfOrNull(selector: (T) -> Double): Double?
24462504

24472505
/**
24482506
* Returns the smallest value among all values produced by [selector] function
2449-
* applied to each element in the collection or `null` if there are no elements.
2507+
* applied to each element in the collection or `null` if the collection is empty.
24502508
*
24512509
* If any of values produced by [selector] function is `NaN`, the returned result is `NaN`.
2510+
*
2511+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfFloatingResult
24522512
*/
24532513
@SinceKotlin("1.4")
24542514
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2467,7 +2527,11 @@ public inline fun <T> Iterable<T>.minOfOrNull(selector: (T) -> Float): Float? {
24672527

24682528
/**
24692529
* Returns the smallest value among all values produced by [selector] function
2470-
* applied to each element in the collection or `null` if there are no elements.
2530+
* applied to each element in the collection or `null` if the collection is empty.
2531+
*
2532+
* If multiple elements produce the minimal value, this function returns the first of those values.
2533+
*
2534+
* @sample samples.collections.Collections.Aggregates.maxOfMinOfGeneric
24712535
*/
24722536
@SinceKotlin("1.4")
24732537
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2490,7 +2554,11 @@ public inline fun <T, R : Comparable<R>> Iterable<T>.minOfOrNull(selector: (T) -
24902554
* Returns the smallest value according to the provided [comparator]
24912555
* among all values produced by [selector] function applied to each element in the collection.
24922556
*
2557+
* If multiple elements produce the minimal value, this function returns the first of those values.
2558+
*
24932559
* @throws NoSuchElementException if the collection is empty.
2560+
*
2561+
* @sample samples.collections.Collections.Aggregates.maxOfWithMinOfWithGeneric
24942562
*/
24952563
@SinceKotlin("1.4")
24962564
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2511,7 +2579,11 @@ public inline fun <T, R> Iterable<T>.minOfWith(comparator: Comparator<in R>, sel
25112579

25122580
/**
25132581
* Returns the smallest value according to the provided [comparator]
2514-
* among all values produced by [selector] function applied to each element in the collection or `null` if there are no elements.
2582+
* among all values produced by [selector] function applied to each element in the collection or `null` if the collection is empty.
2583+
*
2584+
* If multiple elements produce the minimal value, this function returns the first of those values.
2585+
*
2586+
* @sample samples.collections.Collections.Aggregates.maxOfWithMinOfWithGeneric
25152587
*/
25162588
@SinceKotlin("1.4")
25172589
@OptIn(kotlin.experimental.ExperimentalTypeInference::class)
@@ -2531,9 +2603,11 @@ public inline fun <T, R> Iterable<T>.minOfWithOrNull(comparator: Comparator<in R
25312603
}
25322604

25332605
/**
2534-
* Returns the smallest element or `null` if there are no elements.
2606+
* Returns the smallest element or `null` if the collection is empty.
2607+
*
2608+
* If any of elements is `NaN`, this function returns `NaN`.
25352609
*
2536-
* If any of elements is `NaN` returns `NaN`.
2610+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
25372611
*/
25382612
@SinceKotlin("1.4")
25392613
public fun Iterable<Double>.minOrNull(): Double? {
@@ -2548,9 +2622,11 @@ public fun Iterable<Double>.minOrNull(): Double? {
25482622
}
25492623

25502624
/**
2551-
* Returns the smallest element or `null` if there are no elements.
2625+
* Returns the smallest element or `null` if the collection is empty.
2626+
*
2627+
* If any of elements is `NaN`, this function returns `NaN`.
25522628
*
2553-
* If any of elements is `NaN` returns `NaN`.
2629+
* @sample samples.collections.Collections.Aggregates.maxMinFloating
25542630
*/
25552631
@SinceKotlin("1.4")
25562632
public fun Iterable<Float>.minOrNull(): Float? {
@@ -2565,7 +2641,11 @@ public fun Iterable<Float>.minOrNull(): Float? {
25652641
}
25662642

25672643
/**
2568-
* Returns the smallest element or `null` if there are no elements.
2644+
* Returns the smallest element or `null` if the collection is empty.
2645+
*
2646+
* If there are multiple equal minimal elements, this function returns the first of those elements.
2647+
*
2648+
* @sample samples.collections.Collections.Aggregates.maxMinGeneric
25692649
*/
25702650
@SinceKotlin("1.4")
25712651
public fun <T : Comparable<T>> Iterable<T>.minOrNull(): T? {

0 commit comments

Comments
 (0)