Cldr.Collation.Options (Cldr Collation v1.0.0)

Copy Markdown View Source

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

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() :: :default | :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() :: %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()
}

Functions

from_locale(locale)

@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(options)

@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(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). 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?(options)

@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