Temporal.Duration

A Temporal.Duration represents a duration of time which can be used in date/time arithmetic.

Temporal.Duration can be constructed directly or returned from Temporal.Duration.from(). It can also be obtained from the since() method of any other Temporal type that supports arithmetic, and is used in those types' add() and subtract() methods.

When printed, a Temporal.Duration produces a string according to the ISO 8601 notation for durations. The examples in this page use this notation extensively.

Briefly, the ISO 8601 notation consists of a P character, followed by years, months, weeks, and days, followed by a T character, followed by hours, minutes, and seconds with a decimal part, each with a single-letter suffix that indicates the unit. Any zero components may be omitted. For more detailed information, see the ISO 8601 standard or the Wikipedia page.

NOTE: According to the ISO 8601-1 standard, weeks are not allowed to appear together with any other units, and durations can only be positive. As extensions to the standard, ISO 8601-2 allows a sign character at the start of the string, and allows combining weeks with other units. If you intend to use a string such as P3W1D, +P1M, or -P1M for interoperability, note that other programs may not accept it.

Constructor

new Temporal.Duration(years?: number, months?: number, weeks?: number, days?: number, hours?: number, minutes?: number, seconds?: number, milliseconds?: number, microseconds?: number, nanoseconds?: number) : Temporal.Duration

Parameters:

• years (optional number): A number of years.
• months (optional number): A number of months.
• weeks (optional number): A number of weeks.
• days (optional number): A number of days.
• hours (optional number): A number of hours.
• minutes (optional number): A number of minutes.
• seconds (optional number): A number of seconds.
• milliseconds (optional number): A number of milliseconds.
• microseconds (optional number): A number of microseconds.
• nanoseconds (optional number): A number of nanoseconds.

Returns: a new Temporal.Duration object.

All of the arguments are optional. Any missing or undefined numerical arguments are taken to be zero, and all arguments must be integers. Any non-zero arguments must all have the same sign.

Use this constructor directly if you have the correct parameters already as numerical values. Otherwise Temporal.Duration.from() is probably more convenient because it accepts more kinds of input and allows controlling the overflow behavior.

Usage examples:

new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 987, 654, 321); // => P1Y2M3W4DT5H6M7.987654321S
new Temporal.Duration(0, 0, 0, 40); // => P40D
new Temporal.Duration(undefined, undefined, undefined, 40); // => P40D
new Temporal.Duration(); // => PT0S

/* WRONG */ new Temporal.Duration(0, 0, 0, 1.5); // => throws

Static methods

Temporal.Duration.from(item: Temporal.Duration | object | string) : Temporal.Duration

Parameters:

• item: a value convertible to a Temporal.Duration.

Returns: a new Temporal.Duration object.

This static method creates a new Temporal.Duration from another value. If the value is another Temporal.Duration object, a new object representing the same duration is returned. If the value is any other object, a Temporal.Duration will be constructed from the values of any years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds properties that are present. Any missing ones will be assumed to be 0.

All non-zero values must be integers, must have the same sign, and must not be infinite. Otherwise, the function will throw a RangeError.

If the value is not an object, it must be a string, which is expected to be in ISO 8601 format.

NOTE: This function understands strings where weeks and other units are combined, and strings with a single sign character at the start, which are extensions to the ISO 8601 standard described in ISO 8601-2. For example, P3W1D is understood to mean three weeks and one day, -P1Y1M is a negative duration of one year and one month, and +P1Y1M is one year and one month. If no sign character is present, then the sign is assumed to be positive.

Usage examples:

d = Temporal.Duration.from({ years: 1, days: 1 }); // => P1Y1D
d = Temporal.Duration.from({ days: -2, hours: -12 }); // => -P2DT12H

Temporal.Duration.from(d) === d; // => false

d = Temporal.Duration.from('P1Y1D'); // => P1Y1D
d = Temporal.Duration.from('-P2DT12H'); // => -P2DT12H
d = Temporal.Duration.from('P0D'); // => PT0S

// Non-integer numbers are never allowed, even if they are allowed in an ISO string:
/* WRONG */ d = Temporal.Duration.from({ seconds: 1.5 }); // => throws
d = Temporal.Duration.from("PT1.5S"); // ok
d = Temporal.Duration.from({ seconds: 1, milliseconds: 500 }); // ok

// Mixed-sign values are never allowed, even if overall positive:
/* WRONG */ d = Temporal.Duration.from({ hours: 1, minutes: -30 }); // => throws

Temporal.Duration.compare(one: Temporal.Duration | object | string, two: Temporal.Duration | object | string, options?: object) : number

Parameters:

• one (Temporal.Duration or value convertible to one): First duration to compare.
• two (Temporal.Duration or value convertible to one): Second duration to compare.
• options (object): An object with properties representing options for the operation. The following option is recognized:
  • relativeTo (Temporal.PlainDate, Temporal.ZonedDateTime, or value convertible to one of those): The starting point to use when converting between years, months, weeks, and days.

Returns: −1, 0, or 1.

Compares two Temporal.Duration objects. Returns an integer indicating whether one is shorter or longer or is equal to two.

• −1 if one is shorter than two;
• 0 if one and two are equally long;
• 1 if one is longer than two.

If one and two are not Temporal.Duration objects, then they will be converted to one as if they were passed to Temporal.Duration.from().

If any of the years, months, or weeks properties of either of the durations are nonzero, then the relativeTo option is required, since comparing durations with years, months, or weeks requires a point on the calendar to figure out how long they are.

Negative durations are treated as the same as negative numbers for comparison purposes: they are "less" (shorter) than zero.

The relativeTo option may be a Temporal.ZonedDateTime in which case time zone offset changes will be taken into account when comparing days with hours. If relativeTo is a Temporal.PlainDate, then days are always considered equal to 24 hours.

If relativeTo is neither a Temporal.PlainDate nor a Temporal.ZonedDateTime, then it will be converted to one of the two, as if it were first attempted with Temporal.ZonedDateTime.from() and then with Temporal.PlainDate.from(). This means that an ISO 8601 string with a time zone name annotation in it, or a property bag with a timeZone property, will be converted to a Temporal.ZonedDateTime, and an ISO 8601 string without a time zone name or a property bag without a timeZone property will be converted to a Temporal.PlainDate.

This function can be used to sort arrays of Temporal.Duration objects. For example:

one = Temporal.Duration.from({ hours: 79, minutes: 10 });
two = Temporal.Duration.from({ days: 3, hours: 7, seconds: 630 });
three = Temporal.Duration.from({ days: 3, hours: 6, minutes: 50 });
sorted = [one, two, three].sort(Temporal.Duration.compare);
sorted.join(' ');
// => 'P3DT6H50M PT79H10M P3DT7H630S'

// Sorting relative to a date, taking DST changes into account:
relativeTo = Temporal.ZonedDateTime.from('2020-11-01T00:00-07:00[America/Los_Angeles]');
sorted = [one, two, three].sort((one, two) => Temporal.Duration.compare(one, two, { relativeTo }));
sorted.join(' ');
// => 'PT79H10M P3DT6H50M P3DT7H630S'

Properties

duration.years : number

duration.months : number

duration.weeks : number

duration.days : number

duration.hours : number

duration.minutes : number

duration.seconds : number

duration.milliseconds : number

duration.microseconds : number

duration.nanoseconds : number

The above read-only properties allow accessing each component of the duration individually.

Usage examples:

d = Temporal.Duration.from('P1Y2M3W4DT5H6M7.987654321S');
d.years         // => 1
d.months        // => 2
d.weeks         // => 3
d.days          // => 4
d.hours         // => 5
d.minutes       // => 6
d.seconds       // => 7
d.milliseconds  // => 987
d.microseconds  // => 654
d.nanoseconds   // => 321

duration.sign : number

The read-only sign property has the value –1, 0, or 1, depending on whether the duration is negative, zero, or positive.

duration.blank : boolean

The read-only blank property is a convenience property that tells whether duration represents a zero length of time. In other words, duration.blank === (duration.sign === 0).

Usage example:

d = Temporal.Duration.from('PT0S');
d.blank; // => true

d = Temporal.Duration.from({ days: 0, hours: 0, minutes: 0 });
d.blank; // => true

Methods

duration.with(durationLike: object) : Temporal.Duration

Parameters:

• durationLike (object): an object with some or all of the properties of a Temporal.Duration.

Returns: a new Temporal.Duration object.

This method creates a new Temporal.Duration which is a copy of duration, but any properties present on durationLike override the ones already present on duration.

Since Temporal.Duration objects each represent a fixed duration, use this method instead of modifying one.

All non-zero properties of durationLike must have the same sign, and they must additionally have the same sign as the non-zero properties of duration, unless they override all of these non-zero properties. If a property of durationLike is infinity, then this function will throw a RangeError.

Usage example:

duration = Temporal.Duration.from({ months: 50, days: 50, hours: 50, minutes: 100 });
// Perform a balance operation using additional ISO 8601 calendar rules:
let { years, months } = duration;
years += Math.floor(months / 12);
months %= 12;
duration = duration.with({ years, months