# Global.Intl.Collator
Immutable object used to perform language sensitive string comparisons.
# 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
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
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 | String | The string to be compared with argument |
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
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.
- Type
- CollatorOptions
# supportedLocalesOf
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>