Intl.Collator Object (JavaScript)

• 01/18/2017
• 3 minutes to read
• Contributors
  • 
  • 
  • 

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 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.

Properties

The following table lists the properties of the Collator object.

Methods

The following table lists the methods of the Collator object.

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