skip to content

How do you create a kotlin.time.Duration value in Kotlin, and what is the idiomatic way to express '5 seconds' or '100 milliseconds'?

level: juniorimportance: must knowfreq 60%

answer

  1. 5.seconds / 100.milliseconds extension properties
  2. Lives in kotlin.time, inline value class
  3. Int/Long/Double receivers — 1.5.hours works
  4. toDuration(DurationUnit.X) alternative
  5. Duration.ZERO and Duration.INFINITE

basics

~10 s

Use the extension properties on numbers from kotlin.time, like 5.seconds or 100.milliseconds. They return a Duration object that represents a length of time, which you can add, compare, or convert.

solid answer

~30 s

Durations come from the stdlib package kotlin.time. The idiomatic way is the numeric extension properties: 5.seconds, 100.milliseconds, 2.minutes, 1.hours, 500.nanoseconds, 3.days. These work on Int, Long, and Double receivers, so 1.5.seconds is valid. They return a kotlin.time.Duration, an inline value class storing the amount internally as a long count of nanoseconds or milliseconds. Alternatively you can build one with toDuration(unit), e.g. 5.toDuration(DurationUnit.SECONDS). Avoid raw Long millisecond fields in APIs; passing a Duration makes the unit explicit and prevents unit-confusion bugs. Duration.ZERO, Duration.INFINITE, and Duration.parse(...) are the other common constructors.

code

kotlin · 13 lines
kotlin
import kotlin.time.Duration
import kotlin.time.Duration.Companion.seconds
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.DurationUnit
import kotlin.time.toDuration

fun main() {
    val timeout: Duration = 5.seconds
    val tick = 100.milliseconds
    val explicit = 250.toDuration(DurationUnit.MILLISECONDS)
    println(timeout)            // 5s
    println(tick + explicit)    // 350ms
}

go deeper

for a junior

Can write 5.seconds / 100.milliseconds and knows it returns a Duration from kotlin.time.

for a middle

Knows the receivers (Int/Long/Double), the toDuration alternative, ZERO/INFINITE, and why Duration beats raw Long in APIs.

for a senior

Explains the inline-value-class representation and the millis/nanos storage flag, and the interop story via inWhole* accessors.

for a principal

Frames Duration as an API-design tool for eliminating unit ambiguity at module boundaries and can discuss its stabilization history and allocation behavior.

## What is Duration? `kotlin.time.Duration` is a stdlib type representing an amount of elapsed time (a span), independent of any calendar or wall-clock point. It is an **inline value class** (`@JvmInline value class Duration`), so in most cases it incurs no heap allocation — it is backed by a single `Long` plus a flag bit that records whether the stored unit is nanoseconds or milliseconds (this lets it span from nanoseconds up to ~146 years in nanos, and far longer in millis). ## Creating durations The idiomatic, readable way uses **extension properties on numeric receivers** defined in `kotlin.time`: ```kotlin import kotlin.time.Duration import kotlin.time.Duration.Companion.seconds import kotlin.time.Duration.Companion.milliseconds import kotlin.time.Duration.Companion.minutes val a: Duration = 5.seconds val b = 100.milliseconds val c = 1.5.hours // Double receiver works too val d = 3.days ``` These live in the `Duration.Companion` (so you import `Duration.Companion.seconds`, or just `kotlin.time.*`). Receivers can be `Int`, `Long`, or `Double`. ## Other constructors - `5.toDuration(DurationUnit.SECONDS)` — explicit-unit builder. - `Duration.ZERO` — a zero-length duration. - `Duration.INFINITE` — a positive-infinite duration (and `-Duration.INFINITE` for negative). - `Duration.parse("PT5S")` — parse an ISO-8601 / Kotlin string. ## Why prefer Duration over raw Long millis? A `Long` named `timeout` could be seconds, millis, or nanos — the type tells you nothing. A `Duration` parameter is self-documenting and makes unit-conversion bugs impossible at the API boundary. Java interop APIs that need a `Long` can call `duration.inWholeMilliseconds`. ## Stability note `Duration` graduated to stable in Kotlin 1.6; the numeric extension properties (`5.seconds`) became stable around the same time, having moved out of the experimental `kotlin.time` API.

  • Where do the .seconds / .milliseconds extension properties come from at import time?
    They are declared in Duration.Companion, so you import kotlin.time.Duration.Companion.seconds (or kotlin.time.*). They are extensions on Int, Long, and Double.
  • How would you pass a Duration to a Java API that wants a long of milliseconds?
    Call duration.inWholeMilliseconds (a Long). Use the inWhole* family for lossless-ish integer conversion at the boundary.

Think of Duration like a typed money amount instead of a bare number: '5.seconds' is unambiguous the way '$5 USD' is, whereas a raw Long is just '5'.

saying these in an interview costs you the question

  • Thinking Duration is a third-party library rather than kotlin.time stdlib
  • Claiming you must write toDuration(...) because 5.seconds doesn't exist
  • Saying Duration only accepts Int (it also accepts Long and Double)
  • Confusing Duration (a span) with Instant/a wall-clock point in time

context

resolving links…