Stage 3 Draft / May 29, 2023

Temporal proposal

Introduction

The venerable ECMAScript Date object has a number of challenges, including lack of immutability, lack of support for time zones, lack of support for use cases that require dates only or times only, a confusing and non-ergonomic API, and many other challenges.

The Temporal set of types addresses these challenges with a built-in date and time API for ECMAScript that includes:

Figure 1: Temporal Object Relationships
Figure 2: Temporal String Persistence

This specification consists of three parts:

1 The Temporal Object

The Temporal object:

  • is the intrinsic object %Temporal%.
  • is the initial value of the "Temporal" property of the global object.
  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is not a function object.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.

1.1 Value Properties of the Temporal Object

1.1.1 Temporal [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Temporal".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

1.2 Constructor Properties of the Temporal Object

1.2.1 Temporal.Instant ( . . . )

See 8.

1.2.2 Temporal.PlainDateTime ( . . . )

See 5.

1.2.3 Temporal.PlainDate ( . . . )

See 3.

1.2.4 Temporal.PlainTime ( . . . )

See 4.

1.2.5 Temporal.PlainYearMonth ( . . . )

See 9.

1.2.6 Temporal.PlainMonthDay ( . . . )

See 10.

1.2.7 Temporal.TimeZone ( . . . )

See 11.

1.2.8 Temporal.Duration ( . . . )

See 7.

1.3 Other Properties of the Temporal Object

1.3.1 Temporal.Now

See 2.

2 The Temporal.Now Object

The Temporal.Now object:

  • is an ordinary object.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
  • is not a function object.
  • does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.
  • does not have a [[Call]] internal method; it cannot be invoked as a function.

2.1 Value Properties of the Temporal.Now Object

2.1.1 Temporal.Now [ @@toStringTag ]

The initial value of the @@toStringTag property is the String value "Temporal.Now".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

2.2 Function Properties of the Temporal.Now Object

2.2.1 Temporal.Now.timeZoneId ( )

This function performs the following steps when called:

  1. Return DefaultTimeZone().

2.2.2 Temporal.Now.instant ( )

This function performs the following steps when called:

  1. Return ! SystemInstant().

2.2.3 Temporal.Now.plainDateTime ( calendarLike [ , temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Return ? SystemDateTime(temporalTimeZoneLike, calendarLike).

2.2.4 Temporal.Now.plainDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Return ? SystemDateTime(temporalTimeZoneLike, "iso8601").

2.2.5 Temporal.Now.zonedDateTime ( calendarLike [ , temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Return ? SystemZonedDateTime(temporalTimeZoneLike, calendarLike).

2.2.6 Temporal.Now.zonedDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Return ? SystemZonedDateTime(temporalTimeZoneLike, "iso8601").

2.2.7 Temporal.Now.plainDate ( calendarLike [ , temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let dateTime be ? SystemDateTime(temporalTimeZoneLike, calendarLike).
  2. Return ! CreateTemporalDate(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[Calendar]]).

2.2.8 Temporal.Now.plainDateISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let dateTime be ? SystemDateTime(temporalTimeZoneLike, "iso8601").
  2. Return ! CreateTemporalDate(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], "iso8601").

2.2.9 Temporal.Now.plainTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let dateTime be ? SystemDateTime(temporalTimeZoneLike, "iso8601").
  2. Return ! CreateTemporalTime(dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]]).

2.3 Abstract operations

2.3.1 HostSystemUTCEpochNanoseconds ( global )

The host-defined abstract operation HostSystemUTCEpochNanoseconds takes argument global (a global object) and returns an integer. It allows host environments to reduce the precision of the result. In particular, web browsers artificially limit it to prevent abuse of security flaws (e.g., Spectre) and to avoid certain methods of fingerprinting.

An implementation of HostSystemUTCEpochNanoseconds must conform to the following requirements:

Note

This requirement is necessary if the system clock is set to a time outside the range that Temporal.Instant can represent. This is not expected to affect implementations in practice.

The default implementation of HostSystemUTCEpochNanoseconds performs the following steps when called:

  1. Let ns be the approximate current UTC date and time, in nanoseconds since the epoch.
  2. Return the result of clamping ns between nsMinInstant and nsMaxInstant.

ECMAScript hosts that are not web browsers must use the default implementation of HostSystemUTCEpochNanoseconds.

2.3.2 SystemUTCEpochNanoseconds ( )

  1. Let global be GetGlobalObject().
  2. Return ℤ(HostSystemUTCEpochNanoseconds(global)).

2.3.3 SystemInstant ( )

  1. Let ns be ! SystemUTCEpochNanoseconds().
  2. Return ! CreateTemporalInstant(ns).

2.3.4 SystemDateTime ( temporalTimeZoneLike, calendarLike )

  1. If temporalTimeZoneLike is undefined, then
    1. Let timeZone be DefaultTimeZone().
  2. Else,
    1. Let timeZone be ? ToTemporalTimeZoneSlotValue(temporalTimeZoneLike).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Let instant be ! SystemInstant().
  5. Return ? GetPlainDateTimeFor(timeZone, instant, calendar).

2.3.5 SystemZonedDateTime ( temporalTimeZoneLike, calendarLike )

  1. If temporalTimeZoneLike is undefined, then
    1. Let timeZone be DefaultTimeZone().
  2. Else,
    1. Let timeZone be ? ToTemporalTimeZoneSlotValue(temporalTimeZoneLike).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Let ns be ! SystemUTCEpochNanoseconds().
  5. Return ! CreateTemporalZonedDateTime(ns, timeZone, calendar).

3 Temporal.PlainDate Objects

A Temporal.PlainDate object is an Object that contains integers corresponding to a particular year, month, and day in the ISO8601 calendar, as well as an Object value used to interpret those integers in a particular calendar.

3.1 The Temporal.PlainDate Constructor

The Temporal.PlainDate constructor:

  • creates and initializes a new Temporal.PlainDate object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Temporal.PlainDate behaviour must include a super call to the %Temporal.PlainDate% constructor to create and initialize subclass instances with the necessary internal slots.

3.1.1 Temporal.PlainDate ( isoYear, isoMonth, isoDay [ , calendarLike ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, throw a TypeError exception.
  2. Let y be ? ToIntegerWithTruncation(isoYear).
  3. Let m be ? ToIntegerWithTruncation(isoMonth).
  4. Let d be ? ToIntegerWithTruncation(isoDay).
  5. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike, "iso8601").
  6. Return ? CreateTemporalDate(y, m, d, calendar, NewTarget).

3.2 Properties of the Temporal.PlainDate Constructor

The Temporal.PlainDate constructor:

  • has a [[Prototype]] internal slot whose value is %Function.prototype%.
  • has the following properties:

3.2.1 Temporal.PlainDate.prototype

The initial value of Temporal.PlainDate.prototype is %Temporal.PlainDate.prototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

3.2.2 Temporal.PlainDate.from ( item [ , options ] )

This function performs the following steps when called:

  1. Set options to ? GetOptionsObject(options).
  2. If Type(item) is Object and item has an [[InitializedTemporalDate]] internal slot, then
    1. Perform ? ToTemporalOverflow(options).
    2. Return ! CreateTemporalDate(item.[[ISOYear]], item.[[ISOMonth]], item.[[ISODay]], item.[[Calendar]]).
  3. Return ? ToTemporalDate(item, options).

3.2.3 Temporal.PlainDate.compare ( one, two )

This function performs the following steps when called:

  1. Set one to ? ToTemporalDate(one).
  2. Set two to ? ToTemporalDate(two).
  3. Return 𝔽(! CompareISODate(one.[[ISOYear]], one.[[ISOMonth]], one.[[ISODay]], two.[[ISOYear]], two.[[ISOMonth]], two.[[ISODay]])).

3.3 Properties of the Temporal.PlainDate Prototype Object

The Temporal.PlainDate prototype object

  • is itself an ordinary object.
  • is not a Temporal.PlainDate instance and does not have a [[InitializedTemporalDate]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
Note
An ECMAScript implementation that includes the ECMA-402 Internationalization API extends this prototype with additional properties in order to represent calendar data.

3.3.1 Temporal.PlainDate.prototype.constructor

The initial value of Temporal.PlainDate.prototype.constructor is %Temporal.PlainDate%.

3.3.2 Temporal.PlainDate.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Temporal.PlainDate".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

3.3.3 get Temporal.PlainDate.prototype.calendarId

Temporal.PlainDate.prototype.calendarId is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ? ToTemporalCalendarIdentifier(temporalDate.[[Calendar]]).

3.3.4 get Temporal.PlainDate.prototype.year

Temporal.PlainDate.prototype.year is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarYear(calendar, temporalDate)).

3.3.5 get Temporal.PlainDate.prototype.month

Temporal.PlainDate.prototype.month is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarMonth(calendar, temporalDate)).

3.3.6 get Temporal.PlainDate.prototype.monthCode

Temporal.PlainDate.prototype.monthCode is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return ? CalendarMonthCode(calendar, temporalDate).

3.3.7 get Temporal.PlainDate.prototype.day

Temporal.PlainDate.prototype.day is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDay(calendar, temporalDate)).

3.3.8 get Temporal.PlainDate.prototype.dayOfWeek

Temporal.PlainDate.prototype.dayOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDayOfWeek(calendar, temporalDate)).

3.3.9 get Temporal.PlainDate.prototype.dayOfYear

Temporal.PlainDate.prototype.dayOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDayOfYear(calendar, temporalDate)).

3.3.10 get Temporal.PlainDate.prototype.weekOfYear

Temporal.PlainDate.prototype.weekOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarWeekOfYear(calendar, temporalDate)).

3.3.11 get Temporal.PlainDate.prototype.yearOfWeek

Temporal.PlainDate.prototype.yearOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarYearOfWeek(calendar, temporalDate)).

3.3.12 get Temporal.PlainDate.prototype.daysInWeek

Temporal.PlainDate.prototype.daysInWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInWeek(calendar, temporalDate)).

3.3.13 get Temporal.PlainDate.prototype.daysInMonth

Temporal.PlainDate.prototype.daysInMonth is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInMonth(calendar, temporalDate)).

3.3.14 get Temporal.PlainDate.prototype.daysInYear

Temporal.PlainDate.prototype.daysInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInYear(calendar, temporalDate)).

3.3.15 get Temporal.PlainDate.prototype.monthsInYear

Temporal.PlainDate.prototype.monthsInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return 𝔽(? CalendarMonthsInYear(calendar, temporalDate)).

3.3.16 get Temporal.PlainDate.prototype.inLeapYear

Temporal.PlainDate.prototype.inLeapYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Return ? CalendarInLeapYear(calendar, temporalDate).

3.3.17 Temporal.PlainDate.prototype.toPlainYearMonth ( )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Let fieldNames be ? CalendarFields(calendar, « "monthCode", "year" »).
  5. Let fields be ? PrepareTemporalFields(temporalDate, fieldNames, «»).
  6. Return ? CalendarYearMonthFromFields(calendar, fields).
  7. NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

3.3.18 Temporal.PlainDate.prototype.toPlainMonthDay ( )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be temporalDate.[[Calendar]].
  4. Let fieldNames be ? CalendarFields(calendar, « "day", "monthCode" »).
  5. Let fields be ? PrepareTemporalFields(temporalDate, fieldNames, «»).
  6. Return ? CalendarMonthDayFromFields(calendar, fields).
  7. NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

3.3.19 Temporal.PlainDate.prototype.getISOFields ( )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let fields be OrdinaryObjectCreate(%Object.prototype%).
  4. Perform ! CreateDataPropertyOrThrow(fields, "calendar", temporalDate.[[Calendar]]).
  5. Perform ! CreateDataPropertyOrThrow(fields, "isoDay", 𝔽(temporalDate.[[ISODay]])).
  6. Perform ! CreateDataPropertyOrThrow(fields, "isoMonth", 𝔽(temporalDate.[[ISOMonth]])).
  7. Perform ! CreateDataPropertyOrThrow(fields, "isoYear", 𝔽(temporalDate.[[ISOYear]])).
  8. Return fields.

3.3.20 Temporal.PlainDate.prototype.getCalendar ( )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ToTemporalCalendarObject(temporalDate.[[Calendar]]).

3.3.21 Temporal.PlainDate.prototype.add ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let duration be ? ToTemporalDuration(temporalDurationLike).
  4. Set options to ? GetOptionsObject(options).
  5. Return ? CalendarDateAdd(temporalDate.[[Calendar]], temporalDate, duration, options).

3.3.22 Temporal.PlainDate.prototype.subtract ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let duration be ? ToTemporalDuration(temporalDurationLike).
  4. Set options to ? GetOptionsObject(options).
  5. Let negatedDuration be ! CreateNegatedTemporalDuration(duration).
  6. Return ? CalendarDateAdd(temporalDate.[[Calendar]], temporalDate, negatedDuration, options).

3.3.23 Temporal.PlainDate.prototype.with ( temporalDateLike [ , options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. If Type(temporalDateLike) is not Object, then
    1. Throw a TypeError exception.
  4. Perform ? RejectTemporalLikeObject(temporalDateLike).
  5. Set options to ? GetOptionsObject(options).
  6. Let calendar be temporalDate.[[Calendar]].
  7. Let fieldNames be ? CalendarFields(calendar, « "day", "month", "monthCode", "year" »).
  8. Let fields be ? PrepareTemporalFields(temporalDate, fieldNames, «»).
  9. Let partialDate be ? PrepareTemporalFields(temporalDateLike, fieldNames, partial).
  10. Set fields to ? CalendarMergeFields(calendar, fields, partialDate).
  11. Set fields to ? PrepareTemporalFields(fields, fieldNames, «»).
  12. Return ? CalendarDateFromFields(calendar, fields, options).

3.3.24 Temporal.PlainDate.prototype.withCalendar ( calendarLike )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Return ! CreateTemporalDate(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], calendar).

3.3.25 Temporal.PlainDate.prototype.until ( other [ , options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ? DifferenceTemporalPlainDate(until, temporalDate, other, options).

3.3.26 Temporal.PlainDate.prototype.since ( other [ , options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ? DifferenceTemporalPlainDate(since, temporalDate, other, options).

3.3.27 Temporal.PlainDate.prototype.equals ( other )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Set other to ? ToTemporalDate(other).
  4. If temporalDate.[[ISOYear]] ≠ other.[[ISOYear]], return false.
  5. If temporalDate.[[ISOMonth]] ≠ other.[[ISOMonth]], return false.
  6. If temporalDate.[[ISODay]] ≠ other.[[ISODay]], return false.
  7. Return ? CalendarEquals(temporalDate.[[Calendar]], other.[[Calendar]]).

3.3.28 Temporal.PlainDate.prototype.toPlainDateTime ( [ temporalTime ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. If temporalTime is undefined, then
    1. Return ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], 0, 0, 0, 0, 0, 0, temporalDate.[[Calendar]]).
  4. Set temporalTime to ? ToTemporalTime(temporalTime).
  5. Return ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], temporalDate.[[Calendar]]).

3.3.29 Temporal.PlainDate.prototype.toZonedDateTime ( item )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. If Type(item) is Object, then
    1. If item has an [[InitializedTemporalTimeZone]] internal slot, then
      1. Let timeZone be item.
      2. Let temporalTime be undefined.
    2. Else,
      1. Let timeZoneLike be ? Get(item, "timeZone").
      2. If timeZoneLike is undefined, then
        1. Let timeZone be ? ToTemporalTimeZoneSlotValue(item).
        2. Let temporalTime be undefined.
      3. Else,
        1. Let timeZone be ? ToTemporalTimeZoneSlotValue(timeZoneLike).
        2. Let temporalTime be ? Get(item, "plainTime").
  4. Else,
    1. Let timeZone be ? ToTemporalTimeZoneSlotValue(item).
    2. Let temporalTime be undefined.
  5. If temporalTime is undefined, then
    1. Let temporalDateTime be ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], 0, 0, 0, 0, 0, 0, temporalDate.[[Calendar]]).
  6. Else,
    1. Set temporalTime to ? ToTemporalTime(temporalTime).
    2. Let temporalDateTime be ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], temporalDate.[[Calendar]]).
  7. Let instant be ? GetInstantFor(timeZone, temporalDateTime, "compatible").
  8. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, temporalDate.[[Calendar]]).

3.3.30 Temporal.PlainDate.prototype.toString ( [ options ] )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Set options to ? GetOptionsObject(options).
  4. Let showCalendar be ? ToCalendarNameOption(options).
  5. Return ? TemporalDateToString(temporalDate, showCalendar).

