# `Cldr.Collation.Options`
[🔗](https://github.com/elixir-cldr/cldr_collation/blob/v1.0.0/lib/cldr/collation/options.ex#L1)

Cldr.Collation options corresponding to BCP47 -u- extension keys.

Supports both Elixir keyword list construction and parsing from
BCP47 locale strings (e.g., "en-u-co-phonebk-ks-level2").

# `alternate`

```elixir
@type alternate() :: :non_ignorable | :shifted
```

# `backend`

```elixir
@type backend() :: :default | :nif | :elixir
```

# `case_first_opt`

```elixir
@type case_first_opt() :: :upper | :lower | false
```

# `max_variable`

```elixir
@type max_variable() :: :space | :punct | :symbol | :currency
```

# `strength`

```elixir
@type strength() :: :primary | :secondary | :tertiary | :quaternary | :identical
```

# `t`

```elixir
@type t() :: %Cldr.Collation.Options{
  alternate: alternate(),
  backend: backend(),
  backwards: boolean(),
  case_first: case_first_opt(),
  case_level: boolean(),
  max_variable: max_variable(),
  normalization: boolean(),
  numeric: boolean(),
  reorder: [atom()],
  strength: strength(),
  tailoring: map() | nil,
  type: atom()
}
```

# `from_locale`

```elixir
@spec from_locale(String.t()) :: t()
```

Parse collation options from a BCP47 locale string with `-u-` extension.

Extracts collation-related keys from the Unicode locale extension subtag and
applies locale-specific defaults and tailoring rules. Supported BCP47 keys:
`co`, `ks`, `ka`, `kb`, `kk`, `kc`, `kf`, `kn`, `kr`, `kv`.

Option precedence (highest to lowest): BCP47 `-u-` keys > locale defaults >
tailoring rule overrides > struct defaults.

### Arguments

* `locale` - a BCP47 locale string (e.g., `"en-u-co-phonebk-ks-level2-ka-shifted"`).

### Returns

A `%Cldr.Collation.Options{}` struct with parsed values, locale defaults, and a
tailoring overlay (if available for the locale). Unrecognized keys are ignored
and defaults are used for missing keys.

### Examples

    iex> options = Cldr.Collation.Options.from_locale("en-u-ks-level2")
    iex> options.strength
    :secondary

    iex> options = Cldr.Collation.Options.from_locale("da")
    iex> options.case_first
    :upper

# `max_variable_primary`

```elixir
@spec max_variable_primary(t()) :: non_neg_integer()
```

Return the maximum primary weight that counts as "variable" for the given setting.

These boundaries come from the FractionalUCA.txt top_byte groupings. Variable
elements at or below this primary weight threshold are affected by the
`:alternate` setting in shifted mode.

### Arguments

* `options` - a `%Cldr.Collation.Options{}` struct.

### Returns

A non-negative integer representing the maximum primary weight boundary:

* `:space` - `0x0209`.
* `:punct` - `0x0B61`.
* `:symbol` - `0x0EE3`.
* `:currency` - `0x0EFF`.

### Examples

    iex> Cldr.Collation.Options.max_variable_primary(%Cldr.Collation.Options{max_variable: :punct})
    0x0B61

    iex> Cldr.Collation.Options.max_variable_primary(%Cldr.Collation.Options{max_variable: :space})
    0x0209

# `new`

```elixir
@spec new(keyword()) :: t()
```

Create a new options struct from a keyword list.

### Arguments

* `options` - a keyword list of collation options (default: `[]`).

### Options

* `:strength` - `:primary`, `:secondary`, `:tertiary` (default), `:quaternary`, or `:identical`.
* `:alternate` - `:non_ignorable` (default) or `:shifted`.
* `:backwards` - `false` (default) or `true`.
* `:normalization` - `false` (default) or `true`.
* `:case_level` - `false` (default) or `true`.
* `:case_first` - `false` (default), `:upper`, or `:lower`.
* `:numeric` - `false` (default) or `true`.
* `:reorder` - a script code atom or list of script code atoms (default: `[]`).
* `:max_variable` - `:space`, `:punct` (default), `:symbol`, or `:currency`.
* `:type` - `:standard` (default), `:search`, `:phonebook`, etc.
* `:ignore_accents` - `true` to ignore accent differences (sets `strength: :primary`).
  Explicit `:strength` takes precedence.
* `:ignore_case` - `true` to ignore case differences (sets `strength: :secondary`).
  Explicit `:strength` takes precedence.
* `:ignore_punctuation` - `true` to ignore punctuation and whitespace.
  (sets `strength: :tertiary, alternate: :shifted`). Explicit `:strength` or
  `:alternate` take precedence.
* `:casing` - `:sensitive` (default tertiary strength) or `:insensitive` (secondary strength).
  This is a convenience option compatible with the `ex_cldr_collation` API. When provided,
  it sets the `:strength` option accordingly.
* `:backend` - `:default` (use NIF if available, default), `:nif` (require NIF), or `:elixir` (pure Elixir only).

### Returns

A `%Cldr.Collation.Options{}` struct.

### Examples

    iex> Cldr.Collation.Options.new()
    %Cldr.Collation.Options{strength: :tertiary, alternate: :non_ignorable}

    iex> Cldr.Collation.Options.new(strength: :primary, alternate: :shifted)
    %Cldr.Collation.Options{strength: :primary, alternate: :shifted}

# `nif_compatible?`

```elixir
@spec nif_compatible?(t()) :: boolean()
```

Returns whether the given options can be handled by the NIF backend.

The NIF backend supports all ICU-configurable collation attributes:
strength (all 5 levels), backwards, alternate, case_first, case_level,
normalization, numeric collation, and script reordering (for recognized
script codes).

Options that require the pure Elixir backend: `tailoring` (locale-specific
rules), non-default `max_variable` (fragile across ICU versions), and
reorder lists containing unrecognized script codes.

### Arguments

* `options` - a `%Cldr.Collation.Options{}` struct.

### Returns

* `true` if the NIF backend can handle these options.
* `false` if the pure Elixir backend is required.

### Examples

    iex> Cldr.Collation.Options.nif_compatible?(%Cldr.Collation.Options{})
    true

    iex> Cldr.Collation.Options.nif_compatible?(%Cldr.Collation.Options{numeric: true})
    true

    iex> Cldr.Collation.Options.nif_compatible?(%Cldr.Collation.Options{reorder: [:Grek]})
    true

---

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