Stage 3 Draft / February 14, 2025

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 [ %Symbol.toStringTag% ]

The initial value of the %Symbol.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.Duration ( . . . )

See 7.

1.2.8 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 [ %Symbol.toStringTag% ]

The initial value of the %Symbol.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. Let ns be SystemUTCEpochNanoseconds().
  2. Return ! CreateTemporalInstant(ns).

2.2.3 Temporal.Now.plainDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let isoDateTime be ? SystemDateTime(temporalTimeZoneLike).
  2. Return ! CreateTemporalDateTime(isoDateTime, "iso8601").

2.2.4 Temporal.Now.zonedDateTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. If temporalTimeZoneLike is undefined, then
    1. Let timeZone be SystemTimeZoneIdentifier().
  2. Else,
    1. Let timeZone be ? ToTemporalTimeZoneIdentifier(temporalTimeZoneLike).
  3. Let ns be SystemUTCEpochNanoseconds().
  4. Return ! CreateTemporalZonedDateTime(ns, timeZone, "iso8601").

2.2.5 Temporal.Now.plainDateISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let isoDateTime be ? SystemDateTime(temporalTimeZoneLike).
  2. Return ! CreateTemporalDate(isoDateTime.[[ISODate]], "iso8601").

2.2.6 Temporal.Now.plainTimeISO ( [ temporalTimeZoneLike ] )

This function performs the following steps when called:

  1. Let isoDateTime be ? SystemDateTime(temporalTimeZoneLike).
  2. Return ! CreateTemporalTime(isoDateTime.[[Time]]).

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 SystemDateTime ( temporalTimeZoneLike )

The abstract operation SystemDateTime takes argument temporalTimeZoneLike (an ECMAScript language value) and returns either a normal completion containing an ISO Date-Time Record 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 ? ToTemporalTimeZoneIdentifier(temporalTimeZoneLike).
  3. Let epochNs be SystemUTCEpochNanoseconds().
  4. Return GetISODateTimeFor(timeZone, epochNs).

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 [ , calendar ] )

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. If calendar is undefined, set calendar to "iso8601".
  6. If calendar is not a String, throw a TypeError exception.
  7. Set calendar to ? CanonicalizeCalendar(calendar).
  8. If IsValidISODate(y, m, d) is false, throw a RangeError exception.
  9. Let isoDate be CreateISODateRecord(y, m, d).
  10. Return ? CreateTemporalDate(isoDate, 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. 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.[[ISODate]], two.[[ISODate]])).

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[ %Symbol.toStringTag% ]

The initial value of the %Symbol.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 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. Return CalendarISOToDate(plainDate.[[Calendar]], plainDate.[[ISODate]]).[[Era]].

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 result be CalendarISOToDate(plainDate.[[Calendar]], plainDate.[[ISODate]]).[[EraYear]].
  4. If result is undefined, return undefined.
  5. 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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[Year]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[Month]]).

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. Return CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[MonthCode]].

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[Day]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[DayOfWeek]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[DayOfYear]]).

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 result be CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[WeekOfYear]].[[Week]].
  4. If result is undefined, return undefined.
  5. 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 result be CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[WeekOfYear]].[[Year]].
  4. If result is undefined, return undefined.
  5. 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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[DaysInWeek]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[DaysInMonth]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[DaysInYear]]).

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. Return 𝔽(CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[MonthsInYear]]).

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. Return CalendarISOToDate(temporalDate.[[Calendar]], temporalDate.[[ISODate]]).[[InLeapYear]].

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 calendar be temporalDate.[[Calendar]].
  4. Let fields be ISODateToFields(calendar, temporalDate.[[ISODate]], date).
  5. Let isoDate be ? CalendarYearMonthFromFields(calendar, fields, constrain).
  6. Return ! CreateTemporalYearMonth(isoDate, calendar).
  7. NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[Day]] field of the [[ISODate]] internal slot 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 calendar be temporalDate.[[Calendar]].
  4. Let fields be ISODateToFields(calendar, temporalDate.[[ISODate]], date).
  5. Let isoDate be ? CalendarMonthDayFromFields(calendar, fields, constrain).
  6. Return ! CreateTemporalMonthDay(isoDate, calendar).
  7. NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[Year]] field of the [[ISODate]] internal slot set correctly.

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. Return ? AddDurationToDate(add, temporalDate, temporalDurationLike, 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. Return ? AddDurationToDate(subtract, temporalDate, temporalDurationLike, 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 ? IsPartialTemporalObject(temporalDateLike) is false, throw a TypeError exception.
  4. Let calendar be temporalDate.[[Calendar]].
  5. Let fields be ISODateToFields(calendar, temporalDate.[[ISODate]], date).
  6. Let partialDate be ? PrepareCalendarFields(calendar, temporalDateLike, « year, month, month-code, day », « », partial).
  7. Set fields to CalendarMergeFields(calendar, fields, partialDate).
  8. Let resolvedOptions be ? GetOptionsObject(options).
  9. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
  10. Let isoDate be ? CalendarDateFromFields(calendar, fields, overflow).
  11. Return ! CreateTemporalDate(isoDate, calendar).

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 ? ToTemporalCalendarIdentifier(calendarLike).
  4. Return ! CreateTemporalDate(temporalDate.[[ISODate]], 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 CompareISODate(temporalDate.[[ISODate]], other.[[ISODate]]) ≠ 0, return false.
  5. 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. Let time be ? ToTimeRecordOrMidnight(temporalTime).
  4. Let isoDateTime be CombineISODateAndTimeRecord(temporalDate.[[ISODate]], time).
  5. Return ? CreateTemporalDateTime(isoDateTime, 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 item is an Object, then
    1. Let timeZoneLike be ? Get(item, "timeZone").
    2. If timeZoneLike is undefined, then
      1. Let timeZone be ? ToTemporalTimeZoneIdentifier(item).
      2. Let temporalTime be undefined.
    3. Else,
      1. Let timeZone be ? ToTemporalTimeZoneIdentifier(timeZoneLike).
      2. Let temporalTime be ? Get(item, "plainTime").
  4. Else,
    1. Let timeZone be ? ToTemporalTimeZoneIdentifier(item).
    2. Let temporalTime be undefined.
  5. If temporalTime is undefined, then
    1. Let epochNs be ? GetStartOfDay(timeZone, temporalDate.[[ISODate]]).
  6. Else,
    1. Set temporalTime to ? ToTemporalTime(temporalTime).
    2. Let isoDateTime be CombineISODateAndTimeRecord(temporalDate.[[ISODate]], temporalTime.[[Time]]).
    3. If ISODateTimeWithinLimits(isoDateTime) is false, throw a RangeError exception.
    4. Let epochNs be ? GetEpochNanosecondsFor(timeZone, isoDateTime, compatible).
  7. Return ! CreateTemporalZonedDateTime(epochNs, 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. Let resolvedOptions be ? GetOptionsObject(options).
  4. Let showCalendar be ? GetTemporalShowCalendarNameOption(resolvedOptions).
  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.
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.
[[ISODate]] An ISO Date Record.
[[Calendar]] A calendar type.

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 ( isoDate, calendar [ , newTarget ] )

The abstract operation CreateTemporalDate takes arguments isoDate (an ISO Date Record) and calendar (a calendar type) 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 ISODateWithinLimits(isoDate) is false, throw a RangeError exception.
  2. If newTarget is not present, set newTarget to %Temporal.PlainDate%.
  3. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDate.prototype%", « [[InitializedTemporalDate]], [[ISODate]], [[Calendar]] »).
  4. Set object.[[ISODate]] to isoDate.
  5. Set object.[[Calendar]] to calendar.
  6. Return object.

3.5.4 ToTemporalDate ( item [ , options ] )

The abstract operation ToTemporalDate takes argument item (an ECMAScript language value) and optional argument options (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainDate or a throw completion. 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 item is an Object, then
    1. If item has an [[InitializedTemporalDate]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Return ! CreateTemporalDate(item.[[ISODate]], item.[[Calendar]]).
    2. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Let isoDateTime be GetISODateTimeFor(item.[[TimeZone]], item.[[EpochNanoseconds]]).
      2. Let resolvedOptions be ? GetOptionsObject(options).
      3. Perform ? GetTemporalOverflowOption(resolvedOptions).
      4. Return ! CreateTemporalDate(isoDateTime.[[ISODate]], item.[[Calendar]]).
    3. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Return ! CreateTemporalDate(item.[[ISODateTime]].[[ISODate]], item.[[Calendar]]).
    4. Let calendar be ? GetTemporalCalendarIdentifierWithISODefault(item).
    5. Let fields be ? PrepareCalendarFields(calendar, item, « year, month, month-code, day », «», «»).
    6. Let resolvedOptions be ? GetOptionsObject(options).
    7. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
    8. Let isoDate be ? CalendarDateFromFields(calendar, fields, overflow).
    9. Return ! CreateTemporalDate(isoDate, calendar).
  3. If item is not a String, throw a TypeError exception.
  4. Let result be ? ParseISODateTime(item, « TemporalDateTimeString[~Zoned] »).
  5. Let calendar be result.[[Calendar]].
  6. If calendar is empty, set calendar to "iso8601".
  7. Set calendar to ? CanonicalizeCalendar(calendar).
  8. Let resolvedOptions be ? GetOptionsObject(options).
  9. Perform ? GetTemporalOverflowOption(resolvedOptions).
  10. Let isoDate be CreateISODateRecord(result.[[Year]], result.[[Month]], result.[[Day]]).
  11. Return ? CreateTemporalDate(isoDate, calendar).

3.5.5 ISODateSurpasses ( sign, y1, m1, d1, isoDate2 )

The abstract operation ISODateSurpasses takes arguments sign (-1 or 1), y1 (an integer), m1 (an integer), d1 (an integer), and isoDate2 (an ISO Date Record) and returns a Boolean. The return value indicates whether the date denoted by y1, m1, d1 surpasses that denoted by isoDate2 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. If y1isoDate2.[[Year]], then
    1. If sign × (y1 - isoDate2.[[Year]]) > 0, return true.
  2. Else if m1isoDate2.[[Month]], then
    1. If sign × (m1 - isoDate2.[[Month]]) > 0, return true.
  3. Else if d1isoDate2.[[Day]], then
    1. If sign × (d1 - isoDate2.[[Day]]) > 0, return true.
  4. Return false.

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 a throw completion. It performs the overflow correction specified 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 independently clamped to their respective valid range in order of descending unit magnitude. 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.
  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 )

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.10 TemporalDateToString ( temporalDate, showCalendar )

The abstract operation TemporalDateToString takes arguments temporalDate (a Temporal.PlainDate) and showCalendar (auto, always, never, or critical) and returns a String. It formats temporalDate to an RFC 9557 string. It performs the following steps when called:

  1. Let year be PadISOYear(temporalDate.[[ISODate]].[[Year]]).
  2. Let month be ToZeroPaddedDecimalString(temporalDate.[[ISODate]].[[Month]], 2).
  3. Let day be ToZeroPaddedDecimalString(temporalDate.[[ISODate]].[[Day]], 2).
  4. Let calendar be FormatCalendarAnnotation(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.11 ISODateWithinLimits ( isoDate )

The abstract operation ISODateWithinLimits takes argument isoDate (an ISO Date Record) and returns a Boolean. The return value is true if the date in the ISO 8601 calendar given by the argument is within the representable range of Temporal.PlainDate, and false otherwise.

Note

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

It performs the following steps when called:

  1. Let isoDateTime be CombineISODateAndTimeRecord(isoDate, NoonTimeRecord()).
  2. Return ISODateTimeWithinLimits(isoDateTime).

3.5.12 CompareISODate ( isoDate1, isoDate2 )

The abstract operation CompareISODate takes arguments isoDate1 (an ISO Date Record) and isoDate2 (an ISO Date Record) and returns -1, 0, or 1. It performs a comparison of the two dates denoted by isoDate1 and isoDate2 according to ISO 8601 calendar arithmetic. It performs the following steps when called:

  1. If isoDate1.[[Year]] > isoDate2.[[Year]], return 1.
  2. If isoDate1.[[Year]] < isoDate2.[[Year]], return -1.
  3. If isoDate1.[[Month]] > isoDate2.[[Month]], return 1.
  4. If isoDate1.[[Month]] < isoDate2.[[Month]], return -1.
  5. If isoDate1.[[Day]] > isoDate2.[[Day]], return 1.
  6. If isoDate1.[[Day]] < isoDate2.[[Day]], return -1.
  7. 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 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. Set other to ? ToTemporalDate(other).
  2. If CalendarEquals(temporalDate.[[Calendar]], other.[[Calendar]]) is false, throw a RangeError exception.
  3. Let resolvedOptions be ? GetOptionsObject(options).
  4. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, date, « », day, day).
  5. If CompareISODate(temporalDate.[[ISODate]], other.[[ISODate]]) = 0, then
    1. Return ! CreateTemporalDuration(0, 0, 0, 0, 0, 0, 0, 0, 0, 0).
  6. Let dateDifference be CalendarDateUntil(temporalDate.[[Calendar]], temporalDate.[[ISODate]], other.[[ISODate]], settings.[[LargestUnit]]).
  7. Let duration be CombineDateAndTimeDuration(dateDifference, 0).
  8. If settings.[[SmallestUnit]] is not day or settings.[[RoundingIncrement]] ≠ 1, then
    1. Let isoDateTime be CombineISODateAndTimeRecord(temporalDate.[[ISODate]], MidnightTimeRecord()).
    2. Let isoDateTimeOther be CombineISODateAndTimeRecord(other.[[ISODate]], MidnightTimeRecord()).
    3. Let destEpochNs be GetUTCEpochNanoseconds(isoDateTimeOther).
    4. Set duration to ? RoundRelativeDuration(duration, destEpochNs, isoDateTime, unset, temporalDate.[[Calendar]], settings.[[LargestUnit]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]]).
  9. Let result be ! TemporalDurationFromInternal(duration, day).
  10. If operation is since, set result to CreateNegatedTemporalDuration(result).
  11. Return result.

3.5.14 AddDurationToDate ( operation, temporalDate, temporalDurationLike, options )

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

  1. Let calendar be temporalDate.[[Calendar]].
  2. Let duration be ? ToTemporalDuration(temporalDurationLike).
  3. If operation is subtract, set duration to CreateNegatedTemporalDuration(duration).
  4. Let dateDuration be ToDateDurationRecordWithoutTime(duration).
  5. Let resolvedOptions be ? GetOptionsObject(options).
  6. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
  7. Let result be ? CalendarDateAdd(calendar, temporalDate.[[ISODate]], dateDuration, overflow).
  8. Return ! CreateTemporalDate(result, calendar).

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. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
  9. Let time be CreateTimeRecord(hour, minute, second, millisecond, microsecond, nanosecond).
  10. Return ? CreateTemporalTime(time, 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. Return ? ToTemporalTime(item, options).

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 𝔽(CompareTimeRecord(one.[[Time]], two.[[Time]])).

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[ %Symbol.toStringTag% ]

The initial value of the %Symbol.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.[[Time]].[[Hour]]).

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.[[Time]].[[Minute]]).

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.[[Time]].[[Second]]).

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.[[Time]].[[Millisecond]]).

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.[[Time]].[[Microsecond]]).

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.[[Time]].[[Nanosecond]]).

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 ? AddDurationToTime(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 ? AddDurationToTime(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. Let partialTime be ? ToTemporalTimeRecord(temporalTimeLike, partial).
  5. If partialTime.[[Hour]] is not undefined, then
    1. Let hour be partialTime.[[Hour]].
  6. Else,
    1. Let hour be temporalTime.[[Time]].[[Hour]].
  7. If partialTime.[[Minute]] is not undefined, then
    1. Let minute be partialTime.[[Minute]].
  8. Else,
    1. Let minute be temporalTime.[[Time]].[[Minute]].
  9. If partialTime.[[Second]] is not undefined, then
    1. Let second be partialTime.[[Second]].
  10. Else,
    1. Let second be temporalTime.[[Time]].[[Second]].
  11. If partialTime.[[Millisecond]] is not undefined, then
    1. Let millisecond be partialTime.[[Millisecond]].
  12. Else,
    1. Let millisecond be temporalTime.[[Time]].[[Millisecond]].
  13. If partialTime.[[Microsecond]] is not undefined, then
    1. Let microsecond be partialTime.[[Microsecond]].
  14. Else,
    1. Let microsecond be temporalTime.[[Time]].[[Microsecond]].
  15. If partialTime.[[Nanosecond]] is not undefined, then
    1. Let nanosecond be partialTime.[[Nanosecond]].
  16. Else,
    1. Let nanosecond be temporalTime.[[Time]].[[Nanosecond]].
  17. Let resolvedOptions be ? GetOptionsObject(options).
  18. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
  19. Let result be ? RegulateTime(hour, minute, second, millisecond, microsecond, nanosecond, overflow).
  20. Return ! CreateTemporalTime(result).

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 (GetRoundingIncrementOption reads "roundingIncrement" and GetRoundingModeOption reads "roundingMode").
  7. Let roundingIncrement be ? GetRoundingIncrementOption(roundTo).
  8. Let roundingMode be ? GetRoundingModeOption(roundTo, half-expand).
  9. Let smallestUnit be ? GetTemporalUnitValuedOption(roundTo, "smallestUnit", time, required).
  10. Let maximum be MaximumTemporalDurationRoundingIncrement(smallestUnit).
  11. Assert: maximum is not unset.
  12. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, false).
  13. Let result be RoundTime(temporalTime.[[Time]], roundingIncrement, smallestUnit, roundingMode).
  14. Return ! CreateTemporalTime(result).

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 CompareTimeRecord(temporalTime.[[Time]], other.[[Time]]) = 0, return true.
  5. Return false.

4.3.16 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. Let resolvedOptions be ? GetOptionsObject(options).
  4. NOTE: The following steps read options and perform independent validation in alphabetical order (GetTemporalFractionalSecondDigitsOption reads "fractionalSecondDigits" and GetRoundingModeOption reads "roundingMode").
  5. Let digits be ? GetTemporalFractionalSecondDigitsOption(resolvedOptions).
  6. Let roundingMode be ? GetRoundingModeOption(resolvedOptions, trunc).
  7. Let smallestUnit be ? GetTemporalUnitValuedOption(resolvedOptions, "smallestUnit", time, unset).
  8. If smallestUnit is hour, throw a RangeError exception.
  9. Let precision be ToSecondsStringPrecisionRecord(smallestUnit, digits).
  10. Let roundResult be RoundTime(temporalTime.[[Time]], precision.[[Increment]], precision.[[Unit]], roundingMode).
  11. Return TimeRecordToString(roundResult, precision.[[Precision]]).

4.3.17 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 TimeRecordToString(temporalTime.[[Time]], auto).

4.3.18 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 TimeRecordToString(temporalTime.[[Time]], auto).

4.3.19 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.
[[Time]] A Time Record.

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 CreateTimeRecord ( hour, minute, second, millisecond, microsecond, nanosecond [ , deltaDays ] )

The abstract operation CreateTimeRecord 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), and nanosecond (an integer in the inclusive interval from 0 to 999) and optional argument deltaDays (a non-negative integer) and returns a Time Record. Most uses of Time Records do not require the deltaDays parameter. It performs the following steps when called:

  1. If deltaDays is not present, set deltaDays to 0.
  2. Assert: IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond).
  3. Return Time Record { [[Days]]: deltaDays, [[Hour]]: hour, [[Minute]]: minute, [[Second]]: second, [[Millisecond]]: millisecond, [[Microsecond]]: microsecond, [[Nanosecond]]: nanosecond  }.

