# `Intl.Collator`
[🔗](https://github.com/elixir-localize/intl/blob/v1.1.0/lib/intl/collator.ex#L1)

Locale-sensitive string comparison, modelled on
[`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator).

Compares and sorts strings according to the Unicode Collation
Algorithm with CLDR locale tailoring.

Delegates to `Localize.Collation` for the underlying comparison.

Note: the JS Intl.Collator returns -1, 0, or 1 from `compare`.
This module returns `:lt`, `:eq`, or `:gt` following Elixir
conventions, making it compatible with `Enum.sort/2`.

# `compare`

```elixir
@spec compare(String.t(), String.t(), Keyword.t()) ::
  :lt | :eq | :gt | {:error, Exception.t()}
```

Compares two strings according to locale collation rules.

### Arguments

* `string1` is the first string.

* `string2` is the second string.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier string or atom. The default
  is the current process locale.

* `:sensitivity` is `:base`, `:accent`, `:case`, or `:variant`.
  The default is `:variant`.

* `:case_first` is `:upper`, `:lower`, or `:false`.
  Determines whether upper or lower case sorts first.

* `:numeric` is a boolean. When `true`, numeric substrings
  are compared as numbers (so "2" < "10"). The default is `false`.

* `:ignore_punctuation` is a boolean. When `true`, punctuation
  is ignored during comparison. The default is `false`.

* `:usage` is `:sort` or `:search`. When `:search`, the
  locale's search collation tailoring is used. The default
  is `:sort`.

* `:collation` is a collation type atom (for example,
  `:phonebook`, `:pinyin`, `:emoji`). Ignored when `:usage`
  is `:search`. Locales without the requested tailoring fall
  back to the root collation.

### Returns

* `:lt` if `string1` sorts before `string2`.

* `:eq` if the strings are equal under the collation rules.

* `:gt` if `string1` sorts after `string2`.

* `{:error, exception}`, a `Localize.InvalidValueError`, if a string is
  not valid UTF-8 or an option has a value outside its documented set.

### Examples

    iex> Intl.Collator.compare("a", "b", locale: :en)
    :lt

    iex> Intl.Collator.compare("b", "a", locale: :en)
    :gt

    iex> Intl.Collator.compare("a", "a", locale: :en)
    :eq

# `sort`

```elixir
@spec sort([String.t()], Keyword.t()) :: [String.t()] | {:error, Exception.t()}
```

Sorts a list of strings according to locale collation rules.

This is an Elixir convenience function not present in the JS
Intl.Collator API.

### Arguments

* `list` is a list of strings.

* `options` is a keyword list of options. Accepts the same
  options as `compare/3`.

### Returns

* A sorted list of strings, or

* `{:error, exception}`, a `Localize.InvalidValueError`, if the list
  holds anything but valid UTF-8 strings or an option has a value
  outside its documented set.

### Examples

    iex> Intl.Collator.sort(["banana", "apple", "cherry"], locale: :en)
    ["apple", "banana", "cherry"]

    iex> Intl.Collator.sort(["apple", 1], locale: :en) |> elem(0)
    :error

---

*Consult [api-reference.md](api-reference.md) for complete listing*