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

Improve math docs

Browse Source 
Add links from log to ln, log2, log10.
Format lists in docs so that they are pretty in quick doc window.
This commit is contained in:
Ilya Gorbunov
2017-10-06 23:00:32 +03:00
parent 873994545c
commit aab604d154
3 changed files with 506 additions and 548 deletions
Download Patch File Download Diff File Expand all files Collapse all files
js/js.libraries/src/core/math.kt
+167 -181
View File
@@ -34,7 +34,6 @@ public const val E: Double = 2.718281828459045
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -44,7 +43,6 @@ public inline fun sin(a: Double): Double = nativeMath.sin(a)
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -54,7 +52,6 @@ public inline fun cos(a: Double): Double = nativeMath.cos(a)
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -88,7 +85,7 @@ public inline fun acos(a: Double): Double = nativeMath.acos(a)
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -100,15 +97,15 @@ public inline fun atan(a: Double): Double = nativeMath.atan(a)
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -118,10 +115,9 @@ public inline fun atan2(y: Double, x: Double): Double = nativeMath.atan2(y, x)
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -131,9 +127,8 @@ public inline fun sinh(a: Double): Double = nativeMath.sinh(a)
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -143,10 +138,9 @@ public inline fun cosh(a: Double): Double = nativeMath.cosh(a)
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -158,10 +152,9 @@ public inline fun tanh(a: Double): Double = nativeMath.tanh(a)
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -173,10 +166,9 @@ public inline fun asinh(a: Double): Double = nativeMath.asinh(a)
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -188,11 +180,10 @@ public inline fun acosh(a: Double): Double = nativeMath.acosh(a)
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -202,8 +193,8 @@ public inline fun atanh(a: Double): Double = nativeMath.atanh(a)
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -213,7 +204,7 @@ public inline fun hypot(x: Double, y: Double): Double = nativeMath.hypot(x, y)
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -223,9 +214,9 @@ public inline fun sqrt(a: Double): Double = nativeMath.sqrt(a)
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -237,9 +228,9 @@ public inline fun exp(a: Double): Double = nativeMath.exp(a)
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -251,11 +242,13 @@ public inline fun expm1(a: Double): Double = nativeMath.expm1(a)
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public fun log(a: Double, base: Double): Double {
@@ -267,10 +260,10 @@ public fun log(a: Double, base: Double): Double {
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -300,10 +293,10 @@ public inline fun log2(a: Double): Double = nativeMath.log2(a)
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -318,7 +311,7 @@ public inline fun ln1p(a: Double): Double = nativeMath.log1p(a)
* @return the smallest double value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -330,7 +323,7 @@ public inline fun ceil(a: Double): Double = nativeMath.ceil(a).unsafeCast<Double
* @return the largest double value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -342,7 +335,7 @@ public inline fun floor(a: Double): Double = nativeMath.floor(a).unsafeCast<Doub
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -352,7 +345,7 @@ public inline fun truncate(a: Double): Double = nativeMath.trunc(a)
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public fun round(a: Double): Double {
@@ -367,7 +360,7 @@ public fun round(a: Double): Double {
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Double]
*/
@@ -377,12 +370,12 @@ public inline fun abs(a: Double): Double = nativeMath.abs(a)
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -412,12 +405,12 @@ public inline fun max(a: Double, b: Double): Double = nativeMath.max(a, b)
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -436,7 +429,7 @@ public inline fun Double.pow(other: Int): Double = nativeMath.pow(this, other.to
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -446,12 +439,12 @@ public inline val Double.absoluteValue: Double get() = nativeMath.abs(this)
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -482,9 +475,9 @@ public inline fun Double.withSign(sign: Int): Double = this.withSign(sign.toDoub
* An ulp is a positive distance between this value and the next nearest [Double] value larger in magnitude.
*
* Special Cases:
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
*/
@SinceKotlin("1.2")
public val Double.ulp: Double get() = when {
@@ -519,8 +512,8 @@ public fun Double.nextDown(): Double = when {
* Returns the [Double] value nearest to this value in direction from this value towards the value [to].
*
* Special cases:
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
*
*/
@SinceKotlin("1.2")
@@ -537,8 +530,8 @@ public fun Double.nextTowards(to: Double): Double = when {
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -555,8 +548,8 @@ public fun Double.roundToInt(): Int = when {
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -576,7 +569,6 @@ public fun Double.roundToLong(): Long = when {
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -586,7 +578,6 @@ public inline fun sin(a: Float): Float = nativeMath.sin(a.toDouble()).toFloat()
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -596,7 +587,6 @@ public inline fun cos(a: Float): Float = nativeMath.cos(a.toDouble()).toFloat()
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -630,7 +620,7 @@ public inline fun acos(a: Float): Float = nativeMath.acos(a.toDouble()).toFloat(
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -642,15 +632,15 @@ public inline fun atan(a: Float): Float = nativeMath.atan(a.toDouble()).toFloat(
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -660,10 +650,9 @@ public inline fun atan2(y: Float, x: Float): Float = nativeMath.atan2(y.toDouble
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -673,9 +662,8 @@ public inline fun sinh(a: Float): Float = nativeMath.sinh(a.toDouble()).toFloat(
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -685,10 +673,9 @@ public inline fun cosh(a: Float): Float = nativeMath.cosh(a.toDouble()).toFloat(
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -700,10 +687,9 @@ public inline fun tanh(a: Float): Float = nativeMath.tanh(a.toDouble()).toFloat(
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -715,10 +701,9 @@ public inline fun asinh(a: Float): Float = nativeMath.asinh(a.toDouble()).toFloa
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -730,11 +715,10 @@ public inline fun acosh(a: Float): Float = nativeMath.acosh(a.toDouble()).toFloa
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -744,8 +728,8 @@ public inline fun atanh(a: Float): Float = nativeMath.atanh(a.toDouble()).toFloa
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -755,7 +739,7 @@ public inline fun hypot(x: Float, y: Float): Float = nativeMath.hypot(x.toDouble
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -765,9 +749,9 @@ public inline fun sqrt(a: Float): Float = nativeMath.sqrt(a.toDouble()).toFloat(
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -779,9 +763,9 @@ public inline fun exp(a: Float): Float = nativeMath.exp(a.toDouble()).toFloat()
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -793,11 +777,13 @@ public inline fun expm1(a: Float): Float = nativeMath.expm1(a.toDouble()).toFloa
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -807,10 +793,10 @@ public inline fun log(a: Float, base: Float): Float = log(a.toDouble(), base.toD
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -840,10 +826,10 @@ public inline fun log2(a: Float): Float = nativeMath.log2(a.toDouble()).toFloat(
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -858,7 +844,7 @@ public inline fun ln1p(a: Float): Float = nativeMath.log1p(a.toDouble()).toFloat
* @return the smallest Float value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -870,7 +856,7 @@ public inline fun ceil(a: Float): Float = nativeMath.ceil(a.toDouble()).toFloat(
* @return the largest Float value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -882,7 +868,7 @@ public inline fun floor(a: Float): Float = nativeMath.floor(a.toDouble()).toFloa
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -892,7 +878,7 @@ public inline fun truncate(a: Float): Float = truncate(a.toDouble()).toFloat()
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -903,7 +889,7 @@ public inline fun round(a: Float): Float = round(a.toDouble()).toFloat()
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Float]
*/
@@ -913,12 +899,12 @@ public inline fun abs(a: Float): Float = nativeMath.abs(a.toDouble()).toFloat()
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -950,12 +936,12 @@ public inline fun max(a: Float, b: Float): Float = nativeMath.max(a, b)
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -974,7 +960,7 @@ public inline fun Float.pow(other: Int): Float = nativeMath.pow(this.toDouble(),
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -984,12 +970,12 @@ public inline val Float.absoluteValue: Float get() = nativeMath.abs(this.toDoubl
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -1016,8 +1002,8 @@ public inline fun Float.withSign(sign: Int): Float = this.toDouble().withSign(si
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -1030,8 +1016,8 @@ public inline fun Float.roundToInt(): Int = toDouble().roundToInt()
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -1046,7 +1032,7 @@ public inline fun Float.roundToLong(): Long = toDouble().roundToLong()
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Int]
*/
@@ -1072,7 +1058,7 @@ public inline fun max(a: Int, b: Int): Int = maxOf(a, b)
* Returns the absolute value of this value.
*
* Special cases:
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -1082,9 +1068,9 @@ public inline val Int.absoluteValue: Int get() = abs(this)
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public val Int.sign: Int get() = when {
@@ -1099,7 +1085,7 @@ public val Int.sign: Int get() = when {
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Long]
*/
@@ -1124,7 +1110,7 @@ public inline fun max(a: Long, b: Long): Long = maxOf(a, b)
* Returns the absolute value of this value.
*
* Special cases:
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -1134,9 +1120,9 @@ public inline val Long.absoluteValue: Long get() = abs(this)
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public val Long.sign: Int get() = when {
libraries/stdlib/common/src/kotlin/MathH.kt
+167 -181
View File
@@ -32,7 +32,6 @@ public const val E: Double = 2.718281828459045
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -41,7 +40,6 @@ public expect fun sin(a: Double): Double
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -50,7 +48,6 @@ public expect fun cos(a: Double): Double
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -81,7 +78,7 @@ public expect fun acos(a: Double): Double
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun atan(a: Double): Double
@@ -92,15 +89,15 @@ public expect fun atan(a: Double): Double
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun atan2(y: Double, x: Double): Double
@@ -109,10 +106,9 @@ public expect fun atan2(y: Double, x: Double): Double
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun sinh(a: Double): Double
@@ -121,9 +117,8 @@ public expect fun sinh(a: Double): Double
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
public expect fun cosh(a: Double): Double
@@ -132,10 +127,9 @@ public expect fun cosh(a: Double): Double
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
public expect fun tanh(a: Double): Double
@@ -146,10 +140,9 @@ public expect fun tanh(a: Double): Double
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun asinh(a: Double): Double
@@ -160,10 +153,9 @@ public expect fun asinh(a: Double): Double
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
public expect fun acosh(a: Double): Double
@@ -174,11 +166,10 @@ public expect fun acosh(a: Double): Double
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun atanh(a: Double): Double
@@ -187,8 +178,8 @@ public expect fun atanh(a: Double): Double
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
public expect fun hypot(x: Double, y: Double): Double
@@ -197,7 +188,7 @@ public expect fun hypot(x: Double, y: Double): Double
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun sqrt(a: Double): Double
@@ -206,9 +197,9 @@ public expect fun sqrt(a: Double): Double
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
public expect fun exp(a: Double): Double
@@ -219,9 +210,9 @@ public expect fun exp(a: Double): Double
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -232,11 +223,13 @@ public expect fun expm1(a: Double): Double
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public expect fun log(a: Double, base: Double): Double
@@ -245,10 +238,10 @@ public expect fun log(a: Double, base: Double): Double
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun ln(a: Double): Double
@@ -275,10 +268,10 @@ public expect fun log2(a: Double): Double
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -292,7 +285,7 @@ public expect fun ln1p(a: Double): Double
* @return the smallest double value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun ceil(a: Double): Double
@@ -303,7 +296,7 @@ public expect fun ceil(a: Double): Double
* @return the largest double value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun floor(a: Double): Double
@@ -314,7 +307,7 @@ public expect fun floor(a: Double): Double
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun truncate(a: Double): Double
@@ -323,7 +316,7 @@ public expect fun truncate(a: Double): Double
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun round(a: Double): Double
@@ -332,7 +325,7 @@ public expect fun round(a: Double): Double
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Double]
*/
@@ -341,12 +334,12 @@ public expect fun abs(a: Double): Double
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun sign(a: Double): Double
@@ -373,12 +366,12 @@ public expect fun max(a: Double, b: Double): Double
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
public expect fun Double.pow(other: Double): Double
@@ -395,7 +388,7 @@ public expect fun Double.pow(other: Int): Double
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -404,12 +397,12 @@ public expect val Double.absoluteValue: Double
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
public expect val Double.sign: Double
@@ -434,9 +427,9 @@ public expect fun Double.withSign(sign: Int): Double
* An ulp is a positive distance between this value and the next nearest [Double] value larger in magnitude.
*
* Special Cases:
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
*/
@SinceKotlin("1.2")
public expect val Double.ulp: Double
@@ -456,8 +449,8 @@ public expect fun Double.nextDown(): Double
* Returns the [Double] value nearest to this value in direction from this value towards the value [to].
*
* Special cases:
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
*
*/
@SinceKotlin("1.2")
@@ -468,8 +461,8 @@ public expect fun Double.nextTowards(to: Double): Double
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -481,8 +474,8 @@ public expect fun Double.roundToInt(): Int
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -497,7 +490,6 @@ public expect fun Double.roundToLong(): Long
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -506,7 +498,6 @@ public expect fun sin(a: Float): Float
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -515,7 +506,6 @@ public expect fun cos(a: Float): Float
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -546,7 +536,7 @@ public expect fun acos(a: Float): Float
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun atan(a: Float): Float
@@ -557,15 +547,15 @@ public expect fun atan(a: Float): Float
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun atan2(y: Float, x: Float): Float
@@ -574,10 +564,9 @@ public expect fun atan2(y: Float, x: Float): Float
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun sinh(a: Float): Float
@@ -586,9 +575,8 @@ public expect fun sinh(a: Float): Float
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
public expect fun cosh(a: Float): Float
@@ -597,10 +585,9 @@ public expect fun cosh(a: Float): Float
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
public expect fun tanh(a: Float): Float
@@ -611,10 +598,9 @@ public expect fun tanh(a: Float): Float
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun asinh(a: Float): Float
@@ -625,10 +611,9 @@ public expect fun asinh(a: Float): Float
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
public expect fun acosh(a: Float): Float
@@ -639,11 +624,10 @@ public expect fun acosh(a: Float): Float
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun atanh(a: Float): Float
@@ -652,8 +636,8 @@ public expect fun atanh(a: Float): Float
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
public expect fun hypot(x: Float, y: Float): Float
@@ -662,7 +646,7 @@ public expect fun hypot(x: Float, y: Float): Float
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun sqrt(a: Float): Float
@@ -671,9 +655,9 @@ public expect fun sqrt(a: Float): Float
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
public expect fun exp(a: Float): Float
@@ -684,9 +668,9 @@ public expect fun exp(a: Float): Float
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -697,11 +681,13 @@ public expect fun expm1(a: Float): Float
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public expect fun log(a: Float, base: Float): Float
@@ -710,10 +696,10 @@ public expect fun log(a: Float, base: Float): Float
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
public expect fun ln(a: Float): Float
@@ -740,10 +726,10 @@ public expect fun log2(a: Float): Float
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -757,7 +743,7 @@ public expect fun ln1p(a: Float): Float
* @return the smallest Float value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun ceil(a: Float): Float
@@ -768,7 +754,7 @@ public expect fun ceil(a: Float): Float
* @return the largest Float value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun floor(a: Float): Float
@@ -779,7 +765,7 @@ public expect fun floor(a: Float): Float
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun truncate(a: Float): Float
@@ -788,7 +774,7 @@ public expect fun truncate(a: Float): Float
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public expect fun round(a: Float): Float
@@ -798,7 +784,7 @@ public expect fun round(a: Float): Float
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Float]
*/
@@ -807,12 +793,12 @@ public expect fun abs(a: Float): Float
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
public expect fun sign(a: Float): Float
@@ -841,12 +827,12 @@ public expect fun max(a: Float, b: Float): Float
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
public expect fun Float.pow(other: Float): Float
@@ -863,7 +849,7 @@ public expect fun Float.pow(other: Int): Float
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -872,12 +858,12 @@ public expect val Float.absoluteValue: Float
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
public expect val Float.sign: Float
@@ -901,8 +887,8 @@ public expect fun Float.withSign(sign: Int): Float
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -914,8 +900,8 @@ public expect fun Float.roundToInt(): Int
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -929,7 +915,7 @@ public expect fun Float.roundToLong(): Long
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Int]
*/
@@ -952,7 +938,7 @@ public expect fun max(a: Int, b: Int): Int
* Returns the absolute value of this value.
*
* Special cases:
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -961,9 +947,9 @@ public expect val Int.absoluteValue: Int
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public expect val Int.sign: Int
@@ -974,7 +960,7 @@ public expect val Int.sign: Int
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Long]
*/
@@ -997,7 +983,7 @@ public expect fun max(a: Long, b: Long): Long
* Returns the absolute value of this value.
*
* Special cases:
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -1006,9 +992,9 @@ public expect val Long.absoluteValue: Long
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public expect val Long.sign: Int
libraries/stdlib/src/kotlin/util/MathJVM.kt
+172 -186
View File
@@ -43,7 +43,6 @@ private val upper_taylor_n_bound = 1 / taylor_n_bound
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -53,7 +52,6 @@ public inline fun sin(a: Double): Double = nativeMath.sin(a)
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -63,7 +61,6 @@ public inline fun cos(a: Double): Double = nativeMath.cos(a)
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -97,7 +94,7 @@ public inline fun acos(a: Double): Double = nativeMath.acos(a)
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -109,15 +106,15 @@ public inline fun atan(a: Double): Double = nativeMath.atan(a)
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -127,10 +124,9 @@ public inline fun atan2(y: Double, x: Double): Double = nativeMath.atan2(y, x)
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -140,9 +136,8 @@ public inline fun sinh(a: Double): Double = nativeMath.sinh(a)
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -152,10 +147,9 @@ public inline fun cosh(a: Double): Double = nativeMath.cosh(a)
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -171,10 +165,9 @@ public inline fun tanh(a: Double): Double = nativeMath.tanh(a)
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
public fun asinh(a: Double): Double =
@@ -210,10 +203,9 @@ public fun asinh(a: Double): Double =
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
public fun acosh(a: Double): Double =
@@ -246,11 +238,10 @@ public fun acosh(a: Double): Double =
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
public fun atanh(x: Double): Double {
@@ -268,8 +259,8 @@ public fun atanh(x: Double): Double {
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -279,7 +270,7 @@ public inline fun hypot(x: Double, y: Double): Double = nativeMath.hypot(x, y)
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -289,9 +280,9 @@ public inline fun sqrt(a: Double): Double = nativeMath.sqrt(a)
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -303,9 +294,9 @@ public inline fun exp(a: Double): Double = nativeMath.exp(a)
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -317,11 +308,13 @@ public inline fun expm1(a: Double): Double = nativeMath.expm1(a)
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public fun log(a: Double, base: Double): Double {
@@ -333,10 +326,10 @@ public fun log(a: Double, base: Double): Double {
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -365,10 +358,10 @@ public fun log2(a: Double): Double = nativeMath.log(a) / LN2
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -383,7 +376,7 @@ public inline fun ln1p(a: Double): Double = nativeMath.log1p(a)
* @return the smallest double value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -395,7 +388,7 @@ public inline fun ceil(a: Double): Double = nativeMath.ceil(a)
* @return the largest double value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -407,7 +400,7 @@ public inline fun floor(a: Double): Double = nativeMath.floor(a)
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public fun truncate(a: Double): Double = when {
@@ -420,7 +413,7 @@ public fun truncate(a: Double): Double = when {
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -431,7 +424,7 @@ public inline fun round(a: Double): Double = nativeMath.rint(a)
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Double]
*/
@@ -441,12 +434,12 @@ public inline fun abs(a: Double): Double = nativeMath.abs(a)
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -478,12 +471,12 @@ public inline fun max(a: Double, b: Double): Double = nativeMath.max(a, b)
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -518,7 +511,7 @@ public inline fun Double.IEEErem(other: Double): Double = nativeMath.IEEEremaind
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -528,12 +521,12 @@ public inline val Double.absoluteValue: Double get() = nativeMath.abs(this)
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -560,9 +553,9 @@ public inline fun Double.withSign(sign: Int): Double = nativeMath.copySign(this,
* An ulp is a positive distance between this value and the next nearest [Double] value larger in magnitude.
*
* Special Cases:
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Double.MIN_VALUE`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -585,8 +578,8 @@ public inline fun Double.nextDown(): Double = nativeMath.nextAfter(this, Double.
* Returns the [Double] value nearest to this value in direction from this value towards the value [to].
*
* Special cases:
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
*
*/
@SinceKotlin("1.2")
@@ -598,8 +591,8 @@ public inline fun Double.nextTowards(to: Double): Double = nativeMath.nextAfter(
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -616,8 +609,8 @@ public fun Double.roundToInt(): Int = when {
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -631,7 +624,6 @@ public fun Double.roundToLong(): Long = if (isNaN()) throw IllegalArgumentExcept
/** Computes the sine of the angle [a] given in radians.
*
* Special cases:
*
* - `sin(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -641,7 +633,6 @@ public inline fun sin(a: Float): Float = nativeMath.sin(a.toDouble()).toFloat()
/** Computes the cosine of the angle [a] given in radians.
*
* Special cases:
*
* - `cos(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -651,7 +642,6 @@ public inline fun cos(a: Float): Float = nativeMath.cos(a.toDouble()).toFloat()
/** Computes the tangent of the angle [a] given in radians.
*
* Special cases:
*
* - `tan(NaN|+Inf|-Inf)` is `NaN`
*/
@SinceKotlin("1.2")
@@ -685,7 +675,7 @@ public inline fun acos(a: Float): Float = nativeMath.acos(a.toDouble()).toFloat(
* the returned value is an angle in the range from `-PI/2` to `PI/2` radians.
*
* Special cases:
* - `atan(NaN)` is `NaN`
* - `atan(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -697,15 +687,15 @@ public inline fun atan(a: Float): Float = nativeMath.atan(a.toDouble()).toFloat(
* the returned value is an angle in the range from `-PI` to `PI` radians.
*
* Special cases:
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
* - `atan2(0.0, 0.0)` is `0.0`
* - `atan2(0.0, x)` is `0.0` for `x > 0` and `PI` for `x < 0`
* - `atan2(-0.0, x)` is `-0.0` for 'x > 0` and `-PI` for `x < 0`
* - `atan2(y, +Inf)` is `0.0` for `0 < y < +Inf` and `-0.0` for '-Inf < y < 0`
* - `atan2(y, -Inf)` is `PI` for `0 < y < +Inf` and `-PI` for `-Inf < y < 0`
* - `atan2(y, 0.0)` is `PI/2` for `y > 0` and `-PI/2` for `y < 0`
* - `atan2(+Inf, x)` is `PI/2` for finite `x`y
* - `atan2(-Inf, x)` is `-PI/2` for finite `x`
* - `atan2(NaN, x)` and `atan2(y, NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -715,10 +705,9 @@ public inline fun atan2(y: Float, x: Float): Float = nativeMath.atan2(y.toDouble
* Computes the hyperbolic sine of the value [a].
*
* Special cases:
*
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
* - `sinh(NaN)` is `NaN`
* - `sinh(+Inf)` is `+Inf`
* - `sinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -728,9 +717,8 @@ public inline fun sinh(a: Float): Float = nativeMath.sinh(a.toDouble()).toFloat(
* Computes the hyperbolic cosine of the value [a].
*
* Special cases:
*
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
* - `cosh(NaN)` is `NaN`
* - `cosh(+Inf|-Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -740,10 +728,9 @@ public inline fun cosh(a: Float): Float = nativeMath.cosh(a.toDouble()).toFloat(
* Computes the hyperbolic tangent of the value [a].
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
* - `tanh(NaN)` is `NaN`
* - `tanh(+Inf)` is `1.0`
* - `tanh(-Inf)` is `-1.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -755,10 +742,9 @@ public inline fun tanh(a: Float): Float = nativeMath.tanh(a.toDouble()).toFloat(
* The returned value is `x` such that `sinh(x) == a`.
*
* Special cases:
*
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
* - `asinh(NaN)` is `NaN`
* - `asinh(+Inf)` is `+Inf`
* - `asinh(-Inf)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -770,10 +756,9 @@ public inline fun asinh(a: Float): Float = asinh(a.toDouble()).toFloat()
* The returned value is positive `x` such that `cosh(x) == a`.
*
* Special cases:
*
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
* - `acosh(NaN)` is `NaN`
* - `acosh(x)` is `NaN` when `x < 1`
* - `acosh(+Inf)` is `+Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -785,11 +770,10 @@ public inline fun acosh(a: Float): Float = acosh(a.toDouble()).toFloat()
* The returned value is `x` such that `tanh(x) == a`.
*
* Special cases:
*
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
* - `tanh(NaN)` is `NaN`
* - `tanh(x)` is `NaN` when `x > 1` or `x < -1`
* - `tanh(1.0)` is `+Inf`
* - `tanh(-1.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -799,8 +783,8 @@ public inline fun atanh(a: Float): Float = atanh(a.toDouble()).toFloat()
* Computes `sqrt(x^2 + y^2)` without intermediate overflow or underflow.
*
* Special cases:
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
* - returns `+Inf` if any of arguments is infinite
* - returns `NaN` if any of arguments is `NaN` and the other is not infinite
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -810,7 +794,7 @@ public inline fun hypot(x: Float, y: Float): Float = nativeMath.hypot(x.toDouble
* Computes the positive square root of the value [a].
*
* Special cases:
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
* - `sqrt(x)` is `NaN` when `x < 0` or `x` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -820,9 +804,9 @@ public inline fun sqrt(a: Float): Float = nativeMath.sqrt(a.toDouble()).toFloat(
* Computes Euler's number `e` raised to the power of the value [a].
*
* Special cases:
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
* - `exp(NaN)` is `NaN`
* - `exp(+Inf)` is `+Inf`
* - `exp(-Inf)` is `0.0`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -834,9 +818,9 @@ public inline fun exp(a: Float): Float = nativeMath.exp(a.toDouble()).toFloat()
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
* - `expm1(NaN)` is `NaN`
* - `expm1(+Inf)` is `+Inf`
* - `expm1(-Inf)` is `-1.0`
*
* @see [exp] function.
*/
@@ -848,11 +832,13 @@ public inline fun expm1(a: Float): Float = nativeMath.expm1(a.toDouble()).toFloa
* Computes the logarithm of the value [a] to the given [base].
*
* Special cases:
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
* - `log(a, b)` is `NaN` if either `a` or `b` are `NaN`
* - `log(a, b)` is `NaN` when `a < 0` or `b <= 0` or `b == 1.0`
* - `log(+Inf, +Inf)` is `NaN`
* - `log(+Inf, b)` is `+Inf` for `b > 1` and `-Inf` for `b < 1`
* - `log(0.0, b)` is `-Inf` for `b > 1` and `+Inf` for `b > 1`
*
* See also logarithm functions for common fixed bases: [ln], [log10] and [log2].
*/
@SinceKotlin("1.2")
public fun log(a: Float, base: Float): Float {
@@ -864,10 +850,10 @@ public fun log(a: Float, base: Float): Float {
* Computes the natural logarithm (base `E`) of the value [a].
*
* Special cases:
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
* - `ln(NaN)` is `NaN`
* - `ln(x)` is `NaN` when `x < 0.0`
* - `ln(+Inf)` is `+Inf`
* - `ln(0.0)` is `-Inf`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -896,10 +882,10 @@ public fun log2(a: Float): Float = (nativeMath.log(a.toDouble()) / LN2).toFloat(
* This function can be implemented to produce more precise result for [a] near zero.
*
* Special cases:
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
* - `ln1p(NaN)` is `NaN`
* - `ln1p(x)` is `NaN` where `x < -1.0`
* - `ln1p(-1.0)` is `-Inf`
* - `ln1p(+Inf)` is `+Inf`
*
* @see [ln] function
* @see [expm1] function
@@ -914,7 +900,7 @@ public inline fun ln1p(a: Float): Float = nativeMath.log1p(a.toDouble()).toFloat
* @return the smallest Float value that is greater than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `ceil(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -926,7 +912,7 @@ public inline fun ceil(a: Float): Float = nativeMath.ceil(a.toDouble()).toFloat(
* @return the largest Float value that is smaller than the given value [a] and is a mathematical integer.
*
* Special cases:
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `floor(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -938,7 +924,7 @@ public inline fun floor(a: Float): Float = nativeMath.floor(a.toDouble()).toFloa
* @return the value [a] having its fractional part truncated.
*
* Special cases:
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `truncate(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
public fun truncate(a: Float): Float = when {
@@ -951,7 +937,7 @@ public fun truncate(a: Float): Float = when {
* Rounds the given value [a] towards the closest integer with ties rounded towards even integer.
*
* Special cases:
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
* - `round(x)` is `x` where `x` is `NaN` or `+Inf` or `-Inf` or already a mathematical integer.
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -962,7 +948,7 @@ public inline fun round(a: Float): Float = nativeMath.rint(a.toDouble()).toFloat
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(NaN)` is `NaN`
* - `abs(NaN)` is `NaN`
*
* @see absoluteValue extension property for [Float]
*/
@@ -972,12 +958,12 @@ public inline fun abs(a: Float): Float = nativeMath.abs(a)
/**
* Returns the sign of the given value [a]:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `sign(NaN)` is `NaN`
* - `sign(NaN)` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -1009,12 +995,12 @@ public inline fun max(a: Float, b: Float): Float = nativeMath.max(a, b)
* Raises this value to the power [other].
*
* Special cases:
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
* - `x.pow(0.0)` is `1.0`
* - `x.pow(1.0) == x`
* - `x.pow(NaN)` is `NaN`
* - `NaN.pow(x)` is `NaN` for `x != 0.0`
* - `x.pow(Inf)` is `NaN` for `abs(x) == 1.0`
* - `x.pow(y)` is `NaN` for `x < 0` and `y` is finite and not an integer
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -1049,7 +1035,7 @@ public inline fun Float.IEEErem(other: Float): Float = nativeMath.IEEEremainder(
* Returns the absolute value of this value.
*
* Special cases:
* - `NaN.absoluteValue` is `NaN`
* - `NaN.absoluteValue` is `NaN`
*
* @see abs function
*/
@@ -1059,12 +1045,12 @@ public inline val Float.absoluteValue: Float get() = nativeMath.abs(this)
/**
* Returns the sign of this value:
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
* - `-1.0` if the value is negative,
* - zero if the value is zero,
* - `1.0` if the value is positive
*
* Special case:
* - `NaN.sign` is `NaN`
* - `NaN.sign` is `NaN`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -1091,9 +1077,9 @@ public inline fun Float.withSign(sign: Int): Float = nativeMath.copySign(this, s
* An ulp is a positive distance between this value and the next nearest [Float] value larger in magnitude.
*
* Special Cases:
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Float.NIN_VALUE`
* - `NaN.ulp` is `NaN`
* - `x.ulp` is `+Inf` when `x` is `+Inf` or `-Inf`
* - `0.0.ulp` is `Float.NIN_VALUE`
*/
@SinceKotlin("1.2")
@InlineOnly
@@ -1116,8 +1102,8 @@ public inline fun Float.nextDown(): Float = nativeMath.nextAfter(this, Double.NE
* Returns the [Float] value nearest to this value in direction from this value towards the value [to].
*
* Special cases:
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
* - `x.nextTowards(y)` is `NaN` if either `x` or `y` are `NaN`
* - `x.nextTowards(x) == x`
*
*/
@SinceKotlin("1.2")
@@ -1129,8 +1115,8 @@ public inline fun Float.nextTowards(to: Float): Float = nativeMath.nextAfter(thi
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
* - `x.roundToInt() == Int.MAX_VALUE` when `x > Int.MAX_VALUE`
* - `x.roundToInt() == Int.MIN_VALUE` when `x < Int.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -1142,8 +1128,8 @@ public fun Float.roundToInt(): Int = if (isNaN()) throw IllegalArgumentException
* Ties are rounded towards positive infinity.
*
* Special cases:
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
* - `x.roundToLong() == Long.MAX_VALUE` when `x > Long.MAX_VALUE`
* - `x.roundToLong() == Long.MIN_VALUE` when `x < Long.MIN_VALUE`
*
* @throws IllegalArgumentException when this value is `NaN`
*/
@@ -1158,7 +1144,7 @@ public fun Float.roundToLong(): Long = toDouble().roundToLong()
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
* - `abs(Int.MIN_VALUE)` is `Int.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Int]
*/
@@ -1184,7 +1170,7 @@ public inline fun max(a: Int, b: Int): Int = nativeMath.max(a, b)
* Returns the absolute value of this value.
*
* Special cases:
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
* - `Int.MIN_VALUE.absoluteValue` is `Int.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -1194,9 +1180,9 @@ public inline val Int.absoluteValue: Int get() = nativeMath.abs(this)
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public val Int.sign: Int get() = when {
@@ -1211,7 +1197,7 @@ public val Int.sign: Int get() = when {
* Returns the absolute value of the given value [a].
*
* Special cases:
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
* - `abs(Long.MIN_VALUE)` is `Long.MIN_VALUE` due to an overflow
*
* @see absoluteValue extension property for [Long]
*/
@@ -1237,7 +1223,7 @@ public inline fun max(a: Long, b: Long): Long = nativeMath.max(a, b)
* Returns the absolute value of this value.
*
* Special cases:
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
* - `Long.MIN_VALUE.absoluteValue` is `Long.MIN_VALUE` due to an overflow
*
* @see abs function
*/
@@ -1247,9 +1233,9 @@ public inline val Long.absoluteValue: Long get() = nativeMath.abs(this)
/**
* Returns the sign of this value:
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
* - `-1` if the value is negative,
* - `0` if the value is zero,
* - `1` if the value is positive
*/
@SinceKotlin("1.2")
public val Long.sign: Int get() = when {