4.5.3 MidnightTimeRecord ( )

The abstract operation MidnightTimeRecord takes no arguments and returns a Time Record. The returned Record denotes the wall-clock time of midnight. It performs the following steps when called:

  1. Return Time Record { [[Days]]: 0, [[Hour]]: 0, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0  }.

4.5.4 NoonTimeRecord ( )

The abstract operation NoonTimeRecord takes no arguments and returns a Time Record. The returned Record denotes the wall-clock time of noon. It performs the following steps when called:

  1. Return Time Record { [[Days]]: 0, [[Hour]]: 12, [[Minute]]: 0, [[Second]]: 0, [[Millisecond]]: 0, [[Microsecond]]: 0, [[Nanosecond]]: 0  }.

4.5.5 DifferenceTime ( time1, time2 )

The abstract operation DifferenceTime takes arguments time1 (a Time Record) and time2 (a Time Record) and returns a time duration. 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 time2.[[Hour]] - time1.[[Hour]].
  2. Let minutes be time2.[[Minute]] - time1.[[Minute]].
  3. Let seconds be time2.[[Second]] - time1.[[Second]].
  4. Let milliseconds be time2.[[Millisecond]] - time1.[[Millisecond]].
  5. Let microseconds be time2.[[Microsecond]] - time1.[[Microsecond]].
  6. Let nanoseconds be time2.[[Nanosecond]] - time1.[[Nanosecond]].
  7. Let timeDuration be TimeDurationFromComponents(hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
  8. Assert: abs(timeDuration) < nsPerDay.
  9. Return timeDuration.

4.5.6 ToTemporalTime ( item [ , options ] )

The abstract operation ToTemporalTime takes argument item (an ECMAScript language value) and optional argument options (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainTime or a throw Completion. Converts item to a new Temporal.PlainTime 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 item is an Object, then
    1. If item has an [[InitializedTemporalTime]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Return ! CreateTemporalTime(item.[[Time]]).
    2. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Return ! CreateTemporalTime(item.[[ISODateTime]].[[Time]]).
    3. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Let isoDateTime be GetISODateTimeFor(item.[[TimeZone]], item.[[EpochNanoseconds]]).
      2. Let resolvedOptions be ? GetOptionsObject(options).
      3. Perform ? GetTemporalOverflowOption(resolvedOptions).
      4. Return ! CreateTemporalTime(isoDateTime.[[Time]]).
    4. Let result be ? ToTemporalTimeRecord(item).
    5. Let resolvedOptions be ? GetOptionsObject(options).
    6. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
    7. 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 parseResult be ? ParseISODateTime(item, « TemporalTimeString »).
    3. Assert: parseResult.[[Time]] is not start-of-day.
    4. Set result to parseResult.[[Time]].
    5. NOTE: A successful parse using TemporalTimeString guarantees absence of ambiguity with respect to any ISO 8601 date-only, year-month, or month-day representation.
    6. Let resolvedOptions be ? GetOptionsObject(options).
    7. Perform ? GetTemporalOverflowOption(resolvedOptions).
  4. Return ! CreateTemporalTime(result).

4.5.7 ToTimeRecordOrMidnight ( item )

The abstract operation ToTimeRecordOrMidnight takes argument item (an ECMAScript language value) and returns either a normal completion containing a Time Record or a throw completion. Converts item to a Time Record 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 MidnightTimeRecord().
  2. Let plainTime be ? ToTemporalTime(item).
  3. Return plainTime.[[Time]].

4.5.8 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. 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.
  2. Else,
    1. Assert: overflow is reject.
    2. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
  3. Return CreateTimeRecord(hour, minute, second, millisecond, microsecond,nanosecond).

4.5.9 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.10 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 deltaDays be floor(hour / 24).
  12. Set hour to hour modulo 24.
  13. Return CreateTimeRecord(hour, minute, second, millisecond, microsecond, nanosecond, deltaDays).

4.5.11 CreateTemporalTime ( time [ , newTarget ] )

The abstract operation CreateTemporalTime takes argument time (a Time Record) 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 newTarget is not present, set newTarget to %Temporal.PlainTime%.
  2. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainTime.prototype%", « [[InitializedTemporalTime]], [[Time]] »).
  3. Set object.[[Time]] to time.
  4. Return object.

4.5.12 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. If completeness is complete, then
    1. Let result be a new TemporalTimeLike Record with each field set to 0.
  3. Else,
    1. Let result be a new TemporalTimeLike Record with each field set to unset.
  4. Let any be false.
  5. Let hour be ? Get(temporalTimeLike, "hour").
  6. If hour is not undefined, then
    1. Set result.[[Hour]] to ? ToIntegerWithTruncation(hour).
    2. Set any to true.
  7. Let microsecond be ? Get(temporalTimeLike, "microsecond").
  8. If microsecond is not undefined, then
    1. Set result.[[Microsecond]] to ? ToIntegerWithTruncation(microsecond).
    2. Set any to true.
  9. Let millisecond be ? Get(temporalTimeLike, "millisecond").
  10. If millisecond is not undefined, then
    1. Set result.[[Millisecond]] to ? ToIntegerWithTruncation(millisecond).
    2. Set any to true.
  11. Let minute be ? Get(temporalTimeLike, "minute").
  12. If minute is not undefined, then
    1. Set result.[[Minute]] to ? ToIntegerWithTruncation(minute).
    2. Set any to true.
  13. Let nanosecond be ? Get(temporalTimeLike, "nanosecond").
  14. If nanosecond is not undefined, then
    1. Set result.[[Nanosecond]] to ? ToIntegerWithTruncation(nanosecond).
    2. Set any to true.
  15. Let second be ? Get(temporalTimeLike, "second").
  16. If second is not undefined, then
    1. Set result.[[Second]] to ? ToIntegerWithTruncation(second).
    2. Set any to true.
  17. If any is false, throw a TypeError exception.
  18. 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.13 TimeRecordToString ( time, precision )

The abstract operation TimeRecordToString takes arguments time (a Time Record) 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 time.[[Millisecond]] × 106 + time.[[Microsecond]] × 103 + time.[[Nanosecond]].
  2. Return FormatTimeString(time.[[Hour]], time.[[Minute]], time.[[Second]], subSecondNanoseconds, precision).

4.5.14 CompareTimeRecord ( time1, time2 )

The abstract operation CompareTimeRecord takes arguments time1 (a Time Record) and time2 (a Time Record) 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 time1.[[Hour]] > time2.[[Hour]], return 1.
  2. If time1.[[Hour]] < time2.[[Hour]], return -1.
  3. If time1.[[Minute]] > time2.[[Minute]], return 1.
  4. If time1.[[Minute]] < time2.[[Minute]], return -1.
  5. If time1.[[Second]] > time2.[[Second]], return 1.
  6. If time1.[[Second]] < time2.[[Second]], return -1.
  7. If time1.[[Millisecond]] > time2.[[Millisecond]], return 1.
  8. If time1.[[Millisecond]] < time2.[[Millisecond]], return -1.
  9. If time1.[[Microsecond]] > time2.[[Microsecond]], return 1.
  10. If time1.[[Microsecond]] < time2.[[Microsecond]], return -1.
  11. If time1.[[Nanosecond]] > time2.[[Nanosecond]], return 1.
  12. If time1.[[Nanosecond]] < time2.[[Nanosecond]], return -1.
  13. Return 0.

4.5.15 AddTime ( time, timeDuration )

The abstract operation AddTime takes arguments time (a Time Record) and timeDuration (a time duration) and returns a Time Record. It performs the following steps when called:

  1. Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], time.[[Microsecond]], time.[[Nanosecond]] + timeDuration).
  2. NOTE: If using floating points to implement this operation, add the time components separately before balancing to avoid errors with unsafe integers.

4.5.16 RoundTime ( time, increment, unit, roundingMode )

The abstract operation RoundTime takes arguments time (a Time Record), increment (a positive integer), unit (a time unit or day), and roundingMode (a rounding mode) and returns a Time Record. It rounds a time to the given increment. It performs the following steps when called:

  1. If unit is day or hour, then
    1. Let quantity be ((((time.[[Hour]] × 60 + time.[[Minute]]) × 60 + time.[[Second]]) × 1000 + time.[[Millisecond]]) × 1000 + time.[[Microsecond]]) × 1000 + time.[[Nanosecond]].
  2. Else if unit is minute, then
    1. Let quantity be (((time.[[Minute]] × 60 + time.[[Second]]) × 1000 + time.[[Millisecond]]) × 1000 + time.[[Microsecond]]) × 1000 + time.[[Nanosecond]].
  3. Else if unit is second, then
    1. Let quantity be ((time.[[Second]] × 1000 + time.[[Millisecond]]) × 1000 + time.[[Microsecond]]) × 1000 + time.[[Nanosecond]].
  4. Else if unit is millisecond, then
    1. Let quantity be (time.[[Millisecond]] × 1000 + time.[[Microsecond]]) × 1000 + time.[[Nanosecond]].
  5. Else if unit is microsecond, then
    1. Let quantity be time.[[Microsecond]] × 1000 + time.[[Nanosecond]].
  6. Else,
    1. Assert: unit is nanosecond.
    2. Let quantity be time.[[Nanosecond]].
  7. Let unitLength be the value in the "Length in Nanoseconds" column of the row of Table 21 whose "Value" column contains unit.
  8. Let result be RoundNumberToIncrement(quantity, increment × unitLength, roundingMode) / unitLength.
  9. If unit is day, then
    1. Return CreateTimeRecord(0, 0, 0, 0, 0, 0, result).
  10. If unit is hour, then
    1. Return BalanceTime(result, 0, 0, 0, 0, 0).
  11. If unit is minute, then
    1. Return BalanceTime(time.[[Hour]], result, 0, 0, 0, 0).
  12. If unit is second, then
    1. Return BalanceTime(time.[[Hour]], time.[[Minute]], result, 0, 0, 0).
  13. If unit is millisecond, then
    1. Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], result, 0, 0).
  14. If unit is microsecond, then
    1. Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], result, 0).
  15. Assert: unit is nanosecond.
  16. Return BalanceTime(time.[[Hour]], time.[[Minute]], time.[[Second]], time.[[Millisecond]], time.[[Microsecond]], result).

