Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Intl.Collator Object (JavaScript)

Provides locale-specific string comparisons.

collatorObj = new Intl.Collator([locales][, options])

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.

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 the options parameter. If you're using the numeric 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 is undefined.

  • ignorePunctuation . Specifies whether punctuation is ignored in the comparison. The possible values are "true" and "false". The default value is false.

  • numeric . Specifies whether numeric sorting is used. The possible values are "true" and "false". The default value is false.

  • caseFirst . Not currently supported.

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.

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.

The following example creates a Collator object and performs a comparison.

var co = new Intl.Collator(["de-DE"]);
co.compare("a", "b"); // Returns -1

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
}

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
}

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.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft