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

Improve Duration docs

Browse Source 
- Document overflow situation in general
- Document possible rounding in operations involving Double
- Update kotlin.time package description
This commit is contained in:
Ilya Gorbunov
2021-10-21 05:10:15 +03:00
committed by Space
parent e9c8135dfa
commit 9456cd0f5d
2 changed files with 27 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/Module.md
+1 -1
View File
@@ -141,7 +141,7 @@ Functions for working with text and regular expressions.
# Package kotlin.time
Experimental API for representing [Duration][kotlin.time.Duration] values and measuring time intervals.
API for representing [Duration][kotlin.time.Duration] values and experimental API for measuring time intervals.
# Package org.khronos.webgl
libraries/stdlib/src/kotlin/time/Duration.kt
+26 -1
View File
@@ -13,10 +13,13 @@ import kotlin.math.*
* Represents the amount of time one instant of time is away from another instant.
*
* A negative duration is possible in a situation when the second instant is earlier than the first one.
* An infinite duration value [Duration.INFINITE] can be used to represent infinite timeouts.
*
* The type can store duration values up to ±146 years with nanosecond precision,
* and up to ±146 million years with millisecond precision.
* If a duration-returning operation provided in `kotlin.time` produces a duration value that doesn't fit into the above range,
* the returned `Duration` is infinite.
*
* An infinite duration value [Duration.INFINITE] can be used to represent infinite timeouts.
*
* To construct a duration use either the extension function [toDuration],
* or the extension properties [hours], [minutes], [seconds], and so on,
@@ -74,6 +77,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of nanoseconds.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -91,6 +96,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of microseconds.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -108,6 +115,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of milliseconds.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -125,6 +134,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of seconds.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -142,6 +153,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of minutes.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -159,6 +172,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of hours.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -176,6 +191,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a [Duration] equal to this [Double] number of days.
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this [Double] value is `NaN`.
*/
@kotlin.internal.InlineOnly
@@ -531,6 +548,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns a duration whose value is this duration value multiplied by the given [scale] number.
*
* The operation may involve rounding when the result cannot be represented exactly with a [Double] number.
*
* @throws IllegalArgumentException if the operation results in an undefined value for the given arguments,
* e.g. when multiplying an infinite duration by zero.
*/
@@ -717,6 +736,8 @@ public value class Duration internal constructor(private val rawValue: Long) : C
/**
* Returns the value of this duration expressed as a [Double] number of the specified [unit].
*
* The operation may involve rounding when the result cannot be represented exactly with a [Double] number.
*
* An infinite duration value is converted either to [Double.POSITIVE_INFINITY] or [Double.NEGATIVE_INFINITY] depending on its sign.
*/
public fun toDouble(unit: DurationUnit): Double {
@@ -1068,6 +1089,8 @@ public fun Long.toDuration(unit: DurationUnit): Duration {
/**
* Returns a [Duration] equal to this [Double] number of the specified [unit].
*
* Depending on its magnitude, the value is rounded to an integer number of nanoseconds or milliseconds.
*
* @throws IllegalArgumentException if this `Double` value is `NaN`.
*/
@SinceKotlin("1.6")
@@ -1278,6 +1301,8 @@ public inline operator fun Int.times(duration: Duration): Duration = duration *
/**
* Returns a duration whose value is the specified [duration] value multiplied by this number.
*
* The operation may involve rounding when the result cannot be represented exactly with a [Double] number.
*
* @throws IllegalArgumentException if the operation results in a `NaN` value.
*/
@SinceKotlin("1.6")