4.5.17 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 a throw 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. Set other to ? ToTemporalTime(other).
  2. Let resolvedOptions be ? GetOptionsObject(options).
  3. Let settings be ? GetDifferenceSettings(operation, resolvedOptions, time, « », nanosecond, hour).
  4. Let timeDuration be DifferenceTime(temporalTime.[[Time]], other.[[Time]]).
  5. Set timeDuration to ! RoundTimeDuration(timeDuration, settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]]).
  6. Let duration be CombineDateAndTimeDuration(ZeroDateDuration(), timeDuration).
  7. Let result be ! TemporalDurationFromInternal(duration, settings.[[LargestUnit]]).
  8. If operation is since, set result to CreateNegatedTemporalDuration(result).
  9. Return result.

4.5.18 AddDurationToTime ( operation, temporalTime, temporalDurationLike )

The abstract operation AddDurationToTime 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 a throw 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. Let duration be ? ToTemporalDuration(temporalDurationLike).
  2. If operation is subtract, set duration to CreateNegatedTemporalDuration(duration).
  3. Let internalDuration be ToInternalDurationRecord(duration).
  4. Let result be AddTime(temporalTime.[[Time]], internalDuration.[[Time]]).
  5. Return ! CreateTemporalTime(result).

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 [ , calendar ] ] ] ] ] ] ] )

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. If calendar is undefined, set calendar to "iso8601".
  12. If calendar is not a String, throw a TypeError exception.
  13. Set calendar to ? CanonicalizeCalendar(calendar).
  14. If IsValidISODate(isoYear, isoMonth, isoDay) is false, throw a RangeError exception.
  15. Let isoDate be CreateISODateRecord(isoYear, isoMonth, isoDay).
  16. If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
  17. Let time be CreateTimeRecord(hour, minute, second, millisecond, microsecond, nanosecond).
  18. Let isoDateTime be CombineISODateAndTimeRecord(isoDate, time).
  19. Return ? CreateTemporalDateTime(isoDateTime, 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. 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.[[ISODateTime]], two.[[ISODateTime]])).

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[ %Symbol.toStringTag% ]

