diff --git a/docs/README.md b/docs/README.md index 85fa66ac5b..057225b183 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,12 +37,9 @@ Several important concepts are explained elsewhere: [exact time, wall-clock time - `Temporal.Now.instant()` - get the current system exact time - `Temporal.Now.timeZoneId()` - get the current system time zone -- `Temporal.Now.zonedDateTime(calendar)` - get the current date and wall-clock time in the system time zone and specified calendar - `Temporal.Now.zonedDateTimeISO()` - get the current date and wall-clock time in the system time zone and ISO-8601 calendar -- `Temporal.Now.plainDate(calendar)` - get the current date in the system time zone and specified calendar - `Temporal.Now.plainDateISO()` - get the current date in the system time zone and ISO-8601 calendar - `Temporal.Now.plainTimeISO()` - get the current wall-clock time in the system time zone and ISO-8601 calendar -- `Temporal.Now.plainDateTime(calendar)` - get the current system date/time in the system time zone, but return an object that doesn't remember its time zone so should NOT be used to derive other values (e.g. 12 hours later) in time zones that use Daylight Saving Time (DST). - `Temporal.Now.plainDateTimeISO()` - same as above, but return the DateTime in the ISO-8601 calendar ```js diff --git a/docs/instant.md b/docs/instant.md index 20b01ee249..de90370dc5 100644 --- a/docs/instant.md +++ b/docs/instant.md @@ -264,9 +264,8 @@ epochMicros = ns / 1000n + ((ns % 1000n) < 0n ? -1n : 0n); For a list of IANA time zone names, see the current version of the [IANA time zone database](https://www.iana.org/time-zones). A convenient list is also available [on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), although it might not reflect the latest official status. -This method is one way to convert a `Temporal.Instant` to a `Temporal.ZonedDateTime`. -It is the same as `toZonedDateTime()`, but always uses the ISO 8601 calendar. -Use this method if you are not doing computations in other calendars. +This method always returns a `Temporal.ZonedDateTime` with the ISO 8601 calendar. +Remember to use `withCalendar()` on the result if you need to do computations in other calendars. Example usage: @@ -276,39 +275,14 @@ timestamp = Temporal.Instant.fromEpochMilliseconds(1553993100_000); timestamp.toZonedDateTimeISO('Europe/Berlin'); // => 2019-03-31T01:45:00+01:00[Europe/Berlin] timestamp.toZonedDateTimeISO('UTC'); // => 2019-03-31T00:45:00+00:00[UTC] timestamp.toZonedDateTimeISO('-08:00'); // => 2019-03-30T16:45:00-08:00[-08:00] -``` - -### instant.**toZonedDateTime**(_item_: object) : Temporal.ZonedDateTime - -**Parameters:** -- `item` (object): an object with properties to be combined with `instant`. The following properties are recognized: - - `calendar` (required calendar identifier string, `Temporal.Calendar` object, or object implementing the calendar protocol): the calendar in which to interpret `instant`. - - `timeZone` (required time zone identifier string, `Temporal.TimeZone` object, or object implementing the [time zone protocol](./timezone.md#custom-time-zones)): the time zone in which to interpret `instant`. - -**Returns:** a `Temporal.ZonedDateTime` object representing the calendar date, wall-clock time, time zone offset, and `timeZone`, according to the reckoning of `calendar`, at the exact time indicated by `instant`. - -For a list of IANA time zone names, see the current version of the [IANA time zone database](https://www.iana.org/time-zones). -A convenient list is also available [on Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), although it might not reflect the latest official status. - -For a list of calendar identifiers, see the documentation for [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#Parameters). - -If you only want to use the ISO 8601 calendar, use `toZonedDateTimeISO()`. - -Example usage: - - -```js // What time was the Unix epoch (timestamp 0) in Bell Labs (Murray Hill, New Jersey, USA) in the Gregorian calendar? epoch = Temporal.Instant.fromEpochMilliseconds(0); -timeZone = Temporal.TimeZone.from('America/New_York'); -epoch.toZonedDateTime({ timeZone, calendar: 'gregory' }); +epoch.toZonedDateTimeISO('America/New_York').withCalendar('gregory'); // => 1969-12-31T19:00:00-05:00[America/New_York][u-ca=gregory] // What time was the Unix epoch in Tokyo in the Japanese calendar? -timeZone = Temporal.TimeZone.from('Asia/Tokyo'); -calendar = Temporal.Calendar.from('japanese'); -zdt = epoch.toZonedDateTime({ timeZone, calendar }); +zdt = epoch.toZonedDateTimeISO('Asia/Tokyo').withCalendar('japanese'); // => 1970-01-01T09:00:00+09:00[Asia/Tokyo][u-ca=japanese] console.log(zdt.eraYear, zdt.era); // => '45 showa' diff --git a/docs/now.md b/docs/now.md index 4ad98db4c8..b05710e605 100644 --- a/docs/now.md +++ b/docs/now.md @@ -25,7 +25,8 @@ The `Temporal.Now` object has several methods which give information about the c This method gets the current date, time, time zone, and time zone offset according to the system settings, in the reckoning of the ISO 8601 calendar system. Optionally a time zone can be given in which the time is computed, instead of the current system time zone. -This method is the same as `zonedDateTime()`, but always uses the ISO 8601 calendar. +This method always returns a `Temporal.ZonedDateTime` with the ISO 8601 calendar. +Remember to use `withCalendar()` on the result if you need to do computations in other calendars. Example usage: @@ -46,21 +47,6 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => { // Tokyo: 2020-09-18T17:17:48.441068438+09:00[Asia/Tokyo] ``` -### Temporal.Now.**zonedDateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.ZonedDateTime - -**Parameters:** - -- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in. -- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string. - If not given, the current system time zone will be used. - -**Returns:** a `Temporal.ZonedDateTime` object representing the current system date, time, time zone, and time zone offset. - -This method gets the current date, time, time zone, and time zone offset according to the system settings, in the reckoning of the given calendar system. -Optionally a time zone can be given in which the time is computed, instead of the current system time zone. - -If you only want to use the ISO 8601 calendar, use `Temporal.Now.zonedDateTimeISO()`. - ### Temporal.Now.**instant**() : Temporal.Instant **Returns:** a `Temporal.Instant` object representing the current system time. @@ -120,7 +106,8 @@ console.log(`At ${nextTransition.toZonedDateTimeISO(id)} the offset will change This method gets the current calendar date and wall-clock time according to the system settings. Optionally a time zone can be given in which the time is computed, instead of the current system time zone. -This method is the same as `dateTime()`, but always uses the ISO 8601 calendar. +This method always returns a `Temporal.PlainDateTime` with the ISO 8601 calendar. +Remember to use `withCalendar()` on the result if you need to do computations in other calendars. Example usage: @@ -143,21 +130,6 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => { ``` -### Temporal.Now.**plainDateTime**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDateTime - -**Parameters:** - -- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in. -- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string. - If not given, the current system time zone will be used. - -**Returns:** a `Temporal.PlainDateTime` object representing the current system date and time in the reckoning of the given calendar system. - -This method gets the current calendar date and wall-clock time according to the system settings. -Optionally a time zone can be given in which the time is computed, instead of the current system time zone. - -If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateTimeISO()`. - ### Temporal.Now.**plainDateISO**(_timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDate **Parameters:** @@ -170,7 +142,8 @@ If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateTimeIS This method gets the current calendar date according to the system settings. Optionally a time zone can be given in which the time is computed, instead of the current system time zone. -This method is the same as `date()`, but always uses the ISO 8601 calendar. +This method always returns a `Temporal.PlainDate` with the ISO 8601 calendar. +Remember to use `withCalendar()` on the result if you need to do computations in other calendars. Example usage: @@ -178,26 +151,9 @@ Example usage: // Is it New Year in the ISO 8601 calendar? date = Temporal.Now.plainDateISO(); if (date.month === 1 && date.day === 1) console.log('New year!'); -``` -### Temporal.Now.**plainDate**(_calendar_: object | string, _timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDate - -**Parameters:** - -- `calendar` (`Temporal.Calendar`, plain object, or string): The calendar system to get the current date and time in. -- `timeZone` (optional object or string): The time zone to get the current date and time in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string. - If not given, the current system time zone will be used. - -**Returns:** a `Temporal.PlainDate` object representing the current system date in the reckoning of the given calendar. - -This method gets the current calendar date according to the system settings. -Optionally a time zone can be given in which the time is computed, instead of the current system time zone. - -If you only want to use the ISO 8601 calendar, use `Temporal.Now.plainDateISO()`. - -```js // Is it Nowruz (New Year in the Persian calendar)? -date = Temporal.Now.plainDate('persian'); +date = Temporal.Now.plainDateISO().withCalendar('persian'); if (date.month === 1 && date.day === 1) console.log('New year!'); ``` diff --git a/polyfill/index.d.ts b/polyfill/index.d.ts index bf844908d8..8e174ff129 100644 --- a/polyfill/index.d.ts +++ b/polyfill/index.d.ts @@ -594,7 +594,6 @@ export namespace Temporal { round( roundTo: RoundTo<'hour' | 'minute' | 'second' | 'millisecond' | 'microsecond' | 'nanosecond'> ): Temporal.Instant; - toZonedDateTime(calendarAndTimeZone: { timeZone: TimeZoneLike; calendar: CalendarLike }): Temporal.ZonedDateTime; toZonedDateTimeISO(tzLike: TimeZoneLike): Temporal.ZonedDateTime; toLocaleString(locales?: string | string[], options?: Intl.DateTimeFormatOptions): string; toJSON(): string; @@ -1334,26 +1333,6 @@ export namespace Temporal { * */ instant: () => Temporal.Instant; - /** - * Get the current calendar date and clock time in a specific calendar and - * time zone. - * - * The `calendar` parameter is required. When using the ISO 8601 calendar or - * if you don't understand the need for or implications of a calendar, then - * a more ergonomic alternative to this method is - * `Temporal.Now.zonedDateTimeISO()`. - * - * @param {CalendarLike} [calendar] - calendar identifier, or - * a `Temporal.Calendar` instance, or an object implementing the calendar - * protocol. - * @param {TimeZoneLike} [tzLike] - - * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier} - * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an - * object implementing the time zone protocol. If omitted, the environment's - * current time zone will be used. - */ - zonedDateTime: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.ZonedDateTime; - /** * Get the current calendar date and clock time in a specific time zone, * using the ISO 8601 calendar. @@ -1366,31 +1345,6 @@ export namespace Temporal { */ zonedDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.ZonedDateTime; - /** - * Get the current calendar date and clock time in a specific calendar and - * time zone. - * - * The calendar is required. When using the ISO 8601 calendar or if you - * don't understand the need for or implications of a calendar, then a more - * ergonomic alternative to this method is `Temporal.Now.plainDateTimeISO`. - * - * Note that the `Temporal.PlainDateTime` type does not persist the time zone, - * but retaining the time zone is required for most time-zone-related use - * cases. Therefore, it's usually recommended to use - * `Temporal.Now.zonedDateTimeISO` or `Temporal.Now.zonedDateTime` instead - * of this function. - * - * @param {CalendarLike} [calendar] - calendar identifier, or - * a `Temporal.Calendar` instance, or an object implementing the calendar - * protocol. - * @param {TimeZoneLike} [tzLike] - - * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier} - * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an - * object implementing the time zone protocol. If omitted, - * the environment's current time zone will be used. - */ - plainDateTime: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.PlainDateTime; - /** * Get the current date and clock time in a specific time zone, using the * ISO 8601 calendar. @@ -1408,24 +1362,6 @@ export namespace Temporal { */ plainDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainDateTime; - /** - * Get the current calendar date in a specific calendar and time zone. - * - * The calendar is required. When using the ISO 8601 calendar or if you - * don't understand the need for or implications of a calendar, then a more - * ergonomic alternative to this method is `Temporal.Now.plainDateISO`. - * - * @param {CalendarLike} [calendar] - calendar identifier, or - * a `Temporal.Calendar` instance, or an object implementing the calendar - * protocol. - * @param {TimeZoneLike} [tzLike] - - * {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier} - * string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an - * object implementing the time zone protocol. If omitted, - * the environment's current time zone will be used. - */ - plainDate: (calendar: CalendarLike, tzLike?: TimeZoneLike) => Temporal.PlainDate; - /** * Get the current date in a specific time zone, using the ISO 8601 * calendar. diff --git a/polyfill/lib/instant.mjs b/polyfill/lib/instant.mjs index 6890e36784..94ea02a640 100644 --- a/polyfill/lib/instant.mjs +++ b/polyfill/lib/instant.mjs @@ -119,23 +119,6 @@ export class Instant { valueOf() { ES.ValueOfThrows('Instant'); } - toZonedDateTime(item) { - if (!ES.IsTemporalInstant(this)) throw new TypeError('invalid receiver'); - if (ES.Type(item) !== 'Object') { - throw new TypeError('invalid argument in toZonedDateTime'); - } - const calendarLike = item.calendar; - if (calendarLike === undefined) { - throw new TypeError('missing calendar property in toZonedDateTime'); - } - const calendar = ES.ToTemporalCalendarSlotValue(calendarLike); - const temporalTimeZoneLike = item.timeZone; - if (temporalTimeZoneLike === undefined) { - throw new TypeError('missing timeZone property in toZonedDateTime'); - } - const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike); - return ES.CreateTemporalZonedDateTime(GetSlot(this, EPOCHNANOSECONDS), timeZone, calendar); - } toZonedDateTimeISO(timeZone) { if (!ES.IsTemporalInstant(this)) throw new TypeError('invalid receiver'); timeZone = ES.ToTemporalTimeZoneSlotValue(timeZone); diff --git a/polyfill/lib/now.mjs b/polyfill/lib/now.mjs index 0449bbe848..215b2a1c44 100644 --- a/polyfill/lib/now.mjs +++ b/polyfill/lib/now.mjs @@ -6,29 +6,15 @@ const instant = () => { const Instant = GetIntrinsic('%Temporal.Instant%'); return new Instant(ES.SystemUTCEpochNanoSeconds()); }; -const plainDateTime = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => { - const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike); - const calendar = ES.ToTemporalCalendarSlotValue(calendarLike); - const inst = instant(); - const timeZoneRec = new TimeZoneMethodRecord(timeZone, ['getOffsetNanosecondsFor']); - return ES.GetPlainDateTimeFor(timeZoneRec, inst, calendar); -}; const plainDateTimeISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => { const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike); const inst = instant(); const timeZoneRec = new TimeZoneMethodRecord(timeZone, ['getOffsetNanosecondsFor']); return ES.GetPlainDateTimeFor(timeZoneRec, inst, 'iso8601'); }; -const zonedDateTime = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => { - const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike); - const calendar = ES.ToTemporalCalendarSlotValue(calendarLike); - return ES.CreateTemporalZonedDateTime(ES.SystemUTCEpochNanoSeconds(), timeZone, calendar); -}; const zonedDateTimeISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => { - return zonedDateTime('iso8601', temporalTimeZoneLike); -}; -const plainDate = (calendarLike, temporalTimeZoneLike = ES.DefaultTimeZone()) => { - return ES.TemporalDateTimeToDate(plainDateTime(calendarLike, temporalTimeZoneLike)); + const timeZone = ES.ToTemporalTimeZoneSlotValue(temporalTimeZoneLike); + return ES.CreateTemporalZonedDateTime(ES.SystemUTCEpochNanoSeconds(), timeZone, 'iso8601'); }; const plainDateISO = (temporalTimeZoneLike = ES.DefaultTimeZone()) => { return ES.TemporalDateTimeToDate(plainDateTimeISO(temporalTimeZoneLike)); @@ -42,13 +28,10 @@ const timeZoneId = () => { export const Now = { instant, - plainDateTime, plainDateTimeISO, - plainDate, plainDateISO, plainTimeISO, timeZoneId, - zonedDateTime, zonedDateTimeISO }; Object.defineProperty(Now, Symbol.toStringTag, { diff --git a/spec/instant.html b/spec/instant.html index cf07a2845d..4b8470063d 100644 --- a/spec/instant.html +++ b/spec/instant.html @@ -327,28 +327,6 @@

Temporal.Instant.prototype.valueOf ( )

- -

Temporal.Instant.prototype.toZonedDateTime ( _item_ )

-

- This method performs the following steps when called: -

- - 1. Let _instant_ be the *this* value. - 1. Perform ? RequireInternalSlot(_instant_, [[InitializedTemporalInstant]]). - 1. If _item_ is not an Object, then - 1. Throw a *TypeError* exception. - 1. Let _calendarLike_ be ? Get(_item_, *"calendar"*). - 1. If _calendarLike_ is *undefined*, then - 1. Throw a *TypeError* exception. - 1. Let _calendar_ be ? ToTemporalCalendarSlotValue(_calendarLike_). - 1. Let _temporalTimeZoneLike_ be ? Get(_item_, *"timeZone"*). - 1. If _temporalTimeZoneLike_ is *undefined*, then - 1. Throw a *TypeError* exception. - 1. Let _timeZone_ be ? ToTemporalTimeZoneSlotValue(_temporalTimeZoneLike_). - 1. Return ! CreateTemporalZonedDateTime(_instant_.[[Nanoseconds]], _timeZone_, _calendar_). - -
-

Temporal.Instant.prototype.toZonedDateTimeISO ( _timeZone_ )

diff --git a/spec/temporal.html b/spec/temporal.html index a03da87f5b..ef0b49a135 100644 --- a/spec/temporal.html +++ b/spec/temporal.html @@ -119,16 +119,6 @@

Temporal.Now.instant ( )

- -

Temporal.Now.plainDateTime ( _calendarLike_ [ , _temporalTimeZoneLike_ ] )

-

- This function performs the following steps when called: -

- - 1. Return ? SystemDateTime(_temporalTimeZoneLike_, _calendarLike_). - -
-

Temporal.Now.plainDateTimeISO ( [ _temporalTimeZoneLike_ ] )

@@ -139,16 +129,6 @@

Temporal.Now.plainDateTimeISO ( [ _temporalTimeZoneLike_ ] )

- -

Temporal.Now.zonedDateTime ( _calendarLike_ [ , _temporalTimeZoneLike_ ] )

-

- This function performs the following steps when called: -

- - 1. Return ? SystemZonedDateTime(_temporalTimeZoneLike_, _calendarLike_). - -
-

Temporal.Now.zonedDateTimeISO ( [ _temporalTimeZoneLike_ ] )

@@ -159,17 +139,6 @@

Temporal.Now.zonedDateTimeISO ( [ _temporalTimeZoneLike_ ] )

- -

Temporal.Now.plainDate ( _calendarLike_ [ , _temporalTimeZoneLike_ ] )

-

- This function performs the following steps when called: -

- - 1. Let _dateTime_ be ? SystemDateTime(_temporalTimeZoneLike_, _calendarLike_). - 1. Return ! CreateTemporalDate(_dateTime_.[[ISOYear]], _dateTime_.[[ISOMonth]], _dateTime_.[[ISODay]], _dateTime_.[[Calendar]]). - -
-

Temporal.Now.plainDateISO ( [ _temporalTimeZoneLike_ ] )