From ef56146366d65ba6421d19c534869550a28c2a4f Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Thu, 22 Aug 2024 13:53:52 -0700 Subject: [PATCH] fixup! Normative: Remove calendars and time zones --- docs/README.md | 6 ++-- docs/ambiguity.md | 8 ++--- docs/calendar-draft.md | 4 ++- docs/calendar-subclass.md | 2 +- docs/cookbook.md | 6 ++-- .../getInstantWithLocalTimeInZone.mjs | 5 ++-- docs/cookbook/nextWeeklyOccurrence.mjs | 2 +- docs/head.html.part | 2 -- docs/instant.md | 17 +++-------- docs/now.md | 23 +++++++------- docs/parse-draft.md | 30 ++++++++----------- docs/plaindate.md | 8 ++--- docs/plaindatetime.md | 4 +-- docs/plaintime.md | 2 -- docs/strings.md | 16 ++++------ docs/timezone-draft.md | 2 +- docs/zoneddatetime.md | 6 ++-- polyfill/index.d.ts | 16 ++++------ spec/calendar.html | 8 ++--- 19 files changed, 70 insertions(+), 97 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1435f951ef..a9d407b4f9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -53,7 +53,7 @@ See [Temporal.Now Documentation](./now.md) for detailed documentation. ### **Temporal.Instant** A `Temporal.Instant` represents a fixed point in time (called **"exact time"**), without regard to calendar or location, e.g. July 20, 1969, at 20:17 UTC. -For a human-readable local calendar date or clock time, use a `Temporal.TimeZone` and `Temporal.Calendar` to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`. +For a human-readable local calendar date or clock time, use a time zone and calendar identifier to obtain a `Temporal.ZonedDateTime` or `Temporal.PlainDateTime`. ```js const instant = Temporal.Instant.from('1969-07-20T20:17Z'); @@ -83,7 +83,7 @@ const zonedDateTime = Temporal.ZonedDateTime.from({ }); // => 1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles] ``` -As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.TimeZone`, `Temporal.Instant`, and `Temporal.PlainDateTime` (which includes `Temporal.Calendar`). +As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.Instant` and `Temporal.PlainDateTime` with a time zone identifier. See [Temporal.ZonedDateTime Documentation](./zoneddatetime.md) for detailed documentation. @@ -126,7 +126,7 @@ See [Temporal.PlainTime Documentation](./plaintime.md) for detailed documentatio A `Temporal.PlainDateTime` represents a calendar date and wall-clock time that does not carry time zone information, e.g. December 7th, 1995 at 3:00 PM (in the Gregorian calendar). -It can be converted to a `Temporal.ZonedDateTime` using a `Temporal.TimeZone`. +It can be converted to a `Temporal.ZonedDateTime` using time zone identifier. For use cases that require a time zone, especially using arithmetic or other derived values, consider using `Temporal.ZonedDateTime` instead because that type automatically adjusts for Daylight Saving Time. ```js diff --git a/docs/ambiguity.md b/docs/ambiguity.md index 21968eb6b5..f375f5de71 100644 --- a/docs/ambiguity.md +++ b/docs/ambiguity.md @@ -54,10 +54,9 @@ In Temporal: - The [`Temporal.Instant`](./instant.md) type represents exact time only. - The [`Temporal.PlainDateTime`](./plaindatetime.md) type represents calendar date and wall-clock time, as do other narrower types: [`Temporal.PlainDate`](./plaindate.md), [`Temporal.PlainTime`](./plaintime.md), [`Temporal.PlainYearMonth`](./plainyearmonth.md), and [`Temporal.PlainMonthDay`](./plainmonthday.md). - These types all carry a calendar system, which by default is `'iso8601'` (the ISO 8601 calendar) but can be overridden for other [calendars](./calendar.md) like `'islamic'` or `'japanese'`. -- The [`Temporal.TimeZone`](./timezone.md) represents a time zone function that converts between exact time and wall-clock time and vice-versa. - It also includes helper functions, e.g. to fetch the current time zone offset for a particular exact time. -- The [`Temporal.ZonedDateTime`](./zoneddatetime.md) type encapsulates all of the types above: an exact time (like a [`Temporal.Instant`](./instant.md)), its wall-clock equivalent (like a [`Temporal.PlainDateTime`](./plaindatetime.md)), and the time zone that links the two (like a [`Temporal.TimeZone`](./timezone.md)). + These types all carry a calendar system, which by default is `'iso8601'` (the ISO 8601 calendar) but can be overridden for other calendars like `'islamic'` or `'japanese'`. +- The time zone identifier represents a time zone function that converts between exact time and wall-clock time and vice-versa. +- The [`Temporal.ZonedDateTime`](./zoneddatetime.md) type encapsulates all of the types above: an exact time (like a [`Temporal.Instant`](./instant.md)), its wall-clock equivalent (like a [`Temporal.PlainDateTime`](./plaindatetime.md)), and the time zone that links the two. There are two ways to get a human-readable calendar date and clock time from a `Temporal` type that stores exact time. @@ -202,7 +201,6 @@ Methods where this option is present include: - [`Temporal.ZonedDateTime.from` with object argument](./zoneddatetime.md#from) - [`Temporal.ZonedDateTime.prototype.with`](./zoneddatetime.md#with) - [`Temporal.PlainDateTime.prototype.toZonedDateTime`](./plaindatetime.md#toZonedDateTime) -- [`Temporal.TimeZone.prototype.getInstantFor`](./timezone.md#getInstantFor). ## Examples: DST Disambiguation diff --git a/docs/calendar-draft.md b/docs/calendar-draft.md index b45c6bb763..f4b47a43ca 100644 --- a/docs/calendar-draft.md +++ b/docs/calendar-draft.md @@ -2,7 +2,9 @@ This doc describes a design for first-class support for non-Gregorian [calendars](https://en.wikipedia.org/wiki/Calendar) in Temporal. Although most of this document is based on Temporal.PlainDate, most of this applies to Temporal.PlainDateTime, Temporal.PlainYearMonth, Temporal.PlainMonthDay, and Temporal.PlainTime as well. -The approach described in this document was largely adopted, so this document has been superseded by the [`Temporal.Calendar` documentation](./calendar.md). +The approach described in this document was largely adopted, but most of +this document's information is nonetheless obsolete, due to removing the +Temporal.Calendar interface. ## Data Model diff --git a/docs/calendar-subclass.md b/docs/calendar-subclass.md index a53b7c6a2d..c92b75a718 100644 --- a/docs/calendar-subclass.md +++ b/docs/calendar-subclass.md @@ -1,6 +1,6 @@ # Subclass-based Temporal Calendar API -[calendar-draft.md](calendar.md) documents the design for calendar support in Temporal based on a single shared Temporal.PlainDate type with a Temporal.Calendar. This document discusses an alternative approach based on subclassing of Temporal.PlainDate types. This idea was not pursued further due to the drawbacks discussed in this document. +[calendar-draft.md](calendar-draft.md) documents the design for calendar support in Temporal based on a single shared Temporal.PlainDate type with a Temporal.Calendar. This document discusses an alternative approach based on subclassing of Temporal.PlainDate types. This idea was not pursued further due to the drawbacks discussed in this document. In this document, the _Temporal.Calendar Approach_ refers to the solution proposed in [calendar-draft.md](calendar-draft.md), and the _Temporal.PlainDate Subclassing Approach_ refers to the alternative, but eliminated, solution proposed in this document. diff --git a/docs/cookbook.md b/docs/cookbook.md index be35e4889c..67a09941ee 100644 --- a/docs/cookbook.md +++ b/docs/cookbook.md @@ -243,7 +243,7 @@ Similar to the previous recipe, calculate the exact times of a daily occurrence ### UTC offset for a zoned event, as a string -Use `Temporal.TimeZone.getOffsetStringFor()` or `Temporal.ZonedDateTime.offset` to map a `Temporal.Instant` instance and a time zone into the UTC offset at that exact time in that time zone, as a string. +Use `Temporal.Instant.toZonedDateTimeISO()` and `Temporal.ZonedDateTime.offset` to map a `Temporal.Instant` instance and a time zone into the UTC offset at that exact time in that time zone, as a string. ```javascript @@ -253,7 +253,7 @@ Use `Temporal.TimeZone.getOffsetStringFor()` or `Temporal.ZonedDateTime.offset` ### UTC offset for a zoned event, as a number of seconds -Similarly, use `Temporal.TimeZone.getOffsetNanosecondsFor()` to do the same thing for the offset as a number of seconds. +Similarly, use `Temporal.Instant.toZonedDateTimeISO()` and `Temporal.ZonedDateTime.offsetNanoseconds` to do the same thing for the offset as a number of seconds. (Remember to divide by 109 to convert nanoseconds to seconds.) @@ -264,7 +264,7 @@ Similarly, use `Temporal.TimeZone.getOffsetNanosecondsFor()` to do the same thin ### Offset between two time zones at an exact time -Also using `Temporal.TimeZone.getOffsetNanosecondsFor()`, we can map a `Temporal.Instant` instance and two time zones into the signed difference of UTC offsets between those time zones at that exact time, as a number of seconds. +Also using `Temporal.Instant.toZonedDateTimeISO()` and `Temporal.ZonedDateTime.offsetNanoseconds`, we can map a `Temporal.Instant` instance and two time zones into the signed difference of UTC offsets between those time zones at that exact time, as a number of seconds. ```javascript diff --git a/docs/cookbook/getInstantWithLocalTimeInZone.mjs b/docs/cookbook/getInstantWithLocalTimeInZone.mjs index 93cd7b79d9..2300ad63a5 100644 --- a/docs/cookbook/getInstantWithLocalTimeInZone.mjs +++ b/docs/cookbook/getInstantWithLocalTimeInZone.mjs @@ -1,7 +1,8 @@ /** * Get an exact time corresponding with a calendar date / wall-clock time in a - * particular time zone, the same as Temporal.TimeZone.getInstantFor() or - * Temporal.PlainDateTime.toInstant(), but with more disambiguation options. + * particular time zone, the same as + * Temporal.PlainDateTime.toZonedDateTimeISO(), but with more disambiguation + * options. * * As well as the default Temporal disambiguation options 'compatible', * 'earlier', 'later', and 'reject', there are additional options possible: diff --git a/docs/cookbook/nextWeeklyOccurrence.mjs b/docs/cookbook/nextWeeklyOccurrence.mjs index 3529aa5767..01f1c1558c 100644 --- a/docs/cookbook/nextWeeklyOccurrence.mjs +++ b/docs/cookbook/nextWeeklyOccurrence.mjs @@ -5,7 +5,7 @@ * @param {Temporal.ZonedDateTime} now - Starting point * @param {number} weekday - Weekday event occurs on (Monday=1, Sunday=7) * @param {Temporal.PlainTime} eventTime - Time event occurs at - * @param {Temporal.TimeZone} eventTimeZone - Time zone where event is planned + * @param {string} eventTimeZone - Time zone where event is planned * @returns {Temporal.ZonedDateTime} Local date and time of next occurrence */ function nextWeeklyOccurrence(now, weekday, eventTime, eventTimeZone) { diff --git a/docs/head.html.part b/docs/head.html.part index 4661549ac5..fdec28e0c7 100644 --- a/docs/head.html.part +++ b/docs/head.html.part @@ -18,13 +18,11 @@ header(x) { for (const type of [ Temporal.Instant, - Temporal.Calendar, Temporal.PlainDate, Temporal.PlainDateTime, Temporal.Duration, Temporal.PlainMonthDay, Temporal.PlainTime, - Temporal.TimeZone, Temporal.PlainYearMonth ]) { if (x instanceof type) return ['span', {}, `${x[Symbol.toStringTag]} <${x}>`]; diff --git a/docs/instant.md b/docs/instant.md index 8b1141de13..96f94ecdfd 100644 --- a/docs/instant.md +++ b/docs/instant.md @@ -7,7 +7,7 @@ A `Temporal.Instant` is a single point in time (called **"exact time"**), with a precision in nanoseconds. No time zone or calendar information is present. -To obtain local date/time units like year, month, day, or hour, a `Temporal.Instant` must be combined with a `Temporal.TimeZone` instance or a time zone string. +To obtain local date/time units like year, month, day, or hour, a `Temporal.Instant` must be combined with a time zone identifier. ```javascript @@ -20,11 +20,6 @@ instant.year; // => undefined zdtTokyo = instant.toZonedDateTimeISO('Asia/Tokyo'); // => 2020-01-01T03:30:00+09:00[Asia/Tokyo] zdtTokyo.year; // => 2020 zdtTokyo.toPlainDate(); // => 2020-01-01 - -tzLA = Temporal.TimeZone.from('America/Los_Angeles'); -zdtLA = instant.toZonedDateTimeISO(tzLA); // => 2019-12-31T10:30:00-08:00[America/Los_Angeles] -zdtLA.year; // => 2019 -zdtLA.toPlainDate(); // => 2019-12-31 ``` @@ -253,11 +248,7 @@ epochMicros = ns / 1000n + ((ns % 1000n) < 0n ? -1n : 0n); **Parameters:** -- `timeZone` (object or string): either - - a `Temporal.TimeZone` object - - an object implementing the [time zone protocol](./timezone.md#custom-time-zones) - - a string description of the time zone; either its IANA name or UTC offset - - an object with a `timeZone` property whose value is any of the above. +- `timeZone` (string or `Temporal.ZonedDateTime`): The time zone to use for the conversion. Can be the time zone's string identifier, or a `Temporal.ZonedDateTime` object, whose time zone will be used. **Returns:** a `Temporal.ZonedDateTime` object representing the calendar date, wall-clock time, time zone offset, and `timeZone`, according to the reckoning of the ISO 8601 calendar, at the exact time indicated by `instant`. @@ -573,7 +564,7 @@ one.equals(one); // => true - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - - `timeZone` (string or object): the time zone to express `instant` in, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string. + - `timeZone` (string or `Temporal.ZonedDateTime`): the time zone to express `instant` in, as a string identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. The default is to use UTC. - `fractionalSecondDigits` (number or string): How many digits to print after the decimal point in the output string. Valid values are `'auto'`, 0, 1, 2, 3, 4, 5, 6, 7, 8, or 9. @@ -604,7 +595,7 @@ Example usage: ```js instant = Temporal.Instant.fromEpochMilliseconds(1574074321816); instant.toString(); // => '2019-11-18T10:52:01.816Z' -instant.toString({ timeZone: Temporal.TimeZone.from('UTC') }); +instant.toString({ timeZone: 'UTC' }); // => '2019-11-18T10:52:01.816+00:00' instant.toString({ timeZone: 'Asia/Seoul' }); // => '2019-11-18T19:52:01.816+09:00' diff --git a/docs/now.md b/docs/now.md index b05710e605..198a18f572 100644 --- a/docs/now.md +++ b/docs/now.md @@ -17,7 +17,7 @@ The `Temporal.Now` object has several methods which give information about the c **Parameters:** -- `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. +- `timeZone` (optional string or `Temporal.ZonedDateTime`): The time zone to get the current date and time in, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. 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. @@ -82,23 +82,22 @@ This will usually be a named [IANA time zone](https://www.iana.org/time-zones), Example usage: ```js -// When is the next daylight saving change from now, in the current location? +// When is the first daylight saving change in 2025, in the current location? id = Temporal.Now.timeZoneId(); -now = Temporal.Now.instant(); -tz = Temporal.TimeZone.from(id); -nextTransition = tz.getNextTransition(now); -before = tz.getOffsetStringFor(nextTransition.subtract({ nanoseconds: 1 })); -after = tz.getOffsetStringFor(nextTransition.add({ nanoseconds: 1 })); -console.log(`At ${nextTransition.toZonedDateTimeISO(id)} the offset will change from UTC ${before} to ${after}`); +start2025 = Temporal.ZonedDateTime.from({ year: 2025, month: 1, day: 1, timeZone: id }); +nextTransition = start2025.getTimeZoneTransition('next'); +before = nextTransition.subtract({ nanoseconds: 1 }).offset; +after = nextTransition.add({ nanoseconds: 1 }).offset; +console.log(`At ${nextTransition} the offset will change from UTC ${before} to ${after}`); // example output: -// At 2021-03-14T03:00:00-07:00[America/Los_Angeles] the offset will change from UTC -08:00 to -07:00 +// At 2025-03-09T03:00:00-07:00[America/Los_Angeles] the offset will change from UTC -08:00 to -07:00 ``` ### Temporal.Now.**plainDateTimeISO**(_timeZone_: object | string = Temporal.Now.timeZone()) : Temporal.PlainDateTime **Parameters:** -- `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. +- `timeZone` (optional string or `Temporal.ZonedDateTime`): The time zone to get the current date and time in, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. 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 ISO 8601 calendar. @@ -134,7 +133,7 @@ Object.entries(financialCentres).forEach(([name, timeZone]) => { **Parameters:** -- `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. +- `timeZone` (optional string or `Temporal.ZonedDateTime`): The time zone to get the current date and time in, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. 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 ISO 8601 calendar. @@ -161,7 +160,7 @@ if (date.month === 1 && date.day === 1) console.log('New year!'); **Parameters:** -- `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. +- `timeZone` (optional string or `Temporal.ZonedDateTime`): The time zone to get the current date and time in, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. If not given, the current system time zone will be used. **Returns:** a `Temporal.PlainTime` object representing the current system time in the reckoning of the ISO 8601 calendar. diff --git a/docs/parse-draft.md b/docs/parse-draft.md index 65d4451559..aa08a1447f 100644 --- a/docs/parse-draft.md +++ b/docs/parse-draft.md @@ -177,7 +177,7 @@ Temporal.PlainDate.from(valid) // => 2001-09-08 Temporal.PlainYearMonth.from(valid) // => 2001-09 Temporal.PlainMonthDay.from(valid) // => 09-08 Temporal.PlainTime.from(valid) // => 18:46:40 -Temporal.TimeZone.from(valid) // => America/Vancouver +Temporal.ZonedDateTime.from(valid) // => 2001-09-08T18:46:40-07:00[America/Vancouver] Temporal.Instant.from(time24) // => 2020-04-08T07:00Z Temporal.PlainDateTime.from(time24) // => 2020-04-08T00:00 @@ -185,7 +185,7 @@ Temporal.PlainDate.from(time24) // => 2020-04-08 Temporal.PlainYearMonth.from(time24) // => 2020-04 Temporal.PlainMonthDay.from(time24) // => 04-08 Temporal.PlainTime.from(time24) // => 00:00 -Temporal.TimeZone.from(time24) // => America/Vancouver +Temporal.ZonedDateTime.from(time24) // => 2020-04-08T00:00-07:00[America/Vancouver] Temporal.Instant.from(invalidZone) // throws Temporal.{everything else}.from(invalidZone) // => doesn't throw @@ -198,7 +198,7 @@ Temporal.PlainDate.from(onlyDateTime) // => 2001-09-09 Temporal.PlainYearMonth.from(onlyDateTime) // => 2001-09 Temporal.PlainMonthDay.from(onlyDateTime) // => 09-09 Temporal.PlainTime.from(onlyDateTime) // => 01:46:40 -Temporal.TimeZone.from(onlyDateTime) // throws +Temporal.ZonedDateTime.from(onlyDateTime) // throws Temporal.Instant.from(onlyDate) // throws Temporal.PlainDateTime.from(onlyDate) // => 2001-09-09T00:00 @@ -206,7 +206,7 @@ Temporal.PlainDate.from(onlyDate) // => 2001-09-09 Temporal.PlainYearMonth.from(onlyDate) // => 2001-09 Temporal.PlainMonthDay.from(onlyDate) // => 09-09 Temporal.PlainTime.from(onlyDate) // => 00:00 -Temporal.TimeZone.from(onlyDate) // throws +Temporal.ZonedDateTime.from(onlyDate) // throws ``` **Use case 2:** Use Temporal.parse(), which returns an object with members containing the portions of the string exactly as they are spelled in the input, that are relevant for each Temporal type. @@ -247,7 +247,7 @@ Temporal.PlainDate.from(valid) // throws Temporal.PlainYearMonth.from(valid) // throws Temporal.PlainMonthDay.from(valid) // throws Temporal.PlainTime.from(valid) // throws -Temporal.TimeZone.from(valid) // throws +Temporal.ZonedDateTiem.from(valid) // throws parsed = Temporal.parse(valid); dateTime = Temporal.PlainDateTime.from(parsed.dateTime) // => 2001-09-08T18:46:40 @@ -255,7 +255,6 @@ dateTime.getDate() // => 2001-09-08 dateTime.getDate().getYearMonth() // => 2001-09 dateTime.getDate().getMonthDay() // => 09-08 dateTime.getTime() // => 18:46:40 -Temporal.TimeZone.from(parsed.timeZone) // => America/Vancouver Temporal.Instant.from(time24) // => 2020-04-08T07:00Z Temporal.PlainDateTime.from(time24) // throws @@ -263,7 +262,7 @@ Temporal.PlainDate.from(time24) // throws Temporal.PlainYearMonth.from(time24) // throws Temporal.PlainMonthDay.from(time24) // throws Temporal.PlainTime.from(time24) // throws -Temporal.TimeZone.from(time24) // throws +Temporal.ZonedDateTime.from(time24) // throws parsed = Temporal.parse(time24); dateTime = Temporal.PlainDateTime.from(parsed.dateTime); // => 2020-04-08T00:00 @@ -271,7 +270,6 @@ dateTime.getDate() // => 2020-04-08 dateTime.getDate().getYearMonth() // => 2020-04 dateTime.getDate().getMonthDay() // => 04-08 dateTime.getTime() // => 00:00 -Temporal.TimeZone.from(parsed.timeZone) // => America/Vancouver Temporal.*.from(invalidZone) // throws Temporal.*.from(invalidDate) // throws @@ -283,7 +281,7 @@ Temporal.PlainDate.from(onlyDateTime) // throws Temporal.PlainYearMonth.from(onlyDateTime) // throws Temporal.PlainMonthDay.from(onlyDateTime) // throws Temporal.PlainTime.from(onlyDateTime) // throws -Temporal.TimeZone.from(onlyDateTime) // throws +Temporal.ZonedDateTime.from(onlyDateTime) // throws dateTime.getDate() // 2001-09-09 dateTime.getDate().getYearMonth() // 2001-09 @@ -296,7 +294,7 @@ Temporal.PlainDate.from(onlyDate) // => 2001-09-09 Temporal.PlainYearMonth.from(onlyDate) // throws Temporal.PlainMonthDay.from(onlyDate) // throws Temporal.PlainTime.from(onlyDate) // throws -Temporal.TimeZone.from(onlyDate) // throws +Temporal.ZonedDateTime.from(onlyDate) // throws // No longer possible to get a DateTime with time defaulting to midnight, instead use: Temporal.PlainDate.from(onlyDate).withTime(Temporal.PlainTime.from('00:00')) // => 2001-09-09T00:00 ``` @@ -305,7 +303,7 @@ Temporal.PlainDate.from(onlyDate).withTime(Temporal.PlainTime.from('00:00')) // ## Proposal 3. Irrelevant parts ignored in from() -**Use case 1:** Only Temporal.Instant().from() and Temporal.PlainDateTime.from() still have ISO 8601 semantics. To process strings as ISO 8601 requires, use Absolute.from(), or Temporal.PlainDateTime.from() with Temporal.TimeZone.from(), depending on whether you need the time zone. +**Use case 1:** Only Temporal.Instant.from(), Temporal.ZonedDateTime.from() and Temporal.PlainDateTime.from() still have ISO 8601 semantics. To process strings as ISO 8601 requires, use one of those depending on whether you need the time zone. Temporal.parse() isn't necessary in this scenario. @@ -316,7 +314,7 @@ Temporal.PlainDate.from(valid) // => 2001-09-08 Temporal.PlainYearMonth.from(valid) // => 2001-09 Temporal.PlainMonthDay.from(valid) // => 09-08 Temporal.PlainTime.from(valid) // => 18:46:40 -Temporal.TimeZone.from(valid) // => America/Vancouver +Temporal.ZonedDateTime.from(valid) // => 2001-09-08T18:46:40-07:00[America/Vancouver] Temporal.Instant.from(time24) // => 2020-04-08T07:00Z dateTime = Temporal.PlainDateTime.from(time24); // => 2020-04-08T00:00 @@ -324,7 +322,7 @@ dateTime.getDate() // => 2020-04-08 dateTime.getDate().getYearMonth() // => 2020-04 dateTime.getDate().getMonthDay() // => 04-08 dateTime.getTime() // => 00:00 -Temporal.TimeZone.from(time24) // => America/Vancouver +Temporal.ZonedDateTime.from(time24) // => 2020-04-08T00:00-07:00[America/Vancouver] // Depending on which type you pass them to, it may be difficult to // reject strings with mismatching time zones or invalid ISO 8601: @@ -339,7 +337,7 @@ Temporal.PlainDate.from(onlyDateTime) // => 2001-09-09 Temporal.PlainYearMonth.from(onlyDateTime) // => 2001-09 Temporal.PlainMonthDay.from(onlyDateTime) // => 09-09 Temporal.PlainTime.from(onlyDateTime) // => 01:46:40 -Temporal.TimeZone.from(onlyDateTime) // throws +Temporal.ZonedDateTime.from(onlyDateTime) // throws Temporal.Instant.from(onlyDate) // throws Temporal.PlainDateTime.from(onlyDate) // => 2001-09-09T00:00 @@ -347,7 +345,7 @@ Temporal.PlainDate.from(onlyDate) // => 2001-09-09 Temporal.PlainYearMonth.from(onlyDate) // => 2001-09 Temporal.PlainMonthDay.from(onlyDate) // => 09-09 Temporal.PlainTime.from(onlyDate) // => 00:00 -Temporal.TimeZone.from(onlyDate) // throws +Temporal.ZonedDateTime.from(onlyDate) // throws ``` **Use case 2:** Now from() is more useful for this case. @@ -363,12 +361,10 @@ Temporal.PlainDate.from(invalidZone); // => 2001-09-08 Temporal.PlainYearMonth.from(invalidZone); // => 2001-09 Temporal.PlainMonthDay.from(invalidZone); // => 09-08 Temporal.PlainTime.from(invalidZone); // => 18:46:40 -Temporal.TimeZone.from(invalidZone); // => America/Vancouver Temporal.PlainDate.from(invalidTime); // => 2001-09-08 Temporal.PlainYearMonth.from(invalidTime); // => 2001-09 Temporal.PlainMonthDay.from(invalidTime); // => 09-08 -Temporal.TimeZone.from(invalidTime); // => America/Vancouver // etc. ``` diff --git a/docs/plaindate.md b/docs/plaindate.md index 8ae2542188..cb6453e269 100644 --- a/docs/plaindate.md +++ b/docs/plaindate.md @@ -10,7 +10,7 @@ A `Temporal.PlainDate` represents a calendar date. For example, it could be used to represent an event on a calendar which happens during the whole day no matter which time zone it's happening in. `Temporal.PlainDate` refers to the whole of a specific day; if you need to refer to a specific time on that day, use `Temporal.PlainDateTime`. -A `Temporal.PlainDate` can be converted into a `Temporal.ZonedDateTime` by combining it with a `Temporal.PlainTime` and `Temporal.TimeZone` using the `toZonedDateTime()` method. +A `Temporal.PlainDate` can be converted into a `Temporal.ZonedDateTime` by combining it with a `Temporal.PlainTime` and time zone identifier using the `toZonedDateTime()` method. It can also be combined with a `Temporal.PlainTime` to yield a "zoneless" `Temporal.PlainDateTime` using the `toPlainDateTime()` method. `Temporal.PlainYearMonth` and `Temporal.PlainMonthDay` carry less information than `Temporal.PlainDate` and should be used when complete information is not required. @@ -562,11 +562,11 @@ earlier.toPlainDateTime(noon).until(later.toPlainDateTime(noon), { largestUnit: newyear = Temporal.PlainDate.from('2020-01-01'); newyear.until('2020-01-15', { smallestUnit: 'month', roundingMode: 'halfExpand' }); - // => PT0S + // => PT0S newyear.until('2020-01-16', { smallestUnit: 'month', roundingMode: 'halfExpand' }); // => PT0S (mid-month dates rounded down to match `Temporal.PlainDateTime` behavior) newyear.until('2020-01-17', { smallestUnit: 'month', roundingMode: 'halfExpand' }); - // => PT1M + // => PT1M ``` @@ -730,7 +730,7 @@ Use `Temporal.PlainDate.compare()` for this, or `date.equals()` for equality. - `item` (object): an object with properties to be added to `date`. The following properties are recognized: - `plainTime` (optional `Temporal.PlainTime` or value convertible to one): a time of day on `date` used to merge into a `Temporal.ZonedDateTime`. - - `timeZone` (required `Temporal.TimeZone` or value convertible to one, or an object implementing the [time zone protocol](./timezone.md#custom-time-zones)): the time zone in which to interpret `date` and `plainTime`. + - `timeZone` (required string or `Temporal.ZonedDateTime`): the time zone in which to interpret `date` and `plainTime`, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. **Returns:** a `Temporal.ZonedDateTime` object that represents the wall-clock time `plainTime` on the calendar date `date` projected into `timeZone`. diff --git a/docs/plaindatetime.md b/docs/plaindatetime.md index f0279ac132..5e7bb8e1d8 100644 --- a/docs/plaindatetime.md +++ b/docs/plaindatetime.md @@ -8,7 +8,7 @@ A `Temporal.PlainDateTime` represents a calendar date and wall-clock time, with a precision in nanoseconds, and without any time zone. For use cases that require a time zone, especially using arithmetic or other derived values, consider using [`Temporal.ZonedDateTime`](./zoneddatetime.md) instead because that type automatically adjusts for Daylight Saving Time. -A `Temporal.PlainDateTime` can be converted to a `Temporal.ZonedDateTime` using a `Temporal.TimeZone`. +A `Temporal.PlainDateTime` can be converted to a `Temporal.ZonedDateTime` using a time zone identifier. `Temporal.PlainDate`, `Temporal.PlainTime`, `Temporal.PlainYearMonth`, and `Temporal.PlainMonthDay` all carry less information and should be used when complete information is not required. @@ -950,7 +950,7 @@ Use `Temporal.PlainDateTime.compare()` for this, or `datetime.equals()` for equa **Parameters:** -- `timeZone` (optional string or object): The time zone in which to interpret `dateTime`, as a `Temporal.TimeZone` object, an object implementing the [time zone protocol](./timezone.md#custom-time-zones), or a string. + - `timeZone` (string or `Temporal.ZonedDateTime`): the time zone in which to interpret `dateTime`, as a time zone identifier, or a `Temporal.ZonedDateTime` object whose time zone will be used. - `options` (optional object): An object with properties representing options for the operation. The following options are recognized: - `disambiguation` (string): How to disambiguate if the date and time given by `dateTime` does not exist in the time zone, or exists more than once. diff --git a/docs/plaintime.md b/docs/plaintime.md index ac66aabf34..39ca0e2948 100644 --- a/docs/plaintime.md +++ b/docs/plaintime.md @@ -10,8 +10,6 @@ A `Temporal.PlainTime` represents a wall-clock time, with a precision in nanosec For example, it could be used to represent an event that happens daily at a certain time, no matter what time zone. `Temporal.PlainTime` refers to a time with no associated calendar date; if you need to refer to a specific time on a specific day, use `Temporal.PlainDateTime`. -A `Temporal.PlainTime` can be converted into a `Temporal.ZonedDateTime` by combining it with a `Temporal.PlainDate` and `Temporal.TimeZone` using the `toZonedDateTime()` method. -It can also be combined with a `Temporal.PlainDate` to yield a "zoneless" `Temporal.PlainDateTime` using the `toPlainDateTime()` method. ## Constructor diff --git a/docs/strings.md b/docs/strings.md index 44112394b5..20306ab8a2 100644 --- a/docs/strings.md +++ b/docs/strings.md @@ -121,7 +121,7 @@ The time zone ID itself follows the rules of the time zone database, usually cal > Do not use digits, as that might create an ambiguity with POSIX TZ strings. > A file name component must not exceed 14 characters or start with `'-'`. -For more about TZDB, see the [`Temporal.TimeZone` documentation](timezone.md) or the [TZDB documentation](https://htmlpreview.github.io/?https://github.com/eggert/tz/blob/master/theory.html). +For more about TZDB, see the [TZDB documentation](https://htmlpreview.github.io/?https://github.com/eggert/tz/blob/master/theory.html). ### Calendar systems @@ -234,10 +234,6 @@ To determine the `Temporal` class that should be used to parse a string, it's im Other than the few use cases detailed in the [`Temporal.PlainDateTime` documentation](plaindatetime.html), most of the time it's better to use a different type. - `Temporal.Duration` represents a period of time. Its data model is a number of years, months, days, hours, minutes, seconds, milliseconds, microseconds, and nanoseconds. -- `Temporal.TimeZone` represents a time zone in the [IANA time zone database](https://www.iana.org/time-zones), or (rarely) a numeric offset time zone. - Its data model is the identifier of the time zone, like `"Asia/Tokyo"` or `"+06:00"`. -- `Temporal.Calendar` represents a calendar like Hebrew, Chinese, or the default ISO 8601 calendar. - Its data model is the ID of the calendar, e.g. `"iso8601"` or `"hebrew"`. #### Is there one function I can call to parse any string into the appropriate `Temporal` type? @@ -302,14 +298,14 @@ If timezone-aware results are not needed, then use another type like `Temporal.I Timestamp strings like `2022-02-28T03:06:00+02:00` or `2022-02-28T03:06:00Z` are normally parsed by `Temporal.Instant`. Because the data model of `Temporal.Instant` is limited to the number of nanoseconds since January 1, 1970 UTC), the offset is not stored when parsing a string into a `Temporal.Instant`. -If the offset of the string is needed, use `Temporal.TimeZone.from`: +If the offset of the string is needed, use `Temporal.Instant.toZonedDateTime()` with the string as the time zone: ```javascript s = `2022-02-28T03:06:00Z`; -offset = Temporal.TimeZone.from(s); // => UTC +offset = Temporal.Instant.from(s).toZonedDateTimeISO(s).timeZoneId; // => UTC s = `2022-02-28T03:06:00+02:00`; -offset = Temporal.TimeZone.from(s); // => +02:00 +offset = Temporal.Instant.from(s).toZonedDateTimeISO(s).timeZoneId; // => +02:00 ``` #### Why can't I parse a UTC "Z" string using `Temporal.PlainXxx` types? @@ -345,7 +341,7 @@ zdt = Temporal.Instant.from(s).toZonedDateTimeISO(s).toPlainDate(); // => 2022-0 Yes! Temporal parsing methods accept strings that have more information than the type needs. Information not needed for that type's data model is ignored. -This works for all `Temporal.PlainXxx` types, `Temporal.Instant`, and even `Temporal.TimeZone` and `Temporal.Calendar`. +This works for all `Temporal.PlainXxx` types, `Temporal.ZonedDateTime`, and `Temporal.Instant`. ```javascript s = '2022-02-28T11:06:00.092121729+08:00[Asia/Shanghai]'; @@ -356,8 +352,6 @@ Temporal.PlainDateTime.from(s); // => 2022-02-28T11:06:00.092121729 Temporal.PlainYearMonth.from(s); // => 2022-02 Temporal.PlainMonthDay.from(s); // => 02-28 Temporal.Instant.from(s); // => 2022-02-28T03:06:00.092121729Z -Temporal.TimeZone.from(s); // => Asia/Shanghai -Temporal.Calendar.from(s); // => iso8601 (the default calendar when parsing strings) ``` diff --git a/docs/timezone-draft.md b/docs/timezone-draft.md index 6c215dd452..bc67a539d1 100644 --- a/docs/timezone-draft.md +++ b/docs/timezone-draft.md @@ -1,4 +1,4 @@ -This document has been superseded by the documentation of [Temporal.TimeZone](./timezone.md). +This document is obsolete. It's kept here for future reference if needed. # Draft design of custom time zone API diff --git a/docs/zoneddatetime.md b/docs/zoneddatetime.md index d15b66b19d..62d6556f83 100644 --- a/docs/zoneddatetime.md +++ b/docs/zoneddatetime.md @@ -6,7 +6,7 @@ A `Temporal.ZonedDateTime` is a timezone-aware, calendar-aware date/time type that represents a real event that has happened (or will happen) at a particular instant from the perspective of a particular region on Earth. -As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.TimeZone`, `Temporal.Instant`, and `Temporal.PlainDateTime` (which includes `Temporal.Calendar`). +As the broadest `Temporal` type, `Temporal.ZonedDateTime` can be considered a combination of `Temporal.Instant`, `Temporal.PlainDateTime`, and a time zone. As the only `Temporal` type that persists a time zone, `Temporal.ZonedDateTime` is optimized for use cases that require a time zone: @@ -75,7 +75,7 @@ However, ECMAScript implementations generally do not treat those as equivalent. **Parameters:** - `epochNanoseconds` (bigint): A number of nanoseconds. -- `timeZone` (string, `Temporal.TimeZone` instance, or plain object): The time zone in which the event takes place. +- `timeZone` (string): The time zone in which the event takes place. - `calendar` (optional string): Calendar used to interpret dates and times. **Returns:** a new `Temporal.ZonedDateTime` object. @@ -1026,7 +1026,7 @@ To calculate the difference between calendar dates only, use `.toPlainDate().unt To calculate the difference between clock times only, use `.toPlainTime().until(other.toPlainTime())`. If the other `Temporal.ZonedDateTime` is in a different time zone, then the same days can be different lengths in each time zone, e.g. if only one of them observes DST. -Therefore, a `RangeError` will be thrown if `largestUnit` is `'day'` or larger and the two instances' time zones are not equal, using the same equality algorithm as `Temporal.TimeZone.prototype.equals`. +Therefore, a `RangeError` will be thrown if `largestUnit` is `'day'` or larger and the two instances' time zones are not equal, using the same equality algorithm as `Temporal.ZonedDateTime.prototype.equals`. To work around this same-time-zone requirement, transform one of the instances to the other's time zone using `.withTimeZone(other.timeZone)` and then calculate the same-timezone difference. Because of the complexity and ambiguity involved in cross-timezone calculations involving days or larger units, `'hour'` is the default for `largestUnit`. diff --git a/polyfill/index.d.ts b/polyfill/index.d.ts index 278f03e9a2..688be0e148 100644 --- a/polyfill/index.d.ts +++ b/polyfill/index.d.ts @@ -608,7 +608,7 @@ export namespace Temporal { } /** - * Any of these types can be passed to Temporal methods instead of a Temporal.Calendar. + * Any of these types can be passed to Temporal methods instead of a calendar ID. * */ export type CalendarLike = string | ZonedDateTime | PlainDateTime | PlainDate | PlainYearMonth | PlainMonthDay; @@ -891,7 +891,7 @@ export namespace Temporal { } /** - * Any of these types can be passed to Temporal methods instead of a Temporal.TimeZone. + * Any of these types can be passed to Temporal methods instead of a time zone ID. * */ export type TimeZoneLike = string | ZonedDateTime; @@ -1075,8 +1075,7 @@ export namespace Temporal { * * @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 + * string (e.g. `'Europe/London'`). If omitted, the environment's * current time zone will be used. */ zonedDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.ZonedDateTime; @@ -1092,8 +1091,7 @@ export namespace Temporal { * * @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 + * string (e.g. `'Europe/London'`). If omitted, the environment's * current time zone will be used. */ plainDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainDateTime; @@ -1104,8 +1102,7 @@ export namespace Temporal { * * @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 + * string (e.g. `'Europe/London'`). If omitted, the environment's * current time zone will be used. */ plainDateISO: (tzLike?: TimeZoneLike) => Temporal.PlainDate; @@ -1115,8 +1112,7 @@ export namespace Temporal { * * @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 + * string (e.g. `'Europe/London'`). If omitted, the environment's * current time zone will be used. */ plainTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainTime; diff --git a/spec/calendar.html b/spec/calendar.html index 6998ae6bd4..54b781876a 100644 --- a/spec/calendar.html +++ b/spec/calendar.html @@ -47,7 +47,7 @@

