You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<h1><ahref="https://tc39.es/ecma402/#sec-time-zone-support">Time Zone Support</a></h1>
45
45
46
46
<insclass="block">
47
47
<p>
48
-
<emu-xrefhref="#sec-time-zone-names"></emu-xref> defines a set of abstract operations concerning the names of supported time zones.
48
+
<emu-xrefhref="#sec-time-zone-support"></emu-xref> defines a set of abstract operations related to the identifiers of supported time zones.
49
49
This section introduces additional requirements on these operations for implementations.
50
50
</p>
51
-
</ins>
52
51
53
-
<p>
54
-
The ECMAScript 2023 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 except as specifically overridden by CanonicalizeTimeZoneName.
55
-
</p>
52
+
<emu-clauseid="sup-time-zone-identifiers">
53
+
<h1>Time Zone Identifiers</h1>
56
54
57
-
<p>
58
-
A conforming implementation must recognize *"UTC"* and all other Zone and Link names (and <strong>only</strong> 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.
59
-
</p>
55
+
<p>
56
+
The ECMAScript 2024 Internationalization API Specification identifies time zones using the Zone and Link names of the IANA Time Zone Database <ahref="https://www.iana.org/time-zones/">https://www.iana.org/time-zones/</a>.
57
+
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.
58
+
A primary time zone identifier is a Zone name, and a non-primary time zone identifier is a Link name, respectively, in the IANA Time Zone Database except as specifically overridden by AvailableTimeZoneIdentifiers.
59
+
In an implementation that implements the ECMAScript 2024 Internationalization API Specification, available time zone identifiers are the set of Zone and Link identifiers that are supported by an ECMAScript implementation.
60
+
</p>
61
+
62
+
<p>
63
+
In the IANA Time Zone Database, the UTC time zone is represented by the Zone *"Etc/UTC"*, and is distinct from the Zone *"Etc/GMT"*.
64
+
For historical reasons, ECMAScript uses *"UTC"* as the primary identifier for the former Zone and does not recognize the latter Zone as distinct, instead requiring treatment of *"Etc/UTC"*, *"Etc/GMT"*, and *"GMT"* (if available) as non-primary identifiers that resolve to *"UTC"*.
65
+
This is the only deviation from the IANA Time Zone Database that is required of an ECMAScript implementation.
66
+
</p>
67
+
68
+
<p>
69
+
Time zone aware ECMAScript implementations support *"UTC"* and all other Zone and Link names (and <b>only</b> such names) from the IANA Time Zone Database, the mapping between Link names and corresponding Zone names, and the UTC offsets and transitions associated with Zone names that represent local political rules for that time zone.
70
+
An ECMAScript implementation that includes the ECMA-402 Internationalization API <b>must</b> be time zone aware.
71
+
However, it is recommended that all ECMAScript implementations be time zone aware, including those that do not implement the ECMA-402 Internationalization API.
72
+
Furthermore, 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 names as identifiers to represent time zones.
73
+
</p>
74
+
75
+
<p>
76
+
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.
77
+
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.
78
+
</p>
79
+
80
+
<p>
81
+
New Zone identifiers can be added to the IANA Time Zone Database, for example when one part of a country starts observing Daylight Saving Time differently from other parts, or when a new country declares independence.
82
+
ECMAScript implementations are recommended to include newly-added identifiers as soon as possible into the results of AvailableTimeZoneIdentifiers.
83
+
Such prompt action ensures that ECMAScript programs receiving those identifiers from an external source (including the host's operating system) will be able to recognize and calculate using the new time zone.
84
+
</p>
85
+
86
+
<p>
87
+
It is recommended that implementations maintain a fully consistent copy of the IANA Time Zone Database for the lifetime of each agent.
88
+
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.
89
+
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.
90
+
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.
91
+
</p>
92
+
93
+
<emu-note>
94
+
<p>
95
+
The IANA Time Zone Database offers build options that affect which time zone identifiers are primary.
96
+
It is recommended that ECMAScript implementations <b>should not</b> 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"*.
97
+
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.
98
+
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 <ahref="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.
99
+
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.
100
+
</p>
101
+
</emu-note>
102
+
</emu-clause>
103
+
</ins>
60
104
61
105
<delclass="block">
106
+
<p>
107
+
The ECMAScript 2024 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 except as specifically overridden by AvailableTimeZoneIdentifiers.
108
+
</p>
109
+
110
+
<p>
111
+
A conforming implementation must recognize *"UTC"* and all other Zone and Link names (and <strong>only</strong> 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 identifiers are available is implementation dependent.
_timeZone_: a String value that is <del>a valid</del><ins>an available</ins> time zone name as verified by <del>IsValidTimeZoneName</del><ins>IsAvailableTimeZoneName</ins>,
81
-
)
82
-
</h1>
83
-
<dlclass="header">
84
-
<dt>description</dt>
85
-
<dd>It returns the canonical and case-regularized form of _timeZone_.</dd>
86
-
<dt>redefinition</dt>
87
-
<dd>true</dd>
88
-
</dl>
89
127
90
-
<emu-alg>
91
-
1. Let _ianaTimeZone_ be the String value of the Zone or Link name of the IANA Time Zone Database that is an ASCII-case-insensitive match of _timeZone_.
92
-
1. If _ianaTimeZone_ is a Link name, let _ianaTimeZone_ be the String value of the corresponding Zone name as specified in the file <code>backward</code> of the IANA Time Zone Database.
93
-
1. If _ianaTimeZone_ is *"Etc/UTC"* or *"Etc/GMT"*, return *"UTC"*.
_timeZone_: a String value that is a valid time zone name as verified by IsValidTimeZoneName,
132
+
)
133
+
</h1>
134
+
<dlclass="header">
135
+
<dt>description</dt>
136
+
<dd>It returns the canonical and case-regularized form of _timeZone_.</dd>
137
+
<dt>redefinition</dt>
138
+
<dd>true</dd>
139
+
</dl>
96
140
97
-
<insclass="block">
98
-
<p>This definition supersedes the definition provided in <emu-xrefhref="#sec-canonicalizetimezonename"></emu-xref>.</p>
99
-
</ins>
100
-
</emu-clause>
141
+
<emu-alg>
142
+
1. Let _ianaTimeZone_ be the String value of the Zone or Link name of the IANA Time Zone Database that is an ASCII-case-insensitive match of _timeZone_.
143
+
1. If _ianaTimeZone_ is a Link name, let _ianaTimeZone_ be the String value of the corresponding Zone name as specified in the file <code>backward</code> of the IANA Time Zone Database.
144
+
1. If _ianaTimeZone_ is *"Etc/UTC"* or *"Etc/GMT"*, return *"UTC"*.
<h1>AvailableTimeZoneIdentifiers ( ): a List of Time Zone Identifier Records</h1>
108
153
<dlclass="header">
109
154
<dt>description</dt>
110
-
<dd>The returned List is a sorted List of supported Zone and Link names in the IANA Time Zone Database.</dd>
155
+
<dd>
156
+
Its result describes all available time zone identifiers in this implementation, as well as the primary time zone identifier corresponding to each available identifier.
157
+
The List is sorted by [[Identifier]] of each Time Zone Identifier Record.
158
+
</dd>
111
159
<dt>redefinition</dt>
112
160
<dd>true</dd>
113
161
</dl>
114
162
<emu-alg>
115
-
1. Let _timeZones_ be a List containing the String value of each Zone or Link name in the IANA Time Zone Database that is supported by the implementation.
116
-
1.Assert:_timeZones_ contains *"UTC"*.
117
-
1.Assert:_timeZones_ does not contain any element that does not identify a Zone or Link name in the IANA Time Zone Database.
118
-
1. Return SortStringListByCodeUnit(_timeZones_).
163
+
1. Let _identifiers_ be a List containing the String value of each Zone or Link name in the IANA Time Zone Database that is supported by the implementation.
164
+
1.Assert: No element of _identifiers_ is an ASCII-case-insensitive match for any other element.
165
+
1.Assert: No element of _identifiers_ does not identify a Zone or Link name in the IANA Time Zone Database.
166
+
1. Set _identifiers_ to SortStringListByCodeUnit(_identifiers_).
167
+
1. Let _result_ be a new empty List.
168
+
1. For each element _identifier_ of _identifiers_, do
169
+
1. Let _primary_ be _identifier_.
170
+
1. If _identifier_ is a non-primary time zone identifier and _identifier_ is not *"UTC"*, then
171
+
1. Set _primary_ to the name of the primary time zone identifier that _identifier_ resolves to, according to the rules for resolving Link names in the IANA Time Zone Database.
172
+
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.
173
+
1. If _primary_ is one of *"Etc/UTC"*, *"Etc/GMT"*, or *"GMT"*, set _primary_ to *"UTC"*.
174
+
1. Let _record_ be the Time Zone Identifier Record { [[Identifier]]: _identifier_, [[PrimaryIdentifier]]: _primary_ }.
175
+
1. Append _record_ to the end of _result_.
176
+
1.Assert: One element of _result_ is the Time Zone Identifier Record { [[Identifier]]: *"UTC"*, [[PrimaryIdentifier]]: *"UTC"* }.
177
+
1. Return _result_.
119
178
</emu-alg>
120
179
121
-
<p>This definition supersedes the definition provided in <emu-xrefhref="#sec-availabletimezones"></emu-xref>.</p>
180
+
<emu-note>
181
+
Time zone identifiers in the IANA Time Zone Database can change over time.
182
+
At a minimum, it is recommended that implementations limit changes to the result of AvailableTimeZoneIdentifiers to the changes allowed by GetAvailableTimeZoneIdentifier, for the lifetime of the surrounding agent.
183
+
Due to the complexity of supporting these requirements, it is recommended that the result of AvailableTimeZoneIdentifiers remains the same for the lifetime of the surrounding agent.
184
+
</emu-note>
185
+
186
+
<p>This definition supersedes the definition provided in <emu-xrefhref="#sec-availabletimezoneidentifiers"></emu-xref>.</p>
In this version of the ECMAScript 2023 Internationalization API, the *"timeZone"* property will be the name of the default time zone if no *"timeZone"* property was provided in the options object provided to the Intl.DateTimeFormat constructor. The first edition left the *"timeZone"* property *undefined* in this case.
1343
+
In this version of the ECMAScript 2024 Internationalization API, the *"timeZone"* property will be the name of the system time zone identifier if no *"timeZone"* property was provided in the options object provided to the Intl.DateTimeFormat constructor. The first edition left the *"timeZone"* property *undefined* in this case.
0 commit comments