# Global.Intl.Collator

> Immutable object used to perform language sensitive string comparisons.

- Source: https://titaniumsdk.com/docs/sdk/12.5.0/Global.Intl.Collator
- Titanium SDK version: 12.5.0
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 6.0.0, iPad 6.0.0, Android 9.1.0, macOS 9.2.0

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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator).

## Example: Array Sorting

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

## Example: String Compare Sensitivity

``` js
// 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

- Type: Global.Intl.Collator
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

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

#### Syntax

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

#### Parameters

*    `locales`: [String](https://titaniumsdk.com/docs/sdk/Global.String.md)/[String](https://titaniumsdk.com/docs/sdk/Global.String.md)`[]` (optional)

     The [BCP 47](https://www.unicode.org/reports/tr35/tr35.html#BCP_47_Conformance) 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 [Titanium.Locale.currentLocale](https://titaniumsdk.com/docs/sdk/Titanium.Locale.md#currentLocale).

*    `options`: [CollatorOptions](https://titaniumsdk.com/docs/sdk/CollatorOptions.md) (optional)

     Provides settings indicating how strings should be compared.

## Methods

### compare

- Platforms: Android, iPhone, iPad, macOS

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

Parameters:

- `string1` (String): The string to be compared with argument `string2`.
- `string2` (String): The string to be compared with argument `string1`.

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

### resolvedOptions

- Platforms: Android, iPhone, iPad, macOS

Gets the object's collation options.

Returns the collation options the collator object uses.

For more detail, see the MDN website about
[resolvedOptions](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/resolvedOptions).

Returns: CollatorOptions - Returns the collation options used.

### supportedLocalesOf

- Platforms: Android, iPhone, iPad, macOS

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

For more detail, see the MDN website about
[supportedLocalesOf](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/supportedLocalesOf).

Parameters:

- `locales` (String | Array<String>): A string or array of strings providing BCP 47 locale identifiers to query.

Returns: Array<String> - Array containing a subset of the given locale strings supported by collators.

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.