3.3.31 Temporal.PlainDate.prototype.toLocaleString ( [ locales [ , options ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ? TemporalDateToString(temporalDate, "auto").

3.3.32 Temporal.PlainDate.prototype.toJSON ( )

This method performs the following steps when called:

  1. Let temporalDate be the this value.
  2. Perform ? RequireInternalSlot(temporalDate, [[InitializedTemporalDate]]).
  3. Return ? TemporalDateToString(temporalDate, "auto").

3.3.33 Temporal.PlainDate.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.

3.4 Properties of Temporal.PlainDate Instances

Temporal.PlainDate instances are ordinary objects that inherit properties from the %Temporal.PlainDate.prototype% intrinsic object. Temporal.PlainDate instances are initially created with the internal slots described in Table 1.

Table 1: Internal Slots of Temporal.PlainDate Instances
Internal Slot Description
[[InitializedTemporalDate]] The only specified use of this slot is for distinguishing Temporal.PlainDate instances from other objects.
[[ISOYear]] An integer representing the year in the ISO 8601 calendar.
[[ISOMonth]] An integer between 1 and 12, inclusive, representing the month of the year in the ISO 8601 calendar.
[[ISODay]] An integer between 1 and ISODaysInMonth([[ISOYear]], [[ISOMonth]]), inclusive, representing the day of the month in the ISO 8601 calendar.
[[Calendar]] An Object representing the calendar.

3.5 Abstract Operations for Temporal.PlainDate Objects

3.5.1 ISO Date Records

An ISO Date Record is a Record value used to represent a valid calendar date in the ISO 8601 calendar, although the year may be outside of the allowed range for Temporal. ISO Date Records are produced by the abstract operation CreateISODateRecord.

ISO Date Records have the fields listed in Table 2.

Table 2: ISO Date Record Fields
Field Name Value Meaning
[[Year]] an integer The year in the ISO 8601 calendar.
[[Month]] an integer between 1 and 12, inclusive The number of the month in the ISO 8601 calendar.
[[Day]] an integer between 1 and 31, inclusive The number of the day of the month in the ISO 8601 calendar.

3.5.2 CreateISODateRecord ( year, month, day )

The abstract operation CreateISODateRecord takes arguments year (an integer), month (an integer between 1 and 12 inclusive), and day (an integer between 1 and 31 inclusive) and returns an ISO Date Record. It performs the following steps when called:

  1. Assert: IsValidISODate(year, month, day) is true.
  2. Return the Record { [[Year]]: year, [[Month]]: month, [[Day]]: day }.

3.5.3 CreateTemporalDate ( isoYear, isoMonth, isoDay, calendar [ , newTarget ] )

The abstract operation CreateTemporalDate takes arguments isoYear (an integer), isoMonth (an integer), isoDay (an integer), and calendar (a String or Object) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainDate, or an abrupt completion. It creates a Temporal.PlainDate instance and fills the internal slots with valid values. It performs the following steps when called:

  1. If IsValidISODate(isoYear, isoMonth, isoDay) is false, throw a RangeError exception.
  2. If ISODateTimeWithinLimits(isoYear, isoMonth, isoDay, 12, 0, 0, 0, 0, 0) is false, throw a RangeError exception.
  3. If newTarget is not present, set newTarget to %Temporal.PlainDate%.
  4. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDate.prototype%", « [[InitializedTemporalDate]], [[ISOYear]], [[ISOMonth]], [[ISODay]], [[Calendar]] »).
  5. Set object.[[ISOYear]] to isoYear.
  6. Set object.[[ISOMonth]] to isoMonth.
  7. Set object.[[ISODay]] to isoDay.
  8. Set object.[[Calendar]] to calendar.
  9. Return object.
 Note

Deferring to ISODateTimeWithinLimits with an hour of 12 avoids trouble at the extremes of the representable range of dates, which stop just before midnight on each end.

3.5.4 ToTemporalDate ( item [ , options ] )

The abstract operation ToTemporalDate returns its argument item if it is already a Temporal.PlainDate instance, converts item to a new Temporal.PlainDate instance if possible, and throws otherwise.

  1. If options is not present, set options to undefined.
  2. Assert: Type(options) is Object or Undefined.
  3. If Type(item) is Object, then
    1. If item has an [[InitializedTemporalDate]] internal slot, then
      1. Return item.
    2. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Perform ? ToTemporalOverflow(options).
      2. Let instant be ! CreateTemporalInstant(item.[[Nanoseconds]]).
      3. Let plainDateTime be ? GetPlainDateTimeFor(item.[[TimeZone]], instant, item.[[Calendar]]).
      4. Return ! CreateTemporalDate(plainDateTime.[[ISOYear]], plainDateTime.[[ISOMonth]], plainDateTime.[[ISODay]], plainDateTime.[[Calendar]]).
    3. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Perform ? ToTemporalOverflow(options).
      2. Return ! CreateTemporalDate(item.[[ISOYear]], item.[[ISOMonth]], item.[[ISODay]], item.[[Calendar]]).
    4. Let calendar be ? GetTemporalCalendarSlotValueWithISODefault(item).
    5. Let fieldNames be ? CalendarFields(calendar, « "day", "month", "monthCode", "year" »).
    6. Let fields be ? PrepareTemporalFields(item, fieldNames, «»).
    7. Return ? CalendarDateFromFields(calendar, fields, options).
  4. Perform ? ToTemporalOverflow(options).
  5. Let string be ? ToString(item).
  6. Let result be ? ParseTemporalDateString(string).
  7. Assert: IsValidISODate(result.[[Year]], result.[[Month]], result.[[Day]]) is true.
  8. Let calendar be result.[[Calendar]].
  9. If calendar is undefined, set calendar to "iso8601".
  10. If IsBuiltinCalendar(calendar) is false, throw a RangeError exception.
  11. Set calendar to the ASCII-lowercase of calendar.
  12. Return ? CreateTemporalDate(result.[[Year]], result.[[Month]], result.[[Day]], calendar).

3.5.5 DifferenceISODate ( y1, m1, d1, y2, m2, d2, largestUnit )

The abstract operation DifferenceISODate takes arguments y1 (an integer), m1 (an integer), d1 (an integer), y2 (an integer), m2 (an integer), d2 (an integer), and largestUnit ("year", "month", "week", or "day") and returns a Date Duration Record. The return value is the elapsed duration from a first date until a second date, according to the reckoning of the ISO 8601 calendar. No fields larger than largestUnit will be non-zero in the resulting Date Duration Record. It performs the following steps when called:

  1. If largestUnit is "year" or "month", then
    1. Let sign be -(! CompareISODate(y1, m1, d1, y2, m2, d2)).
    2. If sign is 0, return ! CreateDateDurationRecord(0, 0, 0, 0).
    3. Let start be the Record { [[Year]]: y1, [[Month]]: m1, [[Day]]: d1 }.
    4. Let end be the Record { [[Year]]: y2, [[Month]]: m2, [[Day]]: d2 }.
    5. Let years be end.[[Year]] - start.[[Year]].
    6. Let mid be ! AddISODate(y1, m1, d1, years, 0, 0, 0, "constrain").
    7. Let midSign be -(! CompareISODate(mid.[[Year]], mid.[[Month]], mid.[[Day]], y2, m2, d2)).
    8. If midSign is 0, then
      1. If largestUnit is "year", return ! CreateDateDurationRecord(years, 0, 0, 0).
      2. Return ! CreateDateDurationRecord(0, years × 12, 0, 0).
    9. Let months be end.[[Month]] - start.[[Month]].
    10. If midSign is not equal to sign, then
      1. Set years to years - sign.
      2. Set months to months + sign × 12.
    11. Set mid to ! AddISODate(y1, m1, d1, years, months, 0, 0, "constrain").
    12. Set midSign to -(! CompareISODate(mid.[[Year]], mid.[[Month]], mid.[[Day]], y2, m2, d2)).
    13. If midSign is 0, then
      1. If largestUnit is "year", return ! CreateDateDurationRecord(years, months, 0, 0).
      2. Return ! CreateDateDurationRecord(0, months + years × 12, 0, 0).
    14. If midSign is not equal to sign, then
      1. Set months to months - sign.
      2. If months is equal to -sign, then
        1. Set years to years - sign.
        2. Set months to 11 × sign.
      3. Set mid to ! AddISODate(y1, m1, d1, years, months, 0, 0, "constrain").
    15. If mid.[[Month]] = end.[[Month]], then
      1. Assert: mid.[[Year]] = end.[[Year]].
      2. Let days be end.[[Day]] - mid.[[Day]].
    16. Else if sign < 0, let days be -mid.[[Day]] - (ISODaysInMonth(end.[[Year]], end.[[Month]]) - end.[[Day]]).
    17. Else, let days be end.[[Day]] + (ISODaysInMonth(mid.[[Year]], mid.[[Month]]) - mid.[[Day]]).
    18. If largestUnit is "month", then
      1. Set months to months + years × 12.
      2. Set years to 0.
    19. Return ! CreateDateDurationRecord(years, months, 0, days).
  2. Else,
    1. Assert: largestUnit is "day" or "week".
    2. Let epochDays1 be ISODateToEpochDays(y1, m1 - 1, d1).
    3. Let epochDays2 be ISODateToEpochDays(y2, m2 - 1, d2).
    4. Let days be epochDays2 - epochDays1.
    5. Let weeks be 0.
    6. If largestUnit is "week", then
      1. Set weeks to truncate(days / 7).
      2. Set days to remainder(days, 7).
    7. Return ! CreateDateDurationRecord(0, 0, weeks, days).

3.5.6 RegulateISODate ( year, month, day, overflow )

The abstract operation RegulateISODate takes arguments year (an integer), month (an integer), day (an integer), and overflow ("constrain" or "reject") and returns either a normal completion containing an ISO Date Record, or an abrupt completion. It performs the overflow correction given by overflow on the values year, month, and day, in order to arrive at a valid date in the ISO 8601 calendar, as determined by IsValidISODate. For "reject", values that do not form a valid date cause an exception to be thrown. For "constrain", values that do not form a valid date are clamped to the correct range. It performs the following steps when called:

  1. If overflow is "constrain", then
    1. Set month to the result of clamping month between 1 and 12.
    2. Let daysInMonth be ISODaysInMonth(year, month).
    3. Set day to the result of clamping day between 1 and daysInMonth.
    4. Return CreateISODateRecord(year, month, day).
  2. Else,
    1. Assert: overflow is "reject".
    2. If IsValidISODate(year, month, day) is false, throw a RangeError exception.
    3. Return CreateISODateRecord(year, month, day).

3.5.7 IsValidISODate ( year, month, day )

The abstract operation IsValidISODate takes arguments year (an integer), month (an integer), and day (an integer) and returns a Boolean. The return value is true if its arguments form a valid date in the ISO 8601 calendar, and false otherwise. This includes dates that may fall outside of the allowed range for Temporal. It performs the following steps when called:

  1. If month < 1 or month > 12, then
    1. Return false.
  2. Let daysInMonth be ISODaysInMonth(year, month).
  3. If day < 1 or day > daysInMonth, then
    1. Return false.
  4. Return true.

3.5.8 BalanceISODate ( year, month, day )

The abstract operation BalanceISODate takes arguments year (an integer), month (an integer), and day (an integer) and returns an ISO Date Record. It converts the given year, month, and day into a valid calendar date in the ISO 8601 calendar as given by IsValidISODate, by overflowing out-of-range month or day values into the next-highest unit. This date may be outside the range given by ISODateTimeWithinLimits. It performs the following steps when called:

  1. Let epochDays be ISODateToEpochDays(year, month - 1, day).
  2. Let ms be EpochDaysToEpochMs(epochDays, 0).
  3. Return CreateISODateRecord(EpochTimeToEpochYear(ms), EpochTimeToMonthInYear(ms) + 1, EpochTimeToDate(ms)).

3.5.9 PadISOYear ( y )

  1. Assert: y is an integer.
  2. If y ≥ 0 and y ≤ 9999, then
    1. Return ToZeroPaddedDecimalString(y, 4).
  3. If y > 0, let yearSign be "+"; otherwise, let yearSign be "-".
  4. Let year be ToZeroPaddedDecimalString(abs(y), 6).
  5. Return the string-concatenation of yearSign and year.

3.5.10 TemporalDateToString ( temporalDate, showCalendar )

  1. Assert: Type(temporalDate) is Object.
  2. Assert: temporalDate has an [[InitializedTemporalDate]] internal slot.
  3. Let year be ! PadISOYear(temporalDate.[[ISOYear]]).
  4. Let month be ToZeroPaddedDecimalString(temporalDate.[[ISOMonth]], 2).
  5. Let day be ToZeroPaddedDecimalString(temporalDate.[[ISODay]], 2).
  6. Let calendar be ? MaybeFormatCalendarAnnotation(temporalDate.[[Calendar]], showCalendar).
  7. Return the string-concatenation of year, the code unit 0x002D (HYPHEN-MINUS), month, the code unit 0x002D (HYPHEN-MINUS), day, and calendar.

3.5.11 AddISODate ( year, month, day, years, months, weeks, days, overflow )

  1. Assert: year, month, day, years, months, weeks, and days are integers.
  2. Assert: overflow is either "constrain" or "reject".
  3. Let intermediate be ! BalanceISOYearMonth(year + years, month + months).
  4. Let intermediate be ? RegulateISODate(intermediate.[[Year]], intermediate.[[Month]], day, overflow).
  5. Set days to days + 7 × weeks.
  6. Let d be intermediate.[[Day]] + days.
  7. Return BalanceISODate(intermediate.[[Year]], intermediate.[[Month]], d).

3.5.12 CompareISODate ( y1, m1, d1, y2, m2, d2 )

  1. Assert: y1, m1, d1, y2, m2, and d2 are integers.
  2. If y1 > y2, return 1.
  3. If y1 < y2, return -1.
  4. If m1 > m2, return 1.
  5. If m1 < m2, return -1.
  6. If d1 > d2, return 1.
  7. If d1 < d2, return -1.
  8. Return 0.

3.5.13 DifferenceTemporalPlainDate ( operation, temporalDate, other, options )

The abstract operation DifferenceTemporalPlainDate takes arguments operation (since or until), temporalDate (a Temporal.PlainDate), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by temporalDate and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:

  1. If operation is since, let sign be -1. Otherwise, let sign be 1.
  2. Set other to ? ToTemporalDate(other).
  3. If ? CalendarEquals(temporalDate.[[Calendar]], other.[[Calendar]]) is false, throw a RangeError exception.
  4. Let resolvedOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  5. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, date, « », "day", "day").
  6. Perform ! CreateDataPropertyOrThrow(resolvedOptions, "largestUnit", settings.[[LargestUnit]]).
  7. Let result be ? CalendarDateUntil(temporalDate.[[Calendar]], temporalDate, other, resolvedOptions).
  8. If settings.[[SmallestUnit]] is not "day" or settings.[[RoundingIncrement]] ≠ 1, then
    1. Set result to (? RoundDuration(result.[[Years]], result.[[Months]], result.[[Weeks]], result.[[Days]], 0, 0, 0, 0, 0, 0, settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]], temporalDate)).[[DurationRecord]].
  9. Return ! CreateTemporalDuration(sign × result.[[Years]], sign × result.[[Months]], sign × result.[[Weeks]], sign × result.[[Days]], 0, 0, 0, 0, 0, 0).

4 Temporal.PlainTime Objects

A Temporal.PlainTime object is an Object that contains integers corresponding to a particular hour, minute, second, millisecond, microsecond, and nanosecond.

4.1 The Temporal.PlainTime Constructor

The Temporal.PlainTime constructor:

  • creates and initializes a new Temporal.PlainTime object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Temporal.PlainTime behaviour must include a super call to the %Temporal.PlainTime% constructor to create and initialize subclass instances with the necessary internal slots.

4.1.1 Temporal.PlainTime ( [ hour [ , minute [ , second [ , millisecond [ , microsecond [ , nanosecond ] ] ] ] ] ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, then
    1. Throw a TypeError exception.
  2. If hour is undefined, set hour to 0; else set hour to ? ToIntegerWithTruncation(hour).
  3. If minute is undefined, set minute to 0; else set minute to ? ToIntegerWithTruncation(minute).
  4. If second is undefined, set second to 0; else set second to ? ToIntegerWithTruncation(second).
  5. If millisecond is undefined, set millisecond to 0; else set millisecond to ? ToIntegerWithTruncation(millisecond).
  6. If microsecond is undefined, set microsecond to 0; else set microsecond to ? ToIntegerWithTruncation(microsecond).
  7. If nanosecond is undefined, set nanosecond to 0; else set nanosecond to ? ToIntegerWithTruncation(nanosecond).
  8. Return ? CreateTemporalTime(hour, minute, second, millisecond, microsecond, nanosecond, NewTarget).

4.2 Properties of the Temporal.PlainTime Constructor

The value of the [[Prototype]] internal slot of the Temporal.PlainTime constructor is the intrinsic object %Function.prototype%.

The Temporal.PlainTime constructor has the following properties:

4.2.1 Temporal.PlainTime.prototype

The initial value of Temporal.PlainTime.prototype is %Temporal.PlainTime.prototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

4.2.2 Temporal.PlainTime.from ( item [ , options ] )

This function performs the following steps when called:

  1. Set options to ? GetOptionsObject(options).
  2. Let overflow be ? ToTemporalOverflow(options).
  3. If Type(item) is Object and item has an [[InitializedTemporalTime]] internal slot, then
    1. Return ! CreateTemporalTime(item.[[ISOHour]], item.[[ISOMinute]], item.[[ISOSecond]], item.[[ISOMillisecond]], item.[[ISOMicrosecond]], item.[[ISONanosecond]]).
  4. Return ? ToTemporalTime(item, overflow).

4.2.3 Temporal.PlainTime.compare ( one, two )

This function performs the following steps when called:

  1. Set one to ? ToTemporalTime(one).
  2. Set two to ? ToTemporalTime(two).
  3. Return 𝔽(! CompareTemporalTime(one.[[ISOHour]], one.[[ISOMinute]], one.[[ISOSecond]], one.[[ISOMillisecond]], one.[[ISOMicrosecond]], one.[[ISONanosecond]], two.[[ISOHour]], two.[[ISOMinute]], two.[[ISOSecond]], two.[[ISOMillisecond]], two.[[ISOMicrosecond]], two.[[ISONanosecond]])).

4.3 Properties of the Temporal.PlainTime Prototype Object

The Temporal.PlainTime prototype object

  • is itself an ordinary object.
  • is not a Temporal.PlainTime instance and does not have a [[InitializedTemporalTime]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.

4.3.1 Temporal.PlainTime.prototype.constructor

The initial value of Temporal.PlainTime.prototype.constructor is %Temporal.PlainTime%.

4.3.2 Temporal.PlainTime.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Temporal.PlainTime".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

4.3.3 get Temporal.PlainTime.prototype.hour

Temporal.PlainTime.prototype.hour is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISOHour]]).

4.3.4 get Temporal.PlainTime.prototype.minute

Temporal.PlainTime.prototype.minute is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISOMinute]]).

4.3.5 get Temporal.PlainTime.prototype.second

Temporal.PlainTime.prototype.second is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISOSecond]]).

4.3.6 get Temporal.PlainTime.prototype.millisecond

Temporal.PlainTime.prototype.millisecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISOMillisecond]]).

4.3.7 get Temporal.PlainTime.prototype.microsecond

Temporal.PlainTime.prototype.microsecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISOMicrosecond]]).

4.3.8 get Temporal.PlainTime.prototype.nanosecond

Temporal.PlainTime.prototype.nanosecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return 𝔽(temporalTime.[[ISONanosecond]]).

4.3.9 Temporal.PlainTime.prototype.add ( temporalDurationLike )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromPlainTime(add, temporalTime, temporalDurationLike).

4.3.10 Temporal.PlainTime.prototype.subtract ( temporalDurationLike )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromPlainTime(subtract, temporalTime, temporalDurationLike).

4.3.11 Temporal.PlainTime.prototype.with ( temporalTimeLike [ , options ] )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. If Type(temporalTimeLike) is not Object, then
    1. Throw a TypeError exception.
  4. Perform ? RejectTemporalLikeObject(temporalTimeLike).
  5. Set options to ? GetOptionsObject(options).
  6. Let overflow be ? ToTemporalOverflow(options).
  7. Let partialTime be ? ToTemporalTimeRecord(temporalTimeLike, partial).
  8. If partialTime.[[Hour]] is not undefined, then
    1. Let hour be partialTime.[[Hour]].
  9. Else,
    1. Let hour be temporalTime.[[ISOHour]].
  10. If partialTime.[[Minute]] is not undefined, then
    1. Let minute be partialTime.[[Minute]].
  11. Else,
    1. Let minute be temporalTime.[[ISOMinute]].
  12. If partialTime.[[Second]] is not undefined, then
    1. Let second be partialTime.[[Second]].
  13. Else,
    1. Let second be temporalTime.[[ISOSecond]].
  14. If partialTime.[[Millisecond]] is not undefined, then
    1. Let millisecond be partialTime.[[Millisecond]].
  15. Else,
    1. Let millisecond be temporalTime.[[ISOMillisecond]].
  16. If partialTime.[[Microsecond]] is not undefined, then
    1. Let microsecond be partialTime.[[Microsecond]].
  17. Else,
    1. Let microsecond be temporalTime.[[ISOMicrosecond]].
  18. If partialTime.[[Nanosecond]] is not undefined, then
    1. Let nanosecond be partialTime.[[Nanosecond]].
  19. Else,
    1. Let nanosecond be temporalTime.[[ISONanosecond]].
  20. Let result be ? RegulateTime(hour, minute, second, millisecond, microsecond, nanosecond, overflow).
  21. Return ! CreateTemporalTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]).

