# `F3.Native`

Optional native decoder.

A Hex package that includes `checksum-Elixir.F3.Native.exs` downloads a
precompiled NIF for macOS Apple silicon (`aarch64-apple-darwin`) or Linux
x86_64 (`x86_64-unknown-linux-gnu`). OTP 28 uses NIF version 2.17. This
repository has no checksum file, so `available?/0` is false unless
`F3_BUILD_NATIVE=1` at compile time and the `rustler` dependency is
available. `info/0` reports the crate name and version. `decode_encunit/3`
decodes one CASCADE encoding unit on the dirty CPU scheduler. It does not
open files, decode FlatBuffers, or run WebAssembly. The crate does not
link `fff-poc` and does not install a global allocator. Wasmtime 28 is in
the same crate. It runs only when `decode_wasm/5` is called, which
`F3.read/2` does only for `wasm: :sandbox`.

Mix recompiles this module when `F3_BUILD_NATIVE` changes and when the
checksum file appears. Other targets compile from source with
`F3_BUILD_NATIVE=1`.

# `available?`

```elixir
@spec available?() :: boolean()
```

Whether this VM loaded the native scaffold.

The default build does not compile the NIF, so this is `false`.

## Examples

    iex> F3.Native.available?()
    false

# `decode_encunit`

```elixir
@spec decode_encunit(binary(), atom(), atom()) :: {:error, :native_unavailable}
```

Decodes one encoding unit when the NIF was compiled.

`bytes` is the unit. `compression` is `:uncompressed`, `:zstd`, or
`:lz4`. `type` is the physical kind, such as `:i64`. This build returns
`{:error, :native_unavailable}` and does not raise.

## Examples

    iex> F3.Native.decode_encunit(<<>>, :uncompressed, :i64)
    {:error, :native_unavailable}

# `info`

```elixir
@spec info() :: {:ok, {String.t(), String.t()}} | {:error, :native_unavailable}
```

Returns `{:ok, {crate_name, version}}` when the NIF is loaded.

This build has no NIF, so the result is `:native_unavailable`. It does
not raise.

## Examples

    iex> F3.Native.info()
    {:error, :native_unavailable}

---

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