Stage 3 Draft / November 3, 2022

Intl Enumeration API Specification

Introduction

This proposal adds several function properties to the Intl Object to list supported values of options. See the README for more context.

1 Identification of Locales, Currencies, Time Zones, and Measurement Units, Numbering Systems, Collations, and Calendars

This clause describes the String values used in the ECMAScript 2023 Internationalization API Specification to identify locales, currencies, time zones, and measurement units, numbering systems, collations, and calendars .

1.1 Case Sensitivity and Case Mapping

The String values used to identify locales, currencies, scripts, and time zones are interpreted in an ASCII-case-insensitive manner, treating the code units 0x0041 through 0x005A (corresponding to Unicode characters LATIN CAPITAL LETTER A through LATIN CAPITAL LETTER Z) as equivalent to the corresponding code units 0x0061 through 0x007A (corresponding to Unicode characters LATIN SMALL LETTER A through LATIN SMALL LETTER Z), both inclusive. No other case folding equivalences are applied.

Note
For example, "ß" (U+00DF) must not match or be mapped to "SS" (U+0053, U+0053). "ı" (U+0131) must not match or be mapped to "I" (U+0049).

The ASCII-uppercase of a String value S is the String value derived from S by replacing each occurrence of an ASCII lowercase letter code unit (0x0061 through 0x007A, inclusive) with the corresponding ASCII uppercase letter code unit (0x0041 through 0x005A, inclusive) while preserving all other code units.

The ASCII-lowercase of a String value S is the String value derived from S by replacing each occurrence of an ASCII uppercase letter code unit (0x0041 through 0x005A, inclusive) with the corresponding ASCII lowercase letter code unit (0x0061 through 0x007A, inclusive) while preserving all other code units.

A String value A is an ASCII-case-insensitive match for String value B if the ASCII-uppercase of A is exactly the same sequence of code units as the ASCII-uppercase of B. A sequence of Unicode code points A is an ASCII-case-insensitive match for B if B is an ASCII-case-insensitive match for ! CodePointsToString(A).

1.2 Language Tags

...

1.3 Currency Codes

The ECMAScript 2023 Internationalization API Specification identifies currencies using 3-letter currency codes as defined by ISO 4217. Their canonical form is uppercase.

All well-formed 3-letter ISO 4217 currency codes are allowed. However, the set of combinations of currency code and language tag for which localized currency symbols are available is implementation dependent. Where a localized currency symbol is not available, the ISO 4217 currency code is used for formatting.

1.3.1 IsWellFormedCurrencyCode ( currency )

The IsWellFormedCurrencyCode abstract operation verifies that the currency argument (which must be a String value) represents a well-formed 3-letter ISO currency code. The following steps are taken:

  1. If the length of currency is not 3, return false.
  2. Let normalized be the ASCII-uppercase of currency.
  3. If normalized contains any code unit outside of 0x0041 through 0x005A (corresponding to Unicode characters LATIN CAPITAL LETTER A through LATIN CAPITAL LETTER Z), return false.
  4. Return true.

1.3.2 AvailableCanonicalCurrencies ( )

The implementation-defined abstract operation AvailableCanonicalCurrencies takes no arguments and returns a List of Strings. The returned List is ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn, and contains unique, well-formed, and upper case canonicalized 3-letter ISO 4217 currency codes, identifying the currencies for which the implementation provides the functionality of Intl.DisplayNames and Intl.NumberFormat objects.

1.4 Time Zone Names

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.

A conforming implementation must recognize "UTC" and all other Zone and Link names (and only 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.

1.4.1 IsValidTimeZoneName ( timeZone )

The abstract operation IsValidTimeZoneName takes argument timeZone, a String value, and verifies that it represents a valid Zone or Link name of the IANA Time Zone Database.

  1. If one of the Zone or Link names of the IANA Time Zone Database is an ASCII-case-insensitive match of timeZone, return true.
  2. If timeZone is an ASCII-case-insensitive match of "UTC", return true.
  3. Return false.
 Note
Any value returned from DefaultTimeZone must be recognized as valid.

1.4.2 CanonicalizeTimeZoneName ( timeZone )

The abstract operation CanonicalizeTimeZoneName takes argument timeZone (a String value that is a valid time zone name as verified by IsValidTimeZoneName). It returns the canonical and case-regularized form of timeZone. It performs the following steps when called:

  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.
  2. If ianaTimeZone is a Link name, let ianaTimeZone be the String value of the corresponding Zone name as specified in the file backward of the IANA Time Zone Database.
  3. If ianaTimeZone is "Etc/UTC" or "Etc/GMT", return "UTC".
  4. Return ianaTimeZone.

1.4.3 DefaultTimeZone ( )

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

1.4.4 AvailableCanonicalTimeZones ( )

The implementation-defined abstract operation AvailableCanonicalTimeZones takes no arguments and returns a List of Strings. The returned List is a sorted List of supported Zone and Link names in the IANA Time Zone Database. It performs the following steps when called:

  1. Let names be a List of all supported Zone and Link names in the IANA Time Zone Database.
  2. Let result be a new empty List.
  3. For each element name of names, do
    1. Assert: ! IsValidTimeZoneName( name ) is true.
    2. Let canonical be ! CanonicalizeTimeZoneName( name ).
    3. If result does not contain an element equal to canonical, then
      1. Append canonical to the end of result.
  4. Sort result in order as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn.
  5. Return result.

1.5 Measurement Unit Identifiers

The ECMAScript 2023 Internationalization API Specification identifies measurement units using a core unit identifier (or equivalently core unit ID) as defined by Unicode Technical Standard #35, Part 2, Section 6.2. Their canonical form is a string containing only Unicode Basic Latin lowercase letters (U+0061 LATIN SMALL LETTER A through U+007A LATIN SMALL LETTER Z) with zero or more medial hyphens (U+002D HYPHEN-MINUS).

Only a limited set of core unit identifiers are sanctioned. Attempting to use an unsanctioned core unit identifier results in a RangeError.

1.5.1 IsWellFormedUnitIdentifier ( unitIdentifier )

The IsWellFormedUnitIdentifier abstract operation verifies that the unitIdentifier argument (which must be a String value) represents a well-formed UTS #35 core unit identifier that is either a sanctioned single unit or a complex unit formed by division of two sanctioned single units. The following steps are taken:

  1. If ! IsSanctionedSingleUnitIdentifier(unitIdentifier) is true, then
    1. Return true.
  2. Let i be StringIndexOf(unitIdentifier, "-per-", 0).
  3. If i is -1 or StringIndexOf(unitIdentifier, "-per-", i + 1) is not -1, then
    1. Return false.
  4. Assert: The five-character substring "-per-" occurs exactly once in unitIdentifier, at index i.
  5. Let numerator be the substring of unitIdentifier from 0 to i.
  6. Let denominator be the substring of unitIdentifier from i + 5.
  7. If ! IsSanctionedSingleUnitIdentifier(numerator) and ! IsSanctionedSingleUnitIdentifier(denominator) are both true, then
    1. Return true.
  8. Return false.

1.5.2 IsSanctionedSingleUnitIdentifier ( unitIdentifier )

The IsSanctionedSingleUnitIdentifier abstract operation verifies that the unitIdentifier argument (which must be a String value) is among the single unit identifiers sanctioned in the current version of the ECMAScript Internationalization API Specification, which are a subset of the Common Locale Data Repository release 38 unit validity data; the list may grow over time. As discussed in UTS #35, a single unit identifier is a core unit identifier that is not composed of multiplication or division of other unit identifiers. The following steps are taken:

  1. If unitIdentifier is listed in Table 1 below, return true.
  2. Else, return false.
Table 1: Single units sanctioned for use in ECMAScript
Single Unit Identifier
acre
bit
byte
celsius
centimeter
day
degree
fahrenheit
fluid-ounce
foot
gallon
gigabit
gigabyte
gram
hectare
hour
inch
kilobit
kilobyte
kilogram
kilometer
liter
megabit
megabyte
meter
mile
mile-scandinavian
milliliter
millimeter
millisecond
minute
month
ounce
percent
petabyte
pound
second
stone
terabit
terabyte
week
yard
year

1.5.3 AvailableCanonicalUnits ( )

The abstract operation AvailableCanonicalUnits takes no arguments and returns a List of Strings. The returned List is ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn, and consists of the unique values of simple unit identifiers listed in every row of Table 2, except the header row.

1.6 Numbering System Identifiers

The ECMAScript 2023 Internationalization API Specification identifies numbering systems using a numbering system identifier as defined by Unicode Technical Standard #35, Part 3, Section 1. Their canonical form is a string containing all lowercase letters.

1.6.1 AvailableCanonicalNumberingSystems ( )

The implementation-defined abstract operation AvailableCanonicalNumberingSystems takes no arguments and returns a List of Strings. The returned List is ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn, and contains unique numbering systems identifiers identifying the canonical numbering systems for which the implementation provides the functionality of Intl.DateTimeFormat, Intl.NumberFormat, and Intl.RelativeTimeFormat objects. The list must include the Numbering System value of every row of Table 4, except the header row.

1.7 Collation Types

The ECMAScript 2023 Internationalization API Specification identifies collations using a collation type as defined by Unicode Technical Standard #35, Part 5, Section 3.1. Their canonical form is a string containing all lowercase letters with zero or more hyphens.

1.7.1 AvailableCanonicalCollations ( )

The implementation-defined abstract operation AvailableCanonicalCollations takes no arguments and returns a List of Strings. The returned List is ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn, and contains unique canonical collation types identifying the collations for which the implementation provides the functionality of Intl.Collator objects.

1.8 Calendar Types

The ECMAScript 2023 Internationalization API Specification identifies calendars using a calendar type as defined by Unicode Technical Standard #35, Part 4, Section 2. Their canonical form is a string containing all lower case letters with zero or more hyphens.

1.8.1 AvailableCanonicalCalendars ( )

The implementation-defined abstract operation AvailableCanonicalCalendars takes no arguments and returns a List of Strings. The returned List is ordered as if an Array of the same values had been sorted using %Array.prototype.sort% using undefined as comparefn, and contains unique canonical calendar types identifying the calendars for which the implementation provides the functionality of Intl.DateTimeFormat objects. The list must include "iso8601".

2 The Intl Object

The Intl object is the %Intl% intrinsic object and the initial value of the "Intl" property of the global object. The Intl object is a single ordinary object.

The value of the [[Prototype]] internal slot of the Intl object is the intrinsic object %ObjectPrototype%.

The Intl object is not a function object. It does not have a [[Construct]] internal method; it is not possible to use the Intl object as a constructor with the new operator. The Intl object does not have a [[Call]] internal method; it is not possible to invoke the Intl object as a function.

The Intl object has an internal slot, [[FallbackSymbol]], which is a new %Symbol% in the current realm with the [[Description]] "IntlLegacyConstructedSymbol".

2.1 Constructor Properties of the Intl Object

With the exception of Intl.Locale, each of the following constructors is a service constructor that creates objects providing locale-sensitive services.

2.1.1 Intl.Collator ( . . . )

See 10.

2.1.2 Intl.DateTimeFormat ( . . . )

See 11.

2.1.3 Intl.DisplayNames ( . . . )

See 12.

2.1.4 Intl.ListFormat ( . . . )

See 13.

2.1.5 Intl.Locale ( . . . )

See 14.

2.1.6 Intl.NumberFormat ( . . . )

See 15.

2.1.7 Intl.PluralRules ( . . . )

See 16.

2.1.8 Intl.RelativeTimeFormat ( . . . )

See 17.

2.1.9 Intl.Segmenter ( . . . )

See 18.

2.2 Function Properties of the Intl Object

2.2.1 Intl.getCanonicalLocales ( locales )

When the getCanonicalLocales method is called with argument locales, the following steps are taken:

  1. Let ll be ? CanonicalizeLocaleList(locales).
  2. Return CreateArrayFromList(ll).

2.2.2 Intl.supportedValuesOf ( key )

When the supportedValuesOf method is called with argument key , the following steps are taken:

  1. Let key be ? ToString(key).
  2. If key is "calendar", then
    1. Let list be AvailableCanonicalCalendars( ).
  3. Else if key is "collation", then
    1. Let list be AvailableCanonicalCollations( ).
  4. Else if key is "currency", then
    1. Let list be AvailableCanonicalCurrencies( ).
  5. Else if key is "numberingSystem", then
    1. Let list be AvailableCanonicalNumberingSystems( ).
  6. Else if key is "timeZone", then
    1. Let list be AvailableCanonicalTimeZones( ).
  7. Else if key is "unit", then
    1. Let list be AvailableCanonicalUnits( ).
  8. Else,
    1. Throw a RangeError exception.
  9. Return CreateArrayFromList( list ).

A Copyright & Software License

Copyright Notice

© 2022 Google, Ecma International

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.