This repository has been archived by the owner on Jul 31, 2023. It is now read-only.
generated from tc39/template-for-proposals
-
Notifications
You must be signed in to change notification settings - Fork 3
/
displaynames.html
358 lines (317 loc) · 19.1 KB
/
displaynames.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
<emu-biblio href="./biblio.json"></emu-biblio>
<emu-clause id="intl-displaynames-objects">
<h1>DisplayNames Objects</h1>
<emu-clause id="sec-intl-displaynames-abstracts">
<h1>Abstract Operations for DisplayNames Objects</h1>
<emu-clause id="sec-canonicalcodefordisplaynames" aoid="CanonicalCodeForDisplayNames">
<h1>CanonicalCodeForDisplayNames ( _type_, _code_)</h1>
<p>
The CanonicalCodeForDisplayNames abstract operation is called with arguments _type_, _code_. It verifies that the _code_ argument represents a well-formed code according to the _type_ argument and returns the case-regularized form of the _code_. The algorithm refers to <a href="https://www.unicode.org/reports/tr35/#Identifiers">UTS 35's Unicode Language and Locale Identifiers grammar</a>. The following steps are taken:
</p>
<emu-alg>
1. If _type_ is `"language"`, then
1. If _code_ does not matches the `unicode_language_id` production, throw a *RangeError* exceptipon.
1. If IsStructurallyValidLanguageTag(_code_) is *false*, throw a *RangeError* exception.
1. Set _code_ to CanonicalizeUnicodeLocaleId(_code_).
1. Return _code_.
1. If _type_ is `"region"`, then
1. If _code_ does not matches the `unicode_region_subtag` production, throw a *RangeError* exceptipon.
1. Let _code_ be the result of mapping _code_ to upper case as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
1. If _type_ is `"script"`, then
1. If _code_ does not matches the `unicode_script_subtag` production, throw a *RangeError* exceptipon.
1. Let _code_ be the result of mapping the first character in _code_ to upper case, and mapping the second, third and fourth character in _code_ to lower case, as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
1. <ins>If _type_ is `"calendar"`, then</ins>
1. <ins>If _code_ does not match the Unicode Locale Identifier `type` nonterminal, throw a *RangeError* exception.</ins>
1. <ins>Let _code_ be the result of mapping _code_ to lower case as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.</ins>
1. <ins>Return _code_.</ins>
1. <ins>If _type_ is `"dateTimeField"`, then</ins>
1. <ins>If the result of IsValidDateTimeFieldCode(_code_) is *false*, throw a *RangeError* exception.</ins>
1. <ins>Return _code_.</ins>
1. Assert: _type_ is `"currency"`.
1. If ! IsWellFormedCurrencyCode(_code_) is *false*, throw a *RangeError* exceptipon.
1. Let _code_ be the result of mapping _code_ to upper case as described in <emu-xref href="#sec-case-sensitivity-and-case-mapping"></emu-xref>.
1. Return _code_.
</emu-alg>
</emu-clause>
</emu-clause>
<emu-clause id="sec-isvaliddatetimefieldcode" aoid="IsValidDateTimeFieldCode">
<h1><ins>IsValidDateTimeFieldCode ( _field_ )</ins></h1>
<p>
<ins>
The IsValidDateTimeFieldCode abstract operation is called with argument _field_. It verifies that the _field_ argument represents a valid date time field code. The following steps are taken:
</ins>
</p>
<emu-alg>
1. <ins>If _field_ is listed in the Code column of <emu-xref href="#table-validcodefordatetimefield"></emu-xref>, return *true*.</ins>
1. <ins>Return *false*.</ins>
</emu-alg>
<emu-table id="table-validcodefordatetimefield">
<emu-caption><ins>Codes For Date Time Field of DisplayNames</ins></emu-caption>
<table class="real-table">
<thead>
<tr>
<th><ins>Code</ins></th>
<th><ins>Description</ins></th>
</tr>
</thead>
<tr>
<td><ins>`"era"`</ins></td>
<td><ins>The field indicating the era, e.g. AD or BC in the Gregorian (Julian) calendar.</ins></td>
</tr>
<tr>
<td><ins>`"year"`</ins></td>
<td><ins>The field indicating the year.</ins></td>
</tr>
<tr>
<td><ins>`"quarter"`</ins></td>
<td><ins>The field indicating the quarter, e.g. Q2, 2nd quarter, etc.</ins></td>
</tr>
<tr>
<td><ins>`"month"`</ins></td>
<td><ins>The field indicating the month, e.g. Sep, September, etc.</ins></td>
</tr>
<tr>
<td><ins>`"weekOfYear"`</ins></td>
<td><ins>The field indicating the week number within the current year.</ins></td>
</tr>
<tr>
<td><ins>`"weekday"`</ins></td>
<td><ins>The field indicating the day of week, e.g. Tue, Tuesday, etc.</ins></td>
</tr>
<tr>
<td><ins>`"day"`</ins></td>
<td><ins>The field indicating the day in month.</ins></td>
</tr>
<tr>
<td><ins>`"dayPeriod"`</ins></td>
<td><ins>The field indicating the day period, either am/pm marker or others, e.g. noon, evening.</ins></td>
</tr>
<tr>
<td><ins>`"hour"`</ins></td>
<td><ins>The field indicating the hour.</ins></td>
</tr>
<tr>
<td><ins>`"minute"`</ins></td>
<td><ins>The field indicating the minute.</ins></td>
</tr>
<tr>
<td><ins>`"second"`</ins></td>
<td><ins>The field indicating the second.</ins></td>
</tr>
<tr>
<td><ins>`"timeZoneName"`</ins></td>
<td><ins>The field indicating the time zone name, e.g. PDT, Pacific Daylight Time, etc.</ins></td>
</tr>
</table>
</emu-table>
</emu-clause>
<emu-clause id="sec-intl-displaynames-constructor">
<h1>The Intl.DisplayNames Constructor</h1>
<p>
The DisplayNames constructor is a standard built-in property of the Intl object.</p>
<emu-clause id="sec-Intl.DisplayNames">
<h1>Intl.DisplayNames ( _locales_, _options_ )</h1>
<p>
When the *Intl.DisplayNames* function is called with arguments _locales_ and _options_, the following steps are taken:
</p>
<emu-alg>
1. If NewTarget is *undefined*, throw a *TypeError* exception.
1. Let _displayNames_ be ? OrdinaryCreateFromConstructor(NewTarget, `"%DisplayNamesPrototype%"`, « [[InitializedDisplayNames]], [[Locale]], [[Style]], [[Type]], [[Fallback]], <ins>[[LanguageDisplay]], </ins>[[Fields]] »).
1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
1. Let _options_ be ? ToObject(_options_).
1. Let _opt_ be a new Record.
1. Let _localeData_ be %DisplayNames%.[[LocaleData]].
1. Let _matcher_ be ? GetOption(_options_, `"localeMatcher"`, `"string"`, « `"lookup"`, `"best fit"` », `"best fit"`).
1. Set _opt_.[[localeMatcher]] to _matcher_.
1. Let _r_ be ResolveLocale(%DisplayNames%.[[AvailableLocales]], _requestedLocales_, _opt_, %DisplayNames%.[[RelevantExtensionKeys]]).
1. Let _style_ be ? GetOption(_options_, `"style"`, `"string"`, « `"narrow"`, `"short"`, `"long"` », `"long"`).
1. Set _displayNames_.[[Style]] to _style_.
1. Let _type_ be ? GetOption(_options_, `"type"`, `"string"`, « `"language"`, `"region"`, `"script"`, `"currency"` <ins>, `"calendar"`, `"dateTimeField"`</ins>», *undefined*).
1. If _type_ is *undefined*, throw a *TypeError* exception.
1. Set _displayNames_.[[Type]] to _type_.
1. Let _fallback_ be ? GetOption(_options_, `"fallback"`, `"string"`, « `"code"`, `"none"` », `"code"`).
1. Set _displayNames_.[[Fallback]] to _fallback_.
1. Set _displayNames_.[[Locale]] to the value of _r_.[[Locale]].
1. Let _dataLocale_ be _r_.[[dataLocale]].
1. Let _dataLocaleData_ be _localeData_.[[<_dataLocale_>]].
1. Let _types_ be _dataLocaleData_.[[types]].
1. Assert: _types_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. Let _typeFields_ be _types_.[[<_type_>]].
1. Assert: _typeFields_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. <ins>Let _languageDisplay_ be ? GetOption(_options_, `"languageDisplay"`, `"string"`, « `"dialect"`, `"standard"` », `"dialect"`).</ins>
1. <ins>If _type_ is `"language"`, then</ins>
1. <ins>Set _displayNames_.[[LanguageDisplay]] to _languageDisplay_.</ins>
1. <ins>Let _typeFields_ be _typeFields_.[[<_languageDisplay_>]].</ins>
1. <ins>Assert: _typeFields_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).</ins>
1. Let _styleFields_ be _typeFields_.[[<_style_>]].
1. Assert: _styleFields_ is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>).
1. Set _displayNames_.[[Fields]] to _styleFields_.
1. Return _displayNames_.
</emu-alg>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-constructor">
<h1>Properties of the Intl.DisplayNames Constructor</h1>
<p>
The Intl.DisplayNames constructor has the following properties:
</p>
<emu-clause id="sec-Intl.DisplayNames.prototype">
<h1>Intl.DisplayNames.prototype</h1>
<p>
The value of *Intl.DisplayNames.prototype* is *%DisplayNamesPrototype%*.
</p>
<p>
This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *false* }.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.supportedLocalesOf">
<h1>Intl.DisplayNames.supportedLocalesOf ( _locales_ [ , _options_ ] )</h1>
<p>
When the *supportedLocalesOf* method of *%DisplayNames%* is called, the following steps are taken:
</p>
<emu-alg>
1. Let _availableLocales_ be *%DisplayNames%*.[[AvailableLocales]].
1. Let _requestedLocales_ be ? CanonicalizeLocaleList(_locales_).
1. Return ? SupportedLocales(_availableLocales_, _requestedLocales_, _options_).
</emu-alg>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames-internal-slots">
<h1>Internal slots</h1>
<p>
The value of the [[AvailableLocales]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref>.
</p>
<p>
The value of the [[RelevantExtensionKeys]] internal slot is « ».
</p>
<p>
The value of the [[LocaleData]] internal slot is implementation defined within the constraints described in <emu-xref href="#sec-internal-slots"></emu-xref> and the following additional constraints:
</p>
<ul>
<li>[[LocaleData]].[[<_locale_>]] must have a [[types]] field for all locale values _locale_. The value of this field must be a Record, which must have fields with the names of one of the valid display name types: `"language"`, `"region"`, `"script"`, <del>and</del> `"currency"`<ins>, `"calendar"`, and `"dateTimeField"`</ins>.</li>
<li><ins>The value of the field `"language"` must be a Record which must have fields with the names of one of the valid language displays: `"dialect"` and `"standard"`.</ins></li>
<li><ins>The language display fields under display name type `"language"` should contain Records which must have fields with the names of one of the valid display name styles: `"narrow"`, `"short"`, and `"long"`.</ins></li>
<li>The value of fields <del>`"language"`, </del>`"region"`, `"script"`, <del>and </del>`"currency"`<ins>, `"calendar"`, and `"dateTimeField"`</ins> must be a Record which must have fields with the names of one of the valid display name styles: `"narrow"`, `"short"`, and `"long"`.</li>
<li>The display name styles fields under display name type `"language"` should contain Records, with keys corresponding to language codes according to `unicode_language_id` production. The value of these fields must be string values.</li>
<li>The display name styles fields under display name type `"region"` should contain Records, with keys corresponding to region codes. The value of these fields must be string values.</li>
<li>The display name styles fields under display name type `"script"` should contain Records, with keys corresponding to script codes. The value of these fields must be string values.</li>
<li>The display name styles fields under display name type `"currency"` should contain Records, with keys corresponding to currency codes. The value of these fields must be string values.</li>
<li><ins>The display name styles fields under display name type `"calendar"` should contain Records, with keys corresponding to a String value with the `type` given in Unicode Technical Standard 35 for the calendar used for formatting. The value of these fields must be string values.</li>
<li><ins>The display name styles fields under display name type `"dateTimeField"` should contain Records, with keys corresponding to codes listed in <emu-xref href="#table-validcodefordatetimefield"></emu-xref>. The value of these fields must be string values.</ins></li>
</ul>
<emu-note>
It is recommended that implementations use the locale data provided by the Common Locale Data Repository (available at <a href="http://cldr.unicode.org/">http://cldr.unicode.org/</a>).
</emu-note>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-prototype-object">
<h1>Properties of the Intl.DisplayNames Prototype Object</h1>
<p>
The Intl.DisplayNames prototype object, referred to as *%DisplayNamesPrototype%*, is itself an ordinary object. It is not a Intl.DisplayNames instance, does not have an [[InitializedDisplayNames]] internal slot or any of the other internal slots of Intl.DisplayNames instance objects.
</p>
<emu-clause id="sec-Intl.DisplayNames.prototype.constructor">
<h1>Intl.DisplayNames.prototype.constructor</h1>
<p>
The initial value of *Intl.DisplayNames.prototype.constructor* is the intrinsic object *%DisplayNames%*.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype-@@tostringtag">
<h1>Intl.DisplayNames.prototype[ @@toStringTag ]</h1>
<p>
The initial value of the @@toStringTag property is the string value `"Intl.DisplayNames"`.
</p>
<p>
This property has the attributes { [[Writable]]: *false*, [[Enumerable]]: *false*, [[Configurable]]: *true* }.
</p>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype.of" aoid="Intl.DisplayNames.prototype.of">
<h1>Intl.DisplayNames.prototype.of ( _code_ )</h1>
<p>
When the *Intl.DisplayNames.prototype.of* is called with an argument _code_, the following steps are taken:
</p>
<emu-alg>
1. Let _displayNames_ be *this* value.
1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
1. Let _code_ be ? ToString(_code_).
1. Let _code_ be ? CanonicalCodeForDisplayNames(_displayNames_.[[Type]], _code_).
1. Let _fields_ be _displayNames_.[[Fields]].
1. Let _name_ be _fields_[[<_code_>]].
1. If _name_ is not *undefined*, return _name_.
1. If _displayNames_.[[Fallback]] is `"code"`, return _code_.
1. Return *undefined*.
</emu-alg>
</emu-clause>
<emu-clause id="sec-Intl.DisplayNames.prototype.resolvedOptions">
<h1>Intl.DisplayNames.prototype.resolvedOptions ( )</h1>
<p>
This function provides access to the locale and options computed during initialization of the object.
</p>
<emu-alg>
1. Let _displayNames_ be *this* value.
1. If Type(_displayNames_) is not Object, throw a *TypeError* exception.
1. If _displayNames_ does not have an [[InitializedDisplayNames]] internal slot, throw a *TypeError* exception.
1. Let _options_ be ! ObjectCreate(%ObjectPrototype%).
1. For each row of <emu-xref href="#table-displaynames-resolvedoptions-properties"></emu-xref>, except the header row, in table order, do
1. Let _p_ be the Property value of the current row.
1. Let _v_ be the value of _displayNames_'s internal slot whose name is the Internal Slot value of the current row.
1. If _v_ is not *undefined*, then
1. Perform ! CreateDataPropertyOrThrow(_options_, _p_, _v_).
1. Return _options_.
</emu-alg>
<emu-table id="table-displaynames-resolvedoptions-properties">
<emu-caption>Resolved Options of DisplayNames Instances</emu-caption>
<table class="real-table">
<thead>
<tr>
<th>Internal Slot</th>
<th>Property</th>
</tr>
</thead>
<tr>
<td>[[Locale]]</td>
<td>`"locale"`</td>
</tr>
<tr>
<td>[[Style]]</td>
<td>`"style"`</td>
</tr>
<tr>
<td>[[Type]]</td>
<td>`"type"`</td>
</tr>
<tr>
<td>[[Fallback]]</td>
<td>`"fallback"`</td>
</tr>
<tr>
<td><ins>[[LanguageDisplay]]</ins></td>
<td><ins>`"languageDisplay"`</ins></td>
</tr>
</table>
</emu-table>
</emu-clause>
</emu-clause>
<emu-clause id="sec-properties-of-intl-displaynames-instances">
<h1>Properties of Intl.DisplayNames Instances</h1>
<p>
Intl.DisplayNames instances are ordinary objects that inherit properties from %DisplayNamesPrototype%.
</p>
<p>
Intl.DisplayNames instances have an [[InitializedDisplayNames]] internal slot.
</p>
<p>
Intl.DisplayNames instances also have several internal slots that are computed by the constructor:
</p>
<ul>
<li>[[Locale]] is a String value with the language tag of the locale whose localization is used for formatting.</li>
<li>[[Style]] is one of the String values `"narrow"`, `"short"`, or `"long"`, identifying the display names style used.</li>
<li>[[Type]] is one of the String values `"language"`, `"region"`, `"script"`, <del>or </del>`"currency"`,<ins> `"calendar"`, or `"dateTimeField"`,</ins> identifying the type of the display names requested.</li>
<li>[[Fallback]] is one of the String values `"code"`, or `"none"`, identifying the fallback return when the system does not have the requested display name.</li>
<li><ins>[[LanguageDisplay]] is one of the String values `"dialect"` or `"standard"`, identifying the language display kind. It is only used when [[Type]] has the value `"language"`.</ins></li>
<li>[[Fields]] is a Record (see <emu-xref href="#sec-Intl.DisplayNames-internal-slots"></emu-xref>) which
must have fields with keys corresponding to codes according to [[Style]] <del>and</del><ins>,</ins> [[Type]]<ins>, and [[LanguageDisplay]]</ins>.</li>
</ul>
</emu-clause>
</emu-clause>