Stage 3 Draft / June 14, 2024

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.Calendar ( . . . )

See 12.

1.2.2 Temporal.Instant ( . . . )

See 8.

1.2.3 Temporal.PlainDateTime ( . . . )

See 5.

1.2.4 Temporal.PlainDate ( . . . )

See 3.

1.2.5 Temporal.PlainTime ( . . . )

See 4.

1.2.6 Temporal.PlainYearMonth ( . . . )

See 9.

1.2.7 Temporal.PlainMonthDay ( . . . )

See 10.

1.2.8 Temporal.TimeZone ( . . . )

See 11.

1.2.9 Temporal.Duration ( . . . )

See 7.

1.2.10 Temporal.ZonedDateTime ( . . . )

See 6.

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 SystemTimeZoneIdentifier().

2.2.2 Temporal.Now.instant ( )

This function performs the following steps when called:

  1. Return SystemInstant().

2.2.3 Temporal.Now.plainDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

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

2.2.4 Temporal.Now.zonedDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

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

2.2.5 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.6 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 SystemUTCEpochMilliseconds ( )

The abstract operation SystemUTCEpochMilliseconds takes no arguments and returns a Number. It performs the following steps when called:

  1. Let global be GetGlobalObject().
  2. Let nowNs be HostSystemUTCEpochNanoseconds(global).
  3. Return 𝔽(floor(nowNs / 106)).

2.3.3 SystemUTCEpochNanoseconds ( )

The abstract operation SystemUTCEpochNanoseconds takes no arguments and returns a BigInt. It performs the following steps when called:

  1. Let global be GetGlobalObject().
  2. Let nowNs be HostSystemUTCEpochNanoseconds(global).
  3. Return (nowNs).

2.3.4 SystemInstant ( )

The abstract operation SystemInstant takes no arguments and returns a Temporal.Instant. It performs the following steps when called:

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

2.3.5 SystemDateTime ( temporalTimeZoneLike, calendarLike )

The abstract operation SystemDateTime takes arguments temporalTimeZoneLike (an ECMAScript language value) and calendarLike (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainDateTime or a throw completion. It performs the following steps when called:

  1. If temporalTimeZoneLike is undefined, then
    1. Let timeZone be SystemTimeZoneIdentifier().
  2. Else,
    1. Let timeZone be ? ToTemporalTimeZoneSlotValue(temporalTimeZoneLike).
  3. Let calendar be ? ToTemporalCalendarSlotValue(calendarLike).
  4. Let instant be SystemInstant().
  5. Let timeZoneRec be ? CreateTimeZoneMethodsRecord(timeZone, « get-offset-nanoseconds-for »).
  6. Return ? GetPlainDateTimeFor(timeZoneRec, instant, calendar).

2.3.6 SystemZonedDateTime ( temporalTimeZoneLike, calendarLike )

The abstract operation SystemZonedDateTime takes arguments temporalTimeZoneLike (an ECMAScript language value) and calendarLike (an ECMAScript language value) and returns either a normal completion containing a Temporal.ZonedDateTime or a throw completion. It performs the following steps when called:

  1. If temporalTimeZoneLike is undefined, then
    1. Let timeZone be SystemTimeZoneIdentifier().
  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 item is an Object and item has an [[InitializedTemporalDate]] internal slot, then
    1. Perform ? GetTemporalOverflowOption(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.era

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

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

3.3.5 get Temporal.PlainDate.prototype.eraYear

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

  1. Let plainDate be the this value.
  2. Perform ? RequireInternalSlot(plainDate, [[InitializedTemporalDate]]).
  3. Let calendar be plainDate.[[Calendar]].
  4. Let result be ? CalendarEraYear(calendar, plainDate).
  5. If result is undefined, return undefined.
  6. Return 𝔽(result).

3.3.6 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.7 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.8 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.9 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 calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « day »).
  4. Return 𝔽(? CalendarDay(calendarRec, temporalDate)).

3.3.10 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.11 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.12 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. Let result be ? CalendarWeekOfYear(calendar, temporalDate).
  5. If result is undefined, return undefined.
  6. Return 𝔽(result).

3.3.13 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. Let result be ? CalendarYearOfWeek(calendar, temporalDate).
  5. If result is undefined, return undefined.
  6. Return 𝔽(result).

3.3.14 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.15 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.16 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.17 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.18 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.19 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 calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « fields, year-month-from-fields »).
  4. Let fields be ? PrepareCalendarFields(calendarRec, temporalDate, « "monthCode", "year" », «», «»).
  5. Return ? CalendarYearMonthFromFields(calendarRec, fields).
  6. 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.20 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 calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « fields, month-day-from-fields »).
  4. Let fields be ? PrepareCalendarFields(calendarRec, temporalDate, « "day", "monthCode" », «», «»).
  5. Return ? CalendarMonthDayFromFields(calendarRec, fields).
  6. 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.21 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.22 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.23 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. Let calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « date-add »).
  6. Return ? AddDate(calendarRec, temporalDate, duration, options).

