azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document the nature of natural order KT-54168

Browse Source
This commit is contained in:
Ilya Gorbunov
2022-11-24 21:56:41 +01:00
committed by Space Team
parent 0d0cc9250b
commit 7dd907342e
1 changed files with 9 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/comparisons/Comparisons.kt
+9 -1
View File
@@ -1,5 +1,5 @@
/* /*
* Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors. * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
*/ */
@file:kotlin.jvm.JvmName("ComparisonsKt") @file:kotlin.jvm.JvmName("ComparisonsKt")
@@ -225,6 +225,7 @@ public infix fun <T> Comparator<T>.thenDescending(comparator: Comparator<in T>):
/** /**
* Extends the given [comparator] of non-nullable values to a comparator of nullable values * Extends the given [comparator] of non-nullable values to a comparator of nullable values
* considering `null` value less than any other value. * considering `null` value less than any other value.
* Non-null values are compared with the provided [comparator].
* *
* @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator
*/ */
@@ -241,6 +242,7 @@ public fun <T : Any> nullsFirst(comparator: Comparator<in T>): Comparator<T?> =
/** /**
* Provides a comparator of nullable [Comparable] values * Provides a comparator of nullable [Comparable] values
* considering `null` value less than any other value. * considering `null` value less than any other value.
* Non-null values are compared according to their [natural order][naturalOrder].
* *
* @sample samples.comparisons.Comparisons.nullsFirstLastComparator * @sample samples.comparisons.Comparisons.nullsFirstLastComparator
*/ */
@@ -250,6 +252,7 @@ public inline fun <T : Comparable<T>> nullsFirst(): Comparator<T?> = nullsFirst(
/** /**
* Extends the given [comparator] of non-nullable values to a comparator of nullable values * Extends the given [comparator] of non-nullable values to a comparator of nullable values
* considering `null` value greater than any other value. * considering `null` value greater than any other value.
* Non-null values are compared with the provided [comparator].
* *
* @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator
*/ */
@@ -266,6 +269,7 @@ public fun <T : Any> nullsLast(comparator: Comparator<in T>): Comparator<T?> =
/** /**
* Provides a comparator of nullable [Comparable] values * Provides a comparator of nullable [Comparable] values
* considering `null` value greater than any other value. * considering `null` value greater than any other value.
* Non-null values are compared according to their [natural order][naturalOrder].
* *
* @sample samples.comparisons.Comparisons.nullsFirstLastComparator * @sample samples.comparisons.Comparisons.nullsFirstLastComparator
*/ */
@@ -275,6 +279,8 @@ public inline fun <T : Comparable<T>> nullsLast(): Comparator<T?> = nullsLast(na
/** /**
* Returns a comparator that compares [Comparable] objects in natural order. * Returns a comparator that compares [Comparable] objects in natural order.
* *
* The natural order of a `Comparable` type here means the order established by its `compareTo` function.
*
* @sample samples.comparisons.Comparisons.naturalOrderComparator * @sample samples.comparisons.Comparisons.naturalOrderComparator
*/ */
public fun <T : Comparable<T>> naturalOrder(): Comparator<T> = @Suppress("UNCHECKED_CAST") (NaturalOrderComparator as Comparator<T>) public fun <T : Comparable<T>> naturalOrder(): Comparator<T> = @Suppress("UNCHECKED_CAST") (NaturalOrderComparator as Comparator<T>)
@@ -282,6 +288,8 @@ public fun <T : Comparable<T>> naturalOrder(): Comparator<T> = @Suppress("UNCHEC
/** /**
* Returns a comparator that compares [Comparable] objects in reversed natural order. * Returns a comparator that compares [Comparable] objects in reversed natural order.
* *
* The natural order of a `Comparable` type here means the order established by its `compareTo` function.
*
* @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator * @sample samples.comparisons.Comparisons.nullsFirstLastWithComparator
*/ */
public fun <T : Comparable<T>> reverseOrder(): Comparator<T> = @Suppress("UNCHECKED_CAST") (ReverseOrderComparator as Comparator<T>) public fun <T : Comparable<T>> reverseOrder(): Comparator<T> = @Suppress("UNCHECKED_CAST") (ReverseOrderComparator as Comparator<T>)