4.3.12 Temporal.PlainTime.prototype.until ( other [ , options ] )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ? DifferenceTemporalPlainTime(until, temporalTime, other, options).

4.3.13 Temporal.PlainTime.prototype.since ( other [ , options ] )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ? DifferenceTemporalPlainTime(since, temporalTime, other, options).

4.3.14 Temporal.PlainTime.prototype.round ( roundTo )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. If roundTo is undefined, then
    1. Throw a TypeError exception.
  4. If Type(roundTo) is String, then
    1. Let paramString be roundTo.
    2. Set roundTo to OrdinaryObjectCreate(null).
    3. Perform ! CreateDataPropertyOrThrow(roundTo, "smallestUnit", paramString).
  5. Else,
    1. Set roundTo to ? GetOptionsObject(roundTo).
  6. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
  7. Let roundingIncrement be ? ToTemporalRoundingIncrement(roundTo).
  8. Let roundingMode be ? ToTemporalRoundingMode(roundTo, "halfExpand").
  9. Let smallestUnit be ? GetTemporalUnit(roundTo, "smallestUnit", time, required).
  10. Let maximum be ! MaximumTemporalDurationRoundingIncrement(smallestUnit).
  11. Assert: maximum is not undefined.
  12. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, false).
  13. Let result be ! RoundTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], roundingIncrement, smallestUnit, roundingMode).
  14. Return ! CreateTemporalTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]).

4.3.15 Temporal.PlainTime.prototype.equals ( other )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Set other to ? ToTemporalTime(other).
  4. If temporalTime.[[ISOHour]] ≠ other.[[ISOHour]], return false.
  5. If temporalTime.[[ISOMinute]] ≠ other.[[ISOMinute]], return false.
  6. If temporalTime.[[ISOSecond]] ≠ other.[[ISOSecond]], return false.
  7. If temporalTime.[[ISOMillisecond]] ≠ other.[[ISOMillisecond]], return false.
  8. If temporalTime.[[ISOMicrosecond]] ≠ other.[[ISOMicrosecond]], return false.
  9. If temporalTime.[[ISONanosecond]] ≠ other.[[ISONanosecond]], return false.
  10. Return true.

4.3.16 Temporal.PlainTime.prototype.toPlainDateTime ( temporalDate )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Set temporalDate to ? ToTemporalDate(temporalDate).
  4. Return ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], temporalDate.[[Calendar]]).

4.3.17 Temporal.PlainTime.prototype.toZonedDateTime ( item )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. If Type(item) is not Object, then
    1. Throw a TypeError exception.
  4. Let temporalDateLike be ? Get(item, "plainDate").
  5. If temporalDateLike is undefined, then
    1. Throw a TypeError exception.
  6. Let temporalDate be ? ToTemporalDate(temporalDateLike).
  7. Let temporalTimeZoneLike be ? Get(item, "timeZone").
  8. If temporalTimeZoneLike is undefined, then
    1. Throw a TypeError exception.
  9. Let timeZone be ? ToTemporalTimeZoneSlotValue(temporalTimeZoneLike).
  10. Let temporalDateTime be ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], temporalDate.[[Calendar]]).
  11. Let instant be ? GetInstantFor(timeZone, temporalDateTime, "compatible").
  12. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, temporalDate.[[Calendar]]).

4.3.18 Temporal.PlainTime.prototype.getISOFields ( )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Let fields be OrdinaryObjectCreate(%Object.prototype%).
  4. Perform ! CreateDataPropertyOrThrow(fields, "isoHour", 𝔽(temporalTime.[[ISOHour]])).
  5. Perform ! CreateDataPropertyOrThrow(fields, "isoMicrosecond", 𝔽(temporalTime.[[ISOMicrosecond]])).
  6. Perform ! CreateDataPropertyOrThrow(fields, "isoMillisecond", 𝔽(temporalTime.[[ISOMillisecond]])).
  7. Perform ! CreateDataPropertyOrThrow(fields, "isoMinute", 𝔽(temporalTime.[[ISOMinute]])).
  8. Perform ! CreateDataPropertyOrThrow(fields, "isoNanosecond", 𝔽(temporalTime.[[ISONanosecond]])).
  9. Perform ! CreateDataPropertyOrThrow(fields, "isoSecond", 𝔽(temporalTime.[[ISOSecond]])).
  10. Return fields.

4.3.19 Temporal.PlainTime.prototype.toString ( [ options ] )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Set options to ? GetOptionsObject(options).
  4. NOTE: The following steps read options and perform independent validation in alphabetical order (ToFractionalSecondDigits reads "fractionalSecondDigits" and ToTemporalRoundingMode reads "roundingMode").
  5. Let digits be ? ToFractionalSecondDigits(options).
  6. Let roundingMode be ? ToTemporalRoundingMode(options, "trunc").
  7. Let smallestUnit be ? GetTemporalUnit(options, "smallestUnit", time, undefined).
  8. If smallestUnit is "hour", throw a RangeError exception.
  9. Let precision be ToSecondsStringPrecisionRecord(smallestUnit, digits).
  10. Let roundResult be ! RoundTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], precision.[[Increment]], precision.[[Unit]], roundingMode).
  11. Return ! TemporalTimeToString(roundResult.[[Hour]], roundResult.[[Minute]], roundResult.[[Second]], roundResult.[[Millisecond]], roundResult.[[Microsecond]], roundResult.[[Nanosecond]], precision.[[Precision]]).

4.3.20 Temporal.PlainTime.prototype.toLocaleString ( [ locales [ , options ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ! TemporalTimeToString(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], "auto").

4.3.21 Temporal.PlainTime.prototype.toJSON ( )

This method performs the following steps when called:

  1. Let temporalTime be the this value.
  2. Perform ? RequireInternalSlot(temporalTime, [[InitializedTemporalTime]]).
  3. Return ! TemporalTimeToString(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], "auto").

4.3.22 Temporal.PlainTime.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.

4.4 Properties of Temporal.PlainTime Instances

Temporal.PlainTime instances are ordinary objects that inherit properties from the %Temporal.PlainTime.prototype% intrinsic object. Temporal.PlainTime instances are initially created with the internal slots described in Table 3.

Table 3: Internal Slots of Temporal.PlainTime Instances
Internal Slot Description
[[InitializedTemporalTime]] The only specified use of this slot is for distinguishing Temporal.PlainTime instances from other objects.
[[ISOHour]] An integer between 0 and 23, inclusive, representing the hour of the day.
[[ISOMinute]] An integer between 0 and 59, inclusive, representing the minute of the hour.
[[ISOSecond]] An integer between 0 and 59, inclusive, representing the second within the minute.
[[ISOMillisecond]] An integer between 0 and 999, inclusive, representing the millisecond within the second.
[[ISOMicrosecond]] An integer between 0 and 999, inclusive, representing the microsecond within the millisecond.
[[ISONanosecond]] An integer between 0 and 999, inclusive, representing the nanosecond within the microsecond.

4.5 Abstract operations

4.5.1 DifferenceTime ( h1, min1, s1, ms1, mus1, ns1, h2, min2, s2, ms2, mus2, ns2 )

The abstract operation DifferenceTime takes arguments h1 (an integer between 0 and 23 inclusive), min1 (an integer between 0 and 59 inclusive), s1 (an integer between 0 and 59 inclusive), ms1 (an integer between 0 and 999 inclusive), mus1 (an integer between 0 and 999 inclusive), ns1 (an integer between 0 and 999 inclusive), h2 (an integer between 0 and 23 inclusive), min2 (an integer between 0 and 59 inclusive), s2 (an integer between 0 and 59 inclusive), ms2 (an integer between 0 and 999 inclusive), mus2 (an integer between 0 and 999 inclusive), and ns2 (an integer between 0 and 999 inclusive). It returns a Time Duration Record with the elapsed duration from a first wall-clock time, until a second wall-clock time. It performs the following steps when called:

  1. Let hours be h2 - h1.
  2. Let minutes be min2 - min1.
  3. Let seconds be s2 - s1.
  4. Let milliseconds be ms2 - ms1.
  5. Let microseconds be mus2 - mus1.
  6. Let nanoseconds be ns2 - ns1.
  7. Let sign be ! DurationSign(0, 0, 0, 0, hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
  8. Let bt be ! BalanceTime(hours × sign, minutes × sign, seconds × sign, milliseconds × sign, microseconds × sign, nanoseconds × sign).
  9. Assert: bt.[[Days]] is 0.
  10. Return ! CreateTimeDurationRecord(0, bt.[[Hour]] × sign, bt.[[Minute]] × sign, bt.[[Second]] × sign, bt.[[Millisecond]] × sign, bt.[[Microsecond]] × sign, bt.[[Nanosecond]] × sign).

4.5.2 ToTemporalTime ( item [ , overflow ] )

The abstract operation ToTemporalTime returns its argument item if it is already a Temporal.PlainTime instance, converts item to a new Temporal.PlainTime instance if possible, and throws otherwise.

  1. If overflow is not present, set overflow to "constrain".
  2. Assert: overflow is either "constrain" or "reject".
  3. If Type(item) is Object, then
    1. If item has an [[InitializedTemporalTime]] internal slot, then
      1. Return item.
    2. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Let instant be ! CreateTemporalInstant(item.[[Nanoseconds]]).
      2. Let plainDateTime be ? GetPlainDateTimeFor(item.[[TimeZone]], instant, item.[[Calendar]]).
      3. Return ! CreateTemporalTime(plainDateTime.[[ISOHour]], plainDateTime.[[ISOMinute]], plainDateTime.[[ISOSecond]], plainDateTime.[[ISOMillisecond]], plainDateTime.[[ISOMicrosecond]], plainDateTime.[[ISONanosecond]]).
    3. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Return ! CreateTemporalTime(item.[[ISOHour]], item.[[ISOMinute]], item.[[ISOSecond]], item.[[ISOMillisecond]], item.[[ISOMicrosecond]], item.[[ISONanosecond]]).
    4. Let result be ? ToTemporalTimeRecord(item).
    5. Set result to ? RegulateTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], overflow).
  4. Else,
    1. Let string be ? ToString(item).
    2. Let result be ? ParseTemporalTimeString(string).
    3. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
  5. Return ! CreateTemporalTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]).

4.5.3 RegulateTime ( hour, minute, second, millisecond, microsecond, nanosecond, overflow )

  1. Assert: hour, minute, second, millisecond, microsecond and nanosecond are integers.
  2. Assert: overflow is either "constrain" or "reject".
  3. If overflow is "constrain", then
    1. Return ! ConstrainTime(hour, minute, second, millisecond, microsecond, nanosecond).
  4. Else,
    1. Assert: overflow is "reject".
    2. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
    3. Return the Record { [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond }.

4.5.4 IsValidTime ( hour, minute, second, millisecond, microsecond, nanosecond )

The abstract operation IsValidTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and returns a Boolean. The return value is true if its arguments form a valid time of day, and false otherwise. Leap seconds are not taken into account. It performs the following steps when called:

  1. If hour < 0 or hour > 23, then
    1. Return false.
  2. If minute < 0 or minute > 59, then
    1. Return false.
  3. If second < 0 or second > 59, then
    1. Return false.
  4. If millisecond < 0 or millisecond > 999, then
    1. Return false.
  5. If microsecond < 0 or microsecond > 999, then
    1. Return false.
  6. If nanosecond < 0 or nanosecond > 999, then
    1. Return false.
  7. Return true.

4.5.5 BalanceTime ( hour, minute, second, millisecond, microsecond, nanosecond )

  1. Assert: hour, minute, second, millisecond, microsecond, and nanosecond are integers.
  2. Set microsecond to microsecond + floor(nanosecond / 1000).
  3. Set nanosecond to nanosecond modulo 1000.
  4. Set millisecond to millisecond + floor(microsecond / 1000).
  5. Set microsecond to microsecond modulo 1000.
  6. Set second to second + floor(millisecond / 1000).
  7. Set millisecond to millisecond modulo 1000.
  8. Set minute to minute + floor(second / 60).
  9. Set second to second modulo 60.
  10. Set hour to hour + floor(minute / 60).
  11. Set minute to minute modulo 60.
  12. Let days be floor(hour / 24).
  13. Set hour to hour modulo 24.
  14. Return the Record { [[Days]]: days, [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond }.

4.5.6 ConstrainTime ( hour, minute, second, millisecond, microsecond, nanosecond )

  1. Assert: hour, minute, second, millisecond, microsecond, and nanosecond are integers.
  2. Set hour to the result of clamping hour between 0 and 23.
  3. Set minute to the result of clamping minute between 0 and 59.
  4. Set second to the result of clamping second between 0 and 59.
  5. Set millisecond to the result of clamping millisecond between 0 and 999.
  6. Set microsecond to the result of clamping microsecond between 0 and 999.
  7. Set nanosecond to the result of clamping nanosecond between 0 and 999.
  8. Return the Record { [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond }.

4.5.7 CreateTemporalTime ( hour, minute, second, millisecond, microsecond, nanosecond [ , newTarget ] )

The abstract operation CreateTemporalTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainTime, or an abrupt completion. It creates a new Temporal.PlainTime instance and fills the internal slots with valid values. It performs the following steps when called:

  1. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
  2. If newTarget is not present, set newTarget to %Temporal.PlainTime%.
  3. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainTime.prototype%", « [[InitializedTemporalTime]], [[ISOHour]], [[ISOMinute]], [[ISOSecond]], [[ISOMillisecond]], [[ISOMicrosecond]], [[ISONanosecond]] »).
  4. Set object.[[ISOHour]] to hour.
  5. Set object.[[ISOMinute]] to minute.
  6. Set object.[[ISOSecond]] to second.
  7. Set object.[[ISOMillisecond]] to millisecond.
  8. Set object.[[ISOMicrosecond]] to microsecond.
  9. Set object.[[ISONanosecond]] to nanosecond.
  10. Return object.

4.5.8 ToTemporalTimeRecord ( temporalTimeLike [ , completeness ] )

The abstract operation ToTemporalTimeRecord takes argument temporalTimeLike (an Object) and optional argument completeness (partial or complete) and returns either a normal completion containing a TemporalTimeLike Record, or an abrupt completion. It performs the following steps when called:

  1. If completeness is not present, set completeness to complete.
  2. Let partial be ? PrepareTemporalFields(temporalTimeLike, « "hour", "microsecond", "millisecond", "minute", "nanosecond", "second" », partial).
  3. If completeness is complete, then
    1. Let result be a new TemporalTimeLike Record with each field set to 0.
  4. Else,
    1. Let result be a new TemporalTimeLike Record with each field set to undefined.
  5. Let hourDesc be OrdinaryGetOwnProperty(partial, "hour").
  6. If hourDesc is not undefined, then
    1. Assert: hourDesc is a data Property Descriptor.
    2. Set result.[[Hour]] to ℝ(hourDesc.[[Value]]).
  7. Let minuteDesc be OrdinaryGetOwnProperty(partial, "minute").
  8. If minuteDesc is not undefined, then
    1. Assert: minuteDesc is a data Property Descriptor.
    2. Set result.[[Minute]] to ℝ(minuteDesc.[[Value]]).
  9. Let secondDesc be OrdinaryGetOwnProperty(partial, "second").
  10. If secondDesc is not undefined, then
    1. Assert: secondDesc is a data Property Descriptor.
    2. Set result.[[Second]] to ℝ(secondDesc.[[Value]]).
  11. Let millisecondDesc be OrdinaryGetOwnProperty(partial, "millisecond").
  12. If millisecondDesc is not undefined, then
    1. Assert: millisecondDesc is a data Property Descriptor.
    2. Set result.[[Millisecond]] to ℝ(millisecondDesc.[[Value]]).
  13. Let microsecondDesc be OrdinaryGetOwnProperty(partial, "microsecond").
  14. If microsecondDesc is not undefined, then
    1. Assert: microsecondDesc is a data Property Descriptor.
    2. Set result.[[Microsecond]] to ℝ(microsecondDesc.[[Value]]).
  15. Let nanosecondDesc be OrdinaryGetOwnProperty(partial, "nanosecond").
  16. If nanosecondDesc is not undefined, then
    1. Assert: nanosecondDesc is a data Property Descriptor.
    2. Set result.[[Nanosecond]] to ℝ(nanosecondDesc.[[Value]]).
  17. Return result.
Table 4: TemporalTimeLike Record Fields
Field Name Property Name
[[Hour]] "hour"
[[Minute]] "minute"
[[Second]] "second"
[[Millisecond]] "millisecond"
[[Microsecond]] "microsecond"
[[Nanosecond]] "nanosecond"

4.5.9 TemporalTimeToString ( hour, minute, second, millisecond, microsecond, nanosecond, precision )

  1. Assert: hour, minute, second, millisecond, microsecond and nanosecond are integers.
  2. Let hour be ToZeroPaddedDecimalString(hour, 2).
  3. Let minute be ToZeroPaddedDecimalString(minute, 2).
  4. Let seconds be ! FormatSecondsStringPart(second, millisecond, microsecond, nanosecond, precision).
  5. Return the string-concatenation of hour, the code unit 0x003A (COLON), minute, and seconds.

4.5.10 CompareTemporalTime ( h1, min1, s1, ms1, mus1, ns1, h2, min2, s2, ms2, mus2, ns2 )

  1. Assert: h1, min1, s1, ms1, mus1, ns1, h2, min2, s2, ms2, mus2, and ns2 are integers.
  2. If h1 > h2, return 1.
  3. If h1 < h2, return -1.
  4. If min1 > min2, return 1.
  5. If min1 < min2, return -1.
  6. If s1 > s2, return 1.
  7. If s1 < s2, return -1.
  8. If ms1 > ms2, return 1.
  9. If ms1 < ms2, return -1.
  10. If mus1 > mus2, return 1.
  11. If mus1 < mus2, return -1.
  12. If ns1 > ns2, return 1.
  13. If ns1 < ns2, return -1.
  14. Return 0.

4.5.11 AddTime ( hour, minute, second, millisecond, microsecond, nanosecond, hours, minutes, seconds, milliseconds, microseconds, nanoseconds )

  1. Assert: hour, minute, second, millisecond, microsecond, nanosecond, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds are integers.
  2. Assert: IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is true.
  3. Let hour be hour + hours.
  4. Let minute be minute + minutes.
  5. Let second be second + seconds.
  6. Let millisecond be millisecond + milliseconds.
  7. Let microsecond be microsecond + microseconds.
  8. Let nanosecond be nanosecond + nanoseconds.
  9. Return ! BalanceTime(hour, minute, second, millisecond, microsecond, nanosecond).

4.5.12 RoundTime ( hour, minute, second, millisecond, microsecond, nanosecond, increment, unit, roundingMode [ , dayLengthNs ] )

The abstract operation RoundTime rounds a time to the given increment, optionally adjusting for a non-24-hour day.

  1. Assert: hour, minute, second, millisecond, microsecond, nanosecond, and increment are integers.
  2. Assert: IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is true.
  3. Let fractionalSecond be nanosecond × 10-9 + microsecond × 10-6 + millisecond × 10-3 + second.
  4. If unit is "day", then
    1. If dayLengthNs is not present, set dayLengthNs to nsPerDay.
    2. Let quantity be (((((hour × 60 + minute) × 60 + second) × 1000 + millisecond) × 1000 + microsecond) × 1000 + nanosecond) / dayLengthNs.
  5. Else if unit is "hour", then
    1. Let quantity be (fractionalSecond / 60 + minute) / 60 + hour.
  6. Else if unit is "minute", then
    1. Let quantity be fractionalSecond / 60 + minute.
  7. Else if unit is "second", then
    1. Let quantity be fractionalSecond.
  8. Else if unit is "millisecond", then
    1. Let quantity be nanosecond × 10-6 + microsecond × 10-3 + millisecond.
  9. Else if unit is "microsecond", then
    1. Let quantity be nanosecond × 10-3 + microsecond.
  10. Else,
    1. Assert: unit is "nanosecond".
    2. Let quantity be nanosecond.
  11. Let result be RoundNumberToIncrement(quantity, increment, roundingMode).
  12. If unit is "day", then
    1. Return the Record { [[Days]]: result, [[Hour]]: 0, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0 }.
  13. If unit is "hour", then
    1. Return ! BalanceTime(result, 0, 0, 0, 0, 0).
  14. If unit is "minute", then
    1. Return ! BalanceTime(hour, result, 0, 0, 0, 0).
  15. If unit is "second", then
    1. Return ! BalanceTime(hour, minute, result, 0, 0, 0).
  16. If unit is "millisecond", then
    1. Return ! BalanceTime(hour, minute, second, result, 0, 0).
  17. If unit is "microsecond", then
    1. Return ! BalanceTime(hour, minute, second, millisecond, result, 0).
  18. Assert: unit is "nanosecond".
  19. Return ! BalanceTime(hour, minute, second, millisecond, microsecond, result).

4.5.13 DifferenceTemporalPlainTime ( operation, temporalTime, other, options )

The abstract operation DifferenceTemporalPlainTime takes arguments operation (since or until), temporalTime (a Temporal.PlainTime), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by temporalTime and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:

  1. If operation is since, let sign be -1. Otherwise, let sign be 1.
  2. Set other to ? ToTemporalTime(other).
  3. Let resolvedOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  4. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, time, « », "nanosecond", "hour").
  5. Let result be ! DifferenceTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], other.[[ISOHour]], other.[[ISOMinute]], other.[[ISOSecond]], other.[[ISOMillisecond]], other.[[ISOMicrosecond]], other.[[ISONanosecond]]).
  6. Set result to (! RoundDuration(0, 0, 0, 0, result.[[Hours]], result.[[Minutes]], result.[[Seconds]], result.[[Milliseconds]], result.[[Microseconds]], result.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]])).[[DurationRecord]].
  7. Set result to ! BalanceDuration(0, result.[[Hours]], result.[[Minutes]], result.[[Seconds]], result.[[Milliseconds]], result.[[Microseconds]], result.[[Nanoseconds]], settings.[[LargestUnit]]).
  8. Return ! CreateTemporalDuration(0, 0, 0, 0, sign × result.[[Hours]], sign × result.[[Minutes]], sign × result.[[Seconds]], sign × result.[[Milliseconds]], sign × result.[[Microseconds]], sign × result.[[Nanoseconds]]).