3.3.24 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. Let calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « date-add »).
  7. Return ? AddDate(calendarRec, temporalDate, negatedDuration, options).

3.3.25 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 ? IsPartialTemporalObject(temporalDateLike) is false, throw a TypeError exception.
  4. Let resolvedOptions be ? SnapshotOwnProperties(? GetOptionsObject(options), null).
  5. Let calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « date-from-fields, fields, merge-fields »).
  6. Let fieldsResult be ? PrepareCalendarFieldsAndFieldNames(calendarRec, temporalDate, « "day", "month", "monthCode", "year" »).
  7. Let partialDate be ? PrepareTemporalFields(temporalDateLike, fieldsResult.[[FieldNames]], partial).
  8. Let fields be ? CalendarMergeFields(calendarRec, fieldsResult.[[Fields]], partialDate).
  9. Set fields to ? PrepareTemporalFields(fields, fieldsResult.[[FieldNames]], «»).
  10. Return ? CalendarDateFromFields(calendarRec, fields, resolvedOptions).

3.3.26 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.27 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.28 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.29 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.30 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. Set temporalTime to ? ToTemporalTimeOrMidnight(temporalTime).
  4. Return ? CreateTemporalDateTime(temporalDate.[[ISOYear]], temporalDate.[[ISOMonth]], temporalDate.[[ISODay]], temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], temporalDate.[[Calendar]]).

3.3.31 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 item is an 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. Set temporalTime to ? ToTemporalTimeOrMidnight(temporalTime).
  6. 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 timeZoneRec be ? CreateTimeZoneMethodsRecord(timeZone, « get-offset-nanoseconds-for, get-possible-instants-for »).
  8. Let instant be ? GetInstantFor(timeZoneRec, temporalDateTime, "compatible").
  9. Return ! CreateTemporalZonedDateTime(instant.[[Nanoseconds]], timeZone, temporalDate.[[Calendar]]).

3.3.32 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 ? GetTemporalShowCalendarNameOption(options).
  5. Return ? TemporalDateToString(temporalDate, showCalendar).

3.3.33 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.34 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.35 Temporal.PlainDate.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.
Note