The initial value of the %Symbol.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 dateTime.[[Calendar]].

5.3.4 get Temporal.PlainDateTime.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 plainDateTime be the this value.
  2. Perform ? RequireInternalSlot(plainDateTime, [[InitializedTemporalDateTime]]).
  3. Return CalendarISOToDate(plainDateTime.[[Calendar]], plainDateTime.[[ISODateTime]].[[ISODate]]).[[Era]].

5.3.5 get Temporal.PlainDateTime.prototype.eraYear

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

  1. Let plainDateTime be the this value.
  2. Perform ? RequireInternalSlot(plainDateTime, [[InitializedTemporalDateTime]]).
  3. Let result be CalendarISOToDate(plainDateTime.[[Calendar]], plainDateTime.[[ISODateTime]].[[ISODate]]).[[EraYear]].
  4. If result is undefined, return undefined.
  5. Return 𝔽(result).

5.3.6 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[Year]]).

5.3.7 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[Month]]).

5.3.8 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. Return CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[MonthCode]].

5.3.9 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[Day]]).

5.3.10 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.[[ISODateTime]].[[Time]].[[Hour]]).

5.3.11 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.[[ISODateTime]].[[Time]].[[Minute]]).

5.3.12 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.[[ISODateTime]].[[Time]].[[Second]]).

