Cldr.Collation.Nif (Cldr Collation v1.1.0)

Copy Markdown View Source

Optional NIF-based collation using ICU's C library.

This module provides high-performance Unicode collation by wrapping ICU4C via a Native Interface Function (NIF). It supports all ICU-configurable collation attributes: strength, backwards (French), alternate handling, case first, case level, normalization, numeric collation, and script reordering.

The NIF is opt-in and requires:

  1. ICU system libraries installed (libicu or icucore on macOS)
  2. The elixir_make dependency
  3. Enable the NIF via either:
    • Environment variable: CLDR_COLLATION_NIF=true mix compile
    • Application config in config.exs: config :ex_cldr_collation, :nif, true

The config key must be set in config.exs (not runtime.exs) because it is evaluated at compile time to include the :elixir_make compiler.

If the NIF is not available, available?/0 returns false and the pure Elixir implementation is used automatically.

Summary

Functions

available?()

Returns whether the NIF collation backend is available.

nif_compare(string_a, string_b, options)

Compare two strings using the ICU NIF collator with full option support.

reorder_codes_supported?(reorder_codes)

Returns whether all reorder codes in the list can be mapped to ICU values.

Functions

available?()

@spec available?() :: boolean()

Returns whether the NIF collation backend is available.

Returns

  • true if the NIF shared library was loaded successfully.
  • false if the NIF is not compiled or ICU libraries are missing.

Examples

iex> is_boolean(Cldr.Collation.Nif.available?())
true

nif_compare(string_a, string_b, options)

@spec nif_compare(String.t(), String.t(), Cldr.Collation.Options.t()) ::
  :lt | :eq | :gt

Compare two strings using the ICU NIF collator with full option support.

Arguments

  • string_a - the first string to compare.
  • string_b - the second string to compare.
  • options - a %Cldr.Collation.Options{} struct.

Returns

  • :lt if string_a sorts before string_b.
  • :eq if string_a and string_b are collation-equal.
  • :gt if string_a sorts after string_b.

reorder_codes_supported?(reorder_codes)

@spec reorder_codes_supported?([atom()]) :: boolean()

Returns whether all reorder codes in the list can be mapped to ICU values.

Arguments

  • reorder_codes - a list of script code atoms (e.g., [:Grek, :Latn]).

Returns

  • true if all codes are recognized.
  • false if any code is unrecognized.

Examples

iex> Cldr.Collation.Nif.reorder_codes_supported?([:Grek, :Latn])
true

iex> Cldr.Collation.Nif.reorder_codes_supported?([:Unknown])
false

iex> Cldr.Collation.Nif.reorder_codes_supported?([])
true