This method always throws, because in the absence of valueOf(), expressions with arithmetic operators such as plainDate1 > plainDate2 would fall back to being equivalent to plainDate1.toString() > plainDate2.toString(). Lexicographical comparison of serialized strings might not seem obviously wrong, because the result would sometimes be correct. Implementations are encouraged to phrase the error message to point users to Temporal.PlainDate.compare(), Temporal.PlainDate.prototype.equals(), and/or Temporal.PlainDate.prototype.toString().

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]] A String or 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 ISO Date 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 a throw 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 takes argument item (an ECMAScript language value) and optional argument options (an Object or undefined) and returns either a normal completion containing a Temporal.PlainDate or a throw completion. It 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. It performs the following steps when called:

  1. If options is not present, set options to undefined.
  2. If options is not undefined, set options to ? SnapshotOwnProperties(! GetOptionsObject(options), null).
  3. If item is an 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 ? GetTemporalOverflowOption(options).
      2. Let instant be ! CreateTemporalInstant(item.[[Nanoseconds]]).
      3. Let timeZoneRec be ? CreateTimeZoneMethodsRecord(item.[[TimeZone]], « get-offset-nanoseconds-for »).
      4. Let plainDateTime be ? GetPlainDateTimeFor(timeZoneRec, instant, item.[[Calendar]]).
      5. Return ! CreateTemporalDate(plainDateTime.[[ISOYear]], plainDateTime.[[ISOMonth]], plainDateTime.[[ISODay]], plainDateTime.[[Calendar]]).
    3. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Perform ? GetTemporalOverflowOption(options).
      2. Return ! CreateTemporalDate(item.[[ISOYear]], item.[[ISOMonth]], item.[[ISODay]], item.[[Calendar]]).
    4. Let calendar be ? GetTemporalCalendarSlotValueWithISODefault(item).
    5. Let calendarRec be ? CreateCalendarMethodsRecord(calendar, « date-from-fields, fields »).
    6. Let fields be ? PrepareCalendarFields(calendarRec, item, « "day", "month", "monthCode", "year" », «», «»).
    7. Return ? CalendarDateFromFields(calendarRec, fields, options).
  4. If item is not a String, throw a TypeError exception.
  5. Let result be ? ParseTemporalDateTimeString(item).
  6. Assert: IsValidISODate(result.[[Year]], result.[[Month]], result.[[Day]]) is true.
  7. Let calendar be result.[[Calendar]].
  8. If calendar is empty, set calendar to "iso8601".
  9. If IsBuiltinCalendar(calendar) is false, throw a RangeError exception.
  10. Set calendar to the ASCII-lowercase of calendar.
  11. Perform ? GetTemporalOverflowOption(options).
  12. Return ? CreateTemporalDate(result.[[Year]], result.[[Month]], result.[[Day]], calendar).

3.5.5 ISODateSurpasses ( sign, y1, m1, d1, y2, m2, d2 )

The abstract operation ISODateSurpasses takes arguments sign (-1 or 1), y1 (an integer), m1 (an integer), d1 (an integer), y2 (an integer), m2 (an integer), and d2 (an integer) and returns a Boolean. The return value indicates whether the date denoted by y1, m1, d1 surpasses that denoted by y2, m2, d2 in the direction denoted by sign. The former date does not have to exist. Note that this operation is specific to date difference calculations and is not the same as CompareISODate. It performs the following steps when called:

  1. Assert: IsValidISODate(y2, m2, d2).
  2. Let comparison be CompareISODate(y1, m1, d1, y2, m2, d2).
  3. If sign × comparison = 1, return true.
  4. Return false.

3.5.6 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. Assert: IsValidISODate(y1, m1, d1) is true.
  2. Assert: IsValidISODate(y2, m2, d2) is true.
  3. Let sign be -CompareISODate(y1, m1, d1, y2, m2, d2).
  4. If sign = 0, return ! CreateDateDurationRecord(0, 0, 0, 0).
  5. Let years be 0.
  6. If largestUnit is "year", then
    1. Let candidateYears be sign.
    2. Repeat, while ISODateSurpasses(sign, y1 + candidateYears, m1, d1, y2, m2, d2) is false,
      1. Set years to candidateYears.
      2. Set candidateYears to candidateYears + sign.
  7. Let months be 0.
  8. If largestUnit is "year" or largestUnit is "month", then
    1. Let candidateMonths be sign.
    2. Let intermediate be BalanceISOYearMonth(y1 + years, m1 + candidateMonths).
    3. Repeat, while ISODateSurpasses(sign, intermediate.[[Year]], intermediate.[[Month]], d1, y2, m2, d2) is false,
      1. Set months to candidateMonths.
      2. Set candidateMonths to candidateMonths + sign.
      3. Set intermediate to BalanceISOYearMonth(intermediate.[[Year]], intermediate.[[Month]] + sign).
  9. Set intermediate to BalanceISOYearMonth(y1 + years, m1 + months).
  10. Let constrained be ! RegulateISODate(intermediate.[[Year]], intermediate.[[Month]], d1, "constrain").
  11. Let weeks be 0.
  12. If largestUnit is "week", then
    1. Let candidateWeeks be sign.
    2. Set intermediate to BalanceISODate(constrained.[[Year]], constrained.[[Month]], constrained.[[Day]] + 7 × candidateWeeks).
    3. Repeat, while ISODateSurpasses(sign, intermediate.[[Year]], intermediate.[[Month]], intermediate.[[Day]], y2, m2, d2) is false,
      1. Set weeks to candidateWeeks.
      2. Set candidateWeeks to candidateWeeks + sign.
      3. Set intermediate to BalanceISODate(intermediate.[[Year]], intermediate.[[Month]], intermediate.[[Day]] + 7 × sign).
  13. Let days be 0.
  14. Let candidateDays be sign.
  15. Set intermediate to BalanceISODate(constrained.[[Year]], constrained.[[Month]], constrained.[[Day]] + 7 × weeks + candidateDays).
  16. Repeat, while ISODateSurpasses(sign, intermediate.[[Year]], intermediate.[[Month]], intermediate.[[Day]], y2, m2, d2) is false,
    1. Set days to candidateDays.
    2. Set candidateDays to candidateDays + sign.
    3. Set intermediate to BalanceISODate(intermediate.[[Year]], intermediate.[[Month]], intermediate.[[Day]] + sign).
  17. Return ! CreateDateDurationRecord(years, months, weeks, days).

3.5.7 DifferenceDate ( calendarRec, one, two, options )

The abstract operation DifferenceDate takes arguments calendarRec (a Calendar Methods Record), one (a Temporal.PlainDate), two (a Temporal.PlainDate), and options (an Object) and returns either a normal completion containing a Temporal.Duration or a throw completion. It determines the difference between the dates one and two. Usually this is accomplished by calling the dateUntil method of the given calendar as in CalendarDateUntil, but if the dates are equal or no units greater than days are needed in the difference, the computation will not cause an observable method call. It performs the following steps when called:

  1. Assert: one.[[Calendar]] and two.[[Calendar]] have been determined to be equivalent as with CalendarEquals.
  2. Assert: options is an ordinary Object.
  3. Assert: options.[[Prototype]] is null.
  4. Assert: options has a "largestUnit" data property.
  5. If one.[[ISOYear]] = two.[[ISOYear]] and one.[[ISOMonth]] = two.[[ISOMonth]] and one.[[ISODay]] = two.[[ISODay]], then
    1. Return ! CreateTemporalDuration(0, 0, 0, 0, 0, 0, 0, 0, 0, 0).
  6. If ! Get(options, "largestUnit") is "day", then
    1. Let days be DaysUntil(one, two).
    2. Return ! CreateTemporalDuration(0, 0, 0, days, 0, 0, 0, 0, 0, 0).
  7. Return ? CalendarDateUntil(calendarRec, one, two, options).

3.5.8 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 a throw 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.9 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.10 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.11 PadISOYear ( y )

The abstract operation PadISOYear takes argument y (an integer) and returns a String. It returns a String representation of y suitable for inclusion in an ISO 8601 string, either in 4-digit format or 6-digit format with sign. It performs the following steps when called:

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

3.5.12 TemporalDateToString ( temporalDate, showCalendar )

The abstract operation TemporalDateToString takes arguments temporalDate (a Temporal.PlainDate) and showCalendar ("auto", "always", "never", or "critical") and returns either a normal completion containing a String or a throw completion. It formats temporalDate to an ISO 8601 string. It performs the following steps when called:

  1. Let year be PadISOYear(temporalDate.[[ISOYear]]).
  2. Let month be ToZeroPaddedDecimalString(temporalDate.[[ISOMonth]], 2).
  3. Let day be ToZeroPaddedDecimalString(temporalDate.[[ISODay]], 2).
  4. Let calendar be ? MaybeFormatCalendarAnnotation(temporalDate.[[Calendar]], showCalendar).
  5. Return the string-concatenation of year, the code unit 0x002D (HYPHEN-MINUS), month, the code unit 0x002D (HYPHEN-MINUS), day, and calendar.

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

The abstract operation AddISODate takes arguments year (an integer), month (an integer), day (an integer), years (an integer), months (an integer), weeks (an integer), days (an integer), and overflow ("constrain" or "reject") and returns either a normal completion containing an ISO Date Record or a throw completion. It adds the duration denoted by years, months, weeks, days to the date denoted by year, month, day, according to ISO 8601 calendar arithmetic. If addition of years or months results in a nonexistent date, depending on overflow it will be coerced to an existing date or the operation will throw. It performs the following steps when called:

  1. Assert: IsValidISODate(year, month, day) is true.
  2. Let intermediate be BalanceISOYearMonth(year + years, month + months).
  3. Set intermediate to ? RegulateISODate(intermediate.[[Year]], intermediate.[[Month]], day, overflow).
  4. Set days to days + 7 × weeks.
  5. Let d be intermediate.[[Day]] + days.
  6. Return BalanceISODate(intermediate.[[Year]], intermediate.[[Month]], d).

3.5.14 AddDate ( calendarRec, plainDate, duration [ , options ] )

The abstract operation AddDate takes arguments calendarRec (a Calendar Methods Record), plainDate (a Temporal.PlainDate), and duration (a Temporal.Duration) and optional argument options (an Object or undefined) and returns either a normal completion containing a Temporal.PlainDate or a throw completion. It adds duration to plainDate. Usually this is accomplished by calling the dateAdd method of the given calendar as in CalendarDateAdd, but if the duration only contains days, the computation will not cause an observable method call. It performs the following steps when called:

  1. Assert: CalendarMethodsRecordHasLookedUp(calendarRec, date-add) is true.
  2. If options is not present, set options to undefined.
  3. If duration.[[Years]] ≠ 0, or duration.[[Months]] ≠ 0, or duration.[[Weeks]] ≠ 0, then
    1. Return ? CalendarDateAdd(calendarRec, plainDate, duration, options).
  4. Let overflow be ? GetTemporalOverflowOption(options).
  5. Let norm be NormalizeTimeDuration(duration.[[Hours]], duration.[[Minutes]], duration.[[Seconds]], duration.[[Milliseconds]], duration.[[Microseconds]], duration.[[Nanoseconds]]).
  6. Let balancedDuration be ! BalanceTimeDuration(norm, "day").
  7. Let days be duration.[[Days]] + balancedDuration.[[Days]].
  8. Let result be ? AddISODate(plainDate.[[ISOYear]], plainDate.[[ISOMonth]], plainDate.[[ISODay]], 0, 0, 0, days, overflow).
  9. Return ! CreateTemporalDate(result.[[Year]], result.[[Month]], result.[[Day]], calendarRec.[[Receiver]]).

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

The abstract operation CompareISODate takes arguments y1 (an integer), m1 (an integer), d1 (an integer), y2 (an integer), m2 (an integer), and d2 (an integer) and returns -1, 0, or 1. It performs a comparison of the two dates denoted by y1, m1, d1 and _y2, m2, d2 according to ISO 8601 calendar arithmetic. It performs the following steps when called:

  1. Assert: IsValidISODate(y2, m2, d2) is true.
  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.16 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 a throw 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. If temporalDate.[[ISOYear]] = other.[[ISOYear]], and temporalDate.[[ISOMonth]] = other.[[ISOMonth]], and temporalDate.[[ISODay]] = other.[[ISODay]], then
    1. Return ! CreateTemporalDuration(0, 0, 0, 0, 0, 0, 0, 0, 0, 0).
  7. Let calendarRec be ? CreateCalendarMethodsRecord(temporalDate.[[Calendar]], « date-add, date-until »).
  8. Perform ! CreateDataPropertyOrThrow(resolvedOptions, "largestUnit", settings.[[LargestUnit]]).
  9. Let result be ? DifferenceDate(calendarRec, temporalDate, other, resolvedOptions).
  10. Let duration be ! CreateNormalizedDurationRecord(result.[[Years]], result.[[Months]], result.[[Weeks]], result.[[Days]], ZeroTimeDuration()).
  11. If settings.[[SmallestUnit]] is "day" and settings.[[RoundingIncrement]] = 1, let roundingGranularityIsNoop be true; else let roundingGranularityIsNoop be false.
  12. If roundingGranularityIsNoop is false, then
    1. Let destEpochNs be GetUTCEpochNanoseconds(other.[[ISOYear]], other.[[ISOMonth]], other.[[ISODay]], 0, 0, 0, 0, 0, 0).
    2. Let dateTime be ISO Date-Time Record { [[Year]]: temporalDate.[[ISOYear]], [[Month]]: temporalDate.[[ISOMonth]], [[Day]]: temporalDate.[[ISODay]], [[Hour]]: 0, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0 }.
    3. Set duration to ? RoundRelativeDuration(duration, destEpochNs, dateTime, calendarRec, unset, settings.[[LargestUnit]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]]).
  13. Return ! CreateTemporalDuration(sign × duration.[[Years]], sign × duration.[[Months]], sign × duration.[[Weeks]], sign × duration.[[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 ? GetTemporalOverflowOption(options).
  3. If item is an 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 ? IsPartialTemporalObject(temporalTimeLike) is false, throw a TypeError exception.
  4. Set options to ? GetOptionsObject(options).
  5. Let overflow be ? GetTemporalOverflowOption(options).
  6. Let partialTime be ? ToTemporalTimeRecord(temporalTimeLike, partial).
  7. If partialTime.[[Hour]] is not undefined, then
    1. Let hour be partialTime.[[Hour]].
  8. Else,
    1. Let hour be temporalTime.[[ISOHour]].
  9. If partialTime.[[Minute]] is not undefined, then
    1. Let minute be partialTime.[[Minute]].
  10. Else,
    1. Let minute be temporalTime.[[ISOMinute]].
  11. If partialTime.[[Second]] is not undefined, then
    1. Let second be partialTime.[[Second]].
  12. Else,
    1. Let second be temporalTime.[[ISOSecond]].
  13. If partialTime.[[Millisecond]] is not undefined, then
    1. Let millisecond be partialTime.[[Millisecond]].
  14. Else,
    1. Let millisecond be temporalTime.[[ISOMillisecond]].
  15. If partialTime.[[Microsecond]] is not undefined, then
    1. Let microsecond be partialTime.[[Microsecond]].
  16. Else,
    1. Let microsecond be temporalTime.[[ISOMicrosecond]].
  17. If partialTime.[[Nanosecond]] is not undefined, then
    1. Let nanosecond be partialTime.[[Nanosecond]].
  18. Else,
    1. Let nanosecond be temporalTime.[[ISONanosecond]].
  19. Let result be ? RegulateTime(hour, minute, second, millisecond, microsecond, nanosecond, overflow).
  20. 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 roundTo is a 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 ? GetRoundingIncrementOption(roundTo).
  8. Let roundingMode be ? GetRoundingModeOption(roundTo, "halfExpand").
  9. Let smallestUnit be ? GetTemporalUnitValuedOption(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.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.17 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 ? GetTemporalFractionalSecondDigitsOption(options).
  6. Let roundingMode be ? GetRoundingModeOption(options, "trunc").
  7. Let smallestUnit be ? GetTemporalUnitValuedOption(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.18 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.19 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.20 Temporal.PlainTime.prototype.valueOf ( )

This method performs the following steps when called:

  1. Throw a TypeError exception.
Note

This method always throws, because in the absence of valueOf(), expressions with arithmetic operators such as plainTime1 > plainTime2 would fall back to being equivalent to plainTime1.toString() > plainTime2.toString(). Lexicographical comparison of serialized strings might not seem obviously wrong, because the result would sometimes be correct. Implementations are encouraged to phrase the error message to point users to Temporal.PlainTime.compare(), Temporal.PlainTime.prototype.equals(), and/or Temporal.PlainTime.prototype.toString().

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 Time Records

A Time Record is a Record value used to represent a valid clock time, together with a number of overflow days such as might occur in BalanceTime. For any Time Record t, IsValidTime(t.[[Hour]], t.[[Minute]], t.[[Second]], t.[[Millisecond]], t.[[Microsecond]], t.[[Nanosecond]]) must return true.

Time Records have the fields listed in Table 4.

Table 4: Time Record Fields
Field Name Value Meaning
[[Days]] an integer ≥ 0 A number of overflow days.
[[Hour]] an integer in the inclusive interval from 0 to 23 The number of the hour.
[[Minute]] an integer in the inclusive interval from 0 to 59 The number of the minute.
[[Second]] an integer in the inclusive interval from 0 to 59 The number of the second.
[[Millisecond]] an integer in the inclusive interval from 0 to 999 The number of the millisecond.
[[Microsecond]] an integer in the inclusive interval from 0 to 999 The number of the microsecond.
[[Nanosecond]] an integer in the inclusive interval from 0 to 999 The number of the nanosecond.

4.5.2 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) and returns a Normalized Time Duration Record. It returns 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 norm be NormalizeTimeDuration(hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
  8. Assert: NormalizedTimeDurationAbs(norm).[[TotalNanoseconds]] < nsPerDay.
  9. Return norm.

4.5.3 ToTemporalTime ( item [ , overflow ] )

The abstract operation ToTemporalTime takes argument item (an ECMAScript language value) and optional argument overflow ("constrain" or "reject") and returns either a normal completion containing a Temporal.PlainTime or a throw Completion. It 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. It performs the following steps when called:

  1. If overflow is not present, set overflow to "constrain".
  2. If item is an 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 timeZoneRec be ? CreateTimeZoneMethodsRecord(item.[[TimeZone]], « get-offset-nanoseconds-for »).
      3. Let plainDateTime be ? GetPlainDateTimeFor(timeZoneRec, instant, item.[[Calendar]]).
      4. 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).
  3. Else,
    1. If item is not a String, throw a TypeError exception.
    2. Let result be ? ParseTemporalTimeString(item).
    3. Assert: IsValidTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]) is true.
  4. Return ! CreateTemporalTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]]).

