From e2c345544593caad1b8ecc4d4e0324033c511275 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Fri, 22 May 2020 16:01:47 +0300 Subject: [PATCH] Document NaN propagation in top-level minOf/maxOf functions --- .../common/src/generated/_Comparisons.kt | 76 ++++++++++--- .../common/src/generated/_UComparisons.kt | 16 +-- .../js-ir/src/generated/_ComparisonsJs.kt | 62 ++++++++--- .../stdlib/js/src/generated/_ComparisonsJs.kt | 62 ++++++++--- .../jvm/src/generated/_ComparisonsJvm.kt | 62 ++++++++--- .../src/templates/Comparables.kt | 104 +++++++++++------- 6 files changed, 276 insertions(+), 106 deletions(-) diff --git a/libraries/stdlib/common/src/generated/_Comparisons.kt b/libraries/stdlib/common/src/generated/_Comparisons.kt index a4d1963e2ad..1384fc0b29d 100644 --- a/libraries/stdlib/common/src/generated/_Comparisons.kt +++ b/libraries/stdlib/common/src/generated/_Comparisons.kt @@ -17,6 +17,7 @@ import kotlin.random.* /** * Returns the greater of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -52,6 +53,8 @@ public expect inline fun maxOf(a: Long, b: Long): Long /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -59,6 +62,8 @@ public expect inline fun maxOf(a: Float, b: Float): Float /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -66,6 +71,8 @@ public expect inline fun maxOf(a: Double, b: Double): Double /** * Returns the greater of three values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.1") public expect fun > maxOf(a: T, b: T, c: T): T @@ -100,6 +107,8 @@ public expect inline fun maxOf(a: Long, b: Long, c: Long): Long /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -107,6 +116,8 @@ public expect inline fun maxOf(a: Float, b: Float, c: Float): Float /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -114,6 +125,8 @@ public expect inline fun maxOf(a: Double, b: Double, c: Double): Double /** * Returns the greater of three values according to the order specified by the given [comparator]. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.1") public fun maxOf(a: T, b: T, c: T, comparator: Comparator): T { @@ -122,6 +135,7 @@ public fun maxOf(a: T, b: T, c: T, comparator: Comparator): T { /** * Returns the greater of two values according to the order specified by the given [comparator]. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -130,49 +144,57 @@ public fun maxOf(a: T, b: T, comparator: Comparator): T { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.4") public expect fun > maxOf(a: T, vararg other: T): T /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public expect fun maxOf(a: Byte, vararg other: Byte): Byte /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public expect fun maxOf(a: Short, vararg other: Short): Short /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public expect fun maxOf(a: Int, vararg other: Int): Int /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public expect fun maxOf(a: Long, vararg other: Long): Long /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public expect fun maxOf(a: Float, vararg other: Float): Float /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public expect fun maxOf(a: Double, vararg other: Double): Double /** - * Returns the greater of given values according to the order specified by the given [comparator]. + * Returns the greater of the given values according to the order specified by the given [comparator]. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.4") public fun maxOf(a: T, vararg other: T, comparator: Comparator): T { @@ -183,6 +205,7 @@ public fun maxOf(a: T, vararg other: T, comparator: Comparator): T { /** * Returns the smaller of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -218,6 +241,8 @@ public expect inline fun minOf(a: Long, b: Long): Long /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -225,6 +250,8 @@ public expect inline fun minOf(a: Float, b: Float): Float /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -232,6 +259,8 @@ public expect inline fun minOf(a: Double, b: Double): Double /** * Returns the smaller of three values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.1") public expect fun > minOf(a: T, b: T, c: T): T @@ -266,6 +295,8 @@ public expect inline fun minOf(a: Long, b: Long, c: Long): Long /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -273,6 +304,8 @@ public expect inline fun minOf(a: Float, b: Float, c: Float): Float /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -280,6 +313,8 @@ public expect inline fun minOf(a: Double, b: Double, c: Double): Double /** * Returns the smaller of three values according to the order specified by the given [comparator]. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.1") public fun minOf(a: T, b: T, c: T, comparator: Comparator): T { @@ -288,6 +323,7 @@ public fun minOf(a: T, b: T, c: T, comparator: Comparator): T { /** * Returns the smaller of two values according to the order specified by the given [comparator]. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -296,49 +332,57 @@ public fun minOf(a: T, b: T, comparator: Comparator): T { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.4") public expect fun > minOf(a: T, vararg other: T): T /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public expect fun minOf(a: Byte, vararg other: Byte): Byte /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public expect fun minOf(a: Short, vararg other: Short): Short /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public expect fun minOf(a: Int, vararg other: Int): Int /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public expect fun minOf(a: Long, vararg other: Long): Long /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public expect fun minOf(a: Float, vararg other: Float): Float /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public expect fun minOf(a: Double, vararg other: Double): Double /** - * Returns the smaller of given values according to the order specified by the given [comparator]. + * Returns the smaller of the given values according to the order specified by the given [comparator]. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.4") public fun minOf(a: T, vararg other: T, comparator: Comparator): T { diff --git a/libraries/stdlib/common/src/generated/_UComparisons.kt b/libraries/stdlib/common/src/generated/_UComparisons.kt index 008c73250e6..8344e0e21d9 100644 --- a/libraries/stdlib/common/src/generated/_UComparisons.kt +++ b/libraries/stdlib/common/src/generated/_UComparisons.kt @@ -92,7 +92,7 @@ public inline fun maxOf(a: UShort, b: UShort, c: UShort): UShort { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -103,7 +103,7 @@ public fun maxOf(a: UInt, vararg other: UInt): UInt { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -114,7 +114,7 @@ public fun maxOf(a: ULong, vararg other: ULong): ULong { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -125,7 +125,7 @@ public fun maxOf(a: UByte, vararg other: UByte): UByte { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -212,7 +212,7 @@ public inline fun minOf(a: UShort, b: UShort, c: UShort): UShort { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -223,7 +223,7 @@ public fun minOf(a: UInt, vararg other: UInt): UInt { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -234,7 +234,7 @@ public fun minOf(a: ULong, vararg other: ULong): ULong { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes @@ -245,7 +245,7 @@ public fun minOf(a: UByte, vararg other: UByte): UByte { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") @ExperimentalUnsignedTypes diff --git a/libraries/stdlib/js-ir/src/generated/_ComparisonsJs.kt b/libraries/stdlib/js-ir/src/generated/_ComparisonsJs.kt index 7cf47d44cd4..23e1846d40a 100644 --- a/libraries/stdlib/js-ir/src/generated/_ComparisonsJs.kt +++ b/libraries/stdlib/js-ir/src/generated/_ComparisonsJs.kt @@ -14,6 +14,7 @@ import kotlin.js.* /** * Returns the greater of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -62,6 +63,8 @@ public actual inline fun maxOf(a: Long, b: Long): Long { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -72,6 +75,8 @@ public actual inline fun maxOf(a: Float, b: Float): Float { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -82,6 +87,8 @@ public actual inline fun maxOf(a: Double, b: Double): Double { /** * Returns the greater of three values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > maxOf(a: T, b: T, c: T): T { @@ -129,6 +136,8 @@ public actual inline fun maxOf(a: Long, b: Long, c: Long): Long { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -139,6 +148,8 @@ public actual inline fun maxOf(a: Float, b: Float, c: Float): Float { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -148,7 +159,9 @@ public actual inline fun maxOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > maxOf(a: T, vararg other: T): T { @@ -158,7 +171,7 @@ public actual fun > maxOf(a: T, vararg other: T): T { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Byte, vararg other: Byte): Byte { @@ -168,7 +181,7 @@ public actual fun maxOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Short, vararg other: Short): Short { @@ -178,7 +191,7 @@ public actual fun maxOf(a: Short, vararg other: Short): Short { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Int, vararg other: Int): Int { @@ -188,7 +201,7 @@ public actual fun maxOf(a: Int, vararg other: Int): Int { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Long, vararg other: Long): Long { @@ -198,7 +211,9 @@ public actual fun maxOf(a: Long, vararg other: Long): Long { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Float, vararg other: Float): Float { @@ -208,7 +223,9 @@ public actual fun maxOf(a: Float, vararg other: Float): Float { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Double, vararg other: Double): Double { @@ -219,6 +236,7 @@ public actual fun maxOf(a: Double, vararg other: Double): Double { /** * Returns the smaller of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -267,6 +285,8 @@ public actual inline fun minOf(a: Long, b: Long): Long { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -277,6 +297,8 @@ public actual inline fun minOf(a: Float, b: Float): Float { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -287,6 +309,8 @@ public actual inline fun minOf(a: Double, b: Double): Double { /** * Returns the smaller of three values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > minOf(a: T, b: T, c: T): T { @@ -334,6 +358,8 @@ public actual inline fun minOf(a: Long, b: Long, c: Long): Long { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -344,6 +370,8 @@ public actual inline fun minOf(a: Float, b: Float, c: Float): Float { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -353,7 +381,9 @@ public actual inline fun minOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > minOf(a: T, vararg other: T): T { @@ -363,7 +393,7 @@ public actual fun > minOf(a: T, vararg other: T): T { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Byte, vararg other: Byte): Byte { @@ -373,7 +403,7 @@ public actual fun minOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Short, vararg other: Short): Short { @@ -383,7 +413,7 @@ public actual fun minOf(a: Short, vararg other: Short): Short { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Int, vararg other: Int): Int { @@ -393,7 +423,7 @@ public actual fun minOf(a: Int, vararg other: Int): Int { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Long, vararg other: Long): Long { @@ -403,7 +433,9 @@ public actual fun minOf(a: Long, vararg other: Long): Long { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Float, vararg other: Float): Float { @@ -413,7 +445,9 @@ public actual fun minOf(a: Float, vararg other: Float): Float { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Double, vararg other: Double): Double { diff --git a/libraries/stdlib/js/src/generated/_ComparisonsJs.kt b/libraries/stdlib/js/src/generated/_ComparisonsJs.kt index 7cf47d44cd4..23e1846d40a 100644 --- a/libraries/stdlib/js/src/generated/_ComparisonsJs.kt +++ b/libraries/stdlib/js/src/generated/_ComparisonsJs.kt @@ -14,6 +14,7 @@ import kotlin.js.* /** * Returns the greater of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -62,6 +63,8 @@ public actual inline fun maxOf(a: Long, b: Long): Long { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -72,6 +75,8 @@ public actual inline fun maxOf(a: Float, b: Float): Float { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -82,6 +87,8 @@ public actual inline fun maxOf(a: Double, b: Double): Double { /** * Returns the greater of three values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > maxOf(a: T, b: T, c: T): T { @@ -129,6 +136,8 @@ public actual inline fun maxOf(a: Long, b: Long, c: Long): Long { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -139,6 +148,8 @@ public actual inline fun maxOf(a: Float, b: Float, c: Float): Float { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -148,7 +159,9 @@ public actual inline fun maxOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > maxOf(a: T, vararg other: T): T { @@ -158,7 +171,7 @@ public actual fun > maxOf(a: T, vararg other: T): T { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Byte, vararg other: Byte): Byte { @@ -168,7 +181,7 @@ public actual fun maxOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Short, vararg other: Short): Short { @@ -178,7 +191,7 @@ public actual fun maxOf(a: Short, vararg other: Short): Short { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Int, vararg other: Int): Int { @@ -188,7 +201,7 @@ public actual fun maxOf(a: Int, vararg other: Int): Int { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Long, vararg other: Long): Long { @@ -198,7 +211,9 @@ public actual fun maxOf(a: Long, vararg other: Long): Long { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Float, vararg other: Float): Float { @@ -208,7 +223,9 @@ public actual fun maxOf(a: Float, vararg other: Float): Float { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Double, vararg other: Double): Double { @@ -219,6 +236,7 @@ public actual fun maxOf(a: Double, vararg other: Double): Double { /** * Returns the smaller of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -267,6 +285,8 @@ public actual inline fun minOf(a: Long, b: Long): Long { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -277,6 +297,8 @@ public actual inline fun minOf(a: Float, b: Float): Float { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -287,6 +309,8 @@ public actual inline fun minOf(a: Double, b: Double): Double { /** * Returns the smaller of three values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > minOf(a: T, b: T, c: T): T { @@ -334,6 +358,8 @@ public actual inline fun minOf(a: Long, b: Long, c: Long): Long { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -344,6 +370,8 @@ public actual inline fun minOf(a: Float, b: Float, c: Float): Float { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -353,7 +381,9 @@ public actual inline fun minOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > minOf(a: T, vararg other: T): T { @@ -363,7 +393,7 @@ public actual fun > minOf(a: T, vararg other: T): T { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Byte, vararg other: Byte): Byte { @@ -373,7 +403,7 @@ public actual fun minOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Short, vararg other: Short): Short { @@ -383,7 +413,7 @@ public actual fun minOf(a: Short, vararg other: Short): Short { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Int, vararg other: Int): Int { @@ -393,7 +423,7 @@ public actual fun minOf(a: Int, vararg other: Int): Int { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Long, vararg other: Long): Long { @@ -403,7 +433,9 @@ public actual fun minOf(a: Long, vararg other: Long): Long { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Float, vararg other: Float): Float { @@ -413,7 +445,9 @@ public actual fun minOf(a: Float, vararg other: Float): Float { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Double, vararg other: Double): Double { diff --git a/libraries/stdlib/jvm/src/generated/_ComparisonsJvm.kt b/libraries/stdlib/jvm/src/generated/_ComparisonsJvm.kt index 66823134b64..3556db5edc4 100644 --- a/libraries/stdlib/jvm/src/generated/_ComparisonsJvm.kt +++ b/libraries/stdlib/jvm/src/generated/_ComparisonsJvm.kt @@ -16,6 +16,7 @@ package kotlin.comparisons /** * Returns the greater of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -61,6 +62,8 @@ public actual inline fun maxOf(a: Long, b: Long): Long { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -70,6 +73,8 @@ public actual inline fun maxOf(a: Float, b: Float): Float { /** * Returns the greater of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -79,6 +84,8 @@ public actual inline fun maxOf(a: Double, b: Double): Double { /** * Returns the greater of three values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > maxOf(a: T, b: T, c: T): T { @@ -123,6 +130,8 @@ public actual inline fun maxOf(a: Long, b: Long, c: Long): Long { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -132,6 +141,8 @@ public actual inline fun maxOf(a: Float, b: Float, c: Float): Float { /** * Returns the greater of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -140,7 +151,9 @@ public actual inline fun maxOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If there are multiple equal maximal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > maxOf(a: T, vararg other: T): T { @@ -150,7 +163,7 @@ public actual fun > maxOf(a: T, vararg other: T): T { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Byte, vararg other: Byte): Byte { @@ -160,7 +173,7 @@ public actual fun maxOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Short, vararg other: Short): Short { @@ -170,7 +183,7 @@ public actual fun maxOf(a: Short, vararg other: Short): Short { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Int, vararg other: Int): Int { @@ -180,7 +193,7 @@ public actual fun maxOf(a: Int, vararg other: Int): Int { } /** - * Returns the greater of given values. + * Returns the greater of the given values. */ @SinceKotlin("1.4") public actual fun maxOf(a: Long, vararg other: Long): Long { @@ -190,7 +203,9 @@ public actual fun maxOf(a: Long, vararg other: Long): Long { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Float, vararg other: Float): Float { @@ -200,7 +215,9 @@ public actual fun maxOf(a: Float, vararg other: Float): Float { } /** - * Returns the greater of given values. + * Returns the greater of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun maxOf(a: Double, vararg other: Double): Double { @@ -211,6 +228,7 @@ public actual fun maxOf(a: Double, vararg other: Double): Double { /** * Returns the smaller of two values. + * * If values are equal, returns the first one. */ @SinceKotlin("1.1") @@ -256,6 +274,8 @@ public actual inline fun minOf(a: Long, b: Long): Long { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -265,6 +285,8 @@ public actual inline fun minOf(a: Float, b: Float): Float { /** * Returns the smaller of two values. + * + * If either value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -274,6 +296,8 @@ public actual inline fun minOf(a: Double, b: Double): Double { /** * Returns the smaller of three values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.1") public actual fun > minOf(a: T, b: T, c: T): T { @@ -318,6 +342,8 @@ public actual inline fun minOf(a: Long, b: Long, c: Long): Long { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -327,6 +353,8 @@ public actual inline fun minOf(a: Float, b: Float, c: Float): Float { /** * Returns the smaller of three values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.1") @kotlin.internal.InlineOnly @@ -335,7 +363,9 @@ public actual inline fun minOf(a: Double, b: Double, c: Double): Double { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If there are multiple equal minimal values, returns the first of them. */ @SinceKotlin("1.4") public actual fun > minOf(a: T, vararg other: T): T { @@ -345,7 +375,7 @@ public actual fun > minOf(a: T, vararg other: T): T { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Byte, vararg other: Byte): Byte { @@ -355,7 +385,7 @@ public actual fun minOf(a: Byte, vararg other: Byte): Byte { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Short, vararg other: Short): Short { @@ -365,7 +395,7 @@ public actual fun minOf(a: Short, vararg other: Short): Short { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Int, vararg other: Int): Int { @@ -375,7 +405,7 @@ public actual fun minOf(a: Int, vararg other: Int): Int { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. */ @SinceKotlin("1.4") public actual fun minOf(a: Long, vararg other: Long): Long { @@ -385,7 +415,9 @@ public actual fun minOf(a: Long, vararg other: Long): Long { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Float, vararg other: Float): Float { @@ -395,7 +427,9 @@ public actual fun minOf(a: Float, vararg other: Float): Float { } /** - * Returns the smaller of given values. + * Returns the smaller of the given values. + * + * If any value is `NaN`, returns `NaN`. */ @SinceKotlin("1.4") public actual fun minOf(a: Double, vararg other: Double): Double { diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt index a3f94169c3e..be2d157c56d 100644 --- a/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt +++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Comparables.kt @@ -1,5 +1,5 @@ /* - * Copyright 2010-2018 JetBrains s.r.o. and Kotlin Programming Language contributors. + * Copyright 2010-2020 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. */ @@ -161,19 +161,18 @@ object ComparableOps : TemplateGroupBase() { typeParam("T : Comparable") returns("T") receiver("") + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the smaller of two values. - If values are equal, returns the first one. - """ + val lines = listOfNotNull( + "Returns the smaller of two values.", + "", + "If values are equal, returns the first one.".takeIf { primitive == null }, + "If either value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } val defaultImpl = "if (a <= b) a else b" body { "return $defaultImpl" } - - specialFor(Primitives, Unsigned) { - doc { "Returns the smaller of two values." } - } - // TODO: Add a note about NaN propagation for floats. specialFor(Primitives) { inlineOnly() var convertBack = "to$primitive()" @@ -197,7 +196,7 @@ object ComparableOps : TemplateGroupBase() { body { "return minOf(a.toInt(), b.toInt()).$convertBack" } } } - if (primitive?.isFloatingPoint() == true) { + if (isFloat) { on(Platform.Native) { body { """ @@ -227,11 +226,15 @@ object ComparableOps : TemplateGroupBase() { returns("T") receiver("") specialFor(Primitives, Unsigned) { inlineOnly() } - // TODO: Add a note about NaN propagation for floats. + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the smaller of three values. - """ + val lines = listOfNotNull( + "Returns the smaller of three values.", + "", + "If there are multiple equal minimal values, returns the first of them.".takeIf { primitive == null }, + "If any value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } body { "return minOf(a, minOf(b, c))" @@ -269,11 +272,15 @@ object ComparableOps : TemplateGroupBase() { typeParam("T : Comparable") returns("T") receiver("") - // TODO: Add a note about NaN propagation for floats. + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the smaller of given values. - """ + val lines = listOfNotNull( + "Returns the smaller of the given values.", + "", + "If there are multiple equal minimal values, returns the first of them.".takeIf { primitive == null }, + "If any value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } body { """ @@ -297,6 +304,7 @@ object ComparableOps : TemplateGroupBase() { doc { """ Returns the smaller of two values according to the order specified by the given [comparator]. + If values are equal, returns the first one. """ } @@ -315,6 +323,8 @@ object ComparableOps : TemplateGroupBase() { doc { """ Returns the smaller of three values according to the order specified by the given [comparator]. + + If there are multiple equal minimal values, returns the first of them. """ } body { @@ -331,7 +341,9 @@ object ComparableOps : TemplateGroupBase() { receiver("") doc { """ - Returns the smaller of given values according to the order specified by the given [comparator]. + Returns the smaller of the given values according to the order specified by the given [comparator]. + + If there are multiple equal minimal values, returns the first of them. """ } body { @@ -353,19 +365,18 @@ object ComparableOps : TemplateGroupBase() { typeParam("T : Comparable") returns("T") receiver("") + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the greater of two values. - If values are equal, returns the first one. - """ + val lines = listOfNotNull( + "Returns the greater of two values.", + "", + "If values are equal, returns the first one.".takeIf { primitive == null }, + "If either value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } val defaultImpl = "if (a >= b) a else b" body { "return $defaultImpl" } - - specialFor(Primitives, Unsigned) { - doc { "Returns the greater of two values." } - } - // TODO: Add a note about NaN propagation for floats. specialFor(Primitives) { inlineOnly() var convertBack = "to$primitive()" @@ -389,7 +400,7 @@ object ComparableOps : TemplateGroupBase() { body { "return maxOf(a.toInt(), b.toInt()).$convertBack" } } } - if (primitive?.isFloatingPoint() == true) { + if (isFloat) { on(Platform.Native) { body { """ @@ -415,11 +426,15 @@ object ComparableOps : TemplateGroupBase() { returns("T") receiver("") specialFor(Primitives, Unsigned) { inlineOnly() } - // TODO: Add a note about NaN propagation for floats. + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the greater of three values. - """ + val lines = listOfNotNull( + "Returns the greater of three values.", + "", + "If there are multiple equal maximal values, returns the first of them.".takeIf { primitive == null }, + "If any value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } body { "return maxOf(a, maxOf(b, c))" @@ -457,11 +472,15 @@ object ComparableOps : TemplateGroupBase() { typeParam("T : Comparable") returns("T") receiver("") - // TODO: Add a note about NaN propagation for floats. + val isFloat = primitive?.isFloatingPoint() == true doc { - """ - Returns the greater of given values. - """ + val lines = listOfNotNull( + "Returns the greater of the given values.", + "", + "If there are multiple equal maximal values, returns the first of them.".takeIf { primitive == null }, + "If any value is `NaN`, returns `NaN`.".takeIf { isFloat } + ) + lines.joinToString("\n") } body { """ @@ -485,6 +504,7 @@ object ComparableOps : TemplateGroupBase() { doc { """ Returns the greater of two values according to the order specified by the given [comparator]. + If values are equal, returns the first one. """ } @@ -503,7 +523,9 @@ object ComparableOps : TemplateGroupBase() { doc { """ Returns the greater of three values according to the order specified by the given [comparator]. - """ + + If there are multiple equal maximal values, returns the first of them. + """ } body { "return maxOf(a, maxOf(b, c, comparator), comparator)" @@ -519,7 +541,9 @@ object ComparableOps : TemplateGroupBase() { receiver("") doc { """ - Returns the greater of given values according to the order specified by the given [comparator]. + Returns the greater of the given values according to the order specified by the given [comparator]. + + If there are multiple equal maximal values, returns the first of them. """ } body {