Duration
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.
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, available on Int , Long , and Double numeric types.
To get the value of this duration expressed in a particular duration units use the functions toInt , toLong , and toDouble or the properties inWholeHours , inWholeMinutes , inWholeSeconds , inWholeNanoseconds , and so on.
Properties
absoluteValue
Returns the absolute value of this value. The returned value is always non-negative.
val
absoluteValue
:
Duration
inMicroseconds
The value of this duration expressed as a Double number of microseconds.
val
inMicroseconds
:
Double
inMilliseconds
The value of this duration expressed as a Double number of milliseconds.
val
inMilliseconds
:
Double
inMinutes
The value of this duration expressed as a Double number of minutes.
val
inMinutes
:
Double
inNanoseconds
The value of this duration expressed as a Double number of nanoseconds.
val
inNanoseconds
:
Double
inSeconds
The value of this duration expressed as a Double number of seconds.
val
inSeconds
:
Double
inWholeDays
The value of this duration expressed as a Long number of days.
val
inWholeDays
:
Long
inWholeHours
The value of this duration expressed as a Long number of hours.
val
inWholeHours
:
Long
inWholeMicroseconds
The value of this duration expressed as a Long number of microseconds.
val
inWholeMicroseconds
:
Long
inWholeMilliseconds
The value of this duration expressed as a Long number of milliseconds.
val
inWholeMilliseconds
:
Long
inWholeMinutes
The value of this duration expressed as a Long number of minutes.
val
inWholeMinutes
:
Long
inWholeNanoseconds
The value of this duration expressed as a Long number of nanoseconds.
val
inWholeNanoseconds
:
Long
inWholeSeconds
The value of this duration expressed as a Long number of seconds.
val
inWholeSeconds
:
Long
Functions
div
isFinite
Returns true, if the duration value is finite.
fun
isFinite
(
)
:
Boolean
isInfinite
Returns true, if the duration value is infinite.
fun
isInfinite
(
)
:
Boolean
isNegative
Returns true, if the duration value is less than zero.
fun
isNegative
(
)
:
Boolean
isPositive
Returns true, if the duration value is greater than zero.
fun
isPositive
(
)
:
Boolean
toComponents
Splits this duration into days, hours, minutes, seconds, and nanoseconds and executes the given action with these components. The result of action is returned as the result of this function.
fun
<
T
>
toComponents
(
action
:
(
days
:
Long
,
hours
:
Int
,
minutes
:
Int
,
seconds
:
Int
,
nanoseconds
:
Int
)
->
T
)
:
T
Splits this duration into hours, minutes, seconds, and nanoseconds and executes the given action with these components. The result of action is returned as the result of this function.
fun
<
T
>
toComponents
(
action
:
(
hours
:
Long
,
minutes
:
Int
,
seconds
:
Int
,
nanoseconds
:
Int
)
->
T
)
:
T
toDouble
Returns the value of this duration expressed as a Double number of the specified unit .
fun
toDouble
(
unit
:
DurationUnit
)
:
Double
toInt
Returns the value of this duration expressed as an Int number of the specified unit .
fun
toInt
(
unit
:
DurationUnit
)
:
Int
toIsoString
Returns an ISO-8601 based string representation of this duration.
fun
toIsoString
(
)
:
String
toLong
Returns the value of this duration expressed as a Long number of the specified unit .
fun
toLong
(
unit
:
DurationUnit
)
:
Long
toLongMilliseconds
Returns the value of this duration expressed as a Long number of milliseconds.
fun
toLongMilliseconds
(
)
:
Long
toLongNanoseconds
Returns the value of this duration expressed as a Long number of nanoseconds.
fun
toLongNanoseconds
(
)
:
Long
toString
Returns a string representation of this duration value expressed as a combination of numeric components, each in its own unit.
fun
toString
(
)
:
String
Returns a string representation of this duration value expressed in the given unit and formatted with the specified decimals number of digits after decimal point.
fun
toString
(
unit
:
DurationUnit
,
decimals
:
Int
=
0
)
:
String
unaryMinus
Returns the negative of this value.
operator
fun
unaryMinus
(
)
:
Duration
Companion Object Properties
INFINITE
The duration whose value is positive infinity. It is useful for representing timeouts that should never expire.
val
INFINITE
:
Duration
microseconds
milliseconds
Companion Object Functions
convert
Converts the given time duration value expressed in the specified sourceUnit into the specified targetUnit .
fun
convert
(
value
:
Double
,
sourceUnit
:
DurationUnit
,
targetUnit
:
DurationUnit
)
:
Double
parseIsoString
Parses a string that represents a duration in a restricted ISO-8601 composite representation and returns the parsed Duration value. Composite representation is a relaxed version of ISO-8601 duration format that supports negative durations and negative values of individual components.
fun
parseIsoString
(
value
:
String
)
:
Duration
parseIsoStringOrNull
Parses a string that represents a duration in restricted ISO-8601 composite representation
and returns the parsed
Duration
value or
null
if the string doesn't represent a duration in the format
acceptable by
parseIsoString
.
fun
parseIsoStringOrNull
(
value
:
String
)
:
Duration
?
Extension Functions
coerceAtLeast
Ensures that this value is not less than the specified minimumValue .
fun
<
T
:
Comparable
<
T
>
>
T
.
coerceAtLeast
(
minimumValue
:
T
)
:
T
coerceAtMost
Ensures that this value is not greater than the specified maximumValue .
fun
<
T
:
Comparable
<
T
>
>
T
.
coerceAtMost
(
maximumValue
:
T
)
:
T
coerceIn
Ensures that this value lies in the specified range minimumValue .. maximumValue .
fun
<
T
:
Comparable
<
T
>
>
T
.
coerceIn
(
minimumValue
:
T
?
,
maximumValue
:
T
?
)
:
T
Ensures that this value lies in the specified range .
fun
<
T
:
Comparable
<
T
>
>
T
.
coerceIn
(
range
:
ClosedFloatingPointRange
<
T
>
)
:
T
fun
<
T
:
Comparable
<
T
>
>
T
.
coerceIn
(
range
:
ClosedRange
<
T
>
)
:
T
compareTo
Compares this object with the specified object for order. Returns zero if this object is equal to the specified other object, a negative number if it's less than other , or a positive number if it's greater than other .
infix
fun
<
T
>
Comparable
<
T
>
.
compareTo
(
other
:
T
)
:
Int
rangeTo
Creates a range from this Comparable value to the specified that value.
operator
fun
<
T
:
Comparable
<
T
>
>
T
.
rangeTo
(
that
:
T
)
:
ClosedRange
<
T
>
rangeUntil
Creates an open-ended range from this Comparable value to the specified that value.
operator
fun
<
T
:
Comparable
<
T
>
>
T
.
rangeUntil
(
that
:
T
)
:
OpenEndRange
<
T
>
toJavaDuration
Converts kotlin.time.Duration value to java.time.Duration value.