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:
First-class support for all time zones, including DST-safe arithmetic
Strongly-typed objects for dates, times, date/time values, year/month values, month/day values, "zoned" date/time values, and durations
Immutability for all Temporal objects
String serialization and interoperability via standardized formats
Compliance with industry standards like ISO 8601, RFC 3339, and RFC5545 (iCalendar)
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:
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:
Let ns be the approximate current UTC date and time, in nanoseconds since the epoch.
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.
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.
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%.
The initial value of the @@toStringTag property is the string value "Temporal.PlainDate".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
3.3.3 get Temporal.PlainDate.prototype.calendarId
Temporal.PlainDate.prototype.calendarId is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.year is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.month is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.monthCode is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.day is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.dayOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDate.prototype.dayOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.10 get Temporal.PlainDate.prototype.weekOfYear
Temporal.PlainDate.prototype.weekOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.11 get Temporal.PlainDate.prototype.yearOfWeek
Temporal.PlainDate.prototype.yearOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.12 get Temporal.PlainDate.prototype.daysInWeek
Temporal.PlainDate.prototype.daysInWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.13 get Temporal.PlainDate.prototype.daysInMonth
Temporal.PlainDate.prototype.daysInMonth is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.14 get Temporal.PlainDate.prototype.daysInYear
Temporal.PlainDate.prototype.daysInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.15 get Temporal.PlainDate.prototype.monthsInYear
Temporal.PlainDate.prototype.monthsInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
3.3.16 get Temporal.PlainDate.prototype.inLeapYear
Temporal.PlainDate.prototype.inLeapYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.
NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.
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:
This method performs the following steps when called:
Throw a TypeError exception.
3.4 Properties of Temporal.PlainDate Instances
Temporal.PlainDate instances are ordinary objects that inherit properties from the %Temporal.PlainDate.prototype% intrinsic object.
Temporal.PlainDate instances are initially created with the internal slots described in Table 1.
Table 1: Internal Slots of Temporal.PlainDate Instances
Internal Slot
Description
[[InitializedTemporalDate]]
The only specified use of this slot is for distinguishing Temporal.PlainDate instances from other objects.
[[ISOYear]]
An integer representing the year in the ISO 8601 calendar.
[[ISOMonth]]
An integer between 1 and 12, inclusive, representing the month of the year in the ISO 8601 calendar.
[[ISODay]]
An integer between 1 and ISODaysInMonth([[ISOYear]], [[ISOMonth]]), inclusive, representing the day of the month in the ISO 8601 calendar.
[[Calendar]]
An Object representing the calendar.
3.5 Abstract Operations for Temporal.PlainDate Objects
3.5.1 ISO Date Records
An ISO Date Record is a Record value used to represent a valid calendar date in the ISO 8601 calendar, although the year may be outside of the allowed range for Temporal.
ISO Date Records are produced by the abstract operation CreateISODateRecord.
ISO Date Records have the fields listed in Table 2.
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:
The abstract operation CreateTemporalDate takes arguments isoYear (an integer), isoMonth (an integer), isoDay (an integer), and calendar (a String or Object) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainDate, or an abrupt completion. It creates a Temporal.PlainDate instance and fills the internal slots with valid values. It performs the following steps when called:
If IsValidISODate(isoYear, isoMonth, isoDay) is false, throw a RangeError exception.
If ISODateTimeWithinLimits(isoYear, isoMonth, isoDay, 12, 0, 0, 0, 0, 0) is false, throw a RangeError exception.
If newTarget is not present, set newTarget to %Temporal.PlainDate%.
Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDate.prototype%", « [[InitializedTemporalDate]], [[ISOYear]], [[ISOMonth]], [[ISODay]], [[Calendar]] »).
Set object.[[ISOYear]] to isoYear.
Set object.[[ISOMonth]] to isoMonth.
Set object.[[ISODay]] to isoDay.
Set object.[[Calendar]] to calendar.
Return object.
Note
Deferring to ISODateTimeWithinLimits with an hour of 12 avoids trouble at the extremes of the representable range of dates, which stop just before midnight on each end.
3.5.4 ToTemporalDate ( item [ , options ] )
The abstract operation ToTemporalDate takes argument item (an ECMAScript language value) and optional argument options (an Object or undefined) and returns either a normal completion containing a Temporal.PlainDate, or a throw completion. It returns its argument item if it is already a Temporal.PlainDate instance, converts item to a new Temporal.PlainDate instance if possible, and throws otherwise. It performs the following steps when called:
If options is not present, set options to undefined.
The abstract operation DifferenceISODate takes arguments y1 (an integer), m1 (an integer), d1 (an integer), y2 (an integer), m2 (an integer), d2 (an integer), and largestUnit ("year", "month", "week", or "day") and returns a Date Duration Record.
The return value is the elapsed duration from a first date until a second date, according to the reckoning of the ISO 8601 calendar.
No fields larger than largestUnit will be non-zero in the resulting Date Duration Record.
It performs the following steps when called:
The abstract operation RegulateISODate takes arguments year (an integer), month (an integer), day (an integer), and overflow ("constrain" or "reject") and returns either a normal completion containing an ISO Date Record, or an abrupt completion.
It performs the overflow correction given by overflow on the values year, month, and day, in order to arrive at a valid date in the ISO 8601 calendar, as determined by IsValidISODate.
For "reject", values that do not form a valid date cause an exception to be thrown.
For "constrain", values that do not form a valid date are clamped to the correct range.
It performs the following steps when called:
If overflow is "constrain", then
Set month to the result of clampingmonth between 1 and 12.
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:
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:
The abstract operation DifferenceTemporalPlainDate takes arguments operation (since or until), temporalDate (a Temporal.PlainDate), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by temporalDate and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:
If operation is since, let sign be -1. Otherwise, let sign be 1.
A Temporal.PlainTime object is an Object that contains integers corresponding to a particular hour, minute,
second, millisecond, microsecond, and nanosecond.
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.
The initial value of the @@toStringTag property is the string value "Temporal.PlainTime".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
4.3.3 get Temporal.PlainTime.prototype.hour
Temporal.PlainTime.prototype.hour is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainTime.prototype.minute is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainTime.prototype.second is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
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:
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:
Temporal.PlainTime.prototype.nanosecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
Let result be RoundTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], roundingIncrement, smallestUnit, roundingMode).
NOTE: The following steps read options and perform independent validation in alphabetical order (ToFractionalSecondDigits reads "fractionalSecondDigits" and ToTemporalRoundingMode reads "roundingMode").
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:
This method performs the following steps when called:
Throw a TypeError exception.
4.4 Properties of Temporal.PlainTime Instances
Temporal.PlainTime instances are ordinary objects that inherit properties from the %Temporal.PlainTime.prototype% intrinsic object.
Temporal.PlainTime instances are initially created with the internal slots described in Table 3.
Table 3: Internal Slots of Temporal.PlainTime Instances
Internal Slot
Description
[[InitializedTemporalTime]]
The only specified use of this slot is for distinguishing Temporal.PlainTime instances from other objects.
[[ISOHour]]
An integer between 0 and 23, inclusive, representing the hour of the day.
[[ISOMinute]]
An integer between 0 and 59, inclusive, representing the minute of the hour.
[[ISOSecond]]
An integer between 0 and 59, inclusive, representing the second within the minute.
[[ISOMillisecond]]
An integer between 0 and 999, inclusive, representing the millisecond within the second.
[[ISOMicrosecond]]
An integer between 0 and 999, inclusive, representing the microsecond within the millisecond.
[[ISONanosecond]]
An integer between 0 and 999, inclusive, representing the nanosecond within the microsecond.
4.5 Abstract operations
4.5.1 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.
The abstract operation DifferenceTime takes arguments h1 (an integer between 0 and 23 inclusive), min1 (an integer between 0 and 59 inclusive), s1 (an integer between 0 and 59 inclusive), ms1 (an integer between 0 and 999 inclusive), mus1 (an integer between 0 and 999 inclusive), ns1 (an integer between 0 and 999 inclusive), h2 (an integer between 0 and 23 inclusive), min2 (an integer between 0 and 59 inclusive), s2 (an integer between 0 and 59 inclusive), ms2 (an integer between 0 and 999 inclusive), mus2 (an integer between 0 and 999 inclusive), and ns2 (an integer between 0 and 999 inclusive). It returns a Time Duration Record with the elapsed duration from a first wall-clock time, until a second wall-clock time. It performs the following steps when called:
Let hours be h2 - h1.
Let minutes be min2 - min1.
Let seconds be s2 - s1.
Let milliseconds be ms2 - ms1.
Let microseconds be mus2 - mus1.
Let nanoseconds be ns2 - ns1.
Let sign be ! DurationSign(0, 0, 0, 0, hours, minutes, seconds, milliseconds, microseconds, nanoseconds).
The abstract operation ToTemporalTime returns its argument item if it is already a Temporal.PlainTime instance, converts item to a new Temporal.PlainTime instance if possible, and throws otherwise.
If overflow is not present, set overflow to "constrain".
Assert: overflow is either "constrain" or "reject".
Set result to ? RegulateTime(result.[[Hour]], result.[[Minute]], result.[[Second]], result.[[Millisecond]], result.[[Microsecond]], result.[[Nanosecond]], overflow).
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:
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:
Set microsecond to microsecond + floor(nanosecond / 1000).
The abstract operation CreateTemporalTime takes arguments hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), and nanosecond (an integer) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainTime, or an abrupt completion. It creates a new Temporal.PlainTime instance and fills the internal slots with valid values. It performs the following steps when called:
If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
If newTarget is not present, set newTarget to %Temporal.PlainTime%.
Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainTime.prototype%", « [[InitializedTemporalTime]], [[ISOHour]], [[ISOMinute]], [[ISOSecond]], [[ISOMillisecond]], [[ISOMicrosecond]], [[ISONanosecond]] »).
The abstract operation ToTemporalTimeRecord takes argument temporalTimeLike (an Object) and optional argument completeness (partial or complete) and returns either a normal completion containing a TemporalTimeLike Record, or an abrupt completion. It performs the following steps when called:
If completeness is not present, set completeness to complete.
Let partial be ? PrepareTemporalFields(temporalTimeLike, « "hour", "microsecond", "millisecond", "minute", "nanosecond", "second" », partial).
If completeness is complete, then
Let result be a new TemporalTimeLike Record with each field set to 0.
Else,
Let result be a new TemporalTimeLike Record with each field set to undefined.
The abstract operation AddTime takes arguments hour (an integer in the inclusive range 0 to 23), minute (an integer in the inclusive range 0 to 59), second (an integer in the inclusive range 0 to 59), millisecond (an integer in the inclusive range 0 to 999), microsecond (an integer in the inclusive range 0 to 999), nanosecond (an integer in the inclusive range 0 to 999), hours (an integer), minutes (an integer), seconds (an integer), milliseconds (an integer), microseconds (an integer), and nanoseconds (an integer) and returns a Time Record. It performs the following steps when called:
The abstract operation RoundTime takes arguments hour (an integer in the inclusive range 0 to 23), minute (an integer in the inclusive range 0 to 59), second (an integer in the inclusive range 0 to 59), millisecond (an integer in the inclusive range 0 to 999), microsecond (an integer in the inclusive range 0 to 999), nanosecond (an integer in the inclusive range 0 to 999), increment (an integer), unit ("day", "hour", "minute", "second", "millisecond", "microsecond", or "nanosecond"), and roundingMode ("ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", or "halfEven") and optional argument dayLengthNs (an integer) and returns a Time Record. It rounds a time to the given increment, optionally adjusting for a non-24-hour day. It performs the following steps when called:
Let fractionalSecond be nanosecond × 10-9 + microsecond × 10-6 + millisecond × 10-3 + second.
If unit is "day", then
If dayLengthNs is not present, set dayLengthNs to nsPerDay.
The abstract operation DifferenceTemporalPlainTime takes arguments operation (since or until), temporalTime (a Temporal.PlainTime), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by temporalTime and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:
If operation is since, let sign be -1. Otherwise, let sign be 1.
Let settings be ? GetDifferenceSettings(operation, resolvedOptions, time, « », "nanosecond", "hour").
Let result be ! DifferenceTime(temporalTime.[[ISOHour]], temporalTime.[[ISOMinute]], temporalTime.[[ISOSecond]], temporalTime.[[ISOMillisecond]], temporalTime.[[ISOMicrosecond]], temporalTime.[[ISONanosecond]], other.[[ISOHour]], other.[[ISOMinute]], other.[[ISOSecond]], other.[[ISOMillisecond]], other.[[ISOMicrosecond]], other.[[ISONanosecond]]).
If settings.[[SmallestUnit]] is not "nanosecond" or settings.[[RoundingIncrement]] ≠ 1, then
Let roundRecord be ! RoundDuration(0, 0, 0, 0, result.[[Hours]], result.[[Minutes]], result.[[Seconds]], result.[[Milliseconds]], result.[[Microseconds]], result.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]]).
Set result to roundRecord.[[DurationRecord]].
Set result to ! BalanceTimeDuration(0, result.[[Hours]], result.[[Minutes]], result.[[Seconds]], result.[[Milliseconds]], result.[[Microseconds]], result.[[Nanoseconds]], settings.[[LargestUnit]]).
The abstract operation AddDurationToOrSubtractDurationFromPlainTime takes arguments operation (add or subtract), temporalTime (a Temporal.PlainTime), and temporalDurationLike (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainTime or an abrupt completion. It adds/subtracts temporalDurationLike to/from temporalTime, returning a point in time that is in the future/past relative to temporalTime. It performs the following steps when called:
If operation is subtract, let sign be -1. Otherwise, let sign be 1.
A Temporal.PlainDateTime object is an Object that contains integers corresponding to a particular year, month, day, hour, minute, second, millisecond, microsecond, and nanosecond.
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.
An ECMAScript implementation that includes the ECMA-402 Internationalization API extends this prototype with additional properties in order to represent calendar data.
The initial value of the @@toStringTag property is the string value "Temporal.PlainDateTime".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
5.3.3 get Temporal.PlainDateTime.prototype.calendarId
Temporal.PlainDateTime.prototype.calendarId is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDateTime.prototype.year is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDateTime.prototype.month is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.6 get Temporal.PlainDateTime.prototype.monthCode
Temporal.PlainDateTime.prototype.monthCode is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDateTime.prototype.day is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDateTime.prototype.hour is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.PlainDateTime.prototype.minute is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.10 get Temporal.PlainDateTime.prototype.second
Temporal.PlainDateTime.prototype.second is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.11 get Temporal.PlainDateTime.prototype.millisecond
Temporal.PlainDateTime.prototype.millisecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.12 get Temporal.PlainDateTime.prototype.microsecond
Temporal.PlainDateTime.prototype.microsecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.13 get Temporal.PlainDateTime.prototype.nanosecond
Temporal.PlainDateTime.prototype.nanosecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.14 get Temporal.PlainDateTime.prototype.dayOfWeek
Temporal.PlainDateTime.prototype.dayOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.15 get Temporal.PlainDateTime.prototype.dayOfYear
Temporal.PlainDateTime.prototype.dayOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.16 get Temporal.PlainDateTime.prototype.weekOfYear
Temporal.PlainDateTime.prototype.weekOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.17 get Temporal.PlainDateTime.prototype.yearOfWeek
Temporal.PlainDateTime.prototype.yearOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.18 get Temporal.PlainDateTime.prototype.daysInWeek
Temporal.PlainDateTime.prototype.daysInWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.19 get Temporal.PlainDateTime.prototype.daysInMonth
Temporal.PlainDateTime.prototype.daysInMonth is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.20 get Temporal.PlainDateTime.prototype.daysInYear
Temporal.PlainDateTime.prototype.daysInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.21 get Temporal.PlainDateTime.prototype.monthsInYear
Temporal.PlainDateTime.prototype.monthsInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
5.3.22 get Temporal.PlainDateTime.prototype.inLeapYear
Temporal.PlainDateTime.prototype.inLeapYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
Let result be RoundISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], roundingIncrement, smallestUnit, roundingMode).
Let result be RoundISODateTime(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[ISOHour]], dateTime.[[ISOMinute]], dateTime.[[ISOSecond]], dateTime.[[ISOMillisecond]], dateTime.[[ISOMicrosecond]], dateTime.[[ISONanosecond]], precision.[[Increment]], precision.[[Unit]], roundingMode).
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:
NOTE: The call to CalendarYearMonthFromFields is necessary in order to create a PlainYearMonth object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.
NOTE: The call to CalendarMonthDayFromFields is necessary in order to create a PlainMonthDay object with the [[ISOYear]], [[ISOMonth]], and [[ISODay]] internal slots set correctly.
5.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.
[[ISOYear]]
An integer representing the year in the ISO 8601 calendar.
[[ISOMonth]]
An integer between 1 and 12, inclusive, representing the month of the year in the ISO 8601 calendar.
[[ISODay]]
An integer between 1 and ISODaysInMonth([[ISOYear]], [[ISOMonth]]), inclusive, representing the day of the month in the ISO 8601 calendar.
[[ISOHour]]
An integer between 0 and 23, inclusive, representing the hour of the day.
[[ISOMinute]]
An integer between 0 and 59, inclusive, representing the minute of the hour.
[[ISOSecond]]
An integer between 0 and 59, inclusive, representing the second within the minute.
[[ISOMillisecond]]
An integer between 0 and 999, inclusive, representing the millisecond within the second.
[[ISOMicrosecond]]
An integer between 0 and 999, inclusive, representing the microsecond within the millisecond.
[[ISONanosecond]]
An integer between 0 and 999, inclusive, representing the nanosecond within the microsecond.
[[Calendar]]
An Object representing the calendar.
5.5 Abstract operations
5.5.1 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.[[Year]], r.[[Month]], r.[[Day]]) must return true, and IsValidTime(r.[[Hour]], r.[[Minute]], r.[[Second]], r.[[Millisecond]], r.[[Microsecond]], r.[[Nanosecond]]) must return true.
It is not necessary for ISODateTimeWithinLimits(r.[[Year]], r.[[Month]], r.[[Day]], r.[[Hour]], r.[[Minute]], r.[[Second]], r.[[Millisecond]], r.[[Microsecond]], r.[[Nanosecond]]) to return true.
ISO Date-Time Records have the fields listed in Table 7.
The abstract operation ISODateTimeWithinLimits takes arguments year (an integer), month (an integer between 1 and 12 inclusive), day (an integer between 1 and 31 inclusive), hour (an integer between 0 and 23 inclusive), minute (an integer between 0 and 59 inclusive), second (an integer between 0 and 59 inclusive), millisecond (an integer between 0 and 999 inclusive), microsecond (an integer between 0 and 999 inclusive), and nanosecond (an integer between 0 and 999 inclusive) and returns a Boolean. The return value is true if the combination of a date in the ISO 8601 calendar with a wall-clock time, given by the arguments, is within the representable range of Temporal.PlainDateTime, and false otherwise.
Note
Temporal.PlainDateTime objects can represent points in time within 24 hours (8.64 × 1013 nanoseconds) of the Temporal.Instant boundaries.
This ensures that a Temporal.Instant object can be converted into a Temporal.PlainDateTime object using any time zone.
5.5.3 InterpretTemporalDateTimeFields ( calendar, fields, options )
The abstract operation InterpretTemporalDateTimeFields takes arguments calendar (a String or Object), fields (an Object), and options (an Object) 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, and returns a Record with the fields according to the ISO 8601 calendar. It performs the following steps when called:
Assert: options is an ordinary extensible Object that is not directly observable from ECMAScript code and for which the value of the [[Prototype]] internal slot is null and every property is a configurable data property.
The abstract operation ToTemporalDateTime takes argument item (an ECMAScript language value) and optional argument options (an Object or undefined) and returns either a normal completion containing a Temporal.PlainDateTime, or a throw completion. It returns its argument item if it is already a Temporal.PlainDateTime instance, converts item to a new Temporal.PlainDateTime instance if possible, and throws otherwise. It performs the following steps when called:
If options is not present, set options to undefined.
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:
Let balancedTime be BalanceTime(hour, minute, second, millisecond, microsecond, nanosecond).
Let balancedDate be BalanceISODate(year, month, day + balancedTime.[[Days]]).
The abstract operation CreateTemporalDateTime takes arguments isoYear (an integer), isoMonth (an integer), isoDay (an integer), hour (an integer), minute (an integer), second (an integer), millisecond (an integer), microsecond (an integer), nanosecond (an integer), and calendar (a String or Object) and optional argument newTarget (a constructor) and returns either a normal completion containing a Temporal.PlainDateTime instance, or an abrupt completion. It creates a Temporal.PlainDateTime instance and fills the internal slots with valid values. It performs the following steps when called:
If IsValidISODate(isoYear, isoMonth, isoDay) is false, throw a RangeError exception.
If IsValidTime(hour, minute, second, millisecond, microsecond, nanosecond) is false, throw a RangeError exception.
If ISODateTimeWithinLimits(isoYear, isoMonth, isoDay, hour, minute, second, millisecond, microsecond, nanosecond) is false, then
Throw a RangeError exception.
If newTarget is not present, set newTarget to %Temporal.PlainDateTime%.
Let object be ? OrdinaryCreateFromConstructor(newTarget, "%Temporal.PlainDateTime.prototype%", « [[InitializedTemporalDateTime]], [[ISOYear]], [[ISOMonth]], [[ISODay]], [[ISOHour]], [[ISOMinute]], [[ISOSecond]], [[ISOMillisecond]], [[ISOMicrosecond]], [[ISONanosecond]], [[Calendar]] »).
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.
The abstract operation RoundISODateTime takes arguments year (an integer), month (an integer in the inclusive interval from 1 to 12), day (an integer in the inclusive interval from 1 to 31), hour (an integer in the inclusive interval from 0 to 23), minute (an integer in the inclusive interval from 0 to 59), second (an integer in the inclusive interval from 0 to 59), millisecond (an integer in the inclusive interval from 0 to 999), microsecond (an integer in the inclusive interval from 0 to 999), nanosecond (an integer in the inclusive interval from 0 to 999), increment (an integer), unit ("day", "hour", "minute", "second", "millisecond", "microsecond", or "nanosecond"), and roundingMode ("ceil", "floor", "expand", "trunc", "halfCeil", "halfFloor", "halfExpand", "halfTrunc", or "halfEven") and optional argument dayLength (an integer) and returns an ISO Date-Time Record. It rounds the time part of a combined date and time, carrying over any excess into the date part. It performs the following steps when called:
The abstract operation DifferenceISODateTime takes arguments y1 (an integer), mon1 (an integer between 1 and 12 inclusive), d1 (an integer between 1 and 31 inclusive), h1 (an integer between 0 and 23 inclusive), min1 (an integer between 0 and 59 inclusive), s1 (an integer between 0 and 59 inclusive), ms1 (an integer between 0 and 999 inclusive), mus1 (an integer between 0 and 999 inclusive), ns1 (an integer between 0 and 999 inclusive), y2 (an integer), mon2 (an integer between 1 and 12 inclusive), d2 (an integer between 1 and 31 inclusive), h2 (an integer between 0 and 23 inclusive), min2 (an integer between 0 and 59 inclusive), s2 (an integer between 0 and 59 inclusive), ms2 (an integer between 0 and 999 inclusive), mus2 (an integer between 0 and 999 inclusive), ns2 (an integer between 0 and 999 inclusive), calendar (an Object), largestUnit (a String), and options (an Object) and returns either a normal completion containing a Duration Record, or a throw completion.
The returned Duration Record contains the elapsed duration from a first date and time, until a second date and time, according to the reckoning of the given calendar.
The given date and time units are all in the ISO 8601 calendar.
The largestUnit and options arguments are used in calendar's dateUntil method.
It performs the following steps when called:
The abstract operation DifferenceTemporalPlainDateTime takes arguments operation (since or until), dateTime (a Temporal.PlainDateTime), other (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.Duration or an abrupt completion. It computes the difference between the two times represented by dateTime and other, optionally rounds it, and returns it as a Temporal.Duration object. It performs the following steps when called:
If operation is since, let sign be -1. Otherwise, let sign be 1.
Let relativeTo be ! CreateTemporalDate(dateTime.[[ISOYear]], dateTime.[[ISOMonth]], dateTime.[[ISODay]], dateTime.[[Calendar]]).
Let roundRecord be ? RoundDuration(diff.[[Years]], diff.[[Months]], diff.[[Weeks]], diff.[[Days]], diff.[[Hours]], diff.[[Minutes]], diff.[[Seconds]], diff.[[Milliseconds]], diff.[[Microseconds]], diff.[[Nanoseconds]], settings.[[RoundingIncrement]], settings.[[SmallestUnit]], settings.[[RoundingMode]], relativeTo).
Let roundResult be roundRecord.[[DurationRecord]].
Let result be ? BalanceTimeDuration(roundResult.[[Days]], roundResult.[[Hours]], roundResult.[[Minutes]], roundResult.[[Seconds]], roundResult.[[Milliseconds]], roundResult.[[Microseconds]], roundResult.[[Nanoseconds]], settings.[[LargestUnit]]).
The abstract operation AddDurationToOrSubtractDurationFromPlainDateTime takes arguments operation (add or subtract), dateTime (a Temporal.PlainDateTime), temporalDurationLike (an ECMAScript language value), and options (an ECMAScript language value) and returns either a normal completion containing a Temporal.PlainDateTime or an abrupt completion. It adds/subtracts temporalDurationLike to/from dateTime, returning a point in time that is in the future/past relative to datetime. It performs the following steps when called:
If operation is subtract, let sign be -1. Otherwise, let sign be 1.
A Temporal.ZonedDateTime object is an Object referencing a fixed point in time with nanoseconds precision, and containing Object values corresponding to a particular time zone and calendar system.
creates and initializes a new Temporal.ZonedDateTime object when called as a constructor.
is not intended to be called as a function and will throw an exception when called in that manner.
may be used as the value of an extends clause of a class definition.
Subclass constructors that intend to inherit the specified Temporal.ZonedDateTime behaviour must
include a super call to the %Temporal.ZonedDateTime% constructor to create and initialize subclass
instances with the necessary internal slots.
An ECMAScript implementation that includes the ECMA-402 Internationalization API extends this prototype with additional properties in order to represent calendar data.
The initial value of the @@toStringTag property is the string value "Temporal.ZonedDateTime".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.
6.3.3 get Temporal.ZonedDateTime.prototype.calendarId
Temporal.ZonedDateTime.prototype.calendarId is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.4 get Temporal.ZonedDateTime.prototype.timeZoneId
Temporal.ZonedDateTime.prototype.timeZoneId is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.ZonedDateTime.prototype.year is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.ZonedDateTime.prototype.month is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.7 get Temporal.ZonedDateTime.prototype.monthCode
Temporal.ZonedDateTime.prototype.monthCode is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.ZonedDateTime.prototype.day is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
Temporal.ZonedDateTime.prototype.hour is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.10 get Temporal.ZonedDateTime.prototype.minute
Temporal.ZonedDateTime.prototype.minute is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.11 get Temporal.ZonedDateTime.prototype.second
Temporal.ZonedDateTime.prototype.second is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.12 get Temporal.ZonedDateTime.prototype.millisecond
Temporal.ZonedDateTime.prototype.millisecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.13 get Temporal.ZonedDateTime.prototype.microsecond
Temporal.ZonedDateTime.prototype.microsecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.14 get Temporal.ZonedDateTime.prototype.nanosecond
Temporal.ZonedDateTime.prototype.nanosecond is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.15 get Temporal.ZonedDateTime.prototype.epochSeconds
Temporal.ZonedDateTime.prototype.epochSeconds is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.16 get Temporal.ZonedDateTime.prototype.epochMilliseconds
Temporal.ZonedDateTime.prototype.epochMilliseconds is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.17 get Temporal.ZonedDateTime.prototype.epochMicroseconds
Temporal.ZonedDateTime.prototype.epochMicroseconds is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.18 get Temporal.ZonedDateTime.prototype.epochNanoseconds
Temporal.ZonedDateTime.prototype.epochNanoseconds is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.19 get Temporal.ZonedDateTime.prototype.dayOfWeek
Temporal.ZonedDateTime.prototype.dayOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.20 get Temporal.ZonedDateTime.prototype.dayOfYear
Temporal.ZonedDateTime.prototype.dayOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.21 get Temporal.ZonedDateTime.prototype.weekOfYear
Temporal.ZonedDateTime.prototype.weekOfYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.22 get Temporal.ZonedDateTime.prototype.yearOfWeek
Temporal.ZonedDateTime.prototype.yearOfWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.23 get Temporal.ZonedDateTime.prototype.hoursInDay
Temporal.ZonedDateTime.prototype.hoursInDay is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.24 get Temporal.ZonedDateTime.prototype.daysInWeek
Temporal.ZonedDateTime.prototype.daysInWeek is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.25 get Temporal.ZonedDateTime.prototype.daysInMonth
Temporal.ZonedDateTime.prototype.daysInMonth is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.26 get Temporal.ZonedDateTime.prototype.daysInYear
Temporal.ZonedDateTime.prototype.daysInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.27 get Temporal.ZonedDateTime.prototype.monthsInYear
Temporal.ZonedDateTime.prototype.monthsInYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.28 get Temporal.ZonedDateTime.prototype.inLeapYear
Temporal.ZonedDateTime.prototype.inLeapYear is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.29 get Temporal.ZonedDateTime.prototype.offsetNanoseconds
Temporal.ZonedDateTime.prototype.offsetNanoseconds is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
6.3.30 get Temporal.ZonedDateTime.prototype.offset
Temporal.ZonedDateTime.prototype.offset is an accessor property whose set accessor function is undefined.
Its get accessor function performs the following steps:
NOTE: The following steps read options and perform independent validation in alphabetical order (ToTemporalRoundingIncrement reads "roundingIncrement" and ToTemporalRoundingMode reads "roundingMode").
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: