Skip to content

Commit

Permalink
Rename "canonical" to "primary" tz identifier term
Browse files Browse the repository at this point in the history 
We were concerned that "canonical time zone identifier" is too strong,
and that a less-prescriptive term may work better. This is broken out
into a separate commit in case we (or others on TC39) want to revert to
the previous "canonical" term.
  • Loading branch information
@justingrant
justingrant committed Apr 1, 2023
1 parent 4124ca3 commit 724a844
Showing 1 changed file with 23 additions and 23 deletions.
46 changes: 23 additions & 23 deletions spec.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32101,11 +32101,11 @@ <h1>Time Zone Identifiers</h1>
ECMAScript identifies time zones using the Zone and Link names of the IANA Time Zone Database <a href="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.
These names are called <dfn variants="time zone identifier">time zone identifiers</dfn>, and are Strings composed entirely of characters from the Basic Latin Unicode block.
Time zone identifiers are case-insensitive and so are compared using ASCII case-insensitive comparisons, but time zone identifiers returned by ECMAScript built-in objects always use the casing found in the IANA Time Zone Database.
A <dfn id="canonical-time-zone-identifier" variants="canonical time zone identifiers">canonical time zone identifier</dfn> is a Zone name, and a <dfn variants="non-canonical time zone identifiers">non-canonical time zone identifier</dfn> is a Link name, respectively, in the IANA Time Zone Database except as specifically overridden by AvailableTimeZoneIdentifiers.
A <dfn id="primary-time-zone-identifier" variants="primary time zone identifiers">primary time zone identifier</dfn> is a Zone name, and a <dfn variants="non-primary time zone identifiers">non-primary time zone identifier</dfn> is a Link name, respectively, in the IANA Time Zone Database except as specifically overridden by AvailableTimeZoneIdentifiers.
The set of Zone and Link identifiers that are supported by an ECMAScript implementation are called available time zone identifiers.
</p>

<p>In the IANA Time Zone Database, the UTC time zone is represented by the Zone *"Etc/UTC"*, but for backwards compatibility and brevity reasons, *"UTC"* is the canonical identifier used for this time zone in ECMAScript, while *"Etc/UTC"*, *"GMT"*, and *"Etc/GMT"* are all non-canonical identifiers that resolve to *"UTC"*.</p>
<p>In the IANA Time Zone Database, the UTC time zone is represented by the Zone *"Etc/UTC"*, but for backwards compatibility and brevity reasons, *"UTC"* is the primary identifier used for this time zone in ECMAScript, while *"Etc/UTC"*, *"GMT"*, and *"Etc/GMT"* are all non-primary identifiers that resolve to *"UTC"*.</p>

<p>
<dfn id="time-zone-aware">Time zone aware</dfn> ECMAScript implementations support *"UTC"* and local political rules of time zones represented by all other Zone and Link names (and <strong>only</strong> such names) from the IANA Time Zone Database.
Expand All @@ -32114,7 +32114,7 @@ <h1>Time Zone Identifiers</h1>
Fruthermore, even non-time zone aware implementations that do not support the entire IANA Time Zone Database are still recommended to use IANA Time Zone Database identifiers to represent time zones.
</p>

<p>ECMAScript implementations that do not include local political rules for any time zones must support at least one available time zone identifier, *"UTC"*, which must be canonical.</p>
<p>ECMAScript implementations that do not include local political rules for any time zones must support at least one available time zone identifier, *"UTC"*, which must be primary.</p>

<p>
Time zone identifiers in the IANA Time Zone Database can change over time.
Expand All @@ -32124,21 +32124,21 @@ <h1>Time Zone Identifiers</h1>

<p>
The IANA Time Zone Database is typically updated between five and ten times per year, so it is recommended to use the best available current and historical time zone information.
This information includes which identifiers are supported, the canonical time zone identifier associated with any identifier, and the UTC offsets and transitions associated with any Zone.
This information includes which identifiers are supported, the primary time zone identifier associated with any identifier, and the UTC offsets and transitions associated with any Zone.
</p>

<p>
When time zone information is updated, it is recommended that implementations maintain a fully consistent copy of the IANA Time Zone Database for the lifetime of each agent.
If implementations do revise time zone information during the lifetime of an agent, then it is recommended that changes to time zone data, including which identifiers are supported, the canonical time zone identifier associated with any identifier, and the UTC offsets and transitions associated with any Zone, can be incorporated into an agent only if they are consistent with results already observed by all ECMAScript code that can reach that agent.
For example, it is recommended that a new identifier can be incorporated only if no ECMAScript code has already tried to use it, and it is recommended that replacement of a canonical identifier with a Link to a different identifier can only be incorporated only if no ECMAScript code has already resulted in resolving it as canonical.
If implementations do revise time zone information during the lifetime of an agent, then it is recommended that changes to time zone data, including which identifiers are supported, the primary time zone identifier associated with any identifier, and the UTC offsets and transitions associated with any Zone, can be incorporated into an agent only if they are consistent with results already observed by all ECMAScript code that can reach that agent.
For example, it is recommended that a new identifier can be incorporated only if no ECMAScript code has already tried to use it, and it is recommended that replacement of a primary identifier with a Link to a different identifier can only be incorporated only if no ECMAScript code has already resulted in resolving it as primary.
The complexity of maintaining such invariants is why it is recommended that implementations maintain a fully consistent copy of the IANA Time Zone Database for the lifetime of each agent.
</p>

<p>
The IANA Time Zone Database offers build options that affect which time zone identifiers are canonical.
It is recommended that ECMAScript implementations <strong>should not</strong> determine which identifiers are canonical and non-canonical using the data generated by the default build options of the IANA Time Zone Database, because those default build options merge geographically unrelated time zones together, such as *"Atlantic/Reykjavik"* as a Link to the Zone *"Africa/Abidjan"*.
The IANA Time Zone Database offers build options that affect which time zone identifiers are primary.
It is recommended that ECMAScript implementations <strong>should not</strong> determine which identifiers are primary and non-primary using the data generated by the default build options of the IANA Time Zone Database, because those default build options merge geographically unrelated time zones together, such as *"Atlantic/Reykjavik"* as a Link to the Zone *"Africa/Abidjan"*.
These merges can be problematic because geographically and politically distinct locations, especially across country boundaries, are more likely to introduce divergent time zone rules in a future version of the IANA Time Zone Database.
Therefore, it is recommended that all identifiers listed in the IANA Time Zone Database's <code>zone.tab</code> file (which lists at least one Link or Zone name for each <a href="https://www.iso.org/glossary-for-iso-3166.html">ISO 3166-1 Alpha-2</a> country code in the IANA Time Zone Database) should be canonical identifiers.
Therefore, it is recommended that all identifiers listed in the IANA Time Zone Database's <code>zone.tab</code> file (which lists at least one Link or Zone name for each <a href="https://www.iso.org/glossary-for-iso-3166.html">ISO 3166-1 Alpha-2</a> country code in the IANA Time Zone Database) should be primary identifiers.
One way to achieve this result is to build the IANA Time Zone Database with the <code>PACKRATDATA=backzone PACKRATLIST=zone.tab</code> build options.
</p>
</emu-clause>
Expand Down Expand Up @@ -32203,13 +32203,13 @@ <h1>
</emu-clause>

<emu-clause id="sec-availabletimezoneidentifiers" type="implementation-defined abstract operation">
<h1>AvailableTimeZoneIdentifiers ( ): a List of Records with fields [[Identifier]] (a String value that is a time zone identifier) and [[CanonicalIdentifier]] (a String value that is a canonical time zone identifier)</h1>
<h1>AvailableTimeZoneIdentifiers ( ): a List of Records with fields [[Identifier]] (a String value that is a time zone identifier) and [[PrimaryIdentifier]] (a String value that is a primary time zone identifier)</h1>
<dl class="header">
<dt>description</dt>
<dd>
It returns a List of Records describing all available time zone identifiers in this implementation, as well as the canonical time zone identifier corresponding to each available identifier.
It returns a List of Records describing all available time zone identifiers in this implementation, as well as the primary time zone identifier corresponding to each available identifier.
The List is sorted by [[Identifier]].
If an identifier is <emu-xref href="#canonical-time-zone-identifier">canonical</emu-xref>, then [[Identifier]] will be [[CanonicalIdentifier]].
If an identifier is <emu-xref href="#primary-time-zone-identifier">primary</emu-xref>, then [[Identifier]] will be [[PrimaryIdentifier]].
</dd>
</dl>

