Duration

<init>

Duration(nanoseconds: Long)

A span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.

A Duration represents a difference from one point in time to another. The duration may be "negative" if the difference is from a later time to an earlier.

Durations are context independent. For example, a duration of 2 days is always 48 hours, even when it is added to a DateTime just when the time zone is about to do a daylight-savings switch.

Despite the same name, a Duration object does not implement "Durations" as specified by ISO 8601. In particular, a duration object does not keep track of the individually provided members (such as "days" or "hours"), but only uses these arguments to compute the length of the corresponding time interval.

To create a Duration, use the unit extension functions on the primitive Int and Long types:

    val aLongWeekend = 96.hours

To create a Duration from several components, use the Duration factory function:

    val fastestMarathon = Duration(hours = 2, minutes = 3, seconds = 2)

The Duration is the sum of all individual parts. This means that individual parts can be larger than the next-bigger unit. For example, inMinutes can be greater than 59.

    assertEquals(123, fastestMarathon.inMinutes)

All individual parts are allowed to be negative.

Use one of the extensions such as inDays to retrieve the integer value of the Duration in the specified time unit. Note that the returned value is rounded down. For example,

    val aLongWeekend = 86.hours
    assertEquals(3, aLongWeekend.inDays())

compareTo

@Stable fun compareTo(other: Duration): Int

Compares this Duration to other, returning zero if the values are equal.

Returns a negative integer if this Duration is shorter than other, or a positive integer if it is longer.

A negative Duration is always considered shorter than a positive one.

It is always the case that duration1.compareTo(duration2) < 0 if (someDate + duration1).compareTo(someDate + duration2) < 0.

div

@Stable operator fun div(quotient: Int): Duration

Divides this Duration by the given quotient and returns the truncated result as a Duration.

div

@Stable operator fun div(quotient: Double): Duration

Divides this Duration by the given quotient and returns the truncated result as a Duration.

minus

@Stable operator fun minus(other: Duration): Duration

Subtracts other from this Duration and returns the difference.

plus

@Stable operator fun plus(other: Duration): Duration

Adds this Duration and other and returns the sum as a Duration.

times

@Stable operator fun times(factor: Int): Duration

Multiplies this Duration by the given factor and returns the result.

times

@Stable operator fun times(factor: Double): Duration

Multiplies this Duration by the given factor and returns the result.

toString

@Stable fun toString(): String

Returns a string representation of this Duration.

Returns a string with hours, minutes, seconds, and microseconds, in the following format: HH:MM:SS.mmmmmm. For example,

    val d = Duration(days = 1, hours = 1, minutes = 33, microseconds = 500)
    d.toString()  // "25:33:00.000500"

nanoseconds

val nanoseconds: Long

Zero

@Stable val Zero: Duration

An empty Duration. No delay. Instant.