From 9d834b22c41f3a0f749fbc8c9866756c6c406768 Mon Sep 17 00:00:00 2001 From: Philip Chimento Date: Mon, 18 Jan 2021 17:50:35 -0800 Subject: [PATCH 1/2] Clarify which time zones must be supported in a non-402 implementation The abstract operations dealing with the system time zone and the time zone names were part of 402, but here they need to move into 262, without obligating non-402 implementations to offer the full list of time zone names. Closes: #1292 --- spec/biblio.json | 25 +++++-------- spec/intl.html | 69 ++++++++++++++++++++++++++++++++++ spec/timezone.html | 93 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 15 deletions(-) diff --git a/spec/biblio.json b/spec/biblio.json index 364a44c02f..df0e0fb7e9 100644 --- a/spec/biblio.json +++ b/spec/biblio.json @@ -1,5 +1,10 @@ { "https://tc39.es/ecma262/": [ + { + "type": "op", + "aoid": "CodePointsToString", + "id": "sec-codepointstostring" + }, { "type": "op", "aoid": "NumberToBigInt", @@ -15,6 +20,11 @@ "aoid": "RequireInternalSlot", "id": "sec-requireinternalslot" }, + { + "type": "op", + "aoid": "StringToCodePoints", + "id": "sec-stringtocodepoints" + }, { "type": "op", "aoid": "ToBigInt", @@ -32,11 +42,6 @@ } ], "https://tc39.es/ecma402/": [ - { - "type": "op", - "aoid": "IsValidTimeZoneName", - "id": "sec-isvalidtimezonename" - }, { "type": "op", "aoid": "BasicFormatMatcher", @@ -52,16 +57,6 @@ "aoid": "CanonicalizeLocaleList", "id": "sec-canonicalizelocalelist" }, - { - "type": "op", - "aoid": "CanonicalizeTimeZoneName", - "id": "sec-canonicalizetimezonename" - }, - { - "type": "op", - "aoid": "DefaultTimeZone", - "id": "sec-defaulttimezone" - }, { "type": "op", "aoid": "FormatNumeric", diff --git a/spec/intl.html b/spec/intl.html index 6ceb6d7120..7b77b2d489 100644 --- a/spec/intl.html +++ b/spec/intl.html @@ -11,6 +11,75 @@

Amendments to the ECMAScript® 2021 Internationalization API Specification + +

Time Zone Names

+ + +

+ defines a set of abstract operations concerning the names of supported time zones. + This section introduces additional requirements on these operations for implementations. +

+ + +

+ The ECMAScript 2021 Internationalization API Specification identifies time zones using the Zone and Link names of the IANA Time Zone Database. Their canonical form is the corresponding Zone name in the casing used in the IANA Time Zone Database. +

+ +

+ All registered Zone and Link names are allowed. Implementations must recognize all such names, and use best available current and historical information about their offsets from UTC and their daylight saving time rules in calculations. However, the set of combinations of time zone name and language tag for which localized time zone names are available is implementation dependent. +

+ + +

IsValidTimeZoneName ( _timeZone_ )

+ + +

This definition supersedes the definition provided in .

+ +

+ The IsValidTimeZoneName abstract operation verifies that the _timeZone_ argument (which must be a String value) represents a valid Zone or Link name of the IANA Time Zone Database. +

+

+ The abstract operation returns true if _timeZone_, converted to upper case as described in , is equal to one of the Zone or Link names of the IANA Time Zone Database, converted to upper case as described in . It returns false otherwise. +

+ + + +

CanonicalizeTimeZoneName ( _timeZone_ )

+ + +

This definition supersedes the definition provided in .

+ +

+ The CanonicalizeTimeZoneName abstract operation returns the canonical and case-regularized form of the _timeZone_ argument (which must be a String value that is a valid time zone name as verified by the IsValidTimeZoneName abstract operation). + The following steps are taken: +

