How do you create a kotlin.time.Duration value in Kotlin, and what is the idiomatic way to express '5 seconds' or '100 milliseconds'?
answer
- 5.seconds / 100.milliseconds extension properties
- Lives in kotlin.time, inline value class
- Int/Long/Double receivers — 1.5.hours works
- toDuration(DurationUnit.X) alternative
- Duration.ZERO and Duration.INFINITE
basics
~10 sUse 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 sDurations 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 linesimport 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
Can write 5.seconds / 100.milliseconds and knows it returns a Duration from kotlin.time.
Knows the receivers (Int/Long/Double), the toDuration alternative, ZERO/INFINITE, and why Duration beats raw Long in APIs.
Explains the inline-value-class representation and the millis/nanos storage flag, and the interop story via inWhole* accessors.
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