5.3.13 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.[[ISODateTime]].[[Time]].[[Millisecond]]).

5.3.14 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.[[ISODateTime]].[[Time]].[[Microsecond]]).

5.3.15 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.[[ISODateTime]].[[Time]].[[Nanosecond]]).

5.3.16 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[DayOfWeek]]).

5.3.17 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[DayOfYear]]).

5.3.18 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 result be CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[WeekOfYear]].[[Week]].
  4. If result is undefined, return undefined.
  5. Return 𝔽(result).

5.3.19 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 result be CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[WeekOfYear]].[[Year]].
  4. If result is undefined, return undefined.
  5. Return 𝔽(result).

5.3.20 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[DaysInWeek]]).

5.3.21 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[DaysInMonth]]).

5.3.22 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[DaysInYear]]).

5.3.23 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. Return 𝔽(CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[MonthsInYear]]).

5.3.24 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. Return CalendarISOToDate(dateTime.[[Calendar]], dateTime.[[ISODateTime]].[[ISODate]]).[[InLeapYear]].

5.3.25 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 ? IsPartialTemporalObject(temporalDateTimeLike) is false, throw a TypeError exception.
  4. Let calendar be dateTime.[[Calendar]].
  5. Let fields be ISODateToFields(calendar, dateTime.[[ISODateTime]].[[ISODate]], date).
  6. Set fields.[[Hour]] to dateTime.[[ISODateTime]].[[Time]].[[Hour]].
  7. Set fields.[[Minute]] to dateTime.[[ISODateTime]].[[Time]].[[Minute]].
  8. Set fields.[[Second]] to dateTime.[[ISODateTime]].[[Time]].[[Second]].
  9. Set fields.[[Millisecond]] to dateTime.[[ISODateTime]].[[Time]].[[Millisecond]].
  10. Set fields.[[Microsecond]] to dateTime.[[ISODateTime]].[[Time]].[[Microsecond]].
  11. Set fields.[[Nanosecond]] to dateTime.[[ISODateTime]].[[Time]].[[Nanosecond]].
  12. Let partialDateTime be ? PrepareCalendarFields(calendar, temporalDateTimeLike, « year, month, month-code, day », « hour, minute, second, millisecond, microsecond, nanosecond », partial).
  13. Set fields to CalendarMergeFields(calendar, fields, partialDateTime).
  14. Let resolvedOptions be ? GetOptionsObject(options).
  15. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
  16. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, overflow).
  17. Return ? CreateTemporalDateTime(result, calendar).

5.3.26 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. Let time be ? ToTimeRecordOrMidnight(plainTimeLike).
  4. Let isoDateTime be CombineISODateAndTimeRecord(dateTime.[[ISODateTime]].[[ISODate]], time).
  5. Return ? CreateTemporalDateTime(isoDateTime, dateTime.[[Calendar]]).

5.3.27 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 ? ToTemporalCalendarIdentifier(calendarLike).
  4. Return ! CreateTemporalDateTime(dateTime.[[ISODateTime]], calendar).

5.3.28 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 ? AddDurationToDateTime(add, dateTime, temporalDurationLike, options).

5.3.29 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 ? AddDurationToDateTime(subtract, dateTime, temporalDurationLike, options).

