# `Unicode.Transform.Nif`
[🔗](https://github.com/elixir-unicode/unicode_transform/blob/v1.1.0/lib/unicode/transform/nif.ex#L1)

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.

# `available?`

```elixir
@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`

```elixir
@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`

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

---

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