4.5.4 ToTemporalTimeOrMidnight ( item )

The abstract operation ToTemporalTimeOrMidnight takes argument item (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainTime or a throw completion. It returns its argument item if it is already a Temporal.PlainTime instance, converts item to a new Temporal.PlainTime instance if possible, considering undefined to be the same as midnight, and throws otherwise. It performs the following steps when called:

  1. If item is undefined, return ! CreateTemporalTime(0, 0, 0, 0, 0, 0).
  2. Return ? ToTemporalTime(item).

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

The abstract operation RegulateTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), and overflow ("constrain" or "reject") and returns either a normal completion containing a Time Record or a throw completion. It applies the correction given by overflow to the given time. If overflow is "constrain", out-of-range values are clamped. If overflow is "reject", a RangeError is thrown if any values are out of range. It performs the following steps when called:

  1. If overflow is "constrain", then
    1. Return ConstrainTime(hour, minute, second, millisecond, microsecond, nanosecond).
  2. Else,
    1. Assert: overflow is "reject".
    2. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
    3. Return Time Record { [[Days]]: 0, [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond  }.

4.5.6 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.7 BalanceTime ( hour, minute, second, millisecond, microsecond, nanosecond )

The abstract operation BalanceTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and returns a Time Record. It performs the following steps when called:

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

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

The abstract operation ConstrainTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and returns a Time Record. It clamps any out-of-range components of the given time so they are in range. It performs the following steps when called:

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

4.5.9 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 a throw 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.10 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 a throw 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 5: TemporalTimeLike Record Fields
Field Name Property Name
[[Hour]] "hour"
[[Minute]] "minute"
[[Second]] "second"
[[Millisecond]] "millisecond"
[[Microsecond]] "microsecond"
[[Nanosecond]] "nanosecond"

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

The abstract operation TemporalTimeToString takes arguments hour (an integer in the inclusive interval from 0 to 23), minute (an integer in the inclusive interval from 0 to 59), second (an integer in the inclusive interval from 0 to 59), millisecond (an integer in the inclusive interval from 0 to 999), microsecond (an integer in the inclusive interval from 0 to 999), nanosecond (an integer in the inclusive interval from 0 to 999), and precision (an integer in the inclusive interval from 0 to 9, "minute", or "auto") and returns a String. It formats the given time as an ISO 8601 string, to the precision specified by precision. It performs the following steps when called:

  1. Let subSecondNanoseconds be millisecond × 106 + microsecond × 103 + nanosecond.
  2. Return FormatTimeString(hour, minute, second, subSecondNanoseconds, precision).

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

The abstract operation CompareTemporalTime takes arguments h1 (an integer in the inclusive interval from 0 to 23), min1 (an integer in the inclusive interval from 0 to 59), s1 (an integer in the inclusive interval from 0 to 59), ms1 (an integer in the inclusive interval from 0 to 999), mus1 (an integer in the inclusive interval from 0 to 999), ns1 (an integer in the inclusive interval from 0 to 999), h2 (an integer in the inclusive interval from 0 to 23), min2 (an integer in the inclusive interval from 0 to 59), s2 (an integer in the inclusive interval from 0 to 59), ms2 (an integer in the inclusive interval from 0 to 999), mus2 (an integer in the inclusive interval from 0 to 999), and ns2 (an integer in the inclusive interval from 0 to 999) and returns -1, 0, or 1. It compares the two given times and returns -1 if the second comes earlier in the day than the first, 1 if the first comes earlier in the day than the second, and 0 if they are the same. It performs the following steps when called:

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

4.5.13 AddTime ( hour, minute, second, millisecond, microsecond, nanosecond, norm )

The abstract operation AddTime takes arguments hour (an integer in the inclusive interval from 0 to 23), minute (an integer in the inclusive interval from 0 to 59), second (an integer in the inclusive interval from 0 to 59), millisecond (an integer in the inclusive interval from 0 to 999), microsecond (an integer in the inclusive interval from 0 to 999), nanosecond (an integer in the inclusive interval from 0 to 999), and norm (a Normalized Time Duration Record) and returns a Time Record. It performs the following steps when called:

  1. Set second to second + NormalizedTimeDurationSeconds(norm).
  2. Set nanosecond to nanosecond + NormalizedTimeDurationSubseconds(norm).
  3. Return BalanceTime(hour, minute, second, millisecond, microsecond, nanosecond).

4.5.14 RoundTime ( hour, minute, second, millisecond, microsecond, nanosecond, increment, unit, roundingMode )

The abstract operation RoundTime takes arguments hour (an integer in the inclusive interval from 0 to 23), minute (an integer in the inclusive interval from 0 to 59), second (an integer in the inclusive interval from 0 to 59), millisecond (an integer in the