Expand All @@ -32220,14 +32220,14 @@ <h1>AvailableTimeZoneIdentifiers ( ): a List of Records with fields [[Identifier
1. [declared="comparefn"] Sort _identifiers_ in order as if an Array of the same values had been sorted using %Array.prototype.sort% using *undefined* as _comparefn_.
1. Let _result_ be an empty List.
1. For each element _identifier_ of _identifiers_, do
1. Let _canonical_ be _identifier_.
1. If _identifier_ is a non-canonical time zone identifier and _identifier_ is not *"UTC"*, then
1. Set _canonical_ to the name of the canonical time zone identifier that _identifier_ resolves to in the IANA Time Zone Database.
1. NOTE: If _identifier_ resolves to another non-canonical time zone identifier, then the implementation must continue resolution of the entire chain until its terminal canonical time zone identifier.
1. If _canonical_ is one of *"Etc/UTC"*, *"Etc/GMT"*, or *"GMT"*, set _canonical_ to *"UTC"*.
1. Let _record_ be the Record { [[Identifier]]: _identifier_, [[CanonicalIdentifier]]: _canonical_ }.
1. Let _primary_ be _identifier_.
1. If _identifier_ is a non-primary time zone identifier and _identifier_ is not *"UTC"*, then
1. Set _primary_ to the name of the primary time zone identifier that _identifier_ resolves to in the IANA Time Zone Database.
1. NOTE: If _identifier_ resolves to another non-primary time zone identifier, then the implementation must continue resolution of the entire chain until its terminal primary time zone identifier.
1. If _primary_ is one of *"Etc/UTC"*, *"Etc/GMT"*, or *"GMT"*, set _primary_ to *"UTC"*.
1. Let _record_ be the Record { [[Identifier]]: _identifier_, [[PrimaryIdentifier]]: _primary_ }.
1. Append _record_ to the end of _result_.
1. Assert: One element of _result_ is { [[Identifier]]: *"UTC"*, [[CanonicalIdentifier]]: *"UTC"* }.
1. Assert: One element of _result_ is { [[Identifier]]: *"UTC"*, [[PrimaryIdentifier]]: *"UTC"* }.
1. Return _result_.
</emu-alg>

Expand All @@ -32243,7 +32243,7 @@ <h1>HostTimeZoneIdentifier ( ): a String</h1>
<dl class="header">
<dt>description</dt>
<dd>
It returns a String value representing the host environment's current time zone, which is either a String representing a UTC offset for which IsTimeZoneOffsetString returns *true*, or a canonical time zone identifier.
It returns a String value representing the host environment's current time zone, which is either a String representing a UTC offset for which IsTimeZoneOffsetString returns *true*, or a primary time zone identifier.
</dd>
</dl>

Expand All @@ -32252,7 +32252,7 @@ <h1>HostTimeZoneIdentifier ( ): a String</h1>
1. Let _hostTimeZoneString_ be the string representing the host environment's current time zone, either a time zone identifier or a UTC offset string.
1. If IsTimeZoneOffsetString(_hostTimeZoneString_) is *true*, return _hostTimeZoneString_.
1. Assert: GetAvailableTimeZoneIdentifier(_hostTimeZoneString_) is not ~empty~.
1. Assert: GetAvailableTimeZoneIdentifier(_hostTimeZoneString_).[[Identifier]] is GetAvailableTimeZoneIdentifier(_hostTimeZoneString_).[[CanonicalIdentifier]].
1. Assert: GetAvailableTimeZoneIdentifier(_hostTimeZoneString_).[[Identifier]] is GetAvailableTimeZoneIdentifier(_hostTimeZoneString_).[[PrimaryIdentifier]].
1. Return _hostTimeZoneString_.
</emu-alg>

Expand All @@ -32269,7 +32269,7 @@ <h1>HostTimeZoneIdentifier ( ): a String</h1>
<h1>
GetAvailableTimeZoneIdentifier (
_timeZone_: a String value,
): either a Record with fields [[Identifier]] (a String value that is a time zone identifier) and [[CanonicalIdentifier]] (a String value that is a canonical time zone identifier), or ~empty~
): either a Record with fields [[Identifier]] (a String value that is a time zone identifier) and [[PrimaryIdentifier]] (a String value that is a primary time zone identifier), or ~empty~
</h1>

<dl class="header">
Expand All @@ -32286,7 +32286,7 @@ <h1>
</emu-alg>
<emu-note>
Given the same value of _timeZone_ or any value that is an ASCII-case-insensitive match for it, it is recommended that the resulting Record contain the same property values for the lifetime of the surrounding agent.
Furthermore, it is recommended that time zone identifiers do not dynamically change from canonical to non-canonical, meaning that if _timeZone_ is a case-insensitive match for the [[CanonicalIdentifier]] property of the result of a previous call to GetAvailableTimeZoneIdentifier, then GetAvailableTimeZoneIdentifier(_timeZone_) will return a record where [[Identifier]] is [[CanonicalIdentifier]].
Furthermore, it is recommended that time zone identifiers do not dynamically change from primary to non-primary, meaning that if _timeZone_ is a case-insensitive match for the [[PrimaryIdentifier]] property of the result of a previous call to GetAvailableTimeZoneIdentifier, then GetAvailableTimeZoneIdentifier(_timeZone_) will return a record where [[Identifier]] is [[PrimaryIdentifier]].
Due to the complexity of supporting these requirements, it is recommended that the result of AvailableTimeZoneIdentifiers (and therefore GetAvailableTimeZoneIdentifier) remains the same for the lifetime of the surrounding agent.
</emu-note>
</emu-clause>
Expand Down

0 comments on commit 724a844

Please sign in to comment.