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

Suggest duration static factories instead of number extension properties

Browse Source 
Introduce Duration companion functions to convert numbers to Duration.
Deprecate number extension properties and propose to use these
new functions instead.
This commit is contained in:
Ilya Gorbunov
2021-02-12 04:22:43 +03:00
committed by ilya-g
parent ca99fc4fed
commit a7fda66fa1
12 changed files with 523 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/time/Duration.kt
+138 -4
View File
@@ -1,5 +1,5 @@
/*
* Copyright 2010-2020 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
*/
@@ -18,9 +18,9 @@ private inline val storageUnit get() = DurationUnit.NANOSECONDS
* 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.
*
* To construct a duration use either the extension function [toDuration],
* or the extension properties [hours], [minutes], [seconds], and so on,
* available on [Int], [Long], and [Double] numeric types.
* To construct a duration use either the extension function [toDuration] available on [Int], [Long], and [Double] numeric types,
* or the `Duration` companion object functions [Duration.hours], [Duration.minutes], [Duration.seconds], and so on,
* taking [Int], [Long], or [Double] numbers as parameters.
*
* To get the value of this duration expressed in a particular [duration units][DurationUnit]
* use the functions [toInt], [toLong], and [toDouble]
@@ -44,6 +44,119 @@ public value class Duration internal constructor(internal val value: Double) : C
/** Converts the given time duration [value] expressed in the specified [sourceUnit] into the specified [targetUnit]. */
public fun convert(value: Double, sourceUnit: DurationUnit, targetUnit: DurationUnit): Double =
convertDurationUnit(value, sourceUnit, targetUnit)
/** Returns a [Duration] representing the specified [value] number of nanoseconds. */
@SinceKotlin("1.5")
public fun nanoseconds(value: Int): Duration = value.toDuration(DurationUnit.NANOSECONDS)
/** Returns a [Duration] representing the specified [value] number of nanoseconds. */
@SinceKotlin("1.5")
public fun nanoseconds(value: Long): Duration = value.toDuration(DurationUnit.NANOSECONDS)
/**
* Returns a [Duration] representing the specified [value] number of nanoseconds.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun nanoseconds(value: Double): Duration = value.toDuration(DurationUnit.NANOSECONDS)
/** Returns a [Duration] representing the specified [value] number of microseconds. */
@SinceKotlin("1.5")
public fun microseconds(value: Int): Duration = value.toDuration(DurationUnit.MICROSECONDS)
/** Returns a [Duration] representing the specified [value] number of microseconds. */
@SinceKotlin("1.5")
public fun microseconds(value: Long): Duration = value.toDuration(DurationUnit.MICROSECONDS)
/**
* Returns a [Duration] representing the specified [value] number of microseconds.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun microseconds(value: Double): Duration = value.toDuration(DurationUnit.MICROSECONDS)
/** Returns a [Duration] representing the specified [value] number of milliseconds. */
@SinceKotlin("1.5")
public fun milliseconds(value: Int): Duration = value.toDuration(DurationUnit.MILLISECONDS)
/** Returns a [Duration] representing the specified [value] number of milliseconds. */
@SinceKotlin("1.5")
public fun milliseconds(value: Long): Duration = value.toDuration(DurationUnit.MILLISECONDS)
/**
* Returns a [Duration] representing the specified [value] number of milliseconds.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun milliseconds(value: Double): Duration = value.toDuration(DurationUnit.MILLISECONDS)
/** Returns a [Duration] representing the specified [value] number of seconds. */
@SinceKotlin("1.5")
public fun seconds(value: Int): Duration = value.toDuration(DurationUnit.SECONDS)
/** Returns a [Duration] representing the specified [value] number of seconds. */
@SinceKotlin("1.5")
public fun seconds(value: Long): Duration = value.toDuration(DurationUnit.SECONDS)
/**
* Returns a [Duration] representing the specified [value] number of seconds.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun seconds(value: Double): Duration = value.toDuration(DurationUnit.SECONDS)
/** Returns a [Duration] representing the specified [value] number of minutes. */
@SinceKotlin("1.5")
public fun minutes(value: Int): Duration = value.toDuration(DurationUnit.MINUTES)
/** Returns a [Duration] representing the specified [value] number of minutes. */
@SinceKotlin("1.5")
public fun minutes(value: Long): Duration = value.toDuration(DurationUnit.MINUTES)
/**
* Returns a [Duration] representing the specified [value] number of minutes.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun minutes(value: Double): Duration = value.toDuration(DurationUnit.MINUTES)
/** Returns a [Duration] representing the specified [value] number of hours. */
@SinceKotlin("1.5")
public fun hours(value: Int): Duration = value.toDuration(DurationUnit.HOURS)
/** Returns a [Duration] representing the specified [value] number of hours. */
@SinceKotlin("1.5")
public fun hours(value: Long): Duration = value.toDuration(DurationUnit.HOURS)
/**
* Returns a [Duration] representing the specified [value] number of hours.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun hours(value: Double): Duration = value.toDuration(DurationUnit.HOURS)
/** Returns a [Duration] representing the specified [value] number of days. */
@SinceKotlin("1.5")
public fun days(value: Int): Duration = value.toDuration(DurationUnit.DAYS)
/** Returns a [Duration] representing the specified [value] number of days. */
@SinceKotlin("1.5")
public fun days(value: Long): Duration = value.toDuration(DurationUnit.DAYS)
/**
* Returns a [Duration] representing the specified [value] number of days.
*
* @throws IllegalArgumentException if the provided `Double` [value] is `NaN`.
*/
@SinceKotlin("1.5")
public fun days(value: Double): Duration = value.toDuration(DurationUnit.DAYS)
}
// arithmetic operators
@@ -394,11 +507,13 @@ public fun Double.toDuration(unit: DurationUnit): Duration = Duration(convertDur
/** Returns a [Duration] equal to this [Int] number of nanoseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.nanoseconds() function instead.", ReplaceWith("Duration.nanoseconds(this)", "kotlin.time.Duration"))
public val Int.nanoseconds get() = toDuration(DurationUnit.NANOSECONDS)
/** Returns a [Duration] equal to this [Long] number of nanoseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.nanoseconds() function instead.", ReplaceWith("Duration.nanoseconds(this)", "kotlin.time.Duration"))
public val Long.nanoseconds get() = toDuration(DurationUnit.NANOSECONDS)
/**
@@ -408,16 +523,19 @@ public val Long.nanoseconds get() = toDuration(DurationUnit.NANOSECONDS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.nanoseconds() function instead.", ReplaceWith("Duration.nanoseconds(this)", "kotlin.time.Duration"))
public val Double.nanoseconds get() = toDuration(DurationUnit.NANOSECONDS)
/** Returns a [Duration] equal to this [Int] number of microseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.microseconds() function instead.", ReplaceWith("Duration.microseconds(this)", "kotlin.time.Duration"))
public val Int.microseconds get() = toDuration(DurationUnit.MICROSECONDS)
/** Returns a [Duration] equal to this [Long] number of microseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.microseconds() function instead.", ReplaceWith("Duration.microseconds(this)", "kotlin.time.Duration"))
public val Long.microseconds get() = toDuration(DurationUnit.MICROSECONDS)
/**
@@ -427,16 +545,19 @@ public val Long.microseconds get() = toDuration(DurationUnit.MICROSECONDS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.microseconds() function instead.", ReplaceWith("Duration.microseconds(this)", "kotlin.time.Duration"))
public val Double.microseconds get() = toDuration(DurationUnit.MICROSECONDS)
/** Returns a [Duration] equal to this [Int] number of milliseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.milliseconds() function instead.", ReplaceWith("Duration.milliseconds(this)", "kotlin.time.Duration"))
public val Int.milliseconds get() = toDuration(DurationUnit.MILLISECONDS)
/** Returns a [Duration] equal to this [Long] number of milliseconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.milliseconds() function instead.", ReplaceWith("Duration.milliseconds(this)", "kotlin.time.Duration"))
public val Long.milliseconds get() = toDuration(DurationUnit.MILLISECONDS)
/**
@@ -446,16 +567,19 @@ public val Long.milliseconds get() = toDuration(DurationUnit.MILLISECONDS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.milliseconds() function instead.", ReplaceWith("Duration.milliseconds(this)", "kotlin.time.Duration"))
public val Double.milliseconds get() = toDuration(DurationUnit.MILLISECONDS)
/** Returns a [Duration] equal to this [Int] number of seconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.seconds() function instead.", ReplaceWith("Duration.seconds(this)", "kotlin.time.Duration"))
public val Int.seconds get() = toDuration(DurationUnit.SECONDS)
/** Returns a [Duration] equal to this [Long] number of seconds. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.seconds() function instead.", ReplaceWith("Duration.seconds(this)", "kotlin.time.Duration"))
public val Long.seconds get() = toDuration(DurationUnit.SECONDS)
/**
@@ -465,16 +589,19 @@ public val Long.seconds get() = toDuration(DurationUnit.SECONDS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.seconds() function instead.", ReplaceWith("Duration.seconds(this)", "kotlin.time.Duration"))
public val Double.seconds get() = toDuration(DurationUnit.SECONDS)
/** Returns a [Duration] equal to this [Int] number of minutes. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.minutes() function instead.", ReplaceWith("Duration.minutes(this)", "kotlin.time.Duration"))
public val Int.minutes get() = toDuration(DurationUnit.MINUTES)
/** Returns a [Duration] equal to this [Long] number of minutes. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.minutes() function instead.", ReplaceWith("Duration.minutes(this)", "kotlin.time.Duration"))
public val Long.minutes get() = toDuration(DurationUnit.MINUTES)
/**
@@ -484,16 +611,19 @@ public val Long.minutes get() = toDuration(DurationUnit.MINUTES)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.minutes() function instead.", ReplaceWith("Duration.minutes(this)", "kotlin.time.Duration"))
public val Double.minutes get() = toDuration(DurationUnit.MINUTES)
/** Returns a [Duration] equal to this [Int] number of hours. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.hours() function instead.", ReplaceWith("Duration.hours(this)", "kotlin.time.Duration"))
public val Int.hours get() = toDuration(DurationUnit.HOURS)
/** Returns a [Duration] equal to this [Long] number of hours. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.hours() function instead.", ReplaceWith("Duration.hours(this)", "kotlin.time.Duration"))
public val Long.hours get() = toDuration(DurationUnit.HOURS)
/**
@@ -503,16 +633,19 @@ public val Long.hours get() = toDuration(DurationUnit.HOURS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.hours() function instead.", ReplaceWith("Duration.hours(this)", "kotlin.time.Duration"))
public val Double.hours get() = toDuration(DurationUnit.HOURS)
/** Returns a [Duration] equal to this [Int] number of days. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.days() function instead.", ReplaceWith("Duration.days(this)", "kotlin.time.Duration"))
public val Int.days get() = toDuration(DurationUnit.DAYS)
/** Returns a [Duration] equal to this [Long] number of days. */
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.days() function instead.", ReplaceWith("Duration.days(this)", "kotlin.time.Duration"))
public val Long.days get() = toDuration(DurationUnit.DAYS)
/**
@@ -522,6 +655,7 @@ public val Long.days get() = toDuration(DurationUnit.DAYS)
*/
@SinceKotlin("1.3")
@ExperimentalTime
@Deprecated("Use Duration.days() function instead.", ReplaceWith("Duration.days(this)", "kotlin.time.Duration"))
public val Double.days get() = toDuration(DurationUnit.DAYS)