From 9456cd0f5da9fcf55edc5787d08908b9ecccc3c6 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Thu, 21 Oct 2021 05:10:15 +0300 Subject: [PATCH] Improve Duration docs - Document overflow situation in general - Document possible rounding in operations involving Double - Update kotlin.time package description --- libraries/stdlib/src/Module.md | 2 +- libraries/stdlib/src/kotlin/time/Duration.kt | 27 +++++++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/libraries/stdlib/src/Module.md b/libraries/stdlib/src/Module.md index 78a1202ce0d..259e7a2ef44 100644 --- a/libraries/stdlib/src/Module.md +++ b/libraries/stdlib/src/Module.md @@ -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 diff --git a/libraries/stdlib/src/kotlin/time/Duration.kt b/libraries/stdlib/src/kotlin/time/Duration.kt index 2348449525a..b6233651bfc 100644 --- a/libraries/stdlib/src/kotlin/time/Duration.kt +++ b/libraries/stdlib/src/kotlin/time/Duration.kt @@ -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")