# Global.Intl.Collator

Immutable object used to perform language sensitive string comparisons.

Availability
9.1.0
6.0.0
9.2.0
Extends
Object

# Overview

A collator is used to perform a localized string compare or sort using a given language locale.

For more detail, see the MDN website about Intl.Collator (opens new window).

# Examples

# Array Sorting

// Sort using collator. Array becomes: [ 'a', 'b', 'c' ]
const elements = [ 'c', 'b', 'a' ];
elements.sort(new Intl.Collator().compare);
console.log(`Sorted Elements: ${elements}`);

# String Compare Sensitivity

// Case sensitive and accent sensitive string matching.
// This is the default collator sensitivity.
console.log('Variant Sensitivity:');
let collator = new Intl.Collator(Ti.Locale.currentLocale, { sensitivity: 'variant' });
console.log(collator.compare('a', 'a') === 0);  // Equal
console.log(collator.compare('a', 'á') === 0);  // Not Equal
console.log(collator.compare('a', 'A') === 0);  // Not Equal
console.log(collator.compare('a', 'b') === 0);  // Not Equal

// Case sensitive matching, ignoring accents marks.
console.log('Case Sensitivity:');
collator = new Intl.Collator(Ti.Locale.currentLocale, { sensitivity: 'case' });
console.log(collator.compare('a', 'a') === 0);  // Equal
console.log(collator.compare('a', 'á') === 0);  // Equal
console.log(collator.compare('a', 'A') === 0);  // Not Equal
console.log(collator.compare('a', 'b') === 0);  // Not Equal

// Do an accent sensitive match, ignoring case.
console.log('Accent Sensitivity:');
collator = new Intl.Collator(Ti.Locale.currentLocale, { sensitivity: 'accent' });
console.log(collator.compare('a', 'a') === 0);  // Equal
console.log(collator.compare('a', 'á') === 0);  // Not Equal
console.log(collator.compare('a', 'A') === 0);  // Equal
console.log(collator.compare('a', 'b') === 0);  // Not Equal

// Match strings having same base letters, ignoring case and accents.
console.log('Base Sensitivity:');
collator = new Intl.Collator(Ti.Locale.currentLocale, { sensitivity: 'base' });
console.log(collator.compare('a', 'a') === 0);  // Equal
console.log(collator.compare('a', 'á') === 0);  // Equal
console.log(collator.compare('a', 'A') === 0);  // Equal
console.log(collator.compare('a', 'b') === 0);  // Not Equal

# Properties

# constructor READONLY

Availability
9.1.0
6.0.0
9.2.0
constructor :Global.Intl.Collator

Creates a new Intl.Collator object with the given locale and comparison options.

# Syntax

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

# Parameters

  • locales: Global.String/Global.String[] (optional)

    The BCP 47 language and country code(s) to use for localized string comparisons. Can provide multiple locales where the best-supported locale will be favored in the order provided by the array. If parameter is not assigned, then the system may use the 'en-US' locale by default instead of the system's current locale. It's recommended to set this parameter using currentLocale.

  • options: CollatorOptions (optional)

    Provides settings indicating how strings should be compared.

# Methods

# compare

Availability
9.1.0
6.0.0
9.2.0
compare(string1, string2) Number

Determines the sort order of the given strings or if they match.

Parameters

Name Type Description
string1 String

The string to be compared with argument string2.

string2 String

The string to be compared with argument string1.

Returns

Returns zero if strings are equal. Returns a negative value if string1 sorts before string2. Returns a positive value if string1 sorts after string2.

Type
Number

# resolvedOptions

Availability
9.1.0
6.0.0
9.2.0
resolvedOptions() CollatorOptions

Gets the object's collation options.

Returns the collation options the collator object uses.

For more detail, see the MDN website about resolvedOptions.

Returns

Returns the collation options used.


# supportedLocalesOf

Availability
9.1.0
6.0.0
9.2.0
supportedLocalesOf(locales) Array<String>

Static method indicating what locales are supported by collators from the given locale(s).

For more detail, see the MDN website about supportedLocalesOf.

Parameters

Name Type Description
locales String | Array<String>

A string or array of strings providing BCP 47 locale identifiers to query.

Returns

Array containing a subset of the given locale strings supported by collators.

Type
Array<String>