Search documentation of Localize

# Localize.Collation.Options (Localize v0.39.0)

Copy Markdown View Source

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").

## Summary

### Types

alternate()
backend()
case_first_opt()
max_variable()
strength()
t()

### Functions

from_locale(locale)

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

max_variable_primary(options)

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

new(options \\ [])

Create a new options struct from a keyword list.

nif_compatible?(options)

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

## Types

# alternate()

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

# backend()

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

# case_first_opt()

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

# max_variable()

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

# strength()

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

# t()

    @type t() :: %Localize.Collation.Options{
      alternate: alternate(),
      backend: backend(),
      backwards: boolean(),
      case_first: case_first_opt(),
      case_level: boolean(),
      han_ordering: :implicit | :radical_stroke,
      max_variable: max_variable(),
      normalization: boolean(),
      numeric: boolean(),
      reorder: [atom()],
      strength: strength(),
      suppress_contractions: [non_neg_integer()],
      tailoring: map() | nil,
      type: atom()
    }

## Functions

# from_locale(locale)

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

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

### Arguments

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

### Returns

A `%Localize.Collation.Options{}` struct with parsed values.

### Examples

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

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

# max_variable_primary(options)

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

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

### Arguments

- `options` - a `%Localize.Collation.Options{}` struct.

### Returns

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

### Examples

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

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

# new(options \\ [])

    @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`).

- `:ignore_case` - `true` to ignore case differences (sets `strength: :secondary`).

- `:ignore_punctuation` - `true` to ignore punctuation and whitespace.

- `:casing` - `:sensitive` or `:insensitive` (convenience alias for strength).

- `:backend` - `:nif` or `:elixir`. The default is `:elixir`.

### Returns

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

### Examples

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

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

# nif_compatible?(options)

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

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

### Arguments

- `options` - a `%Localize.Collation.Options{}` struct.

### Returns

- `true` if the NIF backend can handle these options.

- `false` if the pure Elixir backend is required.

### Examples

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

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