# 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

#### inNanoseconds

The value of this duration expressed as a Double number of nanoseconds.

`val `~~inNanoseconds~~: 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`

### 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.