Intl.Collator Object (JavaScript)
Provides locale-specific string comparisons.
Syntax
collatorObj = new Intl.Collator([locales][, options])
Parameters
collatorObj
Required. The variable name to assign the Collator
object to.
locales
Optional. An array of locale strings that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used. See the Remarks section for more information.
options
Optional. An object that contains one or more properties that specify comparison options. See the Remarks section for details.
Remarks
The locales
parameter must conform to BCP 47 language or locale tags such as "en-US" and "zh-Hans-CN". The tag may include language, region, country, and variant. For a list of languages, see the IANA language subtag registry. For examples of language tags, see Appendix A of BCP 47. For Collator
, you may include the -u extension in the locale string to specify one or more of the following Unicode extensions:
-co to specify variant collations (locale-specific): "language-region-u-co-value".
-kn to specify a numeric comparison: "language-region-u-kn-true|false".
-kf to specify whether to sort uppercase or lowercase characters first: "language-region-u-kf-upper|lower|false"). This extension is not currently supported.
To specify a numeric comparison, you can set the -kn extension in the locale string or use the
numeric
property in theoptions
parameter. If you're using thenumeric
property, the -kn value will not apply.The
options
parameter may include the following properties:localeMatcher
. Specifies the locale-matching algorithm to use. The possible values are "lookup" and "best fit". The default value is "best fit".usage
. Specifies whether the goal of comparison is sorting or searching. The possible values are "sort" and "search". The default value is "sort".sensitivity
. Specifies the collator's sensitivity. The possible values are "base", "accent", "case", and "variant". The default value isundefined
.ignorePunctuation
. Specifies whether punctuation is ignored in the comparison. The possible values are "true" and "false". The default value isfalse
.numeric
. Specifies whether numeric sorting is used. The possible values are "true" and "false". The default value isfalse
.caseFirst
. Not currently supported.
Properties
The following table lists the properties of the Collator
object.
Property | Description |
compare | Returns a function that compares two strings by using the collator's sort order. |
constructor | Specifies the function that creates a collator. |
prototype | Returns a reference to the prototype for a collator. |
Methods
The following table lists the methods of the Collator
object.
Method | Description |
resolvedOptions | Returns an object that contains the properties and values of the collator. |
Example
The following example creates a Collator
object and performs a comparison.
var co = new Intl.Collator(["de-DE"]);
co.compare("a", "b"); // Returns -1
Example
The following example uses Collator
objects to sort an array. This example shows locale-specific differences.
var co1 = new Intl.Collator(["de-DE-u-co-phonebk"]);
var co2 = new Intl.Collator(["de-DE"]);
var co3 = new Intl.Collator(["en-US"]);
var arr = ["ä", "ad", "af", "a"];
if (console && console.log) {
console.log(arr.sort(co1.compare)); // Returns a,ad,ä,af
console.log(arr.sort(co2.compare)); // Returns a,ä,ad,af
console.log(arr.sort(co3.compare)); // Returns a,ä,ad,af
}
Example
The following example uses a Collator
object to search for a string and specifies comparison options.
// String to search
var arr = ["ä", "ad", "af", "a"];
// String searched for
var s = "af";
var co = new Intl.Collator("de-DE", { usage: "search" });
var matches = arr.filter(function (i) {
return co.compare(i, s) === 0;
});
if (console && console.log) {
console.log(matches); // Returns af
}
Requirements
Supported in the Internet Explorer 11 standards document mode. Also supported in Store apps (Windows 8.1 and Windows Phone 8.1). See Version Information.
Not supported in the following document modes: Quirks, Internet Explorer 6 standards, Internet Explorer 7 standards, Internet Explorer 8 standards, Internet Explorer 9 standards, Internet Explorer 10 standards. Not supported in Windows 8.
See Also
localeCompare Method (String)
Intl.DateTimeFormat Object
Intl.NumberFormat Object