Duration

Common

JVM

Native

1.6

inline class Duration : Comparable<Duration>
(source)

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

Common

JVM

Native

1.0

absoluteValue

Returns the absolute value of this value. The returned value is always non-negative.

val absoluteValue: Duration

Common

JVM

Native

1.0

inDays

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

val inDays: Double

Common

JVM

Native

1.0

inHours

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

val inHours: Double

Common

JVM

Native

1.0

inMicroseconds

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

val inMicroseconds: Double

Common

JVM

Native

1.0

inMilliseconds

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

val inMilliseconds: Double

Common

JVM

Native

1.0

inMinutes

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

val inMinutes: Double

Common

JVM

Native

1.0

inNanoseconds

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

val inNanoseconds: Double

Common

JVM

Native

1.0

inSeconds

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

val inSeconds: Double

Common

JVM

Native

1.0

inWholeDays

The value of this duration expressed as a Long number of days.

val inWholeDays: Long

Common

JVM

Native

1.0

inWholeHours

The value of this duration expressed as a Long number of hours.

val inWholeHours: Long

Common

JVM

Native

1.0

inWholeMicroseconds

The value of this duration expressed as a Long number of microseconds.

val inWholeMicroseconds: Long

Common

JVM

Native

1.0

inWholeMilliseconds

The value of this duration expressed as a Long number of milliseconds.

val inWholeMilliseconds: Long

Common

JVM

Native

1.0

inWholeMinutes

The value of this duration expressed as a Long number of minutes.

val inWholeMinutes: Long

Common

JVM

Native

1.0

inWholeNanoseconds

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

val inWholeNanoseconds: Long

Common

JVM

Native

1.0

inWholeSeconds

The value of this duration expressed as a Long number of seconds.

val inWholeSeconds: Long

Functions

Common

JVM

Native

1.0

compareTo

fun compareTo(other: Duration): Int

Common

JVM

Native

1.0

div

Returns a duration whose value is this duration value divided by the given scale number.

operator fun div(scale: Int): Duration

operator fun div(scale: Double): Duration

Returns a number that is the ratio of this and other duration values.

operator fun div(other: Duration): Double

Common

JVM

Native

1.0

isFinite

Returns true, if the duration value is finite.

fun isFinite(): Boolean

Common

JVM

Native

1.0

isInfinite

Returns true, if the duration value is infinite.

fun isInfinite(): Boolean

Common

JVM

Native

1.0

isNegative

Returns true, if the duration value is less than zero.

fun isNegative(): Boolean

Common

JVM

Native

1.0

isPositive

Returns true, if the duration value is greater than zero.

fun isPositive(): Boolean

Common

JVM

Native

1.0

minus

Returns a duration whose value is the difference between this and other duration values.

operator fun minus(other: Duration): Duration

Common

JVM

Native

1.0

plus

Returns a duration whose value is the sum of this and other duration values.

operator fun plus(other: Duration): Duration

Common

JVM

Native

1.0

times

Returns a duration whose value is this duration value multiplied by the given scale number.

operator fun times(scale: Int): Duration

operator fun times(scale: Double): Duration

Common

JVM

Native

1.0

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

Splits this duration into 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: (minutes: Long, seconds: Int, nanoseconds: Int) -> T
): T

Splits this duration into 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: (seconds: Long, nanoseconds: Int) -> T
): T

Common

JVM

Native

1.0

toDouble

Returns the value of this duration expressed as a Double number of the specified unit.

fun toDouble(unit: DurationUnit): Double

Common

JVM

Native

1.0

toInt

Returns the value of this duration expressed as an Int number of the specified unit.

fun toInt(unit: DurationUnit): Int

Common

JVM

Native

1.0

toIsoString

Returns an ISO-8601 based string representation of this duration.

fun toIsoString(): String

Common

JVM

Native

1.0

toLong

Returns the value of this duration expressed as a Long number of the specified unit.

fun toLong(unit: DurationUnit): Long

Common

JVM

Native

1.0

toLongMilliseconds

Returns the value of this duration expressed as a Long number of milliseconds.

fun toLongMilliseconds(): Long

Common

JVM

Native

1.0

toLongNanoseconds

Returns the value of this duration expressed as a Long number of nanoseconds.

fun toLongNanoseconds(): Long

Common

JVM

Native

1.0

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

Common

JVM

Native

1.0

unaryMinus

Returns the negative of this value.

operator fun unaryMinus(): Duration

Companion Object Properties

Common

JVM

Native

1.0

days

Returns a Duration equal to this Int number of days.

val Int.days: Duration

Returns a Duration equal to this Long number of days.

val Long.days: Duration

Returns a Duration equal to this Double number of days.

val Double.days: Duration

Common

JVM

Native

1.0

hours

Returns a Duration equal to this Int number of hours.

val Int.hours: Duration

Returns a Duration equal to this Long number of hours.

val Long.hours: Duration

Returns a Duration equal to this Double number of hours.

val Double.hours: Duration

Common

JVM

Native

1.0

INFINITE

The duration whose value is positive infinity. It is useful for representing timeouts that should never expire.

val INFINITE: Duration

Common

JVM

Native

1.0

microseconds

Returns a Duration equal to this Int number of microseconds.

val Int.microseconds: Duration

Returns a Duration equal to this Long number of microseconds.

val Long.microseconds: Duration

Returns a Duration equal to this Double number of microseconds.

val Double.microseconds: Duration

Common

JVM

Native

1.0

milliseconds

Returns a Duration equal to this Int number of milliseconds.

val Int.milliseconds: Duration

Returns a Duration equal to this Long number of milliseconds.

val Long.milliseconds: Duration

Returns a Duration equal to this Double number of milliseconds.

val Double.milliseconds: Duration

Common

JVM

Native

1.0

minutes

Returns a Duration equal to this Int number of minutes.

val Int.minutes: Duration

Returns a Duration equal to this Long number of minutes.

val Long.minutes: Duration

Returns a Duration equal to this Double number of minutes.

val Double.minutes: Duration

Common

JVM

Native

1.0

nanoseconds

Returns a Duration equal to this Int number of nanoseconds.

val Int.nanoseconds: Duration

Returns a Duration equal to this Long number of nanoseconds.

val Long.nanoseconds: Duration

Returns a Duration equal to this Double number of nanoseconds.

val Double.nanoseconds: Duration

Common

JVM

Native

1.0

seconds

Returns a Duration equal to this Int number of seconds.

val Int.seconds: Duration

Returns a Duration equal to this Long number of seconds.

val Long.seconds: Duration

Returns a Duration equal to this Double number of seconds.

val Double.seconds: Duration

Common

JVM

Native

1.0

ZERO

The duration equal to exactly 0 seconds.

val ZERO: Duration

Companion Object Functions

Common

JVM

Native

1.0

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

Common

JVM

Native

1.5

days

Returns a Duration representing the specified value number of days.

fun days(value: Int): Duration

fun days(value: Long): Duration

fun days(value: Double): Duration

Common

JVM

Native

1.5

hours

Returns a Duration representing the specified value number of hours.

fun hours(value: Int): Duration

fun hours(value: Long): Duration

fun hours(value: Double): Duration

Common

JVM

Native

1.5

microseconds

Returns a Duration representing the specified value number of microseconds.

fun microseconds(value: Int): Duration

fun microseconds(value: Long): Duration

fun microseconds(value: Double): Duration

Common

JVM

Native

1.5

milliseconds

Returns a Duration representing the specified value number of milliseconds.

fun milliseconds(value: Int): Duration

fun milliseconds(value: Long): Duration

fun milliseconds(value: Double): Duration

Common

JVM

Native

1.5

minutes

Returns a Duration representing the specified value number of minutes.

fun minutes(value: Int): Duration

fun minutes(value: Long): Duration

fun minutes(value: Double): Duration

Common

JVM

Native

1.5

nanoseconds

Returns a Duration representing the specified value number of nanoseconds.

fun nanoseconds(value: Int): Duration

fun nanoseconds(value: Long): Duration

fun nanoseconds(value: Double): Duration

Common

JVM

Native

1.0

parse

Parses a string that represents a duration and returns the parsed Duration value.

fun parse(value: String): Duration

Common

JVM

Native

1.0

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

Common

JVM

Native

1.0

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?

Common

JVM

Native

1.0

parseOrNull

Parses a string that represents a duration and returns the parsed Duration value, or null if the string doesn't represent a duration in any of the supported formats.

fun parseOrNull(value: String): Duration?

Common

JVM

Native

1.5

seconds

Returns a Duration representing the specified value number of seconds.

fun seconds(value: Int): Duration

fun seconds(value: Long): Duration

fun seconds(value: Double): Duration

Extension Functions

Common

JVM

Native

1.0

coerceAtLeast

Ensures that this value is not less than the specified minimumValue.

fun <T : Comparable<T>> T.coerceAtLeast(minimumValue: T): T

Common

JVM

Native

1.0

coerceAtMost

Ensures that this value is not greater than the specified maximumValue.

fun <T : Comparable<T>> T.coerceAtMost(maximumValue: T): T

Common

JVM

Native

1.0

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

Common

JVM

Native

1.6

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

Common

JVM

Native

1.0

rangeTo

Creates a range from this Comparable value to the specified that value.

operator fun <T : Comparable<T>> T.rangeTo(
    that: T
): ClosedRange<T>

Common

JVM

Native

1.9

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>

JVM

JRE8

1.6

toJavaDuration

Converts kotlin.time.Duration value to java.time.Duration value.

fun Duration.toJavaDuration(): Duration