4.5.14 AddDurationToOrSubtractDurationFromPlainTime ( operation, temporalTime, temporalDurationLike )

The abstract operation AddDurationToOrSubtractDurationFromPlainTime takes arguments operation (add or subtract), temporalTime (a Temporal.PlainTime), and temporalDurationLike (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainTime or an abrupt completion. It adds/subtracts temporalDurationLike to/from temporalTime, returning a point in time that is in the future/past relative to temporalTime. It performs the following steps when called:

  1. If operation is subtract, let sign be -1. Otherwise, let sign be 1.
  2. Let duration be ? ToTemporalDurationRecord(temporalDurationLike).
  3. Let result be ! AddTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], sign × duration.[[Hours]], sign × duration.[[Minutes]], sign × duration.[[Seconds]], sign × duration.[[Milliseconds]], sign × duration.[[Microseconds]], sign × duration.[[Nanoseconds]]).
  4. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
  5. Return ! CreateTemporalTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]).

5 Temporal.PlainDateTime Objects

A Temporal.PlainDateTime object is an Object that contains integers corresponding to a particular year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond.

5.1 The Temporal.PlainDateTime Constructor

The Temporal.PlainDateTime constructor:

  • creates and initializes a new Temporal.PlainDateTime object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Temporal.PlainDateTime behaviour must include a super call to the %Temporal.PlainDateTime% constructor to create and initialize subclass instances with the necessary internal slots.

5.1.1 Temporal.PlainDateTime ( isoYear, isoMonth, isoDay [ , hour [ , minute [ , second [ , millisecond [ , microsecond [ , nanosecond [ , calendarLike ] ] ] ] ] ] ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, then
    1. Throw a TypeError exception.
  2. Set isoYear to ? ToIntegerWithTruncation(isoYear).
  3. Set isoMonth to ? ToIntegerWithTruncation(isoMonth).
  4. Set isoDay to ? ToIntegerWithTruncation(isoDay).
  5. If hour is undefined, set hour to 0; else set hour to ? ToIntegerWithTruncation(hour).
  6. If minute is undefined, set minute to 0; else set minute to ? ToIntegerWithTruncation(minute).
  7. If second is undefined, set second to 0; else set second to ? ToIntegerWithTruncation(second).
  8. If millisecond is undefined, set millisecond to 0; else set millisecond to ? ToIntegerWithTruncation(millisecond).
  9. If microsecond is undefined, set microsecond to 0; else set microsecond to ? ToIntegerWithTruncation(microsecond).
  10. If nanosecond is undefined, set nanosecond to 0; else set nanosecond to ? ToIntegerWithTruncation(nanosecond).
  11. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike, "iso8601").
  12. Return ? CreateTemporalDateTime(isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, nanosecond, calendar, NewTarget).

5.2 Properties of the Temporal.PlainDateTime Constructor

The value of the [[Prototype]] internal slot of the Temporal.PlainDateTime constructor is the intrinsic object %Function.prototype%.

The Temporal.PlainDateTime constructor has the following properties:

5.2.1 Temporal.PlainDateTime.prototype

The initial value of Temporal.PlainDateTime.prototype is %Temporal.PlainDateTime.prototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

5.2.2 Temporal.PlainDateTime.from ( item [ , options ] )

This function performs the following steps when called:

  1. Set options to ? GetOptionsObject(options).
  2. If Type(item) is Object and item has an [[InitializedTemporalDateTime]] internal slot, then
    1. Perform ? ToTemporalOverflow(options).
    2. Return ! CreateTemporalDateTime(item.[[ISOYear]], item.[[ISOMonth]], item.[[ISODay]], item.[[ISOHour]], item.[[ISOMinute]], item.[[ISOSecond]], item.[[ISOMillisecond]], item.[[ISOMicrosecond]], item.[[ISONanosecond]], item.[[Calendar]]).
  3. Return ? ToTemporalDateTime(item, options).

5.2.3 Temporal.PlainDateTime.compare ( one, two )

This function performs the following steps when called:

  1. Set one to ? ToTemporalDateTime(one).
  2. Set two to ? ToTemporalDateTime(two).
  3. Return 𝔽(! CompareISODateTime(one.[[ISOYear]], one.[[ISOMonth]], one.[[ISODay]], one.[[ISOHour]], one.[[ISOMinute]], one.[[ISOSecond]], one.[[ISOMillisecond]], one.[[ISOMicrosecond]], one.[[ISONanosecond]], two.[[ISOYear]], two.[[ISOMonth]], two.[[ISODay]], two.[[ISOHour]], two.[[ISOMinute]], two.[[ISOSecond]], two.[[ISOMillisecond]], two.[[ISOMicrosecond]], two.[[ISONanosecond]])).

5.3 Properties of the Temporal.PlainDateTime Prototype Object

The Temporal.PlainDateTime prototype object

  • is the intrinsic object %Temporal.PlainDateTime.prototype%.
  • is itself an ordinary object.
  • is not a Temporal.PlainDateTime instance and does not have a [[InitializedTemporalDateTime]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
Note
An ECMAScript implementation that includes the ECMA-402 Internationalization API extends this prototype with additional properties in order to represent calendar data.

5.3.1 Temporal.PlainDateTime.prototype.constructor

The initial value of Temporal.PlainDateTime.prototype.constructor is %Temporal.PlainDateTime%.

5.3.2 Temporal.PlainDateTime.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Temporal.PlainDateTime".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

5.3.3 get Temporal.PlainDateTime.prototype.calendarId

Temporal.PlainDateTime.prototype.calendarId is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? ToTemporalCalendarIdentifier(dateTime.[[Calendar]]).

5.3.4 get Temporal.PlainDateTime.prototype.year

Temporal.PlainDateTime.prototype.year is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarYear(calendar, dateTime)).

5.3.5 get Temporal.PlainDateTime.prototype.month

Temporal.PlainDateTime.prototype.month is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarMonth(calendar, dateTime)).

5.3.6 get Temporal.PlainDateTime.prototype.monthCode

Temporal.PlainDateTime.prototype.monthCode is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return ? CalendarMonthCode(calendar, dateTime).

5.3.7 get Temporal.PlainDateTime.prototype.day

Temporal.PlainDateTime.prototype.day is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDay(calendar, dateTime)).

5.3.8 get Temporal.PlainDateTime.prototype.hour

Temporal.PlainDateTime.prototype.hour is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISOHour]]).

5.3.9 get Temporal.PlainDateTime.prototype.minute

Temporal.PlainDateTime.prototype.minute is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISOMinute]]).

5.3.10 get Temporal.PlainDateTime.prototype.second

Temporal.PlainDateTime.prototype.second is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISOSecond]]).

5.3.11 get Temporal.PlainDateTime.prototype.millisecond

Temporal.PlainDateTime.prototype.millisecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISOMillisecond]]).

5.3.12 get Temporal.PlainDateTime.prototype.microsecond

Temporal.PlainDateTime.prototype.microsecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISOMicrosecond]]).

5.3.13 get Temporal.PlainDateTime.prototype.nanosecond

Temporal.PlainDateTime.prototype.nanosecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return 𝔽(dateTime.[[ISONanosecond]]).

5.3.14 get Temporal.PlainDateTime.prototype.dayOfWeek

Temporal.PlainDateTime.prototype.dayOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDayOfWeek(calendar, dateTime)).

5.3.15 get Temporal.PlainDateTime.prototype.dayOfYear

Temporal.PlainDateTime.prototype.dayOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDayOfYear(calendar, dateTime)).

5.3.16 get Temporal.PlainDateTime.prototype.weekOfYear

Temporal.PlainDateTime.prototype.weekOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarWeekOfYear(calendar, dateTime)).

5.3.17 get Temporal.PlainDateTime.prototype.yearOfWeek

Temporal.PlainDateTime.prototype.yearOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarYearOfWeek(calendar, dateTime)).

5.3.18 get Temporal.PlainDateTime.prototype.daysInWeek

Temporal.PlainDateTime.prototype.daysInWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInWeek(calendar, dateTime)).

5.3.19 get Temporal.PlainDateTime.prototype.daysInMonth

Temporal.PlainDateTime.prototype.daysInMonth is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInMonth(calendar, dateTime)).

5.3.20 get Temporal.PlainDateTime.prototype.daysInYear

Temporal.PlainDateTime.prototype.daysInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarDaysInYear(calendar, dateTime)).

5.3.21 get Temporal.PlainDateTime.prototype.monthsInYear

Temporal.PlainDateTime.prototype.monthsInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return 𝔽(? CalendarMonthsInYear(calendar, dateTime)).

5.3.22 get Temporal.PlainDateTime.prototype.inLeapYear

Temporal.PlainDateTime.prototype.inLeapYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Return ? CalendarInLeapYear(calendar, dateTime).

5.3.23 Temporal.PlainDateTime.prototype.with ( temporalDateTimeLike [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. If Type(temporalDateTimeLike) is not Object, then
    1. Throw a TypeError exception.
  4. Perform ? RejectTemporalLikeObject(temporalDateTimeLike).
  5. Set options to ? GetOptionsObject(options).
  6. Let calendar be dateTime.[[Calendar]].
  7. Let fieldNames be ? CalendarFields(calendar, « "day", "hour", "microsecond", "millisecond", "minute", "month", "monthCode", "nanosecond", "second", "year" »).
  8. Let fields be ? PrepareTemporalFields(dateTime, fieldNames, «»).
  9. Let partialDateTime be ? PrepareTemporalFields(temporalDateTimeLike, fieldNames, partial).
  10. Set fields to ? CalendarMergeFields(calendar, fields, partialDateTime).
  11. Set fields to ? PrepareTemporalFields(fields, fieldNames, «»).
  12. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, options).
  13. Assert: IsValidISODate(result.[[Year]], result.[[Month]], result.[[Day]]) is true.
  14. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
  15. Return ? CreateTemporalDateTime(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], calendar).

5.3.24 Temporal.PlainDateTime.prototype.withPlainTime ( [ plainTimeLike ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. If plainTimeLike is undefined, then
    1. Return ? CreateTemporalDateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], 0, 0, 0, 0, 0, 0, dateTime.[[Calendar]]).
  4. Let plainTime be ? ToTemporalTime(plainTimeLike).
  5. Return ? CreateTemporalDateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], plainTime.[[ISOHour]], plainTime.[[ISOMinute]], plainTime.[[ISOSecond]], plainTime.[[ISOMillisecond]], plainTime.[[ISOMicrosecond]], plainTime.[[ISONanosecond]], dateTime.[[Calendar]]).

5.3.25 Temporal.PlainDateTime.prototype.withPlainDate ( plainDateLike )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let plainDate be ? ToTemporalDate(plainDateLike).
  4. Let calendar be ? ConsolidateCalendars(dateTime.[[Calendar]], plainDate.[[Calendar]]).
  5. Return ? CreateTemporalDateTime(plainDate.[[ISOYear]], plainDate.[[ISOMonth]], plainDate.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], calendar).

5.3.26 Temporal.PlainDateTime.prototype.withCalendar ( calendarLike )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Return ? CreateTemporalDateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], calendar).

5.3.27 Temporal.PlainDateTime.prototype.add ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromPlainDateTime(add, dateTime, temporalDurationLike, options).

5.3.28 Temporal.PlainDateTime.prototype.subtract ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromPlainDateTime(subtract, dateTime, temporalDurationLike, options).

5.3.29 Temporal.PlainDateTime.prototype.until ( other [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? DifferenceTemporalPlainDateTime(until, dateTime, other, options).

5.3.30 Temporal.PlainDateTime.prototype.since ( other [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? DifferenceTemporalPlainDateTime(since, dateTime, other, options).

5.3.31 Temporal.PlainDateTime.prototype.round ( roundTo )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. If roundTo is undefined, then
    1. Throw a TypeError exception.
  4. If Type(roundTo) is String, then
    1. Let paramString be roundTo.
    2. Set roundTo to OrdinaryObjectCreate(null).
    3. Perform ! CreateDataPropertyOrThrow(roundTo, "smallestUnit", paramString).
  5. Else,
    1. Set roundTo to ? GetOptionsObject(roundTo).
  6. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
  7. Let roundingIncrement be ? ToTemporalRoundingIncrement(roundTo).
  8. Let roundingMode be ? ToTemporalRoundingMode(roundTo, "halfExpand").
  9. Let smallestUnit be ? GetTemporalUnit(roundTo, "smallestUnit", time, required, « "day" »).
  10. If smallestUnit is "day", then
    1. Let maximum be 1.
    2. Let inclusive be true.
  11. Else,
    1. Let maximum be ! MaximumTemporalDurationRoundingIncrement(smallestUnit).
    2. Assert: maximum is not undefined.
    3. Let inclusive be false.
  12. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, inclusive).
  13. Let result be ! RoundISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], roundingIncrement, smallestUnit, roundingMode).
  14. Return ? CreateTemporalDateTime(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], dateTime.[[Calendar]]).

5.3.32 Temporal.PlainDateTime.prototype.equals ( other )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Set other to ? ToTemporalDateTime(other).
  4. Let result be ! CompareISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], other.[[ISOYear]], other.[[ISOMonth]], other.[[ISODay]], other.[[ISOHour]], other.[[ISOMinute]], other.[[ISOSecond]], other.[[ISOMillisecond]], other.[[ISOMicrosecond]], other.[[ISONanosecond]]).
  5. If result is not 0, return false.
  6. Return ? CalendarEquals(dateTime.[[Calendar]], other.[[Calendar]]).

5.3.33 Temporal.PlainDateTime.prototype.toString ( [ options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Set options to ? GetOptionsObject(options).
  4. NOTE: The following steps read options and perform independent validation in alphabetical order (ToCalendarNameOption reads "calendarName", ToFractionalSecondDigits reads "fractionalSecondDigits", and ToTemporalRoundingMode reads "roundingMode").
  5. Let showCalendar be ? ToCalendarNameOption(options).
  6. Let digits be ? ToFractionalSecondDigits(options).
  7. Let roundingMode be ? ToTemporalRoundingMode(options, "trunc").
  8. Let smallestUnit be ? GetTemporalUnit(options, "smallestUnit", time, undefined).
  9. If smallestUnit is "hour", throw a RangeError exception.
  10. Let precision be ToSecondsStringPrecisionRecord(smallestUnit, digits).
  11. Let result be ! RoundISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], precision.[[Increment]], precision.[[Unit]], roundingMode).
  12. Return ? TemporalDateTimeToString(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], dateTime.[[Calendar]], precision.[[Precision]], showCalendar).

