Unicode.Transform.Nif (Unicode Transform v1.1.0)

Copy Markdown View Source

Optional NIF-based Unicode transforms using ICU4C.

This module provides high-performance Unicode transliteration by wrapping ICU4C's utrans API via a Native Interface Function (NIF). When available, transforms are dispatched to ICU for execution; otherwise, the pure-Elixir engine is used automatically.

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: UNICODE_TRANSFORM_NIF=true mix compile
    • Application config in config.exs: config :unicode_transform, :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 transform backend is available.

available_ids()

Returns a list of all ICU-registered transliterator IDs.

transform(id, text, direction)

Transforms a string using an ICU transliterator.

Functions

available?()

@spec available?() :: boolean()

Returns whether the NIF transform backend is available.

The NIF is considered available when it is enabled via the UNICODE_TRANSFORM_NIF environment variable or the :nif application config key, and the shared library was loaded successfully.

Returns

  • true if the NIF is enabled and the shared library was loaded.

  • false otherwise.

Examples

iex> is_boolean(Unicode.Transform.Nif.available?())
true

available_ids()

@spec available_ids() :: [String.t()]

Returns a list of all ICU-registered transliterator IDs.

Returns

A list of transform ID strings (e.g., ["ASCII-Latin", "Any-Accents", ...]).

transform(id, text, direction)

@spec transform(String.t(), String.t(), 0 | 1) ::
  {:ok, String.t()} | {:error, String.t()}

Transforms a string using an ICU transliterator.

Arguments

  • id — the ICU transform ID (e.g., "Latin-ASCII", "Greek-Latin").

  • text — the input string to transform.

  • direction — 0 for forward (UTRANS_FORWARD), 1 for reverse (UTRANS_REVERSE).

Returns

  • {:ok, result} on success.

  • {:error, reason} on failure.