-

Abstract Operations for Temporal.Calendar Objects

+

Abstract Operations

Calendar Date Records

@@ -1040,7 +1040,7 @@

description
-
It implements the calendar-specific logic in the `Temporal.Calendar.prototype.dateFromFields` method for the ISO 8601 calendar.
+
It performs the conversion operation of a Calendar Fields Record to an ISO Date Record for the ISO 8601 calendar, as CalendarDateFromFields does for other calendars.
1. Let _year_ be _fields_.[[Year]]. @@ -1062,7 +1062,7 @@

description
-
It implements the calendar-specific logic in the `Temporal.Calendar.prototype.yearMonthFromFields` method for the ISO 8601 calendar.
+
It performs the conversion operation of a Calendar Fields Record to an ISO Date Record for the ISO 8601 calendar in the context of Temporal.PlainYearMonth, as CalendarYearMonthFromFields does for other calendars.
1. Let _year_ be _fields_.[[Year]]. @@ -1087,7 +1087,7 @@

description
-
It implements the calendar-specific logic in the `Temporal.Calendar.prototype.monthDayFromFields` method for the ISO 8601 calendar.
+
It performs the conversion operation of a Calendar Fields Record to an ISO Date Record for the ISO 8601 calendar in the context of Temporal.PlainMonthDay, as CalendarMonthDayFromFields does for other calendars.
1. Let _month_ be _fields_.[[Month]].