Durations: Temporal's Duration — duration • zutempo

A duration() is a length of time in ten fields, years to nanoseconds, each a float64-representable integer as Temporal defines them, stored as a list of ten double vectors. All fields share one sign. Years, months and weeks are calendar units: operations that need their length take relative_to, a date, and fail without it.

Usage

duration(
  years = 0,
  months = 0,
  weeks = 0,
  days = 0,
  hours = 0,
  minutes = 0,
  seconds = 0,
  milliseconds = 0,
  microseconds = 0,
  nanoseconds = 0,
  ...
)

duration_compare(x, y, relative_to = NULL)

Arguments

years: The years, or a string in ISO 8601 form ("P1Y2M3DT4H5M6.789S", a fraction only on the smallest unit present), a duration() to return as is, or a difftime, whose exact seconds become seconds and nanoseconds.
months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds: The remaining fields, 0 by default.
...: Must be empty.
x, y: duration() values or strings, for duration_compare().
relative_to: A plain_date(), plain_date_time(), zoned_date_time() or a string one of them reads (a zone in brackets makes it zoned): the start the calendar units are counted from; with a zoned value, days follow the zone. Required when either duration has years, months or weeks.

Value

A duration() vector; duration_compare() returns an integer vector of -1, 0 and 1.

Members

Every member of Temporal.Duration in the pinned specification (inst/spec/PINS) and the R function that implements it:

Temporal	R
`new Temporal.Duration()`	`duration()`
`Temporal.Duration.from()`	`duration()`
`Temporal.Duration.compare()`	`duration_compare()`
`.years`	`years()`
`.months`	`months()`
`.weeks`	`weeks()`
`.days`	`days()`
`.hours`	`hours()`
`.minutes`	`minutes()`
`.seconds`	`seconds()`
`.milliseconds`	`milliseconds()`
`.microseconds`	`microseconds()`
`.nanoseconds`	`nanoseconds()`
`.sign`	`sign()`
`.blank`	`blank()`
`.with()`	`temporal_with()`
`.negated()`	`temporal_negated()`
`.abs()`	`temporal_abs()`
`.add()`	`temporal_add()`
`.subtract()`	`temporal_subtract()`
`.round()`	`temporal_round()`
`.total()`	`temporal_total()`
`.toString()`	`temporal_to_string()`
`.toJSON()`	none: format() covers it
`.toLocaleString()`	none: ECMA-402 (locale formatting) is out of scope
`.valueOf()`	none: throws in JavaScript; no R counterpart

Examples

duration("P1Y2M3DT4H5M6.789S")
#> <zutempo_duration[1]>
#> [1] P1Y2M3DT4H5M6.789S
duration(hours = 25)
#> <zutempo_duration[1]>
#> [1] PT25H
duration(milliseconds = 2^53 + 2)
#> <zutempo_duration[1]>
#> [1] PT9007199254740.994S
duration_compare("PT1H", "PT60M")
#> [1] 0
duration_compare("P1M", "P30D", relative_to = "2026-02-01")
#> [1] -1