5.3.30 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.31 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.32 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 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 (GetRoundingIncrementOption reads "roundingIncrement" and GetRoundingModeOption reads "roundingMode").
  7. Let roundingIncrement be ? GetRoundingIncrementOption(roundTo).
  8. Let roundingMode be ? GetRoundingModeOption(roundTo, half-expand).
  9. Let smallestUnit be ? GetTemporalUnitValuedOption(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 unset.
    3. Let inclusive be false.
  12. Perform ? ValidateTemporalRoundingIncrement(roundingIncrement, maximum, inclusive).
  13. If smallestUnit is nanosecond and roundingIncrement = 1, then
    1. Return ! CreateTemporalDateTime(dateTime.[[ISODateTime]], dateTime.[[Calendar]]).
  14. Let result be RoundISODateTime(dateTime.[[ISODateTime]], roundingIncrement, smallestUnit, roundingMode).
  15. Return ? CreateTemporalDateTime(result, dateTime.[[Calendar]]).

5.3.33 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. If CompareISODateTime(dateTime.[[ISODateTime]], other.[[ISODateTime]]) ≠ 0, return false.
  5. Return CalendarEquals(dateTime.[[Calendar]], other.[[Calendar]]).

5.3.34 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. Let resolvedOptions be ? GetOptionsObject(options).
  4. NOTE: The following steps read options and perform independent validation in alphabetical order (GetTemporalShowCalendarNameOption reads "calendarName", GetTemporalFractionalSecondDigitsOption reads "fractionalSecondDigits", and GetRoundingModeOption reads "roundingMode").
  5. Let showCalendar be ? GetTemporalShowCalendarNameOption(resolvedOptions).
  6. Let digits be ? GetTemporalFractionalSecondDigitsOption(resolvedOptions).
  7. Let roundingMode be ? GetRoundingModeOption(resolvedOptions, trunc).
  8. Let smallestUnit be ? GetTemporalUnitValuedOption(resolvedOptions, "smallestUnit", time, unset).
  9. If smallestUnit is hour, throw a RangeError exception.
  10. Let precision be ToSecondsStringPrecisionRecord(smallestUnit, digits).
  11. Let result be RoundISODateTime(dateTime.[[ISODateTime]], precision.[[Increment]], precision.[[Unit]], roundingMode).
  12. If ISODateTimeWithinLimits(result) is false, throw a RangeError exception.
  13. Return ISODateTimeToString(result, dateTime.[[Calendar]], precision.[[Precision]], showCalendar).

5.3.35 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 ISODateTimeToString(dateTime.[[ISODateTime]], dateTime.[[Calendar]], auto, auto).

5.3.36 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 ISODateTimeToString(dateTime.[[ISODateTime]], dateTime.[[Calendar]], auto, auto).

5.3.37 Temporal.PlainDateTime.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 plainDateTime1 > plainDateTime2 would fall back to being equivalent to plainDateTime1.toString() > plainDateTime2.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.PlainDateTime.compare(), Temporal.PlainDateTime.prototype.equals(), and/or Temporal.PlainDateTime.prototype.toString().

5.3.38 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 ? ToTemporalTimeZoneIdentifier(temporalTimeZoneLike).
  4. Let resolvedOptions be ? GetOptionsObject(options).
  5. Let disambiguation be ? GetTemporalDisambiguationOption(resolvedOptions).
  6. Let epochNs be ? GetEpochNanosecondsFor(timeZone, dateTime.[[ISODateTime]], disambiguation).
  7. Return ! CreateTemporalZonedDateTime(epochNs, timeZone, dateTime.[[Calendar]]).

5.3.39 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.[[ISODateTime]].[[ISODate]], dateTime.[[Calendar]]).

5.3.40 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.[[ISODateTime]].[[Time]]).

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 6.

Table 6: 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.
[[ISODateTime]] An ISO Date-Time Record.
[[Calendar]] A calendar type.

5.5 Abstract Operations

5.5.1 ISO Date-Time Records

An ISO Date-Time Record is a Record value used to represent a valid calendar date in the ISO 8601 calendar together with a clock time. For any ISO Date-Time Record r, IsValidISODate(r.[[ISODate]].[[Year]], r.[[ISODate]][[Month]], r.[[ISODate]].[[Day]]) must return true, and IsValidTime(r.[[Time]].[[Hour]], r.[[Time]].[[Minute]], r.[[Time]].[[Second]], r.[[Time]].[[Millisecond]], r.[[Time]].[[Microsecond]], r.[[Time]].[[Nanosecond]]) must return true. It is not necessary for ISODateTimeWithinLimits(r) to return true.

ISO Date-Time Records have the fields listed in Table 7.

Table 7: ISO Date-Time Record Fields
Field Name Value Meaning
[[ISODate]] an ISO Date Record The date in the ISO 8601 calendar.
[[Time]] a Time Record The time. The [[Days]] field is ignored.

5.5.2 TimeValueToISODateTimeRecord ( t )

The abstract operation TimeValueToISODateTimeRecord takes argument t (a finite time value) and returns an ISO Date-Time Record. It converts a time value into an ISO Date-Time Record. It performs the following steps when called:

  1. Let isoDate be CreateISODateRecord((YearFromTime(t)), (MonthFromTime(t)) + 1, (DateFromTime(t))).
  2. Let time be CreateTimeRecord((HourFromTime(t)), (MinFromTime(t)), (SecFromTime(t)), (msFromTime(t)), 0, 0).
  3. Return ISO Date-Time Record { [[ISODate]]: isoDate, [[Time]]: time }.

5.5.3 CombineISODateAndTimeRecord ( isoDate, time )

The abstract operation CombineISODateAndTimeRecord takes arguments isoDate (an ISO Date Record) and time (a Time Record) and returns an ISO Date-Time Record. It combines a date and a time into one ISO Date-Time Record. It performs the following steps when called:

  1. NOTE: time.[[Days]] is ignored.
  2. Return ISO Date-Time Record { [[ISODate]]: isoDate, [[Time]]: time }.

5.5.4 ISODateTimeWithinLimits ( isoDateTime )

The abstract operation ISODateTimeWithinLimits takes argument isoDateTime (an ISO Date-Time Record) 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. If abs(ISODateToEpochDays(isoDateTime.[[ISODate]].[[Year]], isoDateTime.[[ISODate]].[[Month]] - 1, isoDateTime.[[ISODate]].[[Day]])) > 108 + 1, return false.
  2. Let ns be (GetUTCEpochNanoseconds(isoDateTime)).
  3. If nsnsMinInstant - nsPerDay, then
    1. Return false.
  4. If nsnsMaxInstant + nsPerDay, then
    1. Return false.
  5. Return true.

5.5.5 InterpretTemporalDateTimeFields ( calendar, fields, overflow )

The abstract operation InterpretTemporalDateTimeFields takes arguments calendar (a calendar type), fields (a Calendar Fields Record), and overflow (constrain or reject) and returns either a normal completion containing an ISO Date-Time Record, or a throw completion. It interprets the date/time fields in the object fields using the given calendar. It performs the following steps when called:

  1. Let isoDate be ? CalendarDateFromFields(calendar, fields, overflow).
  2. Let time be ? RegulateTime(fields.[[Hour]], fields.[[Minute]], fields.[[Second]], fields.[[Millisecond]], fields.[[Microsecond]], fields.[[Nanosecond]], overflow).
  3. Return CombineISODateAndTimeRecord(isoDate, time).

5.5.6 ToTemporalDateTime ( item [ , options ] )

The abstract operation ToTemporalDateTime takes argument item (an ECMAScript language value) and optional argument options (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainDateTime or a throw completion. Converts item to a new Temporal.PlainDateTime 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 item is an Object, then
    1. If item has an [[InitializedTemporalDateTime]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Return ! CreateTemporalDateTime(item.[[ISODateTime]], item.[[Calendar]]).
    2. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then
      1. Let isoDateTime be GetISODateTimeFor(item.[[TimeZone]], item.[[EpochNanoseconds]]).
      2. Let resolvedOptions be ? GetOptionsObject(options).
      3. Perform ? GetTemporalOverflowOption(resolvedOptions).
      4. Return ! CreateTemporalDateTime(isoDateTime, item.[[Calendar]]).
    3. If item has an [[InitializedTemporalDate]] internal slot, then
      1. Let resolvedOptions be ? GetOptionsObject(options).
      2. Perform ? GetTemporalOverflowOption(resolvedOptions).
      3. Let isoDateTime be CombineISODateAndTimeRecord(item.[[ISODate]], MidnightTimeRecord()).
      4. Return ? CreateTemporalDateTime(isoDateTime, item.[[Calendar]]).
    4. Let calendar be ? GetTemporalCalendarIdentifierWithISODefault(item).
    5. Let fields be ? PrepareCalendarFields(calendar, item, « year, month, month-code, day », « hour, minute, second, millisecond, microsecond, nanosecond », «»).
    6. Let resolvedOptions be ? GetOptionsObject(options).
    7. Let overflow be ? GetTemporalOverflowOption(resolvedOptions).
    8. Let result be ? InterpretTemporalDateTimeFields(calendar, fields, overflow).
    9. Return ? CreateTemporalDateTime(result, calendar).
  3. If item is not a String, throw a TypeError exception.
  4. Let result be ? ParseISODateTime(item, « TemporalDateTimeString[~Zoned] »).
  5. If result.[[Time]] is start-of-day, let time be MidnightTimeRecord(); else let time be result.[[Time]].
  6. Let calendar be result.[[Calendar]].
  7. If calendar is empty, set calendar to "iso8601".
  8. Set calendar to ? CanonicalizeCalendar(calendar).
  9. Let resolvedOptions be ? GetOptionsObject(options).
  10. Perform ? GetTemporalOverflowOption(resolvedOptions).
  11. Let isoDate be CreateISODateRecord(result.[[Year]], result.[[Month]], result.[[Day]]).
  12. Let isoDateTime be CombineISODateAndTimeRecord(isoDate, time).
  13. Return ? CreateTemporalDateTime(isoDateTime, calendar).

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

The abstract operation BalanceISODateTime 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), and nanosecond (an integer) and returns an ISO Date-Time Record. It performs the following steps when called:

  1. Let balancedTime be BalanceTime(hour, minute, second, millisecond, microsecond, nanosecond).
  2. Let balancedDate be BalanceISODate(year, month, day + balancedTime.[[Days]]).
  3. Return CombineISODateAndTimeRecord(balancedDate, balancedTime).

5.5.8 CreateTemporalDateTime ( isoDateTime, calendar [ , newTarget ] )

The abstract operation CreateTemporalDateTime takes arguments isoDateTime (an ISO Date-Time Record) and calendar (a calendar type) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainDateTime or a throw completion. It creates a Temporal.PlainDateTime instance and fills the internal slots with valid values. It performs the following steps when called:

  1. If ISODateTimeWithinLimits(isoDateTime) is false, then
    1. Throw a RangeError exception.
  2. If newTarget is not present, set newTarget to %Temporal.PlainDateTime%.
  3. Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDateTime.prototype%", « [[InitializedTemporalDateTime]], [[ISODateTime]], [[Calendar]] »).
  4. Set object.[[ISODateTime]] to isoDateTime.
  5. Set object.[[Calendar]] to calendar.
  6. Return object.

5.5.9 ISODateTimeToString ( isoDateTime, calendar, precision, showCalendar )

The abstract operation ISODateTimeToString takes arguments isoDateTime (an ISO Date-Time Record), calendar (a calendar type), precision (an integer in the inclusive interval from 0 to 9, minute, or auto), and showCalendar (auto, always, never, or critical) and returns a String. It formats an ISO Date-Time Record into an RFC 9557 string, to the precision specified by precision. It performs the following steps when called:

  1. Let yearString be PadISOYear(isoDateTime.[[ISODate]].[[Year]]).
  2. Let monthString be ToZeroPaddedDecimalString(isoDateTime.[[ISODate]].[[Month]], 2).
  3. Let dayString be ToZeroPaddedDecimalString(isoDateTime.[[ISODate]].[[Day]], 2).
  4. Let subSecondNanoseconds be isoDateTime.[[Time]].[[Millisecond]] × 106 + isoDateTime.[[Time]].[[Microsecond]] × 103 + isoDateTime.[[Time]].[[Nanosecond]].
  5. Let timeString be FormatTimeString(isoDateTime.[[Time]].[[Hour]], isoDateTime.[[Time]].[[Minute]], isoDateTime.[[Time]].[[Second]], subSecondNanoseconds, precision).
  6. Let calendarString be FormatCalendarAnnotation(calendar, showCalendar).
  7. Return the string-concatenation of yearString, the code unit 0x002D (HYPHEN-MINUS), monthString, the code unit 0x002D (HYPHEN-MINUS), dayString, 0x0054 (LATIN CAPITAL LETTER T), timeString, and calendarString.

5.5.10 CompareISODateTime ( isoDateTime1, isoDateTime2 )

The abstract operation CompareISODateTime takes arguments isoDateTime1 (an ISO Date-Time Record) and isoDateTime2 (an ISO Date-Time Record) and returns -1, 0, or 1. It performs a comparison of two date-times according to ISO 8601 calendar arithmetic. It performs the following steps when called:

  1. Let dateResult be CompareISODate(isoDateTime1.[[ISODate]], isoDateTime2.[[ISODate]]).
  2. If dateResult ≠ 0, return dateResult.
  3. Return CompareTimeRecord(isoDateTime1.[[Time]], isoDateTime2.[[Time]]).

5.5.11 RoundISODateTime ( isoDateTime, increment, unit, round