+ + + 1. Assert: Type(_timeZone_) is String. + 1. Assert: ! IsValidTimeZoneName(_timeZone_) is *true*. + 1. Let _ianaTimeZone_ be the Zone or Link name of the IANA Time Zone Database such that _timeZone_, converted to upper case as described in , is equal to _ianaTimeZone_, converted to upper case as described in . + 1. If _ianaTimeZone_ is a Link name, let _ianaTimeZone_ be the corresponding Zone name as specified in the *"backward"* file of the IANA Time Zone Database. + 1. If _ianaTimeZone_ is *"Etc/UTC"* or *"Etc/GMT"*, return *"UTC"*. + 1. Return _ianaTimeZone_. + + +

+ The Intl.DateTimeFormat constructor allows this time zone name; if the time zone is not specified, the host environment's current time zone is used. Implementations shall support UTC and the host environment's current time zone returned from DefaultTimeZone (if different from UTC) in formatting. +

+ + + +

DefaultTimeZone ( )

+ + +

This definition supersedes the definition provided in .

+ +

+ The DefaultTimeZone abstract operation returns a String value representing the valid () and canonicalized () time zone name for the host environment's current time zone. +

+ + +

Abstract Operations For DateTimeFormat Objects

diff --git a/spec/timezone.html b/spec/timezone.html index 55c28199a6..dd921d7f0f 100644 --- a/spec/timezone.html +++ b/spec/timezone.html @@ -5,6 +5,99 @@

Temporal.TimeZone Objects

A Temporal.TimeZone object is an immutable Object referencing a time zone.

+ +

Time Zone Names

+ + +

+ The normative intention of this section is that an implementation must support UTC and a local time zone, which may also be UTC, or a named time zone like `"Europe/London"`, or an offset time zone like `"+01:00"`; and that the local time zone must in any case be consistent with the time zone offsets that can be determined using `Date.prototype.getTimezoneOffset()`, `Date.prototype.toString()`, and `Date.prototype.toTimeString()`. + The exact formal definition of "local time zone" is still to be determined. +

+ + +

+ An ECMAScript implementation must support a number of built-in time zones. + At a minimum, implementations must support a built-in time zone named *"UTC"*. + If the return value of DefaultTimeZone is different from *"UTC"*, and does not satisfy the syntax of a |TimeZoneNumericUTCOffset|, then implementations must support that time zone as a built-in time zone as well. + In addition, implementations may support any number of other built-in time zones. +

+

+ Built-in time zones may be named time zones, represented by Strings for which IsValidTimeZoneName returns *true*. + They may also be offset time zones, represented by Strings that conform to the syntax of |TimeZoneNumericUTCOffset|. +

+ The `Temporal.TimeZone` constructor, when called with the name of a built-in time zone as the argument, will return a valid `Temporal.TimeZone` object. + When called with any other string, it will throw a *RangeError* exception. +

+

+ Implementations are encouraged to support the Zone and Link names of the IANA Time Zone Database, and to use the best available current and historical information about their offsets from UTC and their daylight saving time rules in calculations. +

+

+ An ECMAScript implementation that includes the ECMA-402 Internationalization API has additional requirements for the built-in time zones that must be supported, as specified in the ECMA-402 specification. +

+ + +

IsValidTimeZoneName ( _timeZone_ )

+ +

+ An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the IsValidTimeZoneName abstract operation as specified in the ECMA-402 specification. + If an ECMAScript implementation does not include the ECMA-402 API the following specification of the IsValidTimeZoneName abstract operation is used. +

+

+ The abstract operation IsValidTimeZoneName takes argument _timeZone_, a String value. It returns *true* if _timeZone_, converted to upper case, is equal to one of the built-in named time zone names, converted to upper case. + It returns *false* otherwise. +

+

+ Once IsValidTimeZoneName has returned *true* for a particular value of _timeZone_, for the lifetime of the surrounding agent, it may no longer return *false* for that value of _timeZone_, or for the value of CanonicalizeTimeZoneName(_timeZone_). +

+

The minimum implementation of IsValidTimeZoneName, supporting only the *"UTC"* time zone, performs the following steps when called: +

+ + + 1. Assert: Type(_timeZone_) is String. + 1. Let _tzText_ be ! StringToCodePoints(_timeZone_). + 1. Let _tzUpperText_ be the result of toUppercase(_tzText_), according to the Unicode Default Case Conversion algorithm. + 1. Let _tzUpper_ be ! CodePointsToString(_tzUpperText_). + 1. If _tzUpper_ and *"UTC"* are the same sequence of code points, return *true*. + 1. Return *false*. + + + + +