5.3.34 Temporal.PlainDateTime.prototype.toLocaleString ( [ locales [ , options ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? TemporalDateTimeToString(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], dateTime.[[Calendar]], "auto", "auto").

5.3.35 Temporal.PlainDateTime.prototype.toJSON ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ? TemporalDateTimeToString(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], dateTime.[[Calendar]], "auto", "auto").

5.3.36 Temporal.PlainDateTime.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.

5.3.37 Temporal.PlainDateTime.prototype.toZonedDateTime ( temporalTimeZoneLike [ , options ] )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let timeZone be ? ToTemporalTimeZoneSlotValue(temporalTimeZoneLike).
  4. Set options to ? GetOptionsObject(options).
  5. Let disambiguation be ? ToTemporalDisambiguation(options).
  6. Let instant be ? GetInstantFor(timeZone, dateTime, disambiguation).
  7. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, dateTime.[[Calendar]]).

5.3.38 Temporal.PlainDateTime.prototype.toPlainDate ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ! CreateTemporalDate(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[Calendar]]).

5.3.39 Temporal.PlainDateTime.prototype.toPlainYearMonth ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Let fieldNames be ? CalendarFields(calendar, « "monthCode", "year" »).
  5. Let fields be ? PrepareTemporalFields(dateTime, fieldNames, «»).
  6. Return ? CalendarYearMonthFromFields(calendar, fields).
  7. NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

5.3.40 Temporal.PlainDateTime.prototype.toPlainMonthDay ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let calendar be dateTime.[[Calendar]].
  4. Let fieldNames be ? CalendarFields(calendar, « "day", "monthCode" »).
  5. Let fields be ? PrepareTemporalFields(dateTime, fieldNames, «»).
  6. Return ? CalendarMonthDayFromFields(calendar, fields).
  7. NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

5.3.41 Temporal.PlainDateTime.prototype.toPlainTime ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ! CreateTemporalTime(dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]]).

5.3.42 Temporal.PlainDateTime.prototype.getISOFields ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Let fields be OrdinaryObjectCreate(%Object.prototype%).
  4. Perform ! CreateDataPropertyOrThrow(fields, "calendar", dateTime.[[Calendar]]).
  5. Perform ! CreateDataPropertyOrThrow(fields, "isoDay", 𝔽(dateTime.[[ISODay]])).
  6. Perform ! CreateDataPropertyOrThrow(fields, "isoHour", 𝔽(dateTime.[[ISOHour]])).
  7. Perform ! CreateDataPropertyOrThrow(fields, "isoMicrosecond", 𝔽(dateTime.[[ISOMicrosecond]])).
  8. Perform ! CreateDataPropertyOrThrow(fields, "isoMillisecond", 𝔽(dateTime.[[ISOMillisecond]])).
  9. Perform ! CreateDataPropertyOrThrow(fields, "isoMinute", 𝔽(dateTime.[[ISOMinute]])).
  10. Perform ! CreateDataPropertyOrThrow(fields, "isoMonth", 𝔽(dateTime.[[ISOMonth]])).
  11. Perform ! CreateDataPropertyOrThrow(fields, "isoNanosecond", 𝔽(dateTime.[[ISONanosecond]])).
  12. Perform ! CreateDataPropertyOrThrow(fields, "isoSecond", 𝔽(dateTime.[[ISOSecond]])).
  13. Perform ! CreateDataPropertyOrThrow(fields, "isoYear", 𝔽(dateTime.[[ISOYear]])).
  14. Return fields.

5.3.43 Temporal.PlainDateTime.prototype.getCalendar ( )

This method performs the following steps when called:

  1. Let dateTime be the this value.
  2. Perform ? RequireInternalSlot(dateTime, [[InitializedTemporalDateTime]]).
  3. Return ToTemporalCalendarObject(dateTime).

5.4 Properties of Temporal.PlainDateTime Instances

Temporal.PlainDateTime instances are ordinary objects that inherit properties from the %Temporal.PlainDateTime.prototype% intrinsic object. Temporal.PlainDateTime instances are initially created with the internal slots described in Table 5.

Table 5: Internal Slots of Temporal.PlainDateTime Instances
Internal Slot Description
[[InitializedTemporalDateTime]] The only specified use of this slot is for distinguishing Temporal.PlainDateTime instances from other objects.
[[ISOYear]] An integer representing the year in the ISO 8601 calendar.
[[ISOMonth]] An integer between 1 and 12, inclusive, representing the month of the year in the ISO 8601 calendar.
[[ISODay]] An integer between 1 and ISODaysInMonth([[ISOYear]], [[ISOMonth]]), inclusive, representing the day of the month in the ISO 8601 calendar.
[[ISOHour]] An integer between 0 and 23, inclusive, representing the hour of the day.
[[ISOMinute]] An integer between 0 and 59, inclusive, representing the minute of the hour.
[[ISOSecond]] An integer between 0 and 59, inclusive, representing the second within the minute.
[[ISOMillisecond]] An integer between 0 and 999, inclusive, representing the millisecond within the second.
[[ISOMicrosecond]] An integer between 0 and 999, inclusive, representing the microsecond within the millisecond.
[[ISONanosecond]] An integer between 0 and 999, inclusive, representing the nanosecond within the microsecond.
[[Calendar]] An Object representing the calendar.

5.5 Abstract operations

5.5.1 ISODateTimeWithinLimits ( year, month, day, hour, minute, second, millisecond, microsecond, nanosecond )

The abstract operation ISODateTimeWithinLimits takes arguments year (an integer), month (an integer between 1 and 12 inclusive), day (an integer between 1 and 31 inclusive), hour (an integer between 0 and 23 inclusive), minute (an integer between 0 and 59 inclusive), second (an integer between 0 and 59 inclusive), millisecond (an integer between 0 and 999 inclusive), microsecond (an integer between 0 and 999 inclusive), and nanosecond (an integer between 0 and 999 inclusive) and returns a Boolean. The return value is true if the combination of a date in the ISO 8601 calendar with a wall-clock time, given by the arguments, is within the representable range of Temporal.PlainDateTime, and false otherwise.

Note

Temporal.PlainDateTime objects can represent points in time within 24 hours (8.64 × 1013 nanoseconds) of the Temporal.Instant boundaries. This ensures that a Temporal.Instant object can be converted into a Temporal.PlainDateTime object using any time zone.

It performs the following steps when called:

  1. Assert: IsValidISODate(year, month, day) is true.
  2. Let ns be ℝ(GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond)).
  3. If ns ≤ nsMinInstant - nsPerDay, then
    1. Return false.
  4. If ns ≥ nsMaxInstant + nsPerDay, then
    1. Return false.
  5. Return true.

5.5.2 InterpretTemporalDateTimeFields ( calendar, fields, options )

The abstract operation InterpretTemporalDateTimeFields interprets the date/time fields in the object fields using the given calendar, and returns a Record with the fields according to the ISO 8601 calendar.

  1. Let timeResult be ? ToTemporalTimeRecord(fields).
  2. Let overflow be ? ToTemporalOverflow(options).
  3. Let temporalDate be ? CalendarDateFromFields(calendar, fields, options).
  4. Let timeResult be ? RegulateTime(timeResult.[[Hour]], timeResult.[[Minute]], timeResult.[[Second]], timeResult.[[Millisecond]], timeResult.[[Microsecond]], timeResult.[[Nanosecond]], overflow).
  5. Return the Record { [[Year]]: temporalDate.[[ISOYear]], [[Month]]: temporalDate.[[ISOMonth]], [[Day]]: temporalDate.[[ISODay]], [[Hour]]: timeResult.[[Hour]], [[Minute]]: timeResult.[[Minute]], [[Second]]: timeResult.[[Second]], [[Millisecond]]: timeResult.[[Millisecond]], [[Microsecond]]: timeResult.[[Microsecond]], [[Nanosecond]]: timeResult.[[Nanosecond]] }.

5.5.3 ToTemporalDateTime ( item [ , options ] )

The abstract operation ToTemporalDateTime returns its argument item if it is already a Temporal.PlainDateTime instance, converts item to a new Temporal.PlainDateTime instance if possible, and throws otherwise.

  1. If options is not present, set options to undefined.
  2. Assert: Type(options) is Object or Undefined.
  3. If Type(item) is Object, then
    1. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Return item.
    2. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Perform ? ToTemporalOverflow(options).
      2. Let instant be ! CreateTemporalInstant(item.[[Nanoseconds]]).
      3. Return ? GetPlainDateTimeFor(item.[[TimeZone]], instant, item.[[Calendar]]).
    3. If item has an [[InitializedTemporalDate]] internal slot, then
      1. Perform ? ToTemporalOverflow(options).
      2. Return ? CreateTemporalDateTime(item.[[ISOYear]], item.[[ISOMonth]], item.[[ISODay]], 0, 0, 0, 0, 0, 0, item.[[Calendar]]).
    4. Let calendar be ? GetTemporalCalendarSlotValueWithISODefault(item).
    5. Let fieldNames be ? CalendarFields(calendar, « "day", "hour", "microsecond", "millisecond", "minute", "month", "monthCode", "nanosecond", "second", "year" »).
    6. Let fields be ? PrepareTemporalFields(item, fieldNames, «»).
    7. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, options).
  4. Else,
    1. Perform ? ToTemporalOverflow(options).
    2. Let string be ? ToString(item).
    3. Let result be ? ParseTemporalDateTimeString(string).
    4. Assert: IsValidISODate(result.[[Year]], result.[[Month]], result.[[Day]]) is true.
    5. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
    6. Let calendar be result.[[Calendar]].
    7. If calendar is undefined, set calendar to "iso8601".
    8. If IsBuiltinCalendar(calendar) is false, throw a RangeError exception.
    9. Set calendar to the ASCII-lowercase of calendar.
  5. Return ? CreateTemporalDateTime(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], calendar).

5.5.4 BalanceISODateTime ( year, month, day, hour, minute, second, millisecond, microsecond, nanosecond )

  1. Assert: year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond are integers.
  2. Let balancedTime be ! BalanceTime(hour, minute, second, millisecond, microsecond, nanosecond).
  3. Let balancedDate be BalanceISODate(year, month, day + balancedTime.[[Days]]).
  4. Return the Record { [[Year]]: balancedDate.[[Year]], [[Month]]: balancedDate.[[Month]], [[Day]]: balancedDate.[[Day]], [[Hour]]: balancedTime.[[Hour]], [[Minute]]: balancedTime.[[Minute]], [[Second]]: balancedTime.[[Second]], [[Millisecond]]: balancedTime.[[Millisecond]], [[Microsecond]]: balancedTime.[[Microsecond]], [[Nanosecond]]: balancedTime.[[Nanosecond]] }.

5.5.5 CreateTemporalDateTime ( isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, nanosecond, calendar [ , newTarget ] )

The abstract operation CreateTemporalDateTime takes arguments isoYear (an integer), isoMonth (an integer), isoDay (an integer), hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), and calendar (a String or Object) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainDateTime instance, or an abrupt completion. It creates a Temporal.PlainDateTime instance and fills the internal slots with valid values. It performs the following steps when called:

  1. If IsValidISODate(isoYear, isoMonth, isoDay) is false, throw a RangeError exception.
  2. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
  3. If ISODateTimeWithinLimits(isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, nanosecond) is false, then
    1. Throw a RangeError exception.
  4. If newTarget is not present, set newTarget to %Temporal.PlainDateTime%.
  5. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDateTime.prototype%", « [[InitializedTemporalDateTime]], [[ISOYear]], [[ISOMonth]], [[ISODay]], [[ISOHour]], [[ISOMinute]], [[ISOSecond]], [[ISOMillisecond]], [[ISOMicrosecond]], [[ISONanosecond]], [[Calendar]] »).
  6. Set object.[[ISOYear]] to isoYear.
  7. Set object.[[ISOMonth]] to isoMonth.
  8. Set object.[[ISODay]] to isoDay.
  9. Set object.[[ISOHour]] to hour.
  10. Set object.[[ISOMinute]] to minute.
  11. Set object.[[ISOSecond]] to second.
  12. Set object.[[ISOMillisecond]] to millisecond.
  13. Set object.[[ISOMicrosecond]] to microsecond.
  14. Set object.[[ISONanosecond]] to nanosecond.
  15. Set object.[[Calendar]] to calendar.
  16. Return object.

5.5.6 TemporalDateTimeToString ( isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, nanosecond, calendar, precision, showCalendar )

  1. Assert: isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, and nanosecond are integers.
  2. Let year be ! PadISOYear(isoYear).
  3. Let month be ToZeroPaddedDecimalString(isoMonth, 2).
  4. Let day be ToZeroPaddedDecimalString(isoDay, 2).
  5. Let hour be ToZeroPaddedDecimalString(hour, 2).
  6. Let minute be ToZeroPaddedDecimalString(minute, 2).
  7. Let seconds be ! FormatSecondsStringPart(second, millisecond, microsecond, nanosecond, precision).
  8. Let calendarString be ? MaybeFormatCalendarAnnotation(calendar, showCalendar).
  9. Return the string-concatenation of year, the code unit 0x002D (HYPHEN-MINUS), month, the code unit 0x002D (HYPHEN-MINUS), day, 0x0054 (LATIN CAPITAL LETTER T), hour, the code unit 0x003A (COLON), minute, seconds, and calendarString.

5.5.7 CompareISODateTime ( y1, mon1, d1, h1, min1, s1, ms1, mus1, ns1, y2, mon2, d2, h2, min2, s2, ms2, mus2, ns2 )

  1. Assert: y1, mon1, d1, h1, min1, s1, ms1, mus1, ns1, y2, mon2, d2, h2, min2, s2, ms2, mus2, and ns2 are integers.
  2. Let dateResult be ! CompareISODate(y1, mon1, d1, y2, mon2, d2).
  3. If dateResult is not 0, then
    1. Return dateResult.
  4. Return ! CompareTemporalTime(h1, min1, s1, ms1, mus1, ns1, h2, min2, s2, ms2, mus2, ns2).

5.5.8 AddDateTime ( year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, calendar, years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds, options )

The abstract operation AddDateTime takes arguments year (an integer), month (an integer), day (an integer), hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), calendar (an Object), years (an integer), months (an integer), weeks (an integer), days (an integer), hours (an integer), minutes (an integer), seconds (an integer), milliseconds (an integer), microseconds (an integer), nanoseconds (an integer), and options (an Object or undefined). It adds a duration to a combined date and time, according to the reckoning of the given calendar, and returns the result as a Record. It performs the following steps when called:

  1. Assert: ISODateTimeWithinLimits(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) is true.
  2. Let timeResult be ! AddTime(hour, minute, second, millisecond, microsecond, nanosecond, hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
  3. Let datePart be ! CreateTemporalDate(year, month, day, calendar).
  4. Let dateDuration be ? CreateTemporalDuration(years, months, weeks, days + timeResult.[[Days]], 0, 0, 0, 0, 0, 0).
  5. Let addedDate be ? CalendarDateAdd(calendar, datePart, dateDuration, options).
  6. Return the Record { [[Year]]: addedDate.[[ISOYear]], [[Month]]: addedDate.[[ISOMonth]], [[Day]]: addedDate.[[ISODay]], [[Hour]]: timeResult.[[Hour]], [[Minute]]: timeResult.[[Minute]], [[Second]]: timeResult.[[Second]], [[Millisecond]]: timeResult.[[Millisecond]], [[Microsecond]]: timeResult.[[Microsecond]], [[Nanosecond]]: timeResult.[[Nanosecond]] }.

5.5.9 RoundISODateTime ( year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, increment, unit, roundingMode [ , dayLength ] )

The abstract operation RoundISODateTime rounds the time part of a combined date and time, carrying over any excess into the date part.

  1. Assert: year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond are integers.
  2. Assert: ISODateTimeWithinLimits(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond) is true.
  3. If dayLength is not present, set dayLength to nsPerDay.
  4. Let roundedTime be ! RoundTime(hour, minute, second, millisecond, microsecond, nanosecond, increment, unit, roundingMode, dayLength).
  5. Let balanceResult be BalanceISODate(year, month, day + roundedTime.[[Days]]).
  6. Return the Record { [[Year]]: balanceResult.[[Year]], [[Month]]: balanceResult.[[Month]], [[Day]]: balanceResult.[[Day]], [[Hour]]: roundedTime.[[Hour]], [[Minute]]: roundedTime.[[Minute]], [[Second]]: roundedTime.[[Second]], [[Millisecond]]: roundedTime.[[Millisecond]], [[Microsecond]]: roundedTime.[[Microsecond]], [[Nanosecond]]: roundedTime.[[Nanosecond]] }.

5.5.10 DifferenceISODateTime ( y1, mon1, d1, h1, min1, s1, ms1, mus1, ns1, y2, mon2, d2, h2, min2, s2, ms2, mus2, ns2, calendar, largestUnit, options )

The abstract operation DifferenceISODateTime takes arguments y1 (an integer), mon1 (an integer between 1 and 12 inclusive), d1 (an integer between 1 and 31 inclusive), h1 (an integer between 0 and 23 inclusive), min1 (an integer between 0 and 59 inclusive), s1 (an integer between 0 and 59 inclusive), ms1 (an integer between 0 and 999 inclusive), mus1 (an integer between 0 and 999 inclusive), ns1 (an integer between 0 and 999 inclusive), y2 (an integer), mon2 (an integer between 1 and 12 inclusive), d2 (an integer between 1 and 31 inclusive), h2 (an integer between 0 and 23 inclusive), min2 (an integer between 0 and 59 inclusive), s2 (an integer between 0 and 59 inclusive), ms2 (an integer between 0 and 999 inclusive), mus2 (an integer between 0 and 999 inclusive), ns2 (an integer between 0 and 999 inclusive), calendar (an Object), largestUnit (a String), and options (an Object). It returns a Duration Record with the elapsed duration from a first date and time, until a second date and time, according to the reckoning of the given calendar. The given date and time units are all in the ISO 8601 calendar. The largestUnit and options arguments are used in calendar's dateUntil method. It performs the following steps when called:

  1. Assert: ISODateTimeWithinLimits(y1, mon1, d1, h1, min1, s1, ms1, mus1, ns1) is true.
  2. Assert: ISODateTimeWithinLimits(y2, mon2, d2, h2, min2, s2, ms2, mus2, ns2) is true.
  3. Let timeDifference be ! DifferenceTime(h1, min1, s1, ms1, mus1, ns1, h2, min2, s2, ms2, mus2, ns2).
  4. Let timeSign be ! DurationSign(0, 0, 0, 0, timeDifference.[[Hours]], timeDifference.[[Minutes]], timeDifference.[[Seconds]], timeDifference.[[Milliseconds]], timeDifference.[[Microseconds]], timeDifference.[[Nanoseconds]]).
  5. Let dateSign be ! CompareISODate(y2, mon2, d2, y1, mon1, d1).
  6. Let adjustedDate be CreateISODateRecord(y1, mon1, d1).
  7. If timeSign is -dateSign, then
    1. Set adjustedDate to BalanceISODate(adjustedDate.[[Year]], adjustedDate.[[Month]], adjustedDate.[[Day]] - timeSign).
    2. Set timeDifference to ! BalanceDuration(-timeSign, timeDifference.[[Hours]], timeDifference.[[Minutes]], timeDifference.[[Seconds]], timeDifference.[[Milliseconds]], timeDifference.[[Microseconds]], timeDifference.[[Nanoseconds]], largestUnit).
  8. Let date1 be ! CreateTemporalDate(adjustedDate.[[Year]], adjustedDate.[[Month]], adjustedDate.[[Day]], calendar).
  9. Let date2 be ! CreateTemporalDate(y2, mon2, d2, calendar).
  10. Let dateLargestUnit be ! LargerOfTwoTemporalUnits("day", largestUnit).
  11. Let untilOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  12. Perform ! CreateDataPropertyOrThrow(untilOptions, "largestUnit", dateLargestUnit).
  13. Let dateDifference be ? CalendarDateUntil(calendar, date1, date2, untilOptions).
  14. Let balanceResult be ? BalanceDuration(dateDifference.[[Days]], timeDifference.[[Hours]], timeDifference.[[Minutes]], timeDifference.[[Seconds]], timeDifference.[[Milliseconds]], timeDifference.[[Microseconds]], timeDifference.[[Nanoseconds]], largestUnit).
  15. Return ! CreateDurationRecord(dateDifference.[[Years]], dateDifference.[[Months]], dateDifference.[[Weeks]], balanceResult.[[Days]], balanceResult.[[Hours]], balanceResult.[[Minutes]], balanceResult.[[Seconds]], balanceResult.[[Milliseconds]], balanceResult.[[Microseconds]], balanceResult.[[Nanoseconds]]).

5.5.11 DifferenceTemporalPlainDateTime ( operation, dateTime, other, options )

The abstract operation DifferenceTemporalPlainDateTime takes arguments operation (since or until), dateTime (a Temporal.PlainDateTime), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by dateTime and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:

  1. If operation is since, let sign be -1. Otherwise, let sign be 1.
  2. Set other to ? ToTemporalDateTime(other).
  3. If ? CalendarEquals(dateTime.[[Calendar]], other.[[Calendar]]) is false, throw a RangeError exception.
  4. Let resolvedOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  5. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, datetime, « », "nanosecond", "day").
  6. Let diff be ? DifferenceISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], other.[[ISOYear]], other.[[ISOMonth]], other.[[ISODay]], other.[[ISOHour]], other.[[ISOMinute]], other.[[ISOSecond]], other.[[ISOMillisecond]], other.[[ISOMicrosecond]], other.[[ISONanosecond]], dateTime.[[Calendar]], settings.[[LargestUnit]], resolvedOptions).
  7. Let relativeTo be ! CreateTemporalDate(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[Calendar]]).
  8. Let roundResult be (? RoundDuration(diff.[[Years]], diff.[[Months]], diff.[[Weeks]], diff.[[Days]], diff.[[Hours]], diff.[[Minutes]], diff.[[Seconds]], diff.[[Milliseconds]], diff.[[Microseconds]], diff.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]], relativeTo)).[[DurationRecord]].
  9. Let result be ? BalanceDuration(roundResult.[[Days]], roundResult.[[Hours]], roundResult.[[Minutes]], roundResult.[[Seconds]], roundResult.[[Milliseconds]], roundResult.[[Microseconds]], roundResult.[[Nanoseconds]], settings.[[LargestUnit]]).
  10. Return ! CreateTemporalDuration(sign × roundResult.[[Years]], sign × roundResult.[[Months]], sign × roundResult.[[Weeks]], sign × result.[[Days]], sign × result.[[Hours]], sign × result.[[Minutes]], sign × result.[[Seconds]], sign × result.[[Milliseconds]], sign × result.[[Microseconds]], sign × result.[[Nanoseconds]]).

5.5.12 AddDurationToOrSubtractDurationFromPlainDateTime ( operation, dateTime, temporalDurationLike, options )

The abstract operation AddDurationToOrSubtractDurationFromPlainDateTime takes arguments operation (add or subtract), dateTime (a Temporal.PlainDateTime), temporalDurationLike (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainDateTime or an abrupt completion. It adds/subtracts temporalDurationLike to/from dateTime, returning a point in time that is in the future/past relative to datetime. It performs the following steps when called:

  1. If operation is subtract, let sign be -1. Otherwise, let sign be 1.
  2. Let duration be ? ToTemporalDurationRecord(temporalDurationLike).
  3. Set options to ? GetOptionsObject(options).
  4. Let result be ? AddDateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], dateTime.[[Calendar]], sign × duration.[[Years]], sign × duration.[[Months]], sign × duration.[[Weeks]], sign × duration.[[Days]], sign × duration.[[Hours]], sign × duration.[[Minutes]], sign × duration.[[Seconds]], sign × duration.[[Milliseconds]], sign × duration.[[Microseconds]], sign × duration.[[Nanoseconds]], options).
  5. Assert: IsValidISODate(result.[[Year]], result.[[Month]], result.[[Day]]) is true.
  6. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
  7. Return ? CreateTemporalDateTime(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], dateTime.[[Calendar]]).

6 Temporal.ZonedDateTime Objects

A Temporal.ZonedDateTime object is an Object referencing a fixed point in time with nanoseconds precision, and containing Object values corresponding to a particular time zone and calendar system.

6.1 The Temporal.ZonedDateTime Constructor

The Temporal.ZonedDateTime constructor:

  • creates and initializes a new Temporal.ZonedDateTime object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Temporal.ZonedDateTime behaviour must include a super call to the %Temporal.ZonedDateTime% constructor to create and initialize subclass instances with the necessary internal slots.

6.1.1 Temporal.ZonedDateTime ( epochNanoseconds, timeZoneLike [ , calendarLike ] )

This function performs the following steps when called:

  1. If NewTarget is undefined, then
    1. Throw a TypeError exception.
  2. Set epochNanoseconds to ? ToBigInt(epochNanoseconds).
  3. If ! IsValidEpochNanoseconds(epochNanoseconds) is false, throw a RangeError exception.
  4. Let timeZone be ? ToTemporalTimeZoneSlotValue(timeZoneLike).
  5. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike, "iso8601").
  6. Return ? CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar, NewTarget).

6.2 Properties of the Temporal.ZonedDateTime Constructor

The value of the [[Prototype]] internal slot of the Temporal.ZonedDateTime constructor is the intrinsic object %Function.prototype%.

The Temporal.ZonedDateTime constructor has the following properties:

6.2.1 Temporal.ZonedDateTime.prototype

The initial value of Temporal.ZonedDateTime.prototype is %Temporal.ZonedDateTime.prototype%.

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

6.2.2 Temporal.ZonedDateTime.from ( item [ , options ] )

This function performs the following steps when called:

  1. Set options to ? GetOptionsObject(options).
  2. If Type(item) is Object and item has an [[InitializedTemporalZonedDateTime]] internal slot, then
    1. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalDisambiguation reads "disambiguation", ToTemporalOffset reads "offset", and ToTemporalOverflow reads "overflow").
    2. Perform ? ToTemporalDisambiguation(options).
    3. Perform ? ToTemporalOffset(options, "reject").
    4. Perform ? ToTemporalOverflow(options).
    5. Return ! CreateTemporalZonedDateTime(item.[[Nanoseconds]], item.[[TimeZone]], item.[[Calendar]]).
  3. Return ? ToTemporalZonedDateTime(item, options).

6.2.3 Temporal.ZonedDateTime.compare ( one, two )

This function performs the following steps when called:

  1. Set one to ? ToTemporalZonedDateTime(one).
  2. Set two to ? ToTemporalZonedDateTime(two).
  3. Return 𝔽(CompareEpochNanoseconds(one.[[Nanoseconds]], two.[[Nanoseconds]])).

6.3 Properties of the Temporal.ZonedDateTime Prototype Object

The Temporal.ZonedDateTime prototype object

  • is itself an ordinary object.
  • is not a Temporal.ZonedDateTime instance and does not have a [[InitializedTemporalZonedDateTime]] internal slot.
  • has a [[Prototype]] internal slot whose value is %Object.prototype%.
Note
An ECMAScript implementation that includes the ECMA-402 Internationalization API extends this prototype with additional properties in order to represent calendar data.

6.3.1 Temporal.ZonedDateTime.prototype.constructor

The initial value of Temporal.ZonedDateTime.prototype.constructor is %Temporal.ZonedDateTime%.

6.3.2 Temporal.ZonedDateTime.prototype[ @@toStringTag ]

The initial value of the @@toStringTag property is the string value "Temporal.ZonedDateTime".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

6.3.3 get Temporal.ZonedDateTime.prototype.calendarId

Temporal.ZonedDateTime.prototype.calendarId is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? ToTemporalCalendarIdentifier(zonedDateTime.[[Calendar]]).

6.3.4 get Temporal.ZonedDateTime.prototype.timeZoneId

Temporal.ZonedDateTime.prototype.timeZoneId is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? ToTemporalTimeZoneIdentifier(zonedDateTime.[[TimeZone]]).

6.3.5 get Temporal.ZonedDateTime.prototype.year

Temporal.ZonedDateTime.prototype.year is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarYear(calendar, temporalDateTime)).

6.3.6 get Temporal.ZonedDateTime.prototype.month

Temporal.ZonedDateTime.prototype.month is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarMonth(calendar, temporalDateTime)).

6.3.7 get Temporal.ZonedDateTime.prototype.monthCode

Temporal.ZonedDateTime.prototype.monthCode is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return ? CalendarMonthCode(calendar, temporalDateTime).

6.3.8 get Temporal.ZonedDateTime.prototype.day

Temporal.ZonedDateTime.prototype.day is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDay(calendar, temporalDateTime)).

6.3.9 get Temporal.ZonedDateTime.prototype.hour

Temporal.ZonedDateTime.prototype.hour is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISOHour]]).

6.3.10 get Temporal.ZonedDateTime.prototype.minute

Temporal.ZonedDateTime.prototype.minute is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISOMinute]]).

6.3.11 get Temporal.ZonedDateTime.prototype.second

Temporal.ZonedDateTime.prototype.second is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISOSecond]]).

6.3.12 get Temporal.ZonedDateTime.prototype.millisecond

Temporal.ZonedDateTime.prototype.millisecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISOMillisecond]]).

6.3.13 get Temporal.ZonedDateTime.prototype.microsecond

Temporal.ZonedDateTime.prototype.microsecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISOMicrosecond]]).

6.3.14 get Temporal.ZonedDateTime.prototype.nanosecond

Temporal.ZonedDateTime.prototype.nanosecond is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(temporalDateTime.[[ISONanosecond]]).

6.3.15 get Temporal.ZonedDateTime.prototype.epochSeconds

Temporal.ZonedDateTime.prototype.epochSeconds is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let ns be zonedDateTime.[[Nanoseconds]].
  4. Let s be floor(ℝ(ns) / 109).
  5. Return 𝔽(s).

6.3.16 get Temporal.ZonedDateTime.prototype.epochMilliseconds

Temporal.ZonedDateTime.prototype.epochMilliseconds is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let ns be zonedDateTime.[[Nanoseconds]].
  4. Let ms be floor(ℝ(ns) / 106).
  5. Return 𝔽(ms).

6.3.17 get Temporal.ZonedDateTime.prototype.epochMicroseconds

Temporal.ZonedDateTime.prototype.epochMicroseconds is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let ns be zonedDateTime.[[Nanoseconds]].
  4. Let µs be floor(ℝ(ns) / 103).
  5. Return ℤ(µs).

6.3.18 get Temporal.ZonedDateTime.prototype.epochNanoseconds

Temporal.ZonedDateTime.prototype.epochNanoseconds is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return zonedDateTime.[[Nanoseconds]].

6.3.19 get Temporal.ZonedDateTime.prototype.dayOfWeek

Temporal.ZonedDateTime.prototype.dayOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDayOfWeek(calendar, temporalDateTime)).

6.3.20 get Temporal.ZonedDateTime.prototype.dayOfYear

Temporal.ZonedDateTime.prototype.dayOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDayOfYear(calendar, temporalDateTime)).

6.3.21 get Temporal.ZonedDateTime.prototype.weekOfYear

Temporal.ZonedDateTime.prototype.weekOfYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarWeekOfYear(calendar, temporalDateTime)).

6.3.22 get Temporal.ZonedDateTime.prototype.yearOfWeek

Temporal.ZonedDateTime.prototype.yearOfWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarYearOfWeek(calendar, temporalDateTime)).

6.3.23 get Temporal.ZonedDateTime.prototype.hoursInDay

Temporal.ZonedDateTime.prototype.hoursInDay is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, "iso8601").
  6. Let year be temporalDateTime.[[ISOYear]].
  7. Let month be temporalDateTime.[[ISOMonth]].
  8. Let day be temporalDateTime.[[ISODay]].
  9. Let today be ? CreateTemporalDateTime(year, month, day, 0, 0, 0, 0, 0, 0, "iso8601").
  10. Let tomorrowFields be BalanceISODate(year, month, day + 1).
  11. Let tomorrow be ? CreateTemporalDateTime(tomorrowFields.[[Year]], tomorrowFields.[[Month]], tomorrowFields.[[Day]], 0, 0, 0, 0, 0, 0, "iso8601").
  12. Let todayInstant be ? GetInstantFor(timeZone, today, "compatible").
  13. Let tomorrowInstant be ? GetInstantFor(timeZone, tomorrow, "compatible").
  14. Let diffNs be tomorrowInstant.[[Nanoseconds]] - todayInstant.[[Nanoseconds]].
  15. Return 𝔽(diffNs / (3.6 × 1012)).

6.3.24 get Temporal.ZonedDateTime.prototype.daysInWeek

Temporal.ZonedDateTime.prototype.daysInWeek is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDaysInWeek(calendar, temporalDateTime)).

6.3.25 get Temporal.ZonedDateTime.prototype.daysInMonth

Temporal.ZonedDateTime.prototype.daysInMonth is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDaysInMonth(calendar, temporalDateTime)).

6.3.26 get Temporal.ZonedDateTime.prototype.daysInYear

Temporal.ZonedDateTime.prototype.daysInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarDaysInYear(calendar, temporalDateTime)).

6.3.27 get Temporal.ZonedDateTime.prototype.monthsInYear

Temporal.ZonedDateTime.prototype.monthsInYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return 𝔽(? CalendarMonthsInYear(calendar, temporalDateTime)).

6.3.28 get Temporal.ZonedDateTime.prototype.inLeapYear

Temporal.ZonedDateTime.prototype.inLeapYear is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return ? CalendarInLeapYear(calendar, temporalDateTime).

6.3.29 get Temporal.ZonedDateTime.prototype.offsetNanoseconds

Temporal.ZonedDateTime.prototype.offsetNanoseconds is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Return 𝔽(? GetOffsetNanosecondsFor(timeZone, instant)).

6.3.30 get Temporal.ZonedDateTime.prototype.offset

Temporal.ZonedDateTime.prototype.offset is an accessor property whose set accessor function is undefined. Its get accessor function performs the following steps:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  4. Return ? GetOffsetStringFor(zonedDateTime.[[TimeZone]], instant).

6.3.31 Temporal.ZonedDateTime.prototype.with ( temporalZonedDateTimeLike [ , options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. If Type(temporalZonedDateTimeLike) is not Object, then
    1. Throw a TypeError exception.
  4. Perform ? RejectTemporalLikeObject(temporalZonedDateTimeLike).
  5. Set options to ? GetOptionsObject(options).
  6. Let calendar be zonedDateTime.[[Calendar]].
  7. Let fieldNames be ? CalendarFields(calendar, « "day", "hour", "microsecond", "millisecond", "minute", "month", "monthCode", "nanosecond", "second", "year" »).
  8. Append "offset" to fieldNames.
  9. Let fields be ? PrepareTemporalFields(zonedDateTime, fieldNames, « "offset" »).
  10. Let partialZonedDateTime be ? PrepareTemporalFields(temporalZonedDateTimeLike, fieldNames, partial).
  11. Set fields to ? CalendarMergeFields(calendar, fields, partialZonedDateTime).
  12. Set fields to ? PrepareTemporalFields(fields, fieldNames, « "offset" »).
  13. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalDisambiguation reads "disambiguation", ToTemporalOffset reads "offset", and InterpretTemporalDateTimeFields reads "overflow").
  14. Let disambiguation be ? ToTemporalDisambiguation(options).
  15. Let offset be ? ToTemporalOffset(options, "prefer").
  16. Let dateTimeResult be ? InterpretTemporalDateTimeFields(calendar, fields, options).
  17. Let offsetString be ! Get(fields, "offset").
  18. Assert: Type(offsetString) is String.
  19. If IsTimeZoneOffsetString(offsetString) is false, throw a RangeError exception.
  20. Let offsetNanoseconds be ParseTimeZoneOffsetString(offsetString).
  21. Let timeZone be zonedDateTime.[[TimeZone]].
  22. Let epochNanoseconds be ? InterpretISODateTimeOffset(dateTimeResult.[[Year]], dateTimeResult.[[Month]], dateTimeResult.[[Day]], dateTimeResult.[[Hour]], dateTimeResult.[[Minute]], dateTimeResult.[[Second]], dateTimeResult.[[Millisecond]], dateTimeResult.[[Microsecond]], dateTimeResult.[[Nanosecond]], option, offsetNanoseconds, timeZone, disambiguation, offset, match exactly).
  23. Return ! CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar).

6.3.32 Temporal.ZonedDateTime.prototype.withPlainTime ( [ plainTimeLike ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. If plainTimeLike is undefined, then
    1. Let plainTime be ! CreateTemporalTime(0, 0, 0, 0, 0, 0).
  4. Else,
    1. Let plainTime be ? ToTemporalTime(plainTimeLike).
  5. Let timeZone be zonedDateTime.[[TimeZone]].
  6. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  7. Let calendar be zonedDateTime.[[Calendar]].
  8. Let plainDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  9. Let resultPlainDateTime be ? CreateTemporalDateTime(plainDateTime.[[ISOYear]], plainDateTime.[[ISOMonth]], plainDateTime.[[ISODay]], plainTime.[[ISOHour]], plainTime.[[ISOMinute]], plainTime.[[ISOSecond]], plainTime.[[ISOMillisecond]], plainTime.[[ISOMicrosecond]], plainTime.[[ISONanosecond]], calendar).
  10. Set instant to ? GetInstantFor(timeZone, resultPlainDateTime, "compatible").
  11. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, calendar).

6.3.33 Temporal.ZonedDateTime.prototype.withPlainDate ( plainDateLike )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let plainDate be ? ToTemporalDate(plainDateLike).
  4. Let timeZone be zonedDateTime.[[TimeZone]].
  5. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  6. Let plainDateTime be ? GetPlainDateTimeFor(timeZone, instant, zonedDateTime.[[Calendar]]).
  7. Let calendar be ? ConsolidateCalendars(zonedDateTime.[[Calendar]], plainDate.[[Calendar]]).
  8. Let resultPlainDateTime be ? CreateTemporalDateTime(plainDate.[[ISOYear]], plainDate.[[ISOMonth]], plainDate.[[ISODay]], plainDateTime.[[ISOHour]], plainDateTime.[[ISOMinute]], plainDateTime.[[ISOSecond]], plainDateTime.[[ISOMillisecond]], plainDateTime.[[ISOMicrosecond]], plainDateTime.[[ISONanosecond]], calendar).
  9. Set instant to ? GetInstantFor(timeZone, resultPlainDateTime, "compatible").
  10. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, calendar).

6.3.34 Temporal.ZonedDateTime.prototype.withTimeZone ( timeZoneLike )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be ? ToTemporalTimeZoneSlotValue(timeZoneLike).
  4. Return ! CreateTemporalZonedDateTime(zonedDateTime.[[Nanoseconds]], timeZone, zonedDateTime.[[Calendar]]).

6.3.35 Temporal.ZonedDateTime.prototype.withCalendar ( calendarLike )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Return ! CreateTemporalZonedDateTime(zonedDateTime.[[Nanoseconds]], zonedDateTime.[[TimeZone]], calendar).

6.3.36 Temporal.ZonedDateTime.prototype.add ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromZonedDateTime(add, zonedDateTime, temporalDurationLike, options).

6.3.37 Temporal.ZonedDateTime.prototype.subtract ( temporalDurationLike [ , options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? AddDurationToOrSubtractDurationFromZonedDateTime(subtract, zonedDateTime, temporalDurationLike, options).

6.3.38 Temporal.ZonedDateTime.prototype.until ( other [ , options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? DifferenceTemporalZonedDateTime(until, zonedDateTime, other, options).

6.3.39 Temporal.ZonedDateTime.prototype.since ( other [ , options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? DifferenceTemporalZonedDateTime(since, zonedDateTime, other, options).

6.3.40 Temporal.ZonedDateTime.prototype.round ( roundTo )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. If roundTo is undefined, then
    1. Throw a TypeError exception.
  4. If Type(roundTo) is String, then
    1. Let paramString be roundTo.
    2. Set roundTo to OrdinaryObjectCreate(null).
    3. Perform ! CreateDataPropertyOrThrow(roundTo, "smallestUnit", paramString).
  5. Else,
    1. Set roundTo to ? GetOptionsObject(roundTo).
  6. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
  7. Let roundingIncrement be ? ToTemporalRoundingIncrement(roundTo).
  8. Let roundingMode be ? ToTemporalRoundingMode(roundTo, "halfExpand").
  9. Let smallestUnit be ? GetTemporalUnit(roundTo, "smallestUnit", time, required, « "day" »).
  10. If smallestUnit is "day", then
    1. Let maximum be 1.
    2. Let inclusive be true.
  11. Else,
    1. Let maximum be ! MaximumTemporalDurationRoundingIncrement(smallestUnit).
    2. Assert: maximum is not undefined.
    3. Let inclusive be false.
  12. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, inclusive).
  13. Let timeZone be zonedDateTime.[[TimeZone]].
  14. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  15. Let calendar be zonedDateTime.[[Calendar]].
  16. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  17. Let dtStart be ? CreateTemporalDateTime(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], 0, 0, 0, 0, 0, 0, "iso8601").
  18. Let instantStart be ? GetInstantFor(timeZone, dtStart, "compatible").
  19. Let startNs be instantStart.[[Nanoseconds]].
  20. Let endNs be ? AddZonedDateTime(startNs, timeZone, calendar, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0).
  21. Let dayLengthNs be ℝ(endNs - startNs).
  22. If dayLengthNs ≤ 0, then
    1. Throw a RangeError exception.
  23. Let roundResult be ! RoundISODateTime(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], temporalDateTime.[[ISOHour]], temporalDateTime.[[ISOMinute]], temporalDateTime.[[ISOSecond]], temporalDateTime.[[ISOMillisecond]], temporalDateTime.[[ISOMicrosecond]], temporalDateTime.[[ISONanosecond]], roundingIncrement, smallestUnit, roundingMode, dayLengthNs).
  24. Let offsetNanoseconds be ? GetOffsetNanosecondsFor(timeZone, instant).
  25. Let epochNanoseconds be ? InterpretISODateTimeOffset(roundResult.[[Year]], roundResult.[[Month]], roundResult.[[Day]], roundResult.[[Hour]], roundResult.[[Minute]], roundResult.[[Second]], roundResult.[[Millisecond]], roundResult.[[Microsecond]], roundResult.[[Nanosecond]], option, offsetNanoseconds, timeZone, "compatible", "prefer", match exactly).
  26. Return ! CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar).

6.3.41 Temporal.ZonedDateTime.prototype.equals ( other )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Set other to ? ToTemporalZonedDateTime(other).
  4. If zonedDateTime.[[Nanoseconds]] ≠ other.[[Nanoseconds]], return false.
  5. If ? TimeZoneEquals(zonedDateTime.[[TimeZone]], other.[[TimeZone]]) is false, return false.
  6. Return ? CalendarEquals(zonedDateTime.[[Calendar]], other.[[Calendar]]).

6.3.42 Temporal.ZonedDateTime.prototype.toString ( [ options ] )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Set options to ? GetOptionsObject(options).
  4. NOTE: The following steps read options and perform independent validation in alphabetical order (ToCalendarNameOption reads "calendarName", ToFractionalSecondDigits reads "fractionalSecondDigits", ToShowOffsetOption reads "offset", and ToTemporalRoundingMode reads "roundingMode").
  5. Let showCalendar be ? ToCalendarNameOption(options).
  6. Let digits be ? ToFractionalSecondDigits(options).
  7. Let showOffset be ? ToShowOffsetOption(options).
  8. Let roundingMode be ? ToTemporalRoundingMode(options, "trunc").
  9. Let smallestUnit be ? GetTemporalUnit(options, "smallestUnit", time, undefined).
  10. If smallestUnit is "hour", throw a RangeError exception.
  11. Let showTimeZone be ? ToTimeZoneNameOption(options).
  12. Let precision be ToSecondsStringPrecisionRecord(smallestUnit, digits).
  13. Return ? TemporalZonedDateTimeToString(zonedDateTime, precision.[[Precision]], showCalendar, showTimeZone, showOffset, precision.[[Increment]], precision.[[Unit]], roundingMode).

6.3.43 Temporal.ZonedDateTime.prototype.toLocaleString ( [ locales [ , options ] ] )

An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement this method as specified in the ECMA-402 specification. If an ECMAScript implementation does not include the ECMA-402 API the following specification of this method is used.

The meanings of the optional parameters to this method are defined in the ECMA-402 specification; implementations that do not include ECMA-402 support must not use those parameter positions for anything else.

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? TemporalZonedDateTimeToString(zonedDateTime, "auto", "auto", "auto", "auto").

6.3.44 Temporal.ZonedDateTime.prototype.toJSON ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ? TemporalZonedDateTimeToString(zonedDateTime, "auto", "auto", "auto", "auto").

6.3.45 Temporal.ZonedDateTime.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.

6.3.46 Temporal.ZonedDateTime.prototype.startOfDay ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let calendar be zonedDateTime.[[Calendar]].
  5. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Let startDateTime be ? CreateTemporalDateTime(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], 0, 0, 0, 0, 0, 0, calendar).
  8. Let startInstant be ? GetInstantFor(timeZone, startDateTime, "compatible").
  9. Return ! CreateTemporalZonedDateTime(startInstant.[[Nanoseconds]], timeZone, calendar).

6.3.47 Temporal.ZonedDateTime.prototype.toInstant ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).

6.3.48 Temporal.ZonedDateTime.prototype.toPlainDate ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return ! CreateTemporalDate(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], calendar).

6.3.49 Temporal.ZonedDateTime.prototype.toPlainTime ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Return ! CreateTemporalTime(temporalDateTime.[[ISOHour]], temporalDateTime.[[ISOMinute]], temporalDateTime.[[ISOSecond]], temporalDateTime.[[ISOMillisecond]], temporalDateTime.[[ISOMicrosecond]], temporalDateTime.[[ISONanosecond]]).

6.3.50 Temporal.ZonedDateTime.prototype.toPlainDateTime ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Return ? GetPlainDateTimeFor(timeZone, instant, zonedDateTime.[[Calendar]]).

6.3.51 Temporal.ZonedDateTime.prototype.toPlainYearMonth ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Let fieldNames be ? CalendarFields(calendar, « "monthCode", "year" »).
  8. Let fields be ? PrepareTemporalFields(temporalDateTime, fieldNames, «»).
  9. Return ? CalendarYearMonthFromFields(calendar, fields).
  10. NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

6.3.52 Temporal.ZonedDateTime.prototype.toPlainMonthDay ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let timeZone be zonedDateTime.[[TimeZone]].
  4. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  7. Let fieldNames be ? CalendarFields(calendar, « "day", "monthCode" »).
  8. Let fields be ? PrepareTemporalFields(temporalDateTime, fieldNames, «»).
  9. Return ? CalendarMonthDayFromFields(calendar, fields).
  10. NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.

6.3.53 Temporal.ZonedDateTime.prototype.getISOFields ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Let fields be OrdinaryObjectCreate(%Object.prototype%).
  4. Let timeZone be zonedDateTime.[[TimeZone]].
  5. Let instant be ! CreateTemporalInstant(zonedDateTime.[[Nanoseconds]]).
  6. Let calendar be zonedDateTime.[[Calendar]].
  7. Let dateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  8. Let offset be ? GetOffsetStringFor(timeZone, instant).
  9. Perform ! CreateDataPropertyOrThrow(fields, "calendar", calendar).
  10. Perform ! CreateDataPropertyOrThrow(fields, "isoDay", 𝔽(dateTime.[[ISODay]])).
  11. Perform ! CreateDataPropertyOrThrow(fields, "isoHour", 𝔽(dateTime.[[ISOHour]])).
  12. Perform ! CreateDataPropertyOrThrow(fields, "isoMicrosecond", 𝔽(dateTime.[[ISOMicrosecond]])).
  13. Perform ! CreateDataPropertyOrThrow(fields, "isoMillisecond", 𝔽(dateTime.[[ISOMillisecond]])).
  14. Perform ! CreateDataPropertyOrThrow(fields, "isoMinute", 𝔽(dateTime.[[ISOMinute]])).
  15. Perform ! CreateDataPropertyOrThrow(fields, "isoMonth", 𝔽(dateTime.[[ISOMonth]])).
  16. Perform ! CreateDataPropertyOrThrow(fields, "isoNanosecond", 𝔽(dateTime.[[ISONanosecond]])).
  17. Perform ! CreateDataPropertyOrThrow(fields, "isoSecond", 𝔽(dateTime.[[ISOSecond]])).
  18. Perform ! CreateDataPropertyOrThrow(fields, "isoYear", 𝔽(dateTime.[[ISOYear]])).
  19. Perform ! CreateDataPropertyOrThrow(fields, "offset", offset).
  20. Perform ! CreateDataPropertyOrThrow(fields, "timeZone", timeZone).
  21. Return fields.

6.3.54 Temporal.ZonedDateTime.prototype.getCalendar ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ToTemporalCalendarObject(zonedDateTime.[[Calendar]]).

6.3.55 Temporal.ZonedDateTime.prototype.getTimeZone ( )

This method performs the following steps when called:

  1. Let zonedDateTime be the this value.
  2. Perform ? RequireInternalSlot(zonedDateTime, [[InitializedTemporalZonedDateTime]]).
  3. Return ToTemporalTimeZoneObject(zonedDateTime.[[TimeZone]]).

6.4 Properties of Temporal.ZonedDateTime Instances

Temporal.ZonedDateTime instances are ordinary objects that inherit properties from the %Temporal.ZonedDateTime.prototype% intrinsic object. Temporal.ZonedDateTime instances are initially created with the internal slots described in Table 6.

Table 6: Internal Slots of Temporal.ZonedDateTime Instances
Internal Slot Description
[[InitializedTemporalZonedDateTime]] The only specified use of this slot is for distinguishing Temporal.ZonedDateTime instances from other objects.
[[Nanoseconds]] A BigInt value representing the number of nanoseconds since the Unix epoch.
[[TimeZone]] An Object representing the time zone.
[[Calendar]] An Object representing the calendar.

6.5 Abstract operations

6.5.1 InterpretISODateTimeOffset ( year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, offsetBehaviour, offsetNanoseconds, timeZone, disambiguation, offsetOption, matchBehaviour )

The abstract operation InterpretISODateTimeOffset takes arguments year (an integer), month (an integer), day (an integer), hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), offsetBehaviour (one of option, exact, or wall), offsetNanoseconds (an integer), timeZone (an Object), disambiguation (one of "earlier", "later", "compatible", or "reject"), offsetOption (one of "ignore", "use", "prefer", or "reject"), and matchBehaviour (one of match exactly or match minutes) and returns either a normal completion containing a BigInt or an abrupt completion.

It determines the exact time in timeZone corresponding to the given calendar date and time, and the given UTC offset in nanoseconds. In the case of more than one possible exact time, or no possible exact time, an answer is determined using offsetBehaviour, disambiguation and offsetOption.

As a special case when parsing ISO 8601 strings which are only required to specify time zone offsets to minutes precision, if matchBehaviour is match minutes, then a value for offsetNanoseconds that is rounded to the nearest minute will be accepted in those cases where offsetNanoseconds is compared against timeZone's offset. If matchBehaviour is match exactly, then this does not happen.

It performs the following steps when called:

  1. Assert: IsValidISODate(year, month, day) is true.
  2. Let dateTime be ? CreateTemporalDateTime(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond, "iso8601").
  3. If offsetBehaviour is wall or offsetOption is "ignore", then
    1. Let instant be ? GetInstantFor(timeZone, dateTime, disambiguation).
    2. Return instant.[[Nanoseconds]].
  4. If offsetBehaviour is exact or offsetOption is "use", then
    1. Let epochNanoseconds be GetUTCEpochNanoseconds(year, month, day, hour, minute, second, millisecond, microsecond, nanosecond).
    2. Set epochNanoseconds to epochNanoseconds - ℤ(offsetNanoseconds).
    3. If ! IsValidEpochNanoseconds(epochNanoseconds) is false, throw a RangeError exception.
    4. Return epochNanoseconds.
  5. Assert: offsetBehaviour is option.
  6. Assert: offsetOption is "prefer" or "reject".
  7. Let possibleInstants be ? GetPossibleInstantsFor(timeZone, dateTime).
  8. For each element candidate of possibleInstants, do
    1. Let candidateNanoseconds be ? GetOffsetNanosecondsFor(timeZone, candidate).
    2. If candidateNanoseconds = offsetNanoseconds, then
      1. Return candidate.[[Nanoseconds]].
    3. If matchBehaviour is match minutes, then
      1. Let roundedCandidateNanoseconds be RoundNumberToIncrement(candidateNanoseconds, 60 × 109, "halfExpand").
      2. If roundedCandidateNanoseconds = offsetNanoseconds, then
        1. Return candidate.[[Nanoseconds]].
  9. If offsetOption is "reject", throw a RangeError exception.
  10. Let instant be ? DisambiguatePossibleInstants(possibleInstants, timeZone, dateTime, disambiguation).
  11. Return instant.[[Nanoseconds]].

6.5.2 ToTemporalZonedDateTime ( item [ , options ] )

The abstract operation ToTemporalZonedDateTime takes argument item (an ECMAScript language value) and optional argument options (an Object) and returns either a normal completion containing a Temporal.ZonedDateTime or an abrupt completion. It returns its argument item if it is already a Temporal.ZonedDateTime instance, converts item to a new Temporal.ZonedDateTime instance if possible, and throws otherwise. It performs the following steps when called:

  1. If options is not present, set options to undefined.
  2. Assert: Type(options) is Object or Undefined.
  3. Let offsetBehaviour be option.
  4. Let matchBehaviour be match exactly.
  5. If Type(item) is Object, then
    1. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Return item.
    2. Let calendar be ? GetTemporalCalendarSlotValueWithISODefault(item).
    3. Let fieldNames be ? CalendarFields(calendar, « "day", "hour", "microsecond", "millisecond", "minute", "month", "monthCode", "nanosecond", "second", "year" »).
    4. Append "timeZone" to fieldNames.
    5. Append "offset" to fieldNames.
    6. Let fields be ? PrepareTemporalFields(item, fieldNames, « "timeZone" »).
    7. Let timeZone be ! Get(fields, "timeZone").
    8. Set timeZone to ? ToTemporalTimeZoneSlotValue(timeZone).
    9. Let offsetString be ! Get(fields, "offset").
    10. Assert: offsetString is a String or undefined.
    11. If offsetString is undefined, then
      1. Set offsetBehaviour to wall.
    12. NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalDisambiguation reads "disambiguation", ToTemporalOffset reads "offset", and InterpretTemporalDateTimeFields reads "overflow").
    13. Let disambiguation be ? ToTemporalDisambiguation(options).
    14. Let offsetOption be ? ToTemporalOffset(options, "reject").
    15. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, options).
  6. Else,
    1. Let string be ? ToString(item).
    2. Let result be ? ParseTemporalZonedDateTimeString(string).
    3. Let timeZoneName be result.[[TimeZone]].[[Name]].
    4. Assert: timeZoneName is not undefined.
    5. Let timeZone be ? ToTemporalTimeZoneSlotValue(timeZoneName).
    6. Let offsetString be result.[[TimeZone]].[[OffsetString]].
    7. If result.[[TimeZone]].[[Z]] is true, then
      1. Set offsetBehaviour to exact.
    8. Else if offsetString is undefined, then
      1. Set offsetBehaviour to wall.
    9. Let calendar be result.[[Calendar]].
    10. If calendar is undefined, set calendar to "iso8601".
    11. If IsBuiltinCalendar(calendar) is false, throw a RangeError exception.
    12. Set calendar to the ASCII-lowercase of calendar.
    13. Set matchBehaviour to match minutes.
    14. Let disambiguation be ? ToTemporalDisambiguation(options).
    15. Let offsetOption be ? ToTemporalOffset(options, "reject").
    16. Perform ? ToTemporalOverflow(options).
  7. Let offsetNanoseconds be 0.
  8. If offsetBehaviour is option, then
    1. If IsTimeZoneOffsetString(offsetString) is false, throw a RangeError exception.
    2. Set offsetNanoseconds to ParseTimeZoneOffsetString(offsetString).
  9. Let epochNanoseconds be ? InterpretISODateTimeOffset(result.[[Year]], result.[[Month]], result.[[Day]], result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], offsetBehaviour, offsetNanoseconds, timeZone, disambiguation, offsetOption, matchBehaviour).
  10. Return ! CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar).

6.5.3 CreateTemporalZonedDateTime ( epochNanoseconds, timeZone, calendar [ , newTarget ] )

The abstract operation CreateTemporalZonedDateTime takes arguments epochNanoseconds (a BigInt), timeZone (a String or Object), and calendar (a String or Object) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.ZonedDateTime, or an abrupt completion. It creates a Temporal.ZonedDateTime instance and fills the internal slots with valid values. It performs the following steps when called:

  1. Assert: ! IsValidEpochNanoseconds(epochNanoseconds) is true.
  2. If newTarget is not present, set newTarget to %Temporal.ZonedDateTime%.
  3. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.ZonedDateTime.prototype%", « [[InitializedTemporalZonedDateTime]], [[Nanoseconds]], [[TimeZone]], [[Calendar]] »).
  4. Set object.[[Nanoseconds]] to epochNanoseconds.
  5. Set object.[[TimeZone]] to timeZone.
  6. Set object.[[Calendar]] to calendar.
  7. Return object.

6.5.4 TemporalZonedDateTimeToString ( zonedDateTime, precision, showCalendar, showTimeZone, showOffset [ , increment [ , unit [ , roundingMode ] ] ] )

The abstract operation TemporalZonedDateTimeToString takes arguments zonedDateTime (a Temporal.ZonedDateTime), precision (one of "auto", "minute", or an integer between 0 and 9 inclusive), showCalendar (one of "auto", "always", "never", or "critical"), showTimeZone (one of "auto", "never", or "critical"), and showOffset (one of "auto" or "never") and optional arguments increment (an integer), unit (one of "minute", "second", "millisecond", "microsecond", or "nanosecond"), and roundingMode (one of "ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", or "halfEven") and returns either a normal completion containing a String or an abrupt completion. It returns an ISO 8601 string representation of its argument, including a time zone name annotation and calendar annotation, which are extensions to the ISO 8601 format. It performs the following steps when called:

  1. If increment is not present, set increment to 1.
  2. If unit is not present, set unit to "nanosecond".
  3. If roundingMode is not present, set roundingMode to "trunc".
  4. Let ns be RoundTemporalInstant(zonedDateTime.[[Nanoseconds]], increment, unit, roundingMode).
  5. Let timeZone be zonedDateTime.[[TimeZone]].
  6. Let instant be ! CreateTemporalInstant(ns).
  7. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, "iso8601").
  8. Let dateTimeString be ! TemporalDateTimeToString(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], temporalDateTime.[[ISOHour]], temporalDateTime.[[ISOMinute]], temporalDateTime.[[ISOSecond]], temporalDateTime.[[ISOMillisecond]], temporalDateTime.[[ISOMicrosecond]], temporalDateTime.[[ISONanosecond]], "iso8601", precision, "never").
  9. If showOffset is "never", then
    1. Let offsetString be the empty String.
  10. Else,
    1. Let offsetNs be ? GetOffsetNanosecondsFor(timeZone, instant).
    2. Let offsetString be ! FormatISOTimeZoneOffsetString(offsetNs).
  11. If showTimeZone is "never", then
    1. Let timeZoneString be the empty String.
  12. Else,
    1. Let timeZoneIdentifier be ? ToTemporalTimeZoneIdentifier(timeZone).
    2. If showTimeZone is "critical", let flag be "!"; else let flag be the empty String.
    3. Let timeZoneString be the string-concatenation of the code unit 0x005B (LEFT SQUARE BRACKET), flag, timeZoneIdentifier, and the code unit 0x005D (RIGHT SQUARE BRACKET).
  13. Let calendarString be ? MaybeFormatCalendarAnnotation(zonedDateTime.[[Calendar]], showCalendar).
  14. Return the string-concatenation of dateTimeString, offsetString, timeZoneString, and calendarString.

6.5.5 AddZonedDateTime ( epochNanoseconds, timeZone, calendar, years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds [ , options ] )

The abstract operation AddZonedDateTime takes arguments epochNanoseconds (a BigInt), timeZone (an Object), calendar (an Object), years (an integer), months (an integer), weeks (an integer), days (an integer), hours (an integer), minutes (an integer), seconds (an integer), milliseconds (an integer), microseconds (an integer), and nanoseconds (an integer) and optional argument options (an Object) and returns either a normal completion containing a BigInt or an abrupt completion. It adds a duration in various units to a number of nanoseconds epochNanoseconds since the Unix epoch, subject to the rules of timeZone and calendar, and returns the result as a BigInt value. As specified in RFC 5545, the date portion of the duration is added in calendar days, and the time portion is added in exact time. It performs the following steps when called:

  1. If options is not present, set options to undefined.
  2. Assert: Type(options) is Object or Undefined.
  3. If years = 0, months = 0, weeks = 0, and days = 0, then
    1. Return ? AddInstant(epochNanoseconds, hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
  4. Let instant be ! CreateTemporalInstant(epochNanoseconds).
  5. Let temporalDateTime be ? GetPlainDateTimeFor(timeZone, instant, calendar).
  6. Let datePart be ! CreateTemporalDate(temporalDateTime.[[ISOYear]], temporalDateTime.[[ISOMonth]], temporalDateTime.[[ISODay]], calendar).
  7. Let dateDuration be ! CreateTemporalDuration(years, months, weeks, days, 0, 0, 0, 0, 0, 0).
  8. Let addedDate be ? CalendarDateAdd(calendar, datePart, dateDuration, options).
  9. Let intermediateDateTime be ? CreateTemporalDateTime(addedDate.[[ISOYear]], addedDate.[[ISOMonth]], addedDate.[[ISODay]], temporalDateTime.[[ISOHour]], temporalDateTime.[[ISOMinute]], temporalDateTime.[[ISOSecond]], temporalDateTime.[[ISOMillisecond]], temporalDateTime.[[ISOMicrosecond]], temporalDateTime.[[ISONanosecond]], calendar).
  10. Let intermediateInstant be ? GetInstantFor(timeZone, intermediateDateTime, "compatible").
  11. Return ? AddInstant(intermediateInstant.[[Nanoseconds]], hours, minutes, seconds, milliseconds, microseconds, nanoseconds).

6.5.6 DifferenceZonedDateTime ( ns1, ns2, timeZone, calendar, largestUnit, options )

The abstract operation DifferenceZonedDateTime takes arguments ns1 (a BigInt), ns2 (a BigInt), timeZone (an Object), calendar (an Object), largestUnit (a String), and options (an Object) and returns either a normal completion containing a Duration Record or an abrupt completion. It computes the difference between two exact times expressed in nanoseconds since the Unix epoch, and balances the result so that there is no non-zero unit larger than largestUnit in the result, taking calendar reckoning and time zone offset changes into account. It performs the following steps when called:

  1. If ns1 is ns2, then
    1. Return ! CreateDurationRecord(0, 0, 0, 0, 0, 0, 0, 0, 0, 0).
  2. Let startInstant be ! CreateTemporalInstant(ns1).
  3. Let startDateTime be ? GetPlainDateTimeFor(timeZone, startInstant, calendar).
  4. Let endInstant be ! CreateTemporalInstant(ns2).
  5. Let endDateTime be ? GetPlainDateTimeFor(timeZone, endInstant, calendar).
  6. Let dateDifference be ? DifferenceISODateTime(startDateTime.[[ISOYear]], startDateTime.[[ISOMonth]], startDateTime.[[ISODay]], startDateTime.[[ISOHour]], startDateTime.[[ISOMinute]], startDateTime.[[ISOSecond]], startDateTime.[[ISOMillisecond]], startDateTime.[[ISOMicrosecond]], startDateTime.[[ISONanosecond]], endDateTime.[[ISOYear]], endDateTime.[[ISOMonth]], endDateTime.[[ISODay]], endDateTime.[[ISOHour]], endDateTime.[[ISOMinute]], endDateTime.[[ISOSecond]], endDateTime.[[ISOMillisecond]], endDateTime.[[ISOMicrosecond]], endDateTime.[[ISONanosecond]], calendar, largestUnit, options).
  7. Let intermediateNs be ? AddZonedDateTime(ns1, timeZone, calendar, dateDifference.[[Years]], dateDifference.[[Months]], dateDifference.[[Weeks]], 0, 0, 0, 0, 0, 0, 0).
  8. Let timeRemainderNs be ns2 - intermediateNs.
  9. Let intermediate be ! CreateTemporalZonedDateTime(intermediateNs, timeZone, calendar).
  10. Let result be ? NanosecondsToDays(ℝ(timeRemainderNs), intermediate).
  11. Let timeDifference be ! BalanceDuration(0, 0, 0, 0, 0, 0, result.[[Nanoseconds]], "hour").
  12. Return ! CreateDurationRecord(dateDifference.[[Years]], dateDifference.[[Months]], dateDifference.[[Weeks]], result.[[Days]], timeDifference.[[Hours]], timeDifference.[[Minutes]], timeDifference.[[Seconds]], timeDifference.[[Milliseconds]], timeDifference.[[Microseconds]], timeDifference.[[Nanoseconds]]).

6.5.7 NanosecondsToDays ( nanoseconds, relativeTo )

The abstract operation NanosecondsToDays takes arguments nanoseconds (an integer) and relativeTo (undefined, a Temporal.PlainDate, or a Temporal.ZonedDateTime) and returns either a normal completion containing a Record with fields [[Days]] (an integer), [[Nanoseconds]] (an integer), and [[DayLength]] (an integer), or an abrupt completion. It converts a number of nanoseconds relative to a Temporal.ZonedDateTime relativeTo, and converts it into a number of days and remainder of nanoseconds, taking into account any offset changes in the time zone of relativeTo. It also returns the length of the last day in nanoseconds, for rounding purposes. It performs the following steps when called:

  1. Let dayLengthNs be nsPerDay.
  2. If nanoseconds = 0, then
    1. Return the Record { [[Days]]: 0, [[Nanoseconds]]: 0, [[DayLength]]: dayLengthNs }.
  3. If nanoseconds < 0, let sign be -1; else, let sign be 1.
  4. If Type(relativeTo) is not Object or relativeTo does not have an [[InitializedTemporalZonedDateTime]] internal slot, then
    1. Return the Record { [[Days]]: truncate(nanoseconds / dayLengthNs), [[Nanoseconds]]: (abs(nanoseconds) modulo dayLengthNs) × sign, [[DayLength]]: dayLengthNs }.
  5. Let startNs be ℝ(relativeTo.[[Nanoseconds]]).
  6. Let startInstant be ! CreateTemporalInstant(ℤ(startNs)).
  7. Let startDateTime be ? GetPlainDateTimeFor(relativeTo.[[TimeZone]], startInstant, relativeTo.[[Calendar]]).
  8. Let endNs be startNs + nanoseconds.
  9. If ! IsValidEpochNanoseconds(ℤ(endNs)) is false, throw a RangeError exception.
  10. Let endInstant be ! CreateTemporalInstant(ℤ(endNs)).
  11. Let endDateTime be ? GetPlainDateTimeFor(relativeTo.[[TimeZone]], endInstant, relativeTo.[[Calendar]]).
  12. Let dateDifference be ? DifferenceISODateTime(startDateTime.[[ISOYear]], startDateTime.[[ISOMonth]], startDateTime.[[ISODay]], startDateTime.[[ISOHour]], startDateTime.[[ISOMinute]], startDateTime.[[ISOSecond]], startDateTime.[[ISOMillisecond]], startDateTime.[[ISOMicrosecond]], startDateTime.[[ISONanosecond]], endDateTime.[[ISOYear]], endDateTime.[[ISOMonth]], endDateTime.[[ISODay]], endDateTime.[[ISOHour]], endDateTime.[[ISOMinute]], endDateTime.[[ISOSecond]], endDateTime.[[ISOMillisecond]], endDateTime.[[ISOMicrosecond]], endDateTime.[[ISONanosecond]], relativeTo.[[Calendar]], "day", OrdinaryObjectCreate(null)).
  13. Let days be dateDifference.[[Days]].
  14. Let intermediateNs be ℝ(? AddZonedDateTime(ℤ(startNs), relativeTo.[[TimeZone]], relativeTo.[[Calendar]], 0, 0, 0, days, 0, 0, 0, 0, 0, 0)).
  15. If sign is 1, then
    1. Repeat, while days > 0 and intermediateNs > endNs,
      1. Set days to days - 1.
      2. Set intermediateNs to ℝ(? AddZonedDateTime(ℤ(startNs), relativeTo.[[TimeZone]], relativeTo.[[Calendar]], 0, 0, 0, days, 0, 0, 0, 0, 0, 0)).
  16. Set nanoseconds to endNs - intermediateNs.
  17. Let done be false.
  18. Repeat, while done is false,
    1. Let oneDayFartherNs be ℝ(? AddZonedDateTime(ℤ(intermediateNs), relativeTo.[[TimeZone]], relativeTo.[[Calendar]], 0, 0, 0, sign, 0, 0, 0, 0, 0, 0)).
    2. Set dayLengthNs to oneDayFartherNs - intermediateNs.
    3. If (nanoseconds - dayLengthNs) × sign ≥ 0, then
      1. Set nanoseconds to nanoseconds - dayLengthNs.
      2. Set intermediateNs to oneDayFartherNs.
      3. Set days to days + sign.
    4. Else,
      1. Set done to true.
  19. If days < 0 and sign = 1, throw a RangeError exception.
  20. If days > 0 and sign = -1, throw a RangeError exception.
  21. If nanoseconds < 0, then
    1. Assert: sign is -1.
  22. If nanoseconds > 0 and sign = -1, throw a RangeError exception.
  23. Assert: The inequality abs(nanoseconds) < abs(dayLengthNs) holds.
  24. Return the Record { [[Days]]: days, [[Nanoseconds]]: nanoseconds, [[DayLength]]: abs(dayLengthNs) }.

6.5.8 DifferenceTemporalZonedDateTime ( operation, zonedDateTime, other, options )

The abstract operation DifferenceTemporalZonedDateTime takes arguments operation (until or since), zonedDateTime (a Temporal.ZonedDateTime), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by zonedDateTime and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:

  1. If operation is since, let sign be -1. Otherwise, let sign be 1.
  2. Set other to ? ToTemporalZonedDateTime(other).
  3. If ? CalendarEquals(zonedDateTime.[[Calendar]], other.[[Calendar]]) is false, then
    1. Throw a RangeError exception.
  4. Let resolvedOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  5. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, datetime, « », "nanosecond", "hour").
  6. Perform ! CreateDataPropertyOrThrow(resolvedOptions, "largestUnit", settings.[[LargestUnit]]).
  7. If settings.[[LargestUnit]] is not one of "year", "month", "week", or "day", then
    1. Let result be DifferenceInstant(zonedDateTime.[[Nanoseconds]], other.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[LargestUnit]], settings.[[RoundingMode]]).
    2. Return ! CreateTemporalDuration(0, 0, 0, 0, sign × result.[[Hours]], sign × result.[[Minutes]], sign × result.[[Seconds]], sign × result.[[Milliseconds]], sign × result.[[Microseconds]], sign × result.[[Nanoseconds]]).
  8. If ? TimeZoneEquals(zonedDateTime.[[TimeZone]], other.[[TimeZone]]) is false, then
    1. Throw a RangeError exception.
  9. Let difference be ? DifferenceZonedDateTime(zonedDateTime.[[Nanoseconds]], other.[[Nanoseconds]], zonedDateTime.[[TimeZone]], zonedDateTime.[[Calendar]], settings.[[LargestUnit]], resolvedOptions).
  10. Let roundResult be (? RoundDuration(difference.[[Years]], difference.[[Months]], difference.[[Weeks]], difference.[[Days]], difference.[[Hours]], difference.[[Minutes]], difference.[[Seconds]], difference.[[Milliseconds]], difference.[[Microseconds]], difference.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]], zonedDateTime)).[[DurationRecord]].
  11. Let result be ? AdjustRoundedDurationDays(roundResult.[[Years]], roundResult.[[Months]], roundResult.[[Weeks]], roundResult.[[Days]], roundResult.[[Hours]], roundResult.[[Minutes]], roundResult.[[Seconds]], roundResult.[[Milliseconds]], roundResult.[[Microseconds]], roundResult.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]], zonedDateTime).
  12. Return ! CreateTemporalDuration(sign × result.[[Years]], sign × result.[[Months]], sign × result.[[Weeks]], sign × result.[[Days]], sign × result.[[Hours]], sign × result.[[Minutes]], sign × result.[[Seconds]], sign × result.[[Milliseconds]], sign × result.[[Microseconds]], sign × result.[[Nanoseconds]]).

6.5.9 AddDurationToOrSubtractDurationFromZonedDateTime ( operation, zonedDateTime, temporalDurationLike, options )

The abstract operation AddDurationToOrSubtractDurationFromZonedDateTime takes arguments operation (add or subtract), zonedDateTime (a Temporal.ZonedDateTime), temporalDurationLike (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.ZonedDateTime or an abrupt completion. It adds/subtracts temporalDurationLike to/from zonedDateTime. It performs the following steps when called:

  1. If operation is subtract, let sign be -1. Otherwise, let sign be 1.
  2. Let duration be ? ToTemporalDurationRecord(temporalDurationLike).
  3. Set options to ? GetOptionsObject(options).
  4. Let timeZone be zonedDateTime.[[TimeZone]].
  5. Let calendar be zonedDateTime.[[Calendar]].
  6. Let epochNanoseconds be ? AddZonedDateTime(zonedDateTime.[[Nanoseconds]], timeZone, calendar, sign × duration.[[Years]], sign × duration.[[Months]], sign × duration.[[Weeks]], sign × duration.[[Days]], sign × duration.[[Hours]], sign × duration.[[Minutes]], sign × duration.[[Seconds]], sign × duration.[[Milliseconds]], sign × duration.[[Microseconds]], sign × duration.[[Nanoseconds]], options).
  7. Return ! CreateTemporalZonedDateTime(epochNanoseconds, timeZone, calendar).

7 Temporal.Duration Objects

A Temporal.Duration object describes the difference in elapsed time between two other Temporal objects of the same type: Instant, PlainDate, PlainDateTime, PlainTime, PlainYearMonth, or ZonedDateTime. Objects of this type are only created via the .since() and .until() methods of these objects.

7.1 The Temporal.Duration Constructor

The Temporal.Duration constructor:

  • creates and initializes a new Temporal.Duration object when called as a constructor.
  • is not intended to be called as a function and will throw an exception when called in that manner.
  • may be used as the value of an extends clause of a class definition. Subclass constructors that intend to inherit the specified Temporal.Duration behaviour must include a super call to the %Temporal.D