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
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 {