CanonicalizeTimeZoneName ( _timeZone_ )

+ +

+ An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the CanonicalizeTimeZoneName abstract operation as specified in the ECMA-402 specification. + If an ECMAScript implementation does not include the ECMA-402 API the following specification of the CanonicalizeTimeZoneName abstract operation is used. +

+

+ The abstract operation CanonicalizeTimeZoneName takes argument _timeZone_, a String value, and returns the canonical and case-regularized form of _timeZone_. +

+

+ CanonicalizeTimeZoneName may only be called with a _timeZone_ parameter that is a valid time zone name according to IsValidTimeZoneName. +

+

The minimum implementation of CanonicalizeTimeZoneName, supporting only the *"UTC"* time zone, performs the following steps when called: +

+ + + 1. Assert: Type(_timeZone_) is String. + 1. Assert: ! IsValidTimeZoneName(_timeZone_) is *true*. + 1. Return *"UTC"*. + + + + +

DefaultTimeZone ( )

+ +

+ An ECMAScript implementation that includes the ECMA-402 Internationalization API must implement the DefaultTimeZone abstract operation as specified in the ECMA-402 specification. + If an ECMAScript implementation does not include the ECMA-402 API the following specification of the DefaultTimeZone abstract operation is used. +

+

+ The DefaultTimeZone abstract operation returns a String value representing the host environment's current time zone, which is either a valid () and canonicalized () time zone name, or an offset conforming to the syntax of a |TimeZoneNumericUTCOffset|. +

+ + +

The Temporal.TimeZone Constructor

From c502fef32b65c12f1cceb30791ce26255ca23918 Mon Sep 17 00:00:00 2001 From: Ms2ger Date: Wed, 27 Jan 2021 11:23:47 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- spec/timezone.html | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec/timezone.html b/spec/timezone.html index dd921d7f0f..fc486223f0 100644 --- a/spec/timezone.html +++ b/spec/timezone.html @@ -10,7 +10,7 @@

Time Zone Names

- The normative intention of this section is that an implementation must support UTC and a local time zone, which may also be UTC, or a named time zone like `"Europe/London"`, or an offset time zone like `"+01:00"`; and that the local time zone must in any case be consistent with the time zone offsets that can be determined using `Date.prototype.getTimezoneOffset()`, `Date.prototype.toString()`, and `Date.prototype.toTimeString()`. + The normative intention of this section is that an implementation must support UTC and a local time zone, which may also be UTC, or a named time zone like *"Europe/London"*, or an offset time zone like *"+01:00"*; and that the local time zone must in any case be consistent with the time zone offsets that can be determined using `Date.prototype.getTimezoneOffset()`, `Date.prototype.toString()`, and `Date.prototype.toTimeString()`. The exact formal definition of "local time zone" is still to be determined.

@@ -22,8 +22,8 @@

Time Zone Names

In addition, implementations may support any number of other built-in time zones.

- Built-in time zones may be named time zones, represented by Strings for which IsValidTimeZoneName returns *true*. - They may also be offset time zones, represented by Strings that conform to the syntax of |TimeZoneNumericUTCOffset|. + Built-in time zones may be named time zones, represented by Strings for which IsValidTimeZoneName returns *true*. + They may also be offset time zones, represented by Strings that conform to the syntax of |TimeZoneNumericUTCOffset|.

The `Temporal.TimeZone` constructor, when called with the name of a built-in time zone as the argument, will return a valid `Temporal.TimeZone` object. When called with any other string, it will throw a *RangeError* exception. @@ -75,7 +75,8 @@

CanonicalizeTimeZoneName ( _timeZone_ )

CanonicalizeTimeZoneName may only be called with a _timeZone_ parameter that is a valid time zone name according to IsValidTimeZoneName.

-

The minimum implementation of CanonicalizeTimeZoneName, supporting only the *"UTC"* time zone, performs the following steps when called: +

+ The minimum implementation of CanonicalizeTimeZoneName, supporting only the *"UTC"* time zone, performs the following steps when called: