ECMAScript Internationalization API Specification – ECMA-402 Edition 1.0

Standard ECMA-402
st
Edition / December 2012
ECMAScript Internationalization API Specification
This is the HTML rendering of
ECMA-402 Edition 1.0, ECMAScript Internationalization API Specification
The PDF rendering of this document is located at
The PDF version is the definitive specification. Any discrepancies between this HTML version and the PDF version are
unintentional.
Contents
Introduction
Scope
Conformance
Normative References
Overview
4.1
Internationalization,
Localization, and Globalization
4.2
API Overview
4.3
Implementation Dependencies
Notational Conventions
Identification of Locales, Time Zones, and
Currencies
6.1
Case Sensitivity and Case
Mapping
6.2
Language Tags
6.2.1
Unicode Locale Extension
Sequences
6.2.2
IsStructurallyValidLanguageTag (locale)
6.2.3
CanonicalizeLanguageTag
(locale)
6.2.4
DefaultLocale ()
6.3
Currency Codes
6.3.1
IsWellFormedCurrencyCode
(currency)
6.4
Time Zone Names
Requirements for Standard Built-in
ECMAScript Objects
The Intl Object
8.1
Properties of the Intl Object
Locale and Parameter Negotiation
9.1
Internal Properties of Service
Constructors
9.2
Abstract Operations
9.2.1
CanonicalizeLocaleList
(locales)
9.2.2
BestAvailableLocale
(availableLocales, locale)
9.2.3
LookupMatcher
(availableLocales, requestedLocales)
9.2.4
BestFitMatcher
(availableLocales, requestedLocales)
9.2.5
ResolveLocale
(availableLocales, requestedLocales, options, relevantExtensionKeys, localeData)
9.2.6
LookupSupportedLocales
(availableLocales, requestedLocales)
9.2.7
BestFitSupportedLocales
(availableLocales, requestedLocales)
9.2.8
SupportedLocales
(availableLocales, requestedLocales, options)
9.2.9
GetOption (options,
property, type, values, fallback)
9.2.10
GetNumberOption
(options, property, minimum, maximum, fallback)
10
Collator Objects
10.1
The Intl.Collator Constructor
10.1.1
Initializing an Object
as a Collator
10.1.2
The Intl.Collator
Constructor Called as a Function
10.1.3
The Intl.Collator
Constructor Used in a new Expression
10.2
Properties of the Intl.Collator
Constructor
10.2.1
Intl.Collator.prototype
10.2.2
Intl.Collator.supportedLocalesOf (locales [, options])
10.2.3
Internal Properties
10.3
Properties of the Intl.Collator
Prototype Object
10.3.1
Intl.Collator.prototype.constructor
10.3.2
Intl.Collator.prototype.compare
10.3.3
Intl.Collator.prototype.resolvedOptions ()
10.4
Properties of Intl.Collator
Instances
11
NumberFormat Objects
11.1
The Intl.NumberFormat
Constructor
11.1.1
Initializing an Object
as a NumberFormat
11.1.2
The Intl.NumberFormat
Constructor Called as a Function
11.1.3
The Intl.NumberFormat
Constructor Used in a new Expression
11.2
Properties of the
Intl.NumberFormat Constructor
11.2.1
Intl.NumberFormat.prototype
11.2.2
Intl.NumberFormat.supportedLocalesOf (locales [, options])
11.2.3
Internal Properties
11.3
Properties of the
Intl.NumberFormat Prototype Object
11.3.1
Intl.NumberFormat.prototype.constructor
11.3.2
Intl.NumberFormat.prototype.format
11.3.3
Intl.NumberFormat.prototype.resolvedOptions ()
11.4
Properties of Intl.NumberFormat
Instances
12
DateTimeFormat Objects
12.1
The Intl.DateTimeFormat
Constructor
12.1.1
Initializing an Object
as a DateTimeFormat
12.1.2
The Intl.DateTimeFormat
Constructor Called as a Function
12.1.3
The Intl.DateTimeFormat
Constructor Used in a new Expression
12.2
Properties of the
Intl.DateTimeFormat Constructor
12.2.1
Intl.DateTimeFormat.prototype
12.2.2
Intl.DateTimeFormat.supportedLocalesOf (locales [, options])
12.2.3
Internal Properties
12.3
Properties of the
Intl.DateTimeFormat Prototype Object
12.3.1
Intl.DateTimeFormat.prototype.constructor
12.3.2
Intl.DateTimeFormat.prototype.format
12.3.3
Intl.DateTimeFormat.prototype.resolvedOptions ()
12.4
Properties of
Intl.DateTimeFormat Instances
13
Locale Sensitive Functions of the
ECMAScript Language Specification
13.1
Properties of the String
Prototype Object
13.1.1
String.prototype.localeCompare (that [, locales [, options]])
13.2
Properties of the Number
Prototype Object
13.2.1
Number.prototype.toLocaleString ([locales [, options]])
13.3
Properties of the Date Prototype
Object
13.3.1
Date.prototype.toLocaleString ([locales [, options]])
13.3.2
Date.prototype.toLocaleDateString ([locales [, options]])
13.3.3
Date.prototype.toLocaleTimeString ([locales [, options]])
Annex A
(informative)
Implementation Dependent Behaviour
Introduction
The ECMAScript Internationalization API provides key
language-sensitive functionality as a complement to the ECMAScript
Language Specification, 5.1 edition or successor. Its functionality
has been selected from that of well-established
internationalization APIs such as those of the Internationalization
Components for Unicode (ICU) library, of the .NET framework,
or of the Java platform.
The API was developed by an ad-hoc group established by Ecma TC 39 in September 2010 based on a proposal by Nebojša Ćirić and
Jungshik Shin.
Internationalization of software is never complete. We expect significant enhancements in future editions of this
specification.
Editor
Norbert Lindenberg
Contributors
Eric Albright
Nebojša Ćirić
Peter Constable
Mark Davis
Richard Gillam
Steven Loomis
Mihai Nita
Addison Phillips
Roozbeh Pournader
Jungshik Shin
Shawn Steele
Allen Wirfs-Brock
Feedback provided by Erik Arvidsson, John J. Barton, Zbigniew Braniecki, Marcos Cáceres, Brendan Eich, John Emmons, Gordon P.
Hemsley, David Herman, Luke Hoban, Oliver Hunt, Suresh Jayabalan, Yehuda Katz, Mark S. Miller, Andrew Paprocki, Adam Peller,
Axel Rauschmayer, Andreas Rossberg, Alex Russell, Markus Scherer, Dmitry Soshnikov, Yusuke Suzuki, John Tamplin, Rick Waldron,
Anton Yatsenko, Nicholas Zakas.
This Ecma Standard has been adopted by the General Assembly of December 2012.
COPYRIGHT NOTICE
This document may be copied, published and distributed to
others, and certain derivative works of it may be prepared,
copied, published, and distributed, in whole or in part, provided that
the above copyright notice and this Copyright License and
Disclaimer are included on all such copies and derivative works. The
only derivative works that are permissible under this
Copyright License and Disclaimer are:
(i)
works which incorporate all or portion of this document for the purpose of providing commentary or explanation
(such as an annotated version of the document),
(ii)
works which incorporate all or portion of this document for the purpose of incorporating features that provide
accessibility,
(iii)
translations of this document into languages other than English and into different formats and
(iv)
works by making use of this specification in standard conformant products by implementing (e.g. by copy and
paste wholly or partly) the functionality therein.
However, the content of this document itself may not be modified in any way, including by removing the copyright notice or
references to Ecma International, except as required to translate it into languages other than English or into a different
format.
The official version of an Ecma International document is the English language version on the Ecma International website.
In the event of discrepancies between a translated version and the official version, the official version shall govern.
The limited permissions granted above are perpetual and will not be revoked by Ecma International or its successors or
assigns.
This document and the information contained herein is provided on an "AS IS" basis and ECMA INTERNATIONAL DISCLAIMS ALL
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
ECMAScript Internationalization API Specification
Scope
This Standard defines the application programming interface for ECMAScript objects that support programs that need to adapt
to the linguistic and cultural conventions used by different human languages and countries.
Conformance
A conforming implementation of the ECMAScript Internationalization API must conform to the ECMAScript Language Specification,
5.1 edition or successor, and must provide and support all the objects, properties, functions, and program semantics described
in this specification.
A conforming implementation of the ECMAScript Internationalization
API is permitted to provide additional objects,
properties, and functions beyond those described in this
specification. In particular, a conforming implementation of the
ECMAScript Internationalization API is permitted to provide properties
not described in this specification, and values for those
properties, for objects that are described in this specification. A
conforming implementation is not permitted to add optional
arguments to the functions defined in this specification.
A conforming implementation is permitted to accept additional values, and then have implementation-defined behaviour instead
of throwing a
RangeError
, for the following properties of
options
arguments:
The
options
property localeMatcher in all constructors and supportedLocalesOf methods.
The
options
properties usage and sensitivity in the Collator constructor.
The
options
properties style and currencyDisplay in the NumberFormat constructor.
The
options
properties minimumIntegerDigits,
minimumFractionDigits, maximumFractionDigits,
minimumSignificantDigits, and maximumSignificantDigits in the
NumberFormat constructor, provided that the additional values
are interpreted as integer values higher than the specified
limits.
The
options
property timeZone in the DateTimeFormat
constructor, provided that the additional acceptable input
values are case-insensitive matches of Zone or Link identifiers in
the IANA time zone database and are canonicalized to Zone
identifiers in the casing used in the database for the timeZone
property of the object returned by
DateTimeFormat.resolvedOptions, except that "Etc/GMT" shall be
canonicalized to "UTC".
The
options
properties listed in table 3 in the DateTimeFormat constructor.
The
options
property formatMatcher in the DateTimeFormat constructor.
Normative References
The following referenced documents are required for the application of this document. For dated references, only the edition
cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
ECMA-262, ECMAScript Language Specification, 5.1 edition or successor
NOTE
Throughout this document, the phrase “ES5,
”, where
is a sequence of numbers
separated by periods, may be used as shorthand for “ECMAScript Language Specification, 5.1 edition, subclause
”.
ISO/IEC 10646:2003: Information Technology – Universal Multiple-Octet Coded Character Set (UCS) plus Amendment 1:2005 and
Amendment 2:2006, plus additional amendments and corrigenda, or successor
ISO 4217:2008, Codes for the representation of currencies and funds, or successor
IETF BCP 47:
IETF RFC 6067, BCP 47 Extension U, or successor
IANA Time Zone Database
The Unicode Standard
, Version 5.0
, or successor
Unicode Technical Standard 35, Unicode Locale Data Markup Language, version 21.0.1 or successor
Overview
This section contains a non-normative overview of the ECMAScript Internationalization API.
4.1
Internationalization, Localization,
and Globalization
Internationalization of software means designing it such that it
supports or can be easily adapted to support the needs of
users speaking different languages and having different cultural
expectations, and enables worldwide communication between
them. Localization then is the actual adaptation to a specific
language and culture. Globalization of software is commonly
understood to be the combination of internationalization and
localization. Globalization starts at the lowest level by using a
text representation that supports all languages in the world, and
using standard identifiers to identify languages, countries,
time zones, and other relevant parameters. It continues with using a
user interface language and data presentation that the
user understands, and finally often requires product-specific
adaptations to the user’s language, culture, and
environment.
The ECMAScript Language Specification lays the foundation by
using Unicode for text representation and by providing a few
language-sensitive functions, but gives applications little control
over the behaviour of these functions. The ECMAScript
Internationalization API builds on this by providing a set of
customizable language-sensitive functionality. The API is useful
even for applications that themselves are not internationalized, as
even applications targeting only one language and one
region need to properly support that one language and region.
However, the API also enables applications that support multiple
languages and regions, even concurrently, as may be needed in server
environments.
4.2
API Overview
The ECMAScript Internationalization API is designed to complement the ECMAScript Language Specification by providing key
language-sensitive functionality. The API can be added to an implementation of the ECMAScript Language Specification, 5.1
edition or successor.
The ECMAScript Internationalization API provides three key pieces
of language-sensitive functionality that are required in
most applications: String comparison (collation), number formatting,
and date and time formatting. While the ECMAScript
Language Specification provides functions for this basic
functionality (String.prototype.localeCompare,
Number.prototype.toLocaleString, Date.prototype.toLocaleString,
Date.prototype.toLocaleDateString, and
Date.prototype.toLocaleTimeString), it leaves the actual behaviour
of these functions largely up to implementations to define.
The Internationalization API Specification provides additional
functionality, control over the language and over details of
the behaviour to be used, and a more complete specification of
required functionality.
Applications can use the API in two ways:
Directly, by using the constructors Intl.Collator,
Intl.NumberFormat, or Intl.DateTimeFormat to construct an object,
specifying a list of preferred languages and options to
configure the behaviour of the resulting object. The object then
provides a main function (compare or format), which can be
called repeatedly. It also provides a resolvedOptions
function, which the application can use to find out the exact
configuration of the object.
Indirectly, by using the functions of the ECMAScript Language Specification mentioned above, which are respecified in
this specification to accept the same arguments as the Collator, NumberFormat, and DateTimeFormat constructors and
produce the same results as their compare or format methods.
The Intl object is used to package all functionality defined in the ECMAScript Internationalization API to avoid name
collisions.
4.3
Implementation Dependencies
Due to the nature of internationalization, the API specification has to leave several details implementation dependent:
The set of locales that an implementation supports with adequate localizations:
Linguists estimate the number of
human languages to around 6000, and the more widely spoken ones
have variations based on regions or other parameters. Even
large locale data collections, such as the Common Locale Data
Repository, cover only a subset of this large set.
Implementations targeting resource-constrained devices may have
to further reduce the subset.
The exact form of localizations such as format patterns:
In many cases locale-dependent conventions are not
standardized, so different forms may exist side by side, or they
vary over time. Different internationalization libraries
may have implemented different forms, without any of them being
actually wrong. In order to allow this API to be
implemented on top of existing libraries, such variations have
to be permitted.
Subsets of Unicode:
Some operations, such as
collation, operate on strings that can include characters from the
entire Unicode character set. However, both the Unicode standard
and the ECMAScript standard allow implementations to
limit their functionality to subsets of the Unicode character
set. In addition, locale conventions typically don’t specify
the desired behaviour for the entire Unicode character set, but
only for those characters that are relevant for the
locale. While the Unicode Collation Algorithm combines a default
collation order for the entire Unicode character set with
the ability to tailor for local conventions, subsets and
tailorings still result in differences in behaviour.
Notational Conventions
This standard uses a subset of the notational conventions of the ECMAScript Language Specification, 5.1 edition:
Algorithm conventions, including the use of abstract operations, as described in
ES5, 5.2
Internal properties, as described in
ES5, 8.6.2
The List specification type, as described in
ES5,
8.8
NOTE
As described in the ECMAScript
Language Specification, algorithms are used to precisely
specify the required semantics of ECMAScript constructs, but are not
intended to imply the use of any specific implementation
technique. Internal properties are used to define the semantics of
object values, but are not part of the API. They are
defined purely for expository purposes. An implementation of the API
must behave as if it produced and operated upon internal
properties in the manner described here.
In addition, the Record specification type is used to describe data aggregations within the algorithms of this specification.
A Record type value consists of one or more named fields. The value of each field is an ECMAScript type value. Field names are
always enclosed in double brackets, for example [[field1]]. Field names can also be provided by a variable: The notation
“[[<
name
>]]” denotes a field whose name is given by the variable
name
, which must have a String
value. For example, if a variable
has the value
"a"
, then [[<
>]] denotes the field
[[a]].
In specification text and algorithms, dot notation may be used to refer to a specific field of a Record value. For example,
if
is a record, then
.[[field1]] is shorthand for “the field of
named [[field1]]”.
For ECMAScript objects, this standard may use variable-named internal properties: The notation “[[<
name
>]]”
denotes an internal property whose name is given by the variable
name
, which must have a String value. For example,
if a variable
has the value
"a"
, then [[<
>]] denotes the [[a]] internal
property.
Identification of Locales, Time Zones, and
Currencies
This clause describes the String values used in the ECMAScript Internationalization API to identify locales, currencies, and
time zones.
6.1
Case Sensitivity and Case Mapping
The String values used to identify locales, currencies, and time zones are interpreted in a case-insensitive manner,
treating the Unicode Basic Latin characters "A" to "Z" (U+0041 to U+005A) as equivalent to the corresponding Basic Latin
characters "a" to "z" (U+0061 to U+007A). No other case folding equivalences are applied. When mapping to upper case, a
mapping shall be used that maps characters in the range "a" to "z" (U+0061 to U+007A) to the corresponding characters in the
range "A" to "Z" (U+0041 to U+005A) and maps no other characters to the latter range.
EXAMPLES
"ß" (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).
6.2
Language Tags
The ECMAScript Internationalization API identifies locales using language tags as defined by IETF BCP 47 (RFCs 5646 and
4647 or their successors), which may include extensions such as those registered through RFC 6067. Their canonical form is
specified in RFC 5646 section 4.5 or its successor.
BCP 47 language tags that meet those validity criteria of RFC 5646 section 2.2.9 that can be verified without reference to
the IANA Language Subtag Registry are considered structurally valid. All structurally valid language tags are valid for use
with the APIs defined by this standard. However, the set of locales and thus language tags that an implementation supports
with adequate localizations is implementation dependent. The constructors Collator, NumberFormat, and DateTimeFormat map the
language tags used in requests to locales supported by their respective implementations.
6.2.1
Unicode Locale Extension
Sequences
This standard uses the term “Unicode locale extension sequence”
for any substring of a language tag that starts with a
separator "-" and the singleton "u" and includes the maximum
sequence of following non-singleton subtags and their preceding
"-" separators.
6.2.2
IsStructurallyValidLanguageTag
(locale)
The IsStructurallyValidLanguageTag abstract operation verifies that the
locale
argument (which must be a
String value)
represents a well-formed BCP 47 language tag as specified in RFC 5646 section 2.1, or successor,
does not include duplicate variant subtags, and
does not include duplicate singleton subtags.
The abstract operation returns true if
locale
can be
generated from the ABNF grammar in section 2.1 of the
RFC, starting with Language-Tag, and does not contain duplicate
variant or singleton subtags (other than as a private use
subtag). It returns false otherwise. Terminal value characters in
the grammar are interpreted as the Unicode equivalents of
the ASCII octet values given.
6.2.3
CanonicalizeLanguageTag
(locale)
The CanonicalizeLanguageTag abstract operation returns the canonical and case-regularized form of the locale argument
(which must be a String value that is a structurally valid BCP 47 language tag as verified by the
IsStructurallyValidLanguageTag
abstract operation). It takes the steps specified in RFC 5646 section
4.5, or successor, to bring the language tag into canonical form, and to regularize the case of the subtags, but does not
take the steps to bring a language tag into “extlang form” and to reorder variant subtags.
The specifications for extensions to BCP 47 language tags, such as RFC 6067, may include canonicalization rules for the
extension subtag sequences they define that go beyond the canonicalization rules of RFC 5646 section 4.5. Implementations
are allowed, but not required, to apply these additional rules.
6.2.4
DefaultLocale ()
The DefaultLocale abstract operation returns a String value representing the structurally valid (
6.2.2
) and canonicalized (
6.2.3
) BCP 47 language tag for the host
environment’s current locale.
6.3
Currency Codes
The ECMAScript Internationalization API identifies currencies using 3-letter currency codes as defined by ISO 4217. Their
canonical form is upper case.
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.
6.3.1
IsWellFormedCurrencyCode
(currency)
The IsWellFormedCurrencyCode abstract operation verifies that the currency argument (after conversion to a String value)
represents a well-formed 3-letter ISO currency code. The following steps are taken:
Let
be ToString(
currency
).
Let
normalized
be the result of mapping
to upper case as described in
6.1
If the string length of
normalized
is not 3, return
false
If
normalized
contains any character that is not in the range "A" to "Z" (U+0041 to U+005A), return
false
Return
true
6.4
Time Zone Names
The ECMAScript Internationalization API defines a single time zone name,
"UTC"
, which identifies the UTC time
zone.
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 (if different from
UTC) in formatting.
NOTE
The Conformance clause allows implementations to accept additional time zone names under
specified conditions.
Requirements for Standard Built-in
ECMAScript Objects
Unless specified otherwise in this document, the objects, functions, and constructors described in this standard are subject
to the generic requirements and restrictions specified for standard built-in ECMAScript objects in the ECMAScript Language
Specification 5.1 edition,
introduction of clause 15
, or
successor.
The Intl Object
The Intl object is a standard built-in object that is the initial value of the
Intl
property of the global
object.
The value of the [[Prototype]] internal property of the Intl object is the built-in Object prototype object specified by the
ECMAScript Language Specification.
The Intl object does not have a [[Construct]] internal property; 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 property; it is not possible to invoke the Intl object as a function.
8.1
Properties of the Intl Object
The value of each of the standard built-in properties of the Intl object is a constructor. The behaviour of these
constructors is specified in the following clauses: Collator (
10
), NumberFormat (
11
), and DateTimeFormat (
12
).
Locale and Parameter Negotiation
The constructors for the objects providing locale sensitive
services, Collator, NumberFormat, and DateTimeFormat, use a
common pattern to negotiate the requests represented by the locales
and options arguments against the actual capabilities of
their implementations. The common behaviour is described here in terms
of internal properties describing the capabilities and of
abstract operations using these internal properties.
9.1
Internal Properties of Service
Constructors
The constructors Intl.Collator, Intl.NumberFormat, and Intl.DateTimeFormat have the following internal properties:
[[availableLocales]] is a
List
that contains structurally valid (
6.2.2
and canonicalized (
6.2.3
) BCP 47 language tags identifying the locales for which the
implementation provides the functionality of the constructed objects. Language tags on the list must not have a Unicode
locale extension sequence. The list must include the value returned by the
DefaultLocale
abstract
operation (
6.2.4
), and must not include duplicates. Implementations must include in
[[availableLocales]] locales that can serve as fallbacks in the algorithm used to resolve locales (see
9.2.5
).
For example, implementations that provide a "de-DE" locale must include
a "de" locale that
can serve as a fallback for requests such as "de-AT" and
"de-CH". For locales that in current usage would include a script
subtag (such as Chinese locales), old-style language tags
without script subtags must be included such that, for example,
requests for "zh-TW" and "zh-HK" lead to output in traditional
Chinese rather than the default simplified Chinese. The
ordering of the locales within [[availableLocales]] is
irrelevant.
[[relevantExtensionKeys]] is an array of keys of the language tag extensions defined in Unicode Technical Standard 35
that are relevant for the functionality of the constructed objects.
[[sortLocaleData]] and [[searchLocaleData]] (for
Intl.Collator) and [[localeData]] (for Intl.NumberFormat and
Intl.DateTimeFormat) are objects that have properties for each
locale contained in [[availableLocales]]. The value of each
of these properties must be an object that has properties for
each key contained in [[relevantExtensionKeys]]. The value
of each of these properties must be a non-empty array of those
values defined in Unicode Technical Standard 35 for the
given key that are supported by the implementation for the given
locale, with the first element providing the default
value.
EXAMPLE
An implementation of DateTimeFormat might include the language tag "th" in its
[[availableLocales]] internal property, and must (according to
12.2.3
include the key "ca" in its
[[relevantExtensionKeys]] internal property. For Thai, the
"buddhist" calendar is usually the default, but an implementation
might also support the calendars "gregory", "chinese", and
"islamicc" for the locale "th". The [[localeData]] internal
property would therefore at least include {"th": {ca: ["buddhist",
"gregory", "chinese", "islamicc"]}}.
9.2
Abstract Operations
Where the following abstract operations take an
availableLocales
argument, it must be an [[availableLocales]]
List
as specified in
9.1
9.2.1
CanonicalizeLocaleList
(locales)
The abstract operation CanonicalizeLocaleList takes the following steps:
If
locales
is
undefined
, then
Return a new empty
List
Let
seen
be a new empty
List
If
locales
is a String value, then
Let
locales
be a new array created as if by the expression
new Array(locales)
where
Array
is the standard built-in constructor with that name and
locales
is the value of
locales
Let
be ToObject(
locales
).
Let
lenValue
be the result of calling the [[Get]] internal method of
with the argument
"length"
Let
len
be ToUint32(
lenValue
).
Let
be 0.
Repeat, while
len
Let
Pk
be ToString(
).
Let
kPresent
be the result of calling the [[HasProperty]] internal method of
with argument
Pk
If
kPresent
is
true
, then
Let
kValue
be the result of calling the [[Get]] internal method of
with argument
Pk
If the type of
kValue
is not String or Object, then throw a
TypeError
exception.
Let
tag
be ToString(
kValue
).
If the result of calling the abstract operation
IsStructurallyValidLanguageTag
(defined in
6.2.2
), passing
tag
as the argument, is
false
, then throw a
RangeError
exception.
Let
tag
be the result of calling the abstract operation
CanonicalizeLanguageTag
(defined in
6.2.3
), passing
tag
as the argument.
If
tag
is not an element of
seen
, then append
tag
as the last element of
seen
Increase
by 1.
Return
seen
NOTE
Non-normative summary: The abstract operation interprets the
locales
argument
as an array and copies its elements into a
List
, validating the elements as structurally valid
language tags and canonicalizing them, and omitting duplicates.
NOTE
Requiring
kValue
to be a String or Object means that the Number value
NaN
will not be interpreted as the language tag
"nan"
, which stands for Min Nan Chinese.
9.2.2
BestAvailableLocale
(availableLocales, locale)
The BestAvailableLocale abstract operation compares the provided argument
locale
, which must be a String value
with a structurally valid and canonicalized BCP 47 language tag, against the locales in
availableLocales
and
returns either the longest non-empty prefix of
locale
that is an element of
availableLocales
, or
undefined
if there is no such element. It uses the fallback mechanism of RFC 4647, section 3.4. The following steps
are taken:
Let
candidate
be
locale
Repeat
If
availableLocales
contains an element equal to
candidate
, then return
candidate
Let
pos
be the character index of the last occurrence of
"-"
(U+002D) within
candidate
If that character does not occur, return
undefined
If
pos
≥ 2 and the character
"-"
occurs at index
pos
-2 of
candidate
, then
decrease
pos
by 2.
Let
candidate
be the substring of
candidate
from position 0, inclusive, to position
pos
exclusive.
9.2.3
LookupMatcher (availableLocales,
requestedLocales)
The LookupMatcher abstract operation compares
requestedLocales
, which must be a
List
as
returned by
CanonicalizeLocaleList
, against the locales in
availableLocales
and
determines the best available language to meet the request. The following steps are taken:
Let
be 0.
Let
len
be the number of elements in
requestedLocales
Let
availableLocale
be
undefined
Repeat while
len
and
availableLocale
is
undefined
Let
locale
be the element of
requestedLocales
at 0-origined list position
Let
noExtensionsLocale
be the String value that is
locale
with all Unicode locale extension
sequences removed.
Let
availableLocale
be the result of calling the
BestAvailableLocale
abstract
operation (defined in
9.2.2
) with arguments
availableLocales
and
noExtensionsLocale
Increase
by 1.
Let
result
be a new
Record
If
availableLocale
is not
undefined
, then
Set
result
.[[locale]] to
availableLocale
If
locale
and
noExtensionsLocale
are not the same String value, then
Let
extension
be the String value consisting of the first substring of
locale
that is a Unicode
locale extension sequence.
Let
extensionIndex
be the character position of the initial
"-"
of the first Unicode
locale extension sequence within
locale
Set
result
.[[extension]] to
extension
Set
result
.[[extensionIndex]] to
extensionIndex
Else
Set
result
.[[locale]] to the value returned by the
DefaultLocale
abstract
operation (defined in
6.2.4
).
Return
result
NOTE
The algorithm is based on the Lookup algorithm described in RFC 4647 section 3.4, but
options specified through Unicode locale extension sequences are ignored in the lookup. Information about such
subsequences is returned separately. The abstract operation returns a record with a [[locale]] field, whose value is the
language tag of the selected locale, which must be an element of
availableLocales
If the language tag of the
request locale that led to the selected locale contained a
Unicode locale extension sequence, then the returned record
also contains an [[extension]] field whose value is the first
Unicode locale extension sequence, and an [[extensionIndex]]
field whose value is the index of the first Unicode locale
extension sequence within the request locale language tag.
9.2.4
BestFitMatcher
(availableLocales, requestedLocales)
The BestFitMatcher abstract operation compares
requestedLocales
, which must be a
List
as
returned by
CanonicalizeLocaleList
, against the locales in
availableLocales
and
determines the best available language to meet the request. The algorithm is implementation dependent, but should produce
results that a typical user of the requested locales would perceive as at least as good as those produced by the
LookupMatcher
abstract operation. Options specified through Unicode locale extension sequences must be
ignored by the algorithm. Information about such subsequences is returned separately. The abstract operation returns a
record with a [[locale]] field, whose value is the language tag of the selected locale, which must be an element of
availableLocales
. If the language tag of the request locale that led to the selected locale contained a Unicode
locale extension sequence, then the returned record also contains an [[extension]] field whose value is the first Unicode
locale extension sequence, and an [[extensionIndex]] field whose value is the index of the first Unicode locale extension
sequence within the request locale language tag.
9.2.5
ResolveLocale (availableLocales,
requestedLocales, options, relevantExtensionKeys, localeData)
The ResolveLocale abstract operation compares a BCP 47 language priority list
requestedLocales
against the
locales in
availableLocales
and determines the best available language to meet the request.
availableLocales
and
requestedLocales
must be provided as
List
values,
options
as a
Record
The following steps are taken:
Let
matcher
be the value of
options
.[[localeMatcher]].
If
matcher
is
"lookup"
, then
Let
be the result of calling the
LookupMatcher
abstract operation (defined in
9.2.3
) with arguments
availableLocales
and
requestedLocales
Else
Let
be the result of calling the
BestFitMatcher
abstract operation (defined in
9.2.4
) with arguments
availableLocales
and
requestedLocales
Let
foundLocale
be the value of
.[[locale]].
If
has an [[extension]] field, then
Let
extension
be the value of
.[[extension]].
Let
extensionIndex
be the value of
.[[extensionIndex]].
Let
split
be the standard built-in function object defined in
ES5, 15.5.4.14
Let
extensionSubtags
be the result of calling the [[Call]] internal method of
split
with
extension
as the
this
value and an argument list containing the single item
"-"
Let
extensionSubtagsLength
be the result of calling the [[Get]] internal method of
extensionSubtags
with argument
"length"
Let
result
be a new
Record
Set
result
.[[dataLocale]] to
foundLocale
Let
supportedExtension
be
"-u"
Let
be 0.
Let
len
be the result of calling the [[Get]] internal method of
relevantExtensionKeys
with argument
"length"
Repeat while
len
Let
key
be the result of calling the [[Get]] internal method of
relevantExtensionKeys
with argument
ToString(
).
Let
foundLocaleData
be the result of calling the [[Get]] internal method of
localeData
with the
argument
foundLocale
Let
keyLocaleData
be the result of calling the [[Get]] internal method of
foundLocaleData
with the
argument
key
Let
value
be the result of calling the [[Get]] internal method of
keyLocaleData
with argument
"0"
Let
supportedExtensionAddition
be
""
Let
indexOf
be the standard built-in function object defined in
ES5, 15.4.4.14
If
extensionSubtags
is not
undefined
, then
Let
keyPos
be the result of calling the [[Call]] internal method of
indexOf
with
extensionSubtags
as the
this
value and an argument list containing the single item
key
If
keyPos
≠ -1, then
If
keyPos
+ 1 <
extensionSubtagsLength
and the length of the result of calling the
[[Get]] internal method of
extensionSubtags
with argument ToString(
keyPos
+1) is greater
than 2, then
Let
requestedValue
be the result of calling the [[Get]] internal method of
extensionSubtags
with argument ToString(
keyPos
+ 1).
Let
valuePos
be the result of calling the [[Call]] internal method of
indexOf
with
keyLocaleData
as the
this
value and an argument list containing the single item
requestedValue
If
valuePos
≠ -1, then
Let
value
be
requestedValue
Let
supportedExtensionAddition
be the concatenation of
"-"
key
"-"
, and
value
Else
Let
valuePos
be the result of calling the [[Call]] internal method of
indexOf
with
keyLocaleData
as the
this
value and an argument list containing the single item
"true"
If
valuePos
≠ -1, then
Let
value
be
"true"
If
options
has a field [[<
key
>]], then
Let
optionsValue
be the value of
options
.[[<
key
>]].
If the result of calling the [[Call]] internal method of
indexOf
with
keyLocaleData
as the
this
value and an argument list containing the single item
optionsValue
is not -1, then
If
optionsValue
is not equal to
value
, then
Let
value
be
optionsValue
Let
supportedExtensionAddition
be
""
Set
result
.[[<
key
>]] to
value
Append
supportedExtensionAddition
to
supportedExtension
Increase
by 1.
If the length of
supportedExtension
is greater than 2, then
Let
preExtension
be the substring of
foundLocale
from position 0, inclusive, to position
extensionIndex
, exclusive.
Let
postExtension
be the substring of
foundLocale
from position
extensionIndex
to the end of
the string.
Let
foundLocale
be the concatenation of
preExtension
supportedExtension
, and
postExtension
Set
result
.[[locale]] to
foundLocale
Return
result
NOTE
Non-normative summary: Two
algorithms are available to match the locales: the Lookup
algorithm described in RFC 4647 section 3.4, and an
implementation dependent best-fit algorithm. Independent of the locale
matching algorithm, options specified through Unicode locale
extension sequences are negotiated separately, taking the
caller’s relevant extension keys and locale data as well as
client-provided options into consideration. The abstract
operation returns a record with a [[locale]] field whose value
is the language tag of the selected locale, and fields for
each key in
relevantExtensionKeys
providing the selected value for that key.
9.2.6
LookupSupportedLocales
(availableLocales, requestedLocales)
The LookupSupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list
requestedLocales
for which
availableLocales
has a matching locale when using the BCP 47 Lookup
algorithm. Locales appear in the same order in the returned list as in
requestedLocales
. The following steps are
taken:
Let
len
be the number of elements in
requestedLocales
Let
subset
be a new empty
List
Let
be 0.
Repeat while
len
Let
locale
be the element of
requestedLocales
at 0-origined list position
Let
noExtensionsLocale
be the String value that is
locale
with all Unicode locale extension
sequences removed.
Let
availableLocale
be the result of calling the
BestAvailableLocale
abstract
operation (defined in
9.2.2
) with arguments
availableLocales
and
noExtensionsLocale
If
availableLocale
is not
undefined
, then append
locale
to the end of
subset
Increment
by 1.
Let
subsetArray
be a new Array object whose elements are the same values in the same order as the elements of
subset
Return
subsetArray
9.2.7
BestFitSupportedLocales
(availableLocales, requestedLocales)
The BestFitSupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list
requestedLocales
for which
availableLocales
has a matching locale when using the Best Fit Matcher
algorithm. Locales appear in the same order in the returned list as in
requestedLocales
. The steps taken are
implementation dependent.
9.2.8
SupportedLocales
(availableLocales, requestedLocales, options)
The SupportedLocales abstract operation returns the subset of the provided BCP 47 language priority list
requestedLocales
for which
availableLocales
has a matching locale. Two algorithms are available to
match the locales: the Lookup algorithm described in RFC 4647 section 3.4, and an implementation dependent best-fit
algorithm. Locales appear in the same order in the returned list as in
requestedLocales
. The following steps are
taken:
If
options
is not
undefined
, then
Let
options
be ToObject(
options
).
Let
matcher
be the result of calling the [[Get]] internal method of
options
with argument
"localeMatcher"
If
matcher
is not
undefined
, then
Let
matcher
be ToString(
matcher
).
If
matcher
is not
"lookup"
or
"best fit"
, then throw a
RangeError
exception.
If
matcher
is
undefined
or
"best fit"
, then
Let
subset
be the result of calling the
BestFitSupportedLocales
abstract operation
(defined in
9.2.7
) with arguments
availableLocales
and
requestedLocales
Else
Let
subset
be the result of calling the
LookupSupportedLocales
abstract operation
(defined in
9.2.6
) with arguments
availableLocales
and
requestedLocales
For each named own property name
of
subset
Let
desc
be the result of calling the [[GetOwnProperty]] internal method of
subset
with
Set
desc
.[[Writable]] to
false
Set
desc
.[[Configurable]] to
false
Call the [[DefineOwnProperty]] internal method of
subset
with
desc
, and
true
as
arguments.
Return
subset
9.2.9
GetOption (options, property,
type, values, fallback)
The GetOption abstract operation extracts the value of the property named
property
from the provided
options
object, converts it to the required
type
, checks whether it is one of a
List
of allowed
values
, and fills in a
fallback
value if necessary.
Let
value
be the result of calling the [[Get]] internal method of
options
with argument
property
If
value
is not
undefined
, then
Assert:
type
is
"boolean"
or
"string"
If
type
is
"boolean"
, then let
value
be ToBoolean(
value
).
If
type
is
"string"
, then let
value
be ToString(
value
).
If
values
is not
undefined
, then
If
values
does not contain an element equal to
value
, then throw a
RangeError
exception.
Return
value
Else return
fallback
9.2.10
GetNumberOption (options,
property, minimum, maximum, fallback)
The GetNumberOption abstract operation extracts a property value from the provided options object, converts it to a
Number value, checks whether it is in the allowed range, and fills in a fallback value if necessary.
Let
value
be the result of calling the [[Get]] internal method of
options
with argument
property
If
value
is not
undefined
, then
Let
value
be ToNumber(
value
).
If
value
is
NaN
or less than
minimum
or greater than
maximum
, throw a
RangeError
exception.
Return floor(
value
).
Else return
fallback
10
Collator Objects
10.1
The Intl.Collator Constructor
The Intl.Collator constructor is a standard built-in property of the Intl object. Behaviour common to all service
constructor properties of the Intl object is specified in
9.1
10.1.1
Initializing an Object as a
Collator
10.1.1.1
InitializeCollator
(collator, locales, options)
The abstract operation InitializeCollator accepts the arguments
collator
(which must be an object),
locales
, and
options
. It initializes
collator
as a Collator object.
Several steps in the algorithm use values from the following table, which associates Unicode locale extension keys,
property names, types, and allowable values:
Table 1
– Collator options settable through both extension keys and options properties
Key
Property
Type
Values
kn
numeric
"boolean"
kf
caseFirst
"string"
"upper", "lower", "false"
The following steps are taken:
If
collator
has an [[initializedIntlObject]] internal property with value
true
, throw a
TypeError
exception.
Set the [[initializedIntlObject]] internal property of
collator
to
true
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
If
options
is
undefined
, then
Let
options
be the result of creating a new object as if by the expression
new Object()
where
Object
is the standard built-in constructor with that name.
Else
Let
options
be ToObject(
options
).
Let
be the result of calling the
GetOption
abstract operation (defined in
9.2.9
) with arguments
options
"usage"
"string"
, a
List
containing the two String values
"sort"
and
"search"
, and
"sort"
Set the [[usage]] internal property of
collator
to
Let
Collator
be the standard built-in object that is the initial value of Intl.Collator.
If
is
"sort"
, then let
localeData
be the value of the [[sortLocaleData]] internal
property of
Collator
; else let
localeData
be the value of the [[searchLocaleData]] internal property
of
Collator
Let
opt
be a new
Record
Let
matcher
be the result of calling the
GetOption
abstract operation with arguments
options
"localeMatcher"
"string"
, a
List
containing the two
String values
"lookup"
and
"best fit"
, and
"best fit"
Set
opt
.[[localeMatcher]] to
matcher
For each row in
Table 1
, except the header row, do:
Let
key
be the name given in the Key column of the row.
Let
value
be the result of calling the
GetOption
abstract operation, passing as
arguments
options
, the name given in the Property column of the row, the string given in the Type column
of the row, a
List
containing the Strings given in the Values column of the row or
undefined
if no strings are given, and
undefined
If the string given in the Type column of the row is
"boolean"
and
value
is not
undefined
, then
Let
value
be ToString(
value
).
Set
opt
.[[<
key
>]] to
value
Let
relevantExtensionKeys
be the value of the [[relevantExtensionKeys]] internal property of
Collator
Let
be the result of calling the
ResolveLocale
abstract operation (defined in
9.2.5
) with the [[availableLocales]] internal property of
Collator
requestedLocales
opt
relevantExtensionKeys
, and
localeData
Set the [[locale]] internal property of
collator
to the value of
.[[locale]].
Let
be 0.
Let
len
be the result of calling the [[Get]] internal method of
relevantExtensionKeys
with argument
"length"
Repeat while
len
Let
key
be the result of calling the [[Get]] internal method of
relevantExtensionKeys
with
argument ToString(
).
If
key
is
"co"
, then
Let
property
be
"collation"
Let
value
be the value of
.[[co]].
If
value
is
null
, then let
value
be
"default"
Else use the row of
Table 1
that contains the value of
key
in the Key column:
Let
property
be the name given in the Property column of the row.
Let
value
be the value of
.[[<
key
>]].
If the name given in the Type column of the row is
"boolean"
, then let
value
be the
result of comparing
value
with
"true"
Set the [[<
property
>]] internal property of
collator
to
value
Increase
by 1.
Let
be the result of calling the
GetOption
abstract operation with arguments
options
"sensitivity"
"string"
, a
List
containing the four
String values
"base"
"accent"
"case"
, and
"variant"
, and
undefined
If
is
undefined
, then
If
is
"sort"
, then let s be
"variant"
Else
Let
dataLocale
be the value of
.[[dataLocale]].
Let
dataLocaleData
be the result of calling the [[Get]] internal operation of
localeData
with
argument
dataLocale
Let
be the result of calling the [[Get]] internal operation of
dataLocaleData
with argument
"sensitivity"
Set the [[sensitivity]] internal property of
collator
to
Let
ip
be the result of calling the
GetOption
abstract operation with arguments
options
"ignorePunctuation"
"boolean"
undefined
, and
false
Set the [[ignorePunctuation]] internal property of
collator
to
ip
Set the [[boundCompare]] internal property of
collator
to
undefined
Set the [[initializedCollator]] internal property of
collator
to
true
10.1.2
The Intl.Collator Constructor
Called as a Function
10.1.2.1
Intl.Collator.call (this
[, locales [, options]])
When
Intl.Collator
is called as a function rather than as a constructor, it accepts the optional arguments
locales
and
options
and takes the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
If
this
is the standard built-in Intl object defined in
or
undefined
, then
Return the result of creating a new object as if by the expression new
Intl.Collator(locales,
options)
, where
Intl.Collator
is the standard built-in constructor defined in
10.1.3
Let
obj
be the result of calling ToObject passing the
this
value as the argument.
If the [[Extensible]] internal property of
obj
is
false
, throw a
TypeError
exception.
Call the
InitializeCollator
abstract operation (defined in
10.1.1.1
) with arguments
obj
locales
, and
options
Return
obj
10.1.3
The Intl.Collator Constructor
Used in a new Expression
10.1.3.1
new Intl.Collator
([locales [, options]])
When
Intl.Collator
is called as part of a
new
expression, it is a constructor: it initializes
the newly created object.
The [[Prototype]] internal property of the newly constructed object is set to the original Intl.Collator prototype
object, the one that is the initial value of
Intl.Collator.prototype
10.2.1
).
The [[Extensible]] internal property of the newly constructed object is set to
true
Collator-specific properties of the newly constructed object are set using the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Call the
InitializeCollator
abstract operation (defined in
10.1.1.1
), passing as arguments the newly constructed object,
locales
, and
options
10.2
Properties of the Intl.Collator
Constructor
Besides the internal properties and the
length
property (whose value is 0), the Intl.Collator constructor has
the following properties:
10.2.1
Intl.Collator.prototype
The value of
Intl.Collator.prototype
is the built-in Intl.Collator prototype object (
10.3
).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
10.2.2
Intl.Collator.supportedLocalesOf (locales [, options])
When the
supportedLocalesOf
method of Intl.Collator is called, the following steps are taken:
If
options
is not provided, then let
options
be
undefined
Let
availableLocales
be the value of the [[availableLocales]] internal property of the standard built-in object
that is the initial value of Intl.Collator.
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
Return the result of calling the
SupportedLocales
abstract operation (defined in
9.2.8
) with arguments
availableLocales
requestedLocales
, and
options
The value of the
length
property of the
supportedLocalesOf
method is
10.2.3
Internal Properties
The value of the [[availableLocales]] internal property is implementation defined within the constraints described in
9.1
The value of the [[relevantExtensionKeys]] internal property is an array that must include the element
"co"
may include any or all of the elements
"kn"
and
"kf"
, and must not include any other elements.
NOTE
Unicode Technical Standard 35
describes ten locale extension keys that are relevant to
collation: "co" for collator usage and specializations, "ka" for
alternate handling, "kb" for backward second level
weight, "kc" for case level, "kn" for numeric, "kh" for hiragana
quaternary, "kk" for normalization, "kf" for case first,
"kr" for reordering, "ks" for collation strength, and "vt" for
variable top. Collator, however, requires that the usage is
specified through the usage property of the options object,
alternate handling through the ignorePunctuation property of
the options object, and case level and the strength through the
sensitivity property of the options object. The "co" key
in the language tag is supported only for collator
specializations, and the keys "kb", "kh", "kk", "kr", and "vt" are not
allowed in this version of the Internationalization API. Support
for the remaining keys is implementation dependent.
The values of the [[sortLocaleData]] and [[searchLocaleData]] internal properties are implementation defined within the
constraints described in
9.1
and the following additional constraints:
The first element of [[sortLocaleData]][locale].co and [[searchLocaleData]][locale].co must be null for all locale
values.
The values
"standard"
and
"search"
must not be used as elements in any
[[sortLocaleData]][locale].co and [[searchLocaleData]][locale].co array.
[[searchLocaleData]][locale] must have a sensitivity property with a String value equal to
"base"
"accent"
"case"
, or
"variant"
for all locale values.
10.3
Properties of the Intl.Collator
Prototype Object
The Intl.Collator prototype object is itself an Intl.Collator instance as specified in
10.4
, whose
internal properties are set as if it had been constructed by the expression
Intl.Collator.call({})
with the
standard built-in values of Intl.Collator and Function.prototype.call.
In the following descriptions of functions that are properties or [[Get]] attributes of properties of the Intl.Collator
prototype object, the phrase “this Collator object” refers to the object that is the
this
value for the invocation of
the function; a
TypeError
exception is thrown if the this value is not an object or an object that does not have an
[[initializedCollator]] internal property with value
true
10.3.1
Intl.Collator.prototype.constructor
The initial value of
Intl.Collator.prototype.constructor
is the built-in Intl.Collator constructor.
10.3.2
Intl.Collator.prototype.compare
This named accessor property returns a function that compares two strings according to the sort order of this Collator
object.
The value of the [[Get]] attribute is a function that takes the following steps:
If the [[boundCompare]] internal property of this Collator object is
undefined
, then:
Let
be a Function object, with internal properties set as specified for built-in functions in
ES5, 15
, or successor, and the length property set
to 2, that takes the arguments
and
and performs the following steps:
If
is not provided, then let
be
undefined
If
is not provided, then let
be
undefined
Let
be ToString(
).
Let
be ToString(
).
Return the result of calling the
CompareStrings
abstract operation (defined
below) with arguments
this
, and
Let
bind
be the standard built-in function object defined in
ES5, 15.3.4.5
Let
bc
be the result of calling the [[Call]] internal method of
bind
with
as the
this
value and an argument
List
containing the single item
this
Set the [[boundCompare]] internal property of this Collator object to
bc
Return the value of the [[boundCompare]] internal property of this Collator object.
NOTE
The function returned by [[Get]] is bound to this Collator object so that it can be passed
directly to Array.prototype.sort or other functions.
The value of the [[Set]] attribute is
undefined
When the
CompareStrings
abstract operation is called with arguments
collator
(which must be an object initialized as a Collator),
and
(which must be String values), it returns
a Number other than
NaN
that represents the result of a locale-sensitive String comparison of
with
. The two Strings are compared in an implementation-defined fashion. The result is intended to order String
values in the sort order specified by the effective locale and collation options computed during construction of
collator
, and will be negative, zero, or positive, depending on whether
comes before
in
the sort order, the Strings are equal under the sort order, or
comes after
in the sort order,
respectively. String values must be interpreted as UTF-16 code unit sequences, and a surrogate pair (a code unit in the
range 0xD800 to 0xDBFF followed by a code unit in the range 0xDC00 to 0xDFFF) within a string must be interpreted as the
corresponding code point.
The sensitivity of
collator
is interpreted as follows:
base: Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A.
accent: Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples: a
≠ b, a ≠ á, a = A.
case: Only strings that differ in base letters or case compare as unequal. Examples: a ≠ b, a = á, a ≠ A.
variant: Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other
differences may also be taken into consideration. Examples: a ≠ b, a ≠ á, a ≠ A.
NOTE
In some languages, certain letters with diacritic marks are considered base letters. For
example, in Swedish, “ö” is a base letter that’s different from “o”.
If the collator is set to ignore punctuation, then strings that differ only in punctuation compare as equal.
For the interpretation of options settable through extension keys, see Unicode Technical Standard 35.
The
CompareStrings
abstract operation with any given
collator
argument, if
considered as a function of the remaining two arguments
and
, must be a consistent comparison
function (as defined in
ES5, 15.4.4.11
) on the set
of all Strings.
The actual return values are implementation-defined to permit implementers to encode additional information in the value.
The method is required to return 0 when comparing Strings that are considered canonically equivalent by the Unicode
standard.
NOTE 1
It is recommended that the
CompareStrings
abstract
operation be implemented following Unicode Technical Standard 10, Unicode Collation Algorithm (available at
), using tailorings for the effective locale
and collation options of
collator
. It is recommended that implementations use the tailorings provided by the
Common Locale Data Repository (available at
).
NOTE 2
Applications should not assume that the behaviour of the
CompareStrings
abstract operation for Collator instances with the same resolved options will
remain the same for different versions of the same implementation.
10.3.3
Intl.Collator.prototype.resolvedOptions ()
This function provides access to the locale and collation options computed during initialization of the object.
The function returns a new object whose properties and
attributes are set as if constructed by an object literal
assigning to each of the following properties the value of the
corresponding internal property of this Collator object (see
10.4
): locale, usage, sensitivity, ignorePunctuation, collation, as well as those properties shown
in
Table 1
whose keys are included in the [[relevantExtensionKeys]] internal property of the standard
built-in object that is the initial value of Intl.Collator.
10.4
Properties of Intl.Collator
Instances
Intl.Collator instances inherit properties from the Intl.Collator prototype object. Their [[Class]] internal property value
is
"Object"
Intl.Collator instances and other objects that have been successfully initialized as a Collator have
[[initializedIntlObject]] and [[initializedCollator]] internal properties whose values are
true
Objects that have been successfully initialized as a Collator also have several internal properties that are computed by
the constructor:
[[locale]] is a String value with the language tag of the locale whose localization is used for collation.
[[usage]] is one of the String values
"sort"
or
"search"
, identifying the collator usage.
[[sensitivity]] is one of the String values
"base"
"accent"
"case"
, or
"variant"
, identifying the collator’s sensitivity.
[[ignorePunctuation]] is a Boolean value, specifying whether punctuation should be ignored in comparisons.
[[collation]] is a String value with the “type” given in Unicode Technical Standard 35 for the collation, except that
the values
"standard"
and
"search"
are not allowed, while the value
"default"
is
allowed.
Objects that have been successfully initialized as a Collator also have the following internal properties if the key
corresponding to the name of the internal property in
Table 1
is included in the
[[relevantExtensionKeys]] internal property of Intl.Collator:
[[numeric]] is a Boolean value, specifying whether numeric sorting is used.
[[caseFirst]] is a String value; allowed values are specified in
Table 1
Finally, objects that have been successfully initialized as a Collator have a [[boundCompare]] internal property that
caches the function returned by the compare accessor (
10.3.2
).
11
NumberFormat Objects
11.1
The Intl.NumberFormat
Constructor
The NumberFormat constructor is a standard built-in property of the Intl object. Behaviour common to all service
constructor properties of the Intl object is specified in
9.1
11.1.1
Initializing an Object as a
NumberFormat
11.1.1.1
InitializeNumberFormat
(numberFormat, locales, options)
The abstract operation InitializeNumberFormat accepts the arguments
numberFormat
(which must be an object),
locales
, and
options
. It initializes
numberFormat
as a NumberFormat object.
The following steps are taken:
If
numberFormat
has an [[initializedIntlObject]] internal property with value
true
, throw a
TypeError
exception.
Set the [[initializedIntlObject]] internal property of
numberFormat
to
true
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
If
options
is
undefined
, then
Let
options
be the result of creating a new object as if by the expression
new Object()
where
Object
is the standard built-in constructor with that name.
Else
Let
options
be ToObject(
options
).
Let
opt
be a new
Record
Let
matcher
be the result of calling the
GetOption
abstract operation (defined in
9.2.9
) with the arguments
options
"localeMatcher"
"string"
List
containing the two String values
"lookup"
and
"best fit"
, and
"best fit"
Set
opt
.[[localeMatcher]] to
matcher
Let
NumberFormat
be the standard built-in object that is the initial value of Intl.NumberFormat.
Let
localeData
be the value of the [[localeData]] internal property of
NumberFormat
Let
be the result of calling the
ResolveLocale
abstract operation (defined in
9.2.5
) with the [[availableLocales]] internal property of
NumberFormat
requestedLocales
opt
, the [[relevantExtensionKeys]] internal property of
NumberFormat
, and
localeData
Set the [[locale]] internal property of
numberFormat
to the value of
.[[locale]].
Set the [[numberingSystem]] internal property of
numberFormat
to the value of
.[[nu]].
Let
dataLocale
be the value of
.[[dataLocale]].
Let
be the result of calling the
GetOption
abstract operation with the arguments
options
"style"
"string"
, a
List
containing the three String
values
"decimal"
"percent"
, and
"currency"
, and
"decimal"
Set the [[style]] internal property of
numberFormat
to
Let
be the result of calling the
GetOption
abstract operation with the arguments
options
"currency"
"string"
undefined
, and
undefined
If
is not undefined and the result of calling the
IsWellFormedCurrencyCode
abstract operation (defined in
6.3.1
) with argument
is
false
, then throw a
RangeError
exception.
If
is
"currency"
and
is
undefined
, throw a
TypeError
exception.
If
is
"currency"
, then
Let
be the result of converting
to upper case as specified in
6.1
Set the [[currency]] internal property of
numberFormat
to
Let
cDigits
be the result of calling the CurrencyDigits abstract operation (defined below) with argument
Let
cd
be the result of calling the
GetOption
abstract operation with the arguments
options
"currencyDisplay"
"string"
, a
List
containing the
three String values
"code"
"symbol"
, and
"name"
, and
"symbol"
If
is
"currency"
, then set the [[currencyDisplay]] internal property of
numberFormat
to
cd
Let
mnid
be the result of calling the
GetNumberOption
abstract operation (defined
in
9.2.10
) with arguments
options
"minimumIntegerDigits"
, 1, 21, and
1.
Set the [[minimumIntegerDigits]] internal property of
numberFormat
to
mnid
If
is
"currency"
, then let
mnfdDefault
be
cDigits
; else let
mnfdDefault
be 0.
Let
mnfd
be the result of calling the
GetNumberOption
abstract operation with
arguments
options
"minimumFractionDigits"
, 0, 20, and
mnfdDefault
Set the [[minimumFractionDigits]] internal property of
numberFormat
to
mnfd
If
is
"currency"
, then let
mxfdDefault
be max(
mnfd
cDigits
); else if
is
"percent"
, then let
mxfdDefault
be max(
mnfd
, 0); else let
mxfdDefault
be max(
mnfd
, 3).
Let
mxfd
be the result of calling the
GetNumberOption
abstract operation with
arguments
options
"maximumFractionDigits"
mnfd
, 20, and
mxfdDefault
Set the [[maximumFractionDigits]] internal property of
numberFormat
to
mxfd
Let
mnsd
be the result of calling the [[Get]] internal method of
options
with argument
"minimumSignificantDigits"
Let
mxsd
be the result of calling the [[Get]] internal method of
options
with argument
"maximumSignificantDigits"
If
mnsd
is not
undefined
or
mxsd
is not
undefined
, then:
Let
mnsd
be the result of calling the
GetNumberOption
abstract operation with
arguments
options
"minimumSignificantDigits"
, 1, 21, and 1.
Let
mxsd
be the result of calling the
GetNumberOption
abstract operation with
arguments
options
"maximumSignificantDigits"
mnsd
, 21, and 21.
Set the [[minimumSignificantDigits]] internal property of
numberFormat
to
mnsd
, and the
[[maximumSignificantDigits]] internal property of
numberFormat
to
mxsd
Let
be the result of calling the
GetOption
abstract operation with the arguments
options
"useGrouping"
"boolean"
undefined
, and
true
Set the [[useGrouping]] internal property of
numberFormat
to
Let
dataLocaleData
be the result of calling the [[Get]] internal method of
localeData
with argument
dataLocale
Let
patterns
be the result of calling the [[Get]] internal method of
dataLocaleData
with argument
"patterns"
Assert:
patterns
is an object (see
11.2.3
).
Let
stylePatterns
be the result of calling the [[Get]] internal method of
patterns
with argument
Set the [[positivePattern]] internal property of
numberFormat
to the result of calling the [[Get]] internal
method of
stylePatterns
with the argument
"positivePattern"
Set the [[negativePattern]] internal property of
numberFormat
to the result of calling the [[Get]] internal
method of
stylePatterns
with the argument
"negativePattern"
Set the [[boundFormat]] internal property of
numberFormat
to
undefined
Set the [[initializedNumberFormat]] internal property of
numberFormat
to
true
When the CurrencyDigits abstract operation is called with an argument
currency
(which must be an upper case
String value), the following steps are taken:
If the ISO 4217 currency and funds code list contains
currency
as an alphabetic code, then return the minor
unit value corresponding to the
currency
from the list; else return 2.
11.1.2
The Intl.NumberFormat
Constructor Called as a Function
11.1.2.1
Intl.NumberFormat.call
(this [, locales [, options]])
When
Intl.NumberFormat
is called as a function rather than as a constructor, it accepts the optional
arguments
locales
and
options
and takes the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
If
this
is the standard built-in Intl object defined in
or
undefined
, then
Return the result of creating a new object as if by the expression
new Intl.NumberFormat(locales,
options)
, where
Intl.NumberFormat
is the standard built-in constructor defined in
11.1.3
Let
obj
be the result of calling ToObject passing the
this
value as the argument.
If the [[Extensible]] internal property of
obj
is
false
, throw a
TypeError
exception.
Call the
InitializeNumberFormat
abstract operation (defined in
11.1.1.1
) with arguments
obj
locales
, and
options
Return
obj
11.1.3
The Intl.NumberFormat
Constructor Used in a new Expression
11.1.3.1
new Intl.NumberFormat
([locales [, options]])
When
Intl.NumberFormat
is called as part of a
new
expression, it is a constructor: it
initializes the newly created object.
The [[Prototype]] internal property of the newly constructed object is set to the original Intl.NumberFormat prototype
object, the one that is the initial value of
Intl.NumberFormat.prototype
11.2.1
).
The [[Extensible]] internal property of the newly constructed object is set to
true
NumberFormat-specific properties of the newly constructed object are set using the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Call the
InitializeNumberFormat
abstract operation (defined in
11.1.1.1
), passing as arguments the newly constructed object,
locales
, and
options
11.2
Properties of the Intl.NumberFormat
Constructor
Besides the internal properties and the
length
property (whose value is 0), the Intl.NumberFormat constructor
has the following properties:
11.2.1
Intl.NumberFormat.prototype
The value of
Intl.NumberFormat.prototype
is the built-in Intl.NumberFormat prototype object (
11.3
).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
11.2.2
Intl.NumberFormat.supportedLocalesOf (locales [, options])
When the
supportedLocalesOf
method of Intl.NumberFormat is called, the following steps are taken:
If
options
is not provided, then let
options
be
undefined
Let
availableLocales
be the value of the [[availableLocales]] internal property of the standard built-in object
that is the initial value of Intl.NumberFormat.
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
Return the result of calling the
SupportedLocales
abstract operation (defined in
9.2.8
) with arguments
availableLocales
requestedLocales
, and
options
The value of the
length
property of the
supportedLocalesOf
method is
11.2.3
Internal Properties
The value of the [[availableLocales]] internal property is implementation defined within the constraints described in
9.1
The value of the [[relevantExtensionKeys]] internal property is
["nu"]
NOTE
Unicode Technical Standard 35
describes two locale extension keys that are relevant to
number formatting, "nu" for numbering system and "cu" for
currency. Intl.NumberFormat, however, requires that the currency
of a currency format is specified through the currency property
in the options objects.
The value of the [[localeData]] internal property is implementation defined within the constraints described in
9.1
and the following additional constraints:
The array that is the value of the "nu" property of any locale property of [[localeData]] must not include the values
"native", "traditio", or "finance".
[[localeData]][locale] must have a patterns property for all locale values. The value of this property must be an
object, which must have properties with the names of the three number format styles:
"decimal"
"percent"
, and
"currency"
. Each of these properties in turn must be an object with the
properties positivePattern and negativePattern. The value of these properties must be string values that contain a
substring
"{number}"
; the values within the currency property must also contain a substring
"{currency}"
. The pattern strings must not contain any characters in the General Category “Number, decimal
digit” as specified by the Unicode Standard.
NOTE
It is recommended that implementations use the locale data provided by the Common Locale
Data Repository (available at
).
11.3
Properties of the Intl.NumberFormat
Prototype Object
The Intl.NumberFormat prototype object is itself an Intl.NumberFormat instance as specified in
11.4
, whose internal properties are set as if it had been constructed by the expression
Intl.NumberFormat.call({})
with the standard built-in values of Intl.NumberFormat and
Function.prototype.call.
In the following descriptions of functions that are properties or
[[Get]] attributes of properties of the Intl.NumberFormat
prototype object, the phrase “this NumberFormat object” refers to
the object that is the this value for the invocation of the
function; a
TypeError
exception is thrown if the this value is not an object or an object that does not have an
[[initializedNumberFormat]] internal property with value
true
11.3.1
Intl.NumberFormat.prototype.constructor
The initial value of
Intl.NumberFormat.prototype.constructor
is the built-in Intl.NumberFormat
constructor.
11.3.2
Intl.NumberFormat.prototype.format
This named accessor property returns a function that formats a number according to the effective locale and the
formatting options of this NumberFormat object.
The value of the [[Get]] attribute is a function that takes the following steps:
If the [[boundFormat]] internal property of this NumberFormat object is
undefined
, then:
Let
be a Function object, with internal properties set as specified for built-in functions in
ES5, 15
, or successor, and the length property set
to 1, that takes the argument
value
and performs the following steps:
If
value
is not provided, then let
value
be
undefined
Let
be ToNumber(
value
).
Return the result of calling the
FormatNumber
abstract operation (defined below)
with arguments
this
and
Let
bind
be the standard built-in function object defined in
ES5, 15.3.4.5
Let
bf
be the result of calling the [[Call]] internal method of
bind
with
as the
this
value and an argument list containing the single item
this
Set the [[boundFormat]] internal property of this NumberFormat object to
bf
Return the value of the [[boundFormat]] internal property of this NumberFormat object.
NOTE
The function returned by [[Get]] is bound to this NumberFormat object so that it can be
passed directly to Array.prototype.map or other functions.
The value of the [[Set]] attribute is
undefined
When the
FormatNumber
abstract operation is called with arguments
numberFormat
(which must be an object initialized as a NumberFormat) and
(which must be a Number value), it returns a String
value representing
according to the effective locale and the formatting options of
numberFormat
The computations rely on String values and locations within numeric strings that are dependent upon the implementation
and the effective locale of
numberFormat
(“ILD”) or upon the implementation, the effective locale, and the
numbering system of
numberFormat
(“ILND”). The ILD and ILND Strings mentioned, other than those for currency
names, must not contain any characters in the General Category “Number, decimal digit” as specified by the Unicode
Standard.
NOTE
It is recommended that implementations use the locale data provided by the Common Locale
Data Repository (available at
).
The following steps are taken:
Let
negative
be
false
If the result of isFinite(
) is
false
, then
If
is
NaN
, then let
be an ILD String value indicating the NaN value.
Else
Let
be an ILD String value indicating infinity.
If
< 0, then let
negative
be
true
Else
If
< 0, then
Let
negative
be
true
Let
be -
If the value of the [[style]] internal property of
numberFormat
is
"percent"
, let
be 100
If the [[minimumSignificantDigits]] and [[maximumSignificantDigits]] internal properties of
numberFormat
are present, then
Let
be the result of calling the
ToRawPrecision
abstract operation
(defined below), passing as arguments
and the values of the [[minimumSignificantDigits]] and
[[maximumSignificantDigits]] internal properties of
numberFormat
Else
Let
be the result of calling the
ToRawFixed
abstract operation (defined
below), passing as arguments
and the values of the [[minimumIntegerDigits]],
[[minimumFractionDigits]], and [[maximumFractionDigits]] internal properties of
numberFormat
If the value of the [[numberingSystem]] internal property of
numberFormat
matches one of the values in the
“Numbering System” column of
Table 2
below, then
Let
digits
be an array whose 10 String valued elements are the UTF-16 string representations of the 10
digits specified in the “Digits” column of
Table 2
in the row containing the value of
the [[numberingSystem]] internal property.
Replace each
digit
in
with the value of
digits
digit
].
Else use an implementation dependent algorithm to map
to the appropriate representation of
in
the given numbering system.
If
contains the character
"."
, then replace it with an ILND String representing the decimal
separator.
If the value of the [[useGrouping]] internal property of
numberFormat
is
true
, then insert an ILND
String representing a grouping separator into an ILND set of locations within the integer part of
If
negative
is
true
, then let
result
be the value of the [[negativePattern]] internal property of
numberFormat
; else let
result
be the value of the [[positivePattern]] internal property of
numberFormat
Replace the substring
"{number}"
within
result
with
If the value of the [[style]] internal property of
numberFormat
is
"currency"
, then:
Let
currency
be the value of the [[currency]] internal property of
numberFormat
If the value of the [[currencyDisplay]] internal property of
numberFormat
is
"code"
, then let
cd
be
currency
Else if the value of the [[currencyDisplay]] internal property of
numberFormat
is
"symbol"
then let
cd
be an ILD string representing
currency
in short form. If the implementation does not
have such a representation of
currency
, then use
currency
itself.
Else if the value of the [[currencyDisplay]] internal property of
numberFormat
is
"name"
, then
let
cd
be an ILD string representing
currency
in long form. If the implementation does not have such
a representation of
currency
, then use
currency
itself.
Replace the substring
"{currency}"
within
result
with
cd
Return
result
When the
ToRawPrecision
abstract operation is called with arguments
(which
must be a finite non-negative number),
minPrecision
, and
maxPrecision
(both must be integers between 1
and 21) the following steps are taken:
Let
be
maxPrecision
If
= 0, then
Let
be the String consisting of
occurrences of the character
"0"
Let
be 0.
Else
Let
and
be integers such that 10
–1
< 10
and
for which the exact mathematical value of n
10
+1
is as close to zero as possible. If there are two such sets of
and
, pick the
and
for which
10
+1
is larger.
Let
be the String consisting of the digits of the decimal representation of
(in order, with no
leading zeroes).
If
, then
Return the concatenation of
and
+1 occurrences of the character
"0"
If
-1, then
Return
If
≥ 0, then
Let
be the concatenation of the first
+1 characters of
, the character
"."
and the remaining
–(
+1) characters of
If
< 0, then
Let
be the concatenation of the String
"0."
, –(
+1) occurrences of the character
"0"
, and the string
If
contains the character
"."
, and
maxPrecision
minPrecision
, then
Let
cut
be
maxPrecision
minPrecision
Repeat while
cut
> 0 and the last character of
is
"0"
Remove the last character from
Decrease
cut
by 1.
If the last character of
is
"."
, then
Remove the last character from
Return
When the
ToRawFixed
abstract operation is called with arguments
(which must be
a finite non-negative number),
minInteger
(which must be an integer between 1 and 21),
minFraction
and
maxFraction
(which must be integers between 0 and 20) the following steps are taken:
Let
be
maxFraction
Let
be an integer for which the exact mathematical value of
10
is as close to zero as possible. If there are two such
pick the larger
If
= 0, let
be the String
"0"
. Otherwise, let
be the String consisting of the
digits of the decimal representation of
(in order, with no leading zeroes).
If
≠ 0, then
Let
be the number of characters in
If
, then
Let
be the String consisting of
+1–
occurrences of the character
"0"
Let
be the concatenation of Strings
and
Let
+1.
Let
be the first
characters of m, and let
be the remaining
characters
of
Let
be the concatenation of the three Strings
, ".", and
Let
int
be the number of characters in
Else let
int
be the number of characters in
Let
cut
be
maxFraction
minFraction
Repeat while
cut
> 0 and the last character of
is
"0"
Remove the last character from
Decrease
cut
by 1.
If the last character of
is
"."
, then
Remove the last character from
If
int
minInteger
, then
Let
be the String consisting of
minInteger
int
occurrences of the character
"0"
Let
be the concatenation of Strings
and
Return
Table 2
– Numbering systems with simple digit mappings
Numbering System
Digits
arab
U+0660 to U+0669
arabext
U+06F0 to U+06F9
bali
U+1B50 to U+1B59
beng
U+09E6 to U+09EF
deva
U+0966 to U+096F
fullwide
U+FF10 to U+FF19
gujr
U+0AE6 to U+0AEF
guru
U+0A66 to U+0A6F
hanidec
U+3007, U+4E00, U+4E8C, U+4E09, U+56DB, U+4E94, U+516D, U+4E03, U+516B, U+4E5D
khmr
U+17E0 to U+17E9
knda
U+0CE6 to U+0CEF
laoo
U+0ED0 to U+0ED9
latn
U+0030 to U+0039
limb
U+1946 to U+194F
mlym
U+0D66 to U+0D6F
mong
U+1810 to U+1819
mymr
U+1040 to U+1049
orya
U+0B66 to U+0B6F
tamldec
U+0BE6 to U+0BEF
telu
U+0C66 to U+0C6F
thai
U+0E50 to U+0E59
tibt
U+0F20 to U+0F29
11.3.3
Intl.NumberFormat.prototype.resolvedOptions ()
This function provides access to the locale and formatting options computed during initialization of the object.
The function returns a new object whose properties and attributes are set as if constructed by an object literal
assigning to each of the following properties the value of the corresponding internal property of this NumberFormat object
(see
11.4
): locale, numberingSystem, style, currency, currencyDisplay, minimumIntegerDigits,
minimumFractionDigits, maximumFractionDigits, minimumSignificantDigits, maximumSignificantDigits, and useGrouping.
Properties whose corresponding internal properties are not present are not assigned.
11.4
Properties of Intl.NumberFormat
Instances
Intl.NumberFormat instances inherit properties from the Intl.NumberFormat prototype object. Their [[Class]] internal
property value is
"Object"
Intl.NumberFormat instances and other objects that have been successfully initialized as a NumberFormat have
[[initializedIntlObject]] and [[initializedNumberFormat]] internal properties whose values are
true
Objects that have been successfully initialized as a NumberFormat also have several internal properties that are computed
by the constructor:
[[locale]] is a String value with the language tag of the locale whose localization is used for formatting.
[[numberingSystem]] is a String value with the “type” given in Unicode Technical Standard 35 for the numbering system
used for formatting.
[[style]] is one of the String values
"decimal"
"currency"
, or
"percent"
identifying the number format style used.
[[currency]] is a String value with the currency code identifying the currency to be used if formatting with the
"currency"
style. It is only present when [[style]] has the value
"currency"
[[currencyDisplay]] is one of the String values
"code"
"symbol"
, or
"name"
specifying whether to display the currency as an ISO 4217 alphabetic currency code, a localized currency symbol, or a
localized currency name if formatting with the
"currency"
style. It is only present when [[style]] has the
value
"currency"
[[minimumIntegerDigits]] is a non-negative integer Number value indicating the minimum integer digits to be used.
Numbers will be padded with leading zeroes if necessary.
[[minimumFractionDigits]] and [[maximumFractionDigits]] are non-negative integer Number values indicating the minimum
and maximum fraction digits to be used. Numbers will be rounded or padded with trailing zeroes if necessary.
[[minimumSignificantDigits]] and [[maximumSignificantDigits]]
are positive integer Number values indicating the minimum
and maximum fraction digits to be shown. Either none or both of
these properties are present; if they are, they override
minimum and maximum integer and fraction digits – the formatter
uses however many integer and fraction digits are required
to display the specified number of significant digits.
[[useGrouping]] is a Boolean value indicating whether a grouping separator should be used.
[[positivePattern]] and [[negativePattern]] are String values as described in
11.2.3
Finally, objects that have been successfully initialized as a NumberFormat have a [[boundFormat]] internal property that
caches the function returned by the format accessor (
11.3.2
).
12
DateTimeFormat Objects
12.1
The Intl.DateTimeFormat
Constructor
The Intl.DateTimeFormat constructor is a standard built-in property of the Intl object. Behaviour common to all service
constructor properties of the Intl object is specified in
9.1
12.1.1
Initializing an Object as a
DateTimeFormat
12.1.1.1
InitializeDateTimeFormat
(dateTimeFormat, locales, options)
The abstract operation InitializeDateTimeFormat accepts the arguments
dateTimeFormat
(which must be an
object),
locales
, and
options
. It initializes
dateTimeFormat
as a DateTimeFormat
object.
Several DateTimeFormat algorithms use values from the following table, which provides property names and allowable
values for the components of date and time formats:
Table 3
– Components of date and time formats
Property
Values
weekday
"narrow", "short", "long"
era
"narrow", "short", "long"
year
"2-digit", "numeric"
month
"2-digit", "numeric", "narrow", "short", "long"
day
"2-digit", "numeric"
hour
"2-digit", "numeric"
minute
"2-digit", "numeric"
second
"2-digit", "numeric"
timeZoneName
"short", "long"
The following steps are taken:
If
dateTimeFormat
has an [[initializedIntlObject]] internal property with value
true
, throw a
TypeError
exception.
Set the [[initializedIntlObject]] internal property of
dateTimeFormat
to
true
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
Let
options
be the result of calling the
ToDateTimeOptions
abstract
operation (defined below) with arguments
options
"any"
, and
"date"
Let
opt
be a new
Record
Let
matcher
be the result of calling the
GetOption
abstract operation (defined in
9.2.9
) with arguments
options
"localeMatcher"
"string"
, a
List
containing the two String values
"lookup"
and
"best fit"
, and
"best fit"
Set
opt
.[[localeMatcher]] to
matcher
Let
DateTimeFormat
be the standard built-in object that is the initial value of Intl.DateTimeFormat.
Let
localeData
be the value of the [[localeData]] internal property of
DateTimeFormat
Let
be the result of calling the
ResolveLocale
abstract operation (defined in
9.2.5
) with the [[availableLocales]] internal property of
DateTimeFormat
requestedLocales
opt
, the [[relevantExtensionKeys]] internal property of
DateTimeFormat
, and
localeData
Set the [[locale]] internal property of
dateTimeFormat
to the value of
.[[locale]].
Set the [[calendar]] internal property of
dateTimeFormat
to the value of
.[[ca]].
Set the [[numberingSystem]] internal property of
dateTimeFormat
to the value of
.[[nu]].
Let
dataLocale
be the value of
.[[dataLocale]].
Let
tz
be the result of calling the [[Get]] internal method of
options
with argument
"timeZone"
If
tz
is not
undefined
, then
Let
tz
be ToString(
tz
).
Convert
tz
to upper case as described in
6.1
NOTE:
If an implementation accepts additional time zone
values, as permitted under certain conditions by the Conformance clause, different casing rules
apply.
If
tz
is not
"UTC"
, then throw a
RangeError
exception.
Set the [[timeZone]] internal property of
dateTimeFormat
to
tz
Let
opt
be a new
Record
For each row of
Table 3
, except the header row, do:
Let
prop
be the name given in the Property column of the row.
Let
value
be the result of calling the
GetOption
abstract operation, passing as
argument
options
, the name given in the Property column of the row,
"string"
, a
List
containing the strings given in the Values column of the row, and
undefined
Set
opt
.[[<
prop
>]] to
value
Let
dataLocaleData
be the result of calling the [[Get]] internal method of
localeData
with argument
dataLocale
Let
formats
be the result of calling the [[Get]] internal method of
dataLocaleData
with argument
"formats"
Let
matcher
be the result of calling the
GetOption
abstract operation with arguments
options
"formatMatcher"
"string"
, a
List
containing the two
String values
"basic"
and
"best fit"
, and
"best fit"
If
matcher
is
"basic"
, then
Let
bestFormat
be the result of calling the
BasicFormatMatcher
abstract
operation (defined below) with
opt
and
formats
Else
Let
bestFormat
be the result of calling the
BestFitFormatMatcher
abstract operation (defined below) with
opt
and
formats
For each row in
Table 3
, except the header row, do
Let
prop
be the name given in the Property column of the row.
Let
pDesc
be the result of calling the [[GetOwnProperty]] internal method of
bestFormat
with
argument
prop
If
pDesc
is not
undefined
, then
Let
be the result of calling the [[Get]] internal method of
bestFormat
with argument
prop
Set the [[<
prop
>]] internal property of
dateTimeFormat
to
Let
hr12
be the result of calling the
GetOption
abstract operation with arguments
options
"hour12"
"boolean"
undefined
, and
undefined
If
dateTimeFormat
has an internal property [[hour]], then
If
hr12
is
undefined
, then let
hr12
be the result of calling the [[Get]] internal method of
dataLocaleData
with argument
"hour12"
Set the [[hour12]] internal property of
dateTimeFormat
to
hr12
If
hr12
is
true
, then
Let
hourNo0
be the result of calling the [[Get]] internal method of
dataLocaleData
with
argument
"hourNo0"
Set the [[hourNo0]] internal property of
dateTimeFormat
to
hourNo0
Let
pattern
be the result of calling the [[Get]] internal method of
bestFormat
with argument
"pattern12"
Else
Let
pattern
be the result of calling the [[Get]] internal method of
bestFormat
with argument
"pattern"
Else
Let
pattern
be the result of calling the [[Get]] internal method of
bestFormat
with argument
"pattern"
Set the [[pattern]] internal property of
dateTimeFormat
to
pattern
Set the [[boundFormat]] internal property of
dateTimeFormat
to
undefined
Set the [[initializedDateTimeFormat]] internal property of
dateTimeFormat
to
true
When the
ToDateTimeOptions
abstract operation is called with arguments
options
required
, and
defaults
, the following steps are taken:
If
options
is
undefined
, then let
options
be
null
, else let
options
be
ToObject(
options
).
Let
create
be the standard built-in function object defined in
ES5, 15.2.3.5
Let
options
be the result of calling the [[Call]] internal method of
create
with
undefined
as
the
this
value and an argument list containing the single item
options
Let
needDefaults
be
true
If
required
is
"date"
or
"any"
, then
For each of the property names
"weekday"
"year"
"month"
"day"
If the result of calling the [[Get]] internal method of
options
with the property name is not
undefined
, then let
needDefaults
be
false
If
required
is
"time"
or
"any"
, then
For each of the property names
"hour"
"minute"
"second"
If the result of calling the [[Get]] internal method of
options
with the property name is not
undefined
, then let
needDefaults
be
false
If
needDefaults
is
true
and
defaults
is either
"date"
or
"all"
, then
For each of the property names
"year"
"month"
"day"
Call the [[DefineOwnProperty]] internal method of
options
with the property name, Property Descriptor
{[[Value]]:
"numeric"
, [[Writable]]:
true
, [[Enumerable]]:
true
[[Configurable]]:
true
}, and
false
If
needDefaults
is
true
and
defaults
is either
"time"
or
"all"
, then
For each of the property names
"hour"
"minute"
"second"
Call the [[DefineOwnProperty]] internal method of
options
with the property name, Property Descriptor
{[[Value]]:
"numeric"
, [[Writable]]:
true
, [[Enumerable]]:
true
[[Configurable]]:
true
}, and
false
Return
options
When the
BasicFormatMatcher
abstract operation is called with two arguments
options
and
formats
, the following steps are taken:
Let
removalPenalty
be 120.
Let
additionPenalty
be 20.
Let
longLessPenalty
be 8.
Let
longMorePenalty
be 6.
Let
shortLessPenalty
be 6.
Let
shortMorePenalty
be 3.
Let
bestScore
be -
Infinity
Let
bestFormat
be
undefined
Let
be 0.
Let
len
be the result of calling the [[Get]] internal method of
formats
with argument
"length"
Repeat while
len
Let
format
be the result of calling the [[Get]] internal method of
formats
with argument
ToString(
).
Let
score
be 0.
For each
property
shown in
Table 3
Let
optionsProp
be
options
.[[<
property
>]].
Let
formatPropDesc
be the result of calling the [[GetOwnProperty]] internal method of
format
with argument
property
If
formatPropDesc
is not
undefined
, then
Let
formatProp
be the result of calling the [[Get]] internal method of
format
with
argument
property
If
optionsProp
is
undefined
and
formatProp
is not
undefined
, then decrease
score
by
additionPenalty
Else if
optionsProp
is not
undefined
and
formatProp
is
undefined
, then decrease
score
by
removalPenalty
Else
Let
values
be the array
["2-digit", "numeric", "narrow", "short", "long"]
Let
optionsPropIndex
be the index of
optionsProp
within
values
Let
formatPropIndex
be the index of
formatProp
within
values
Let
delta
be max(min(
formatPropIndex
optionsPropIndex
, 2), -2).
If
delta
= 2, decrease
score
by
longMorePenalty
Else if
delta
= 1, decrease
score
by
shortMorePenalty
Else if
delta
= -1, decrease
score
by
shortLessPenalty
Else if
delta
= -2, decrease
score
by
longLessPenalty
If
score
bestScore
, then
Let
bestScore
be
score
Let
bestFormat
be
format
Increase
by 1.
Return
bestFormat
When the
BestFitFormatMatcher
abstract operation is called with two arguments
options
and
formats
, it performs implementation dependent steps, which should return a set of
component representations that a typical user of the selected locale would perceive as at least as good as the one
returned by
BasicFormatMatcher
12.1.2
The Intl.DateTimeFormat
Constructor Called as a Function
12.1.2.1
Intl.DateTimeFormat.call
(this [, locales [, options]])
When
Intl.DateTimeFormat
is called as a function rather than as a constructor, it accepts the optional
arguments
locales
and
options
and takes the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
If
this
is the standard built-in Intl object defined in
or
undefined
, then
Return the result of creating a new object as if by the expression new
Intl.DateTimeFormat(locales,
options)
, where
Intl.DateTimeFormat
is the standard built-in constructor defined in
12.1.3
Let
obj
be the result of calling ToObject passing the
this
value as the argument.
If the [[Extensible]] internal property of
obj
is
false
, throw a
TypeError
exception.
Call the
InitializeDateTimeFormat
abstract operation (defined in
12.1.1.1
) with arguments
obj
locales
, and
options
Return
obj
12.1.3
The Intl.DateTimeFormat
Constructor Used in a new Expression
12.1.3.1
new Intl.DateTimeFormat
([locales [, options]])
When
Intl.DateTimeFormat
is called as part of a
new
expression, it is a constructor: it
initializes the newly created object.
The [[Prototype]] internal property of the newly constructed object is set to the original Intl.DateTimeFormat
prototype object, the one that is the initial value of
Intl.DateTimeFormat.prototype
12.2.1
).
The [[Extensible]] internal property of the newly constructed object is set to
true
DateTimeFormat-specific properties of the newly constructed object are set using the following steps:
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Call the
InitializeDateTimeFormat
abstract operation (defined in
12.1.1.1
), passing as arguments the newly constructed object,
locales
, and
options
12.2
Properties of the
Intl.DateTimeFormat Constructor
Besides the internal properties and the
length
property (whose value is 0), the Intl.DateTimeFormat
constructor has the following properties:
12.2.1
Intl.DateTimeFormat.prototype
The value of
Intl.DateTimeFormat.prototype
is the built-in Intl.DateTimeFormat prototype object (
12.3
).
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
12.2.2
Intl.DateTimeFormat.supportedLocalesOf (locales [, options])
When the
supportedLocalesOf
method of Intl.DateTimeFormat is called, the following steps are taken:
If
options
is not provided, then let
options
be
undefined
Let
availableLocales
be the value of the [[availableLocales]] internal property of the standard built-in object
that is the initial value of Intl.DateTimeFormat.
Let
requestedLocales
be the result of calling the
CanonicalizeLocaleList
abstract
operation (defined in
9.2.1
) with argument
locales
Return the result of calling the
SupportedLocales
abstract operation (defined in
9.2.8
) with arguments
availableLocales
requestedLocales
, and
options
The value of the
length
property of the
supportedLocalesOf
method is
12.2.3
Internal Properties
The value of the [[availableLocales]] internal property is implementation defined within the constraints described in
9.1
The value of the [[relevantExtensionKeys]] internal property is
["ca", "nu"]
NOTE
Unicode Technical Standard 35 describes three locale extension keys that are relevant to
date and time formatting, "ca" for calendar, "tz" for time zone, and implicitly "nu" for the numbering system of the
number format used for numbers within the date format. DateTimeFormat, however, requires that the time zone is specified
through the timeZone property in the options objects.
The value of the [[localeData]] internal property is implementation defined within the constraints described in
9.1
and the following additional constraints:
The array that is the value of the "nu" property of any locale property of [[localeData]] must not include the values
"native", "traditio", or "finance".
[[localeData]][locale] must have hour12 and hourNo0 properties with Boolean values for all locale values.
[[localeData]][locale] must have a formats property for all locale values. The value of this property must be an
array of objects, each of which has a subset of the properties shown in
Table 3
, where each
property must have one of the values specified for the property in
Table 3
. Multiple objects in
an array may use the same subset of the properties as long as they have different values for the properties. The
following subsets must be available for each locale:
weekday, year, month, day, hour, minute, second
weekday, year, month, day
year, month, day
year, month
month, day
hour, minute, second
hour, minute
Each of the objects must also have a pattern property,
whose value is a String value that contains for each of the
date and time format component properties of the object a
substring starting with "{", followed by the name of the
property, followed by "}". If the object has an hour property,
it must also have a pattern12 property, whose value is a
String value that, in addition to the substrings of the
pattern property, contains a substring "{ampm}".
EXAMPLE
An implementation might include the following object as part of its English locale
data: {hour: "numeric", minute: "2-digit", second: "2-digit", pattern: "{hour}:{minute}:{second}", pattern12:
"{hour}:{minute}:{second} {ampm}"}.
NOTE
It is recommended that implementations use the locale data provided by the Common Locale
Data Repository (available at
).
12.3
Properties of the
Intl.DateTimeFormat Prototype Object
The Intl.DateTimeFormat prototype object is itself an Intl.DateTimeFormat instance as specified in
12.4
, whose internal properties are set as if it had been constructed by the expression
Intl.DateTimeFormat.call({})
with the standard built-in values of Intl.DateTimeFormat and
Function.prototype.call.
In the following descriptions of functions that are properties or
[[Get]] attributes of properties of the
Intl.DateTimeFormat prototype object, the phrase “this
DateTimeFormat object” refers to the object that is the this value for
the invocation of the function; a
TypeError
exception is thrown if the this value is not an object or an object that
does not have an [[initializedDateTimeFormat]] internal property with value
true
12.3.1
Intl.DateTimeFormat.prototype.constructor
The initial value of
Intl.DateTimeFormat.prototype.constructor
is the built-in Intl.DateTimeFormat
constructor.
12.3.2
Intl.DateTimeFormat.prototype.format
This named accessor property returns a function that formats a date according to the effective locale and the formatting
options of this DateTimeFormat object.
The value of the [[Get]] attribute is a function that takes the following steps:
If the [[boundFormat]] internal property of this DateTimeFormat object is
undefined
, then:
Let
be a Function object, with internal properties set as specified for built-in functions in
ES5, 15
, or successor, and the length property set
to 0, that takes the argument
date
and performs the following steps:
If
date
is not provided or is
undefined
, then let
be the result as if by the expression
Date.now()
where
Date.now
is the standard built-in function defined in
ES5, 15.9.4.4
Else let
be ToNumber(
date
).
Return the result of calling the
FormatDateTime
abstract operation (defined
below) with arguments
this
and
Let
bind
be the standard built-in function object defined in
ES5, 15.3.4.5
Let
bf
be the result of calling the [[Call]] internal method of
bind
with
as the
this
value and an argument list containing the single item
this
Set the [[boundFormat]] internal property of this DateTimeFormat object to
bf
Return the value of the [[boundFormat]] internal property of this DateTimeFormat object.
NOTE
The function returned by [[Get]] is bound to this DateTimeFormat object so that it can be
passed directly to Array.prototype.map or other functions.
The value of the [[Set]] attribute is
undefined
When the
FormatDateTime
abstract operation is called with arguments
dateTimeFormat
(which must be an object initialized as a DateTimeFormat) and
(which must be a Number
value), it returns a String value representing
(interpreted as a time value as specified in
ES5, 15.9.1.1
) according to the effective locale and the
formatting options of
dateTimeFormat
If
is not a finite Number, then throw a
RangeError
exception.
Let
locale
be the value of the [[locale]] internal property of
dateTimeFormat
Let
nf
be the result of creating a new NumberFormat object as if by the expression
new
Intl.NumberFormat([locale], {useGrouping: false})
where
Intl.NumberFormat
is the standard built-in
constructor defined in
11.1.3
Let
nf2
be the result of creating a new NumberFormat object as if by the expression
new
Intl.NumberFormat([locale], {minimumIntegerDigits: 2, useGrouping: false})
where
Intl.NumberFormat
is the standard built-in constructor defined in
11.1.3
Let
tm
be the result of calling the
ToLocalTime
abstract operation (defined below)
with
, the value of the [[calendar]] internal property of
dateTimeFormat
, and the value of the
[[timeZone]] internal property of
dateTimeFormat
Let
result
be the value of the [[pattern]] internal property of
dateTimeFormat
For each row of
Table 3
, except the header row, do:
If
dateTimeFormat
has an internal property with the name given in the Property column of the row, then:
Let
be the name given in the Property column of the row.
Let
be the value of the [[<
>]] internal property of
dateTimeFormat
Let
be the value of
tm
.[[<
>]].
If
is
"year"
and
≤ 0, then let
be 1 -
If
is
"month"
, then increase
by 1.
If
is
"hour"
and the value of the [[hour12]] internal property of
dateTimeFormat
is
true
, then
Let
be
modulo 12.
If
is equal to the value of
tm
.[[<
>]], then let
pm
be
false
else let
pm
be
true
If
is 0 and the value of the [[hourNo0]] internal property of
dateTimeFormat
is
true
, then let
be 12.
If
is
"numeric"
, then
Let
fv
be the result of calling the
FormatNumber
abstract operation
(defined in
11.3.2
) with arguments
nf
and
Else if
is
"2-digit"
, then
Let
fv
be the result of calling the
FormatNumber
abstract operation
with arguments
nf2
and
If the length of
fv
is greater than 2, let
fv
be the substring of
fv
containing the
last two characters.
Else if
is
"narrow"
"short"
, or
"long"
, then let
fv
be
a String value representing
in the desired form; the String value depends upon the implementation and
the effective locale and calendar of
dateTimeFormat
. If
is
"month"
, then the
String value may also depend on whether
dateTimeFormat
has a [[day]] internal property. If
is
"timeZoneName"
, then the String value may also depend on the value of the [[inDST]] field of
tm
Replace the substring of
result
that consists of
"{"
, and
"}"
, with
fv
If
dateTimeFormat
has an internal property [[hour12]] whose value is
true
, then
If
pm
is
true
, then let
fv
be an implementation and locale dependent String value
representing “post meridiem”; else let
fv
be an implementation and locale dependent String value
representing “ante meridiem”.
Replace the substring of
result
that consists of
"{ampm}"
, with
fv
Return
result
NOTE
It is recommended that implementations use the locale and calendar dependent strings
provided by the Common Locale Data Repository (available at
), and use CLDR “abbreviated” strings for DateTimeFormat
“short” strings, and CLDR “wide” strings for DateTimeFormat “long” strings.
When the
ToLocalTime
abstract operation is called with arguments
date
calendar
, and
timeZone
, the following steps are taken:
Apply calendrical calculations on date for the given calendar and time zone to produce weekday, era, year, month, day,
hour, minute, second, and inDST values. The calculations should use best available information about the specified
calendar and time zone. If the calendar is
"gregory"
, then the calculations must match the algorithms
specified in
ES5, 15.9.1
, except that
calculations are not bound by the restrictions on the use of best available information on time zones for local time
zone adjustment and daylight saving time adjustment imposed by
ES5, 15.9.1.7
and
15.9.1.8
Return a
Record
with fields [[weekday]], [[era]], [[year]], [[month]], [[day]], [[hour]],
[[minute]], [[second]], and [[inDST]], each with the corresponding calculated value.
NOTE
It is recommended that implementations use the time zone information of the IANA Time Zone
Database.
12.3.3
Intl.DateTimeFormat.prototype.resolvedOptions ()
This function provides access to the locale and formatting options computed during initialization of the object.
The function returns a new object whose properties and
attributes are set as if constructed by an object literal
assigning to each of the following properties the value of the
corresponding internal property of this DateTimeFormat object
(see
12.4
): locale, calendar, numberingSystem, timeZone, hour12, weekday, era, year, month, day,
hour, minute, second, and timeZoneName. Properties whose corresponding internal properties are not present are not
assigned.
NOTE
In this version of the ECMAScript Internationalization API, the timeZone property will
remain undefined if no timeZone property was provided in the options object provided to the Intl.DateTimeFormat
constructor. However, applications should not rely on this, as future versions may return a String value identifying the
host environment’s current time zone instead.
12.4
Properties of Intl.DateTimeFormat
Instances
Intl.DateTimeFormat instances inherit properties from the Intl.DateTimeFormat prototype object. Their [[Class]] internal
property value is
"Object"
Intl.DateTimeFormat instances and other objects that have been successfully initialized as a DateTimeFormat have
[[initializedIntlObject]] and [[initializedDateTimeFormat]] internal properties whose values are
true
Objects that have been successfully initialized as a DateTimeFormat also have several internal properties that are computed
by the constructor:
[[locale]] is a String value with the language tag of the locale whose localization is used for formatting.
[[calendar]] is a String value with the “type” given in Unicode Technical Standard 35 for the calendar used for
formatting.
[[numberingSystem]] is a String value with the “type” given in Unicode Technical Standard 35 for the numbering system
used for formatting.
[[timeZone]] is either the String value
"UTC"
or
undefined
[[weekday]], [[era]], [[year]], [[month]], [[day]], [[hour]], [[minute]], [[second]], [[timeZoneName]] are each either
absent, indicating that the component is not used for formatting, or one of the String values given in
Table 3
, indicating how the component should be presented in the formatted output.
[[hour12]] is a Boolean value indicating whether 12-hour format (
true
) or 24-hour format (
false
) should
be used. It is only present when [[hour]] is also present.
[[hourNo0]] is a Boolean value indicating whether hours from 1 to 12 (
true
) or from 0 to 11 (
false
should be used. It is only present when [[hour12]] is also present and has the value
true
[[pattern]] is a String value as described in
12.2.3
Finally, objects that have been successfully initialized as a DateTimeFormat have a [[boundFormat]] internal property that
caches the function returned by the format accessor (
12.3.2
).
13
Locale Sensitive Functions of the
ECMAScript Language Specification
The ECMAScript Language Specification, edition 5.1 or successor, describes several locale sensitive functions. An ECMAScript
implementation that implements this Internationalization API shall implement these functions as described here.
NOTE
The Collator, NumberFormat, or
DateTimeFormat objects created in the algorithms in this clause
are only used within these algorithms. They are never directly
accessed by ECMAScript code and need not actually exist within
an implementation.
13.1
Properties of the String Prototype
Object
13.1.1
String.prototype.localeCompare
(that [, locales [, options]])
This definition supersedes the definition provided in
ES5, 15.5.4.9
When the
localeCompare
method is called with argument
that
and optional arguments
locales
, and
options
, the following steps are taken:
Call CheckObjectCoercible passing the
this
value as its argument.
Let
be the result of calling ToString passing the
this
value as its argument.
Let
That
be ToString(
that
).
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Let
collator
be the result of creating an object as if by the expression
new Intl.Collator(locales,
options)
where
Intl.Collator
is the standard built-in constructor defined in
10.1.3
Return the result of calling the
CompareStrings
abstract operation (defined in
10.3.2
) with arguments
collator
, and
That
The value of the
length
property of the
localeCompare
method is
NOTE 1
The
localeCompare
method itself is not directly suitable as an argument to
Array.prototype.sort
because the latter requires a function of two arguments.
NOTE 2
The
localeCompare
function is intentionally generic; it does not require
that its
this
value be a String object. Therefore, it can be transferred to other kinds of objects for use as a
method.
13.2
Properties of the Number Prototype
Object
13.2.1
Number.prototype.toLocaleString ([locales [, options]])
This definition supersedes the definition provided in
ES5, 15.7.4.3
When the
toLocaleString
method is called with optional arguments
locales
and
options
the following steps are taken:
Let
be this Number value (as defined in
ES5,
15.7.4
).
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Let
numberFormat
be the result of creating a new object as if by the expression
new
Intl.NumberFormat(locales, options)
where
Intl.NumberFormat
is the standard built-in constructor
defined in
11.1.3
Return the result of calling the
FormatNumber
abstract operation (defined in
11.3.2
) with arguments
numberFormat
and
The value of the
length
property of the
toLocaleString
method is
13.3
Properties of the Date Prototype
Object
13.3.1
Date.prototype.toLocaleString
([locales [, options]])
This definition supersedes the definition provided in
ES5, 15.9.5.5
When the
toLocaleString
method is called with optional arguments
locales
and
options
the following steps are taken:
Let
be this time value (as defined in
ES5,
15.9.5
).
If
is
NaN
, then return
"Invalid Date"
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Let
options
be the result of calling the
ToDateTimeOptions
abstract operation
(defined in
12.1.1
) with arguments
options
"any"
, and
"all"
Let
dateTimeFormat
be the result of creating a new object as if by the expression
new
Intl.DateTimeFormat(locales, options)
where
Intl.DateTimeFormat
is the standard built-in
constructor defined in
12.1.3
Return the result of calling the
FormatDateTime
abstract operation (defined in
12.3.2
) with arguments
dateTimeFormat
and
The value of the
length
property of the
toLocaleString
method is
13.3.2
Date.prototype.toLocaleDateString ([locales [, options]])
This definition supersedes the definition provided in
ES5, 15.9.5.6
When the
toLocaleDateString
method is called with optional arguments
locales
and
options
, the following steps are taken:
Let
be this time value (as defined in
ES5,
15.9.5
).
If
is
NaN
, then return
"Invalid Date"
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Let
options
be the result of calling the
ToDateTimeOptions
abstract operation
(defined in
12.1.1
) with arguments
options
"date"
, and
"date"
Let
dateFormat
be the result of creating a new object as if by the expression
new
Intl.DateTimeFormat(locales, options)
where
Intl.DateTimeFormat
is the standard built-in
constructor defined in
12.1.3
Return the result of calling the
FormatDateTime
abstract operation (defined in
12.3.2
) with arguments
dateTimeFormat
and
The value of the
length
property of the
toLocaleDateString
method is
13.3.3
Date.prototype.toLocaleTimeString ([locales [, options]])
This definition supersedes the definition provided in
ES5, 15.9.5.7
When the
toLocaleTimeString
method is called with optional arguments
locales
and
options
, the following steps are taken:
Let
be this time value (as defined in
ES5,
15.9.5
).
If x is
NaN
, then return
"Invalid Date"
If
locales
is not provided, then let
locales
be
undefined
If
options
is not provided, then let
options
be
undefined
Let
options
be the result of calling the
ToDateTimeOptions
abstract operation
(defined in
12.1.1
) with arguments
options
"time"
, and
"time"
Let
timeFormat
be the result of creating a new object as if by the expression
new
Intl.DateTimeFormat(locales, options)
where
Intl.DateTimeFormat
is the standard built-in
constructor defined in
12.1.3
Return the result of calling the
FormatDateTime
abstract operation (defined in
12.3.2
) with arguments
dateTimeFormat
and
The value of the
length
property of the
toLocaleTimeString
method is
Annex A
(informative)
Implementation Dependent Behaviour
The following aspects of the ECMAScript Internationalization API are implementation dependent:
In all functionality:
Additional values for some properties of
options
arguments (
Canonicalization of extension subtag sequences beyond the rules of RFC 5646 (
6.2.3
The default locale (
6.2.4
The host environment’s current time zone (
6.4
The set of available locales for each constructor (
9.1
The
BestFitMatcher
algorithm (
9.2.4
The
BestFitSupportedLocales
algorithm (
9.2.7
In Collator:
Support for the Unicode extensions keys kn, kf and the parallel options properties numeric, caseFirst (
10.2.3
The set of supported
"co"
key values (collations) per locale beyond a default collation (
10.2.3
The set of supported
"kn"
key values (numeric collation) per locale (
10.2.3
The set of supported
"kf"
key values (case order) per locale (
10.2.3
The default search sensitivity per locale (
10.2.3
The sort order for each supported locale and options combination (
10.3.2
In NumberFormat:
The set of supported
"nu"
key values (numbering systems) per locale (
11.2.3
The patterns used for formatting positive and negative values as decimal, percent, or currency values per locale (
11.2.3
Localized representations of
NaN
and
Infinity
11.3.2
The implementation of numbering systems not listed in
Table 2
11.3.2
Localized decimal and grouping separators (
11.3.2
Localized digit grouping schemata (
11.3.2
Localized currency symbols and names (
11.3.2
In DateTimeFormat:
The
BestFitFormatMatcher
algorithm (
12.1.1
The set of supported
"ca"
key values (calendars) per locale (
12.2.3
The set of supported
"nu"
key values (numbering systems) per locale (
12.2.3
The default hour12 and hourNo0 settings per locale (
11.2.3
The set of supported date-time formats per locale beyond a core set, including the representations used for each
component and the associated patterns (
12.2.3
Localized weekday names, era names, month names, am/pm indicators, and time zone names (
12.3.2
The calendrical calculations used for calendars other than
"gregory"
, and adjustments for local time
zones and daylight saving time (
12.3.2