# `ExDataSketch.Hash.XXH3`
[🔗](https://github.com/thanos/ex_data_sketch/blob/main/lib/ex_data_sketch/hash/xxh3.ex#L1)

XXHash3 (64-bit) hash algorithm.

XXHash3 is the **default** hash algorithm for ExDataSketch. It is stable
across platforms, OS versions, CPU architectures, and OTP versions when
computed via the Rust NIF.

## Properties

| Property            | Value                                   |
|---------------------|-----------------------------------------|
| Output bits         | 64                                      |
| Seedable            | Yes (`u64`)                             |
| Cross-platform      | Yes                                     |
| Cross-OTP stable    | Yes (via NIF). No when NIF unavailable. |
| BEAM-side fallback  | `:erlang.phash2` + `mix64`              |

When the Rust NIF is available, `hash/2` calls the upstream `xxhash-rust`
implementation directly. When the NIF is unavailable, `hash/2` raises an
`ArgumentError` so that hash drift cannot occur silently — callers that
want a NIF-less fallback must explicitly select `ExDataSketch.Hash`
with `hash_strategy: :phash2`.

## Examples

    iex> ExDataSketch.Hash.XXH3.available?() in [true, false]
    true

# `available?`

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

Returns whether this algorithm is available in the current runtime.

XXHash3 requires the Rust NIF to be loaded.

## Examples

    iex> is_boolean(ExDataSketch.Hash.XXH3.available?())
    true

# `hash`

```elixir
@spec hash(binary(), non_neg_integer()) :: ExDataSketch.Hash.hash64()
```

Hashes a binary using XXHash3 (64-bit) with the given seed.

Requires the Rust NIF. Raises `ArgumentError` if the NIF is not loaded;
this is intentional so that hash drift cannot occur silently when the
NIF is missing. Callers that want a BEAM-only fallback must explicitly
pick `hash_strategy: :phash2` (or `:murmur3` for cross-OTP-stable
pure-Elixir hashing) via `ExDataSketch.Hash.hash64/2`.

## Examples

When the NIF is available, `hash/2` returns a `u64` value:

    iex> if ExDataSketch.Hash.XXH3.available?() do
    ...>   h = ExDataSketch.Hash.XXH3.hash("hello", 0)
    ...>   is_integer(h) and h >= 0 and h <= 0xFFFFFFFFFFFFFFFF
    ...> else
    ...>   # When the NIF is missing, hash/2 MUST raise ArgumentError.
    ...>   # We verify that contract explicitly.
    ...>   try do
    ...>     ExDataSketch.Hash.XXH3.hash("hello", 0)
    ...>     false
    ...>   rescue
    ...>     ArgumentError -> true
    ...>   end
    ...> end
    true

# `id`

```elixir
@spec id() :: :xxhash3
```

Returns the algorithm identifier `:xxhash3`.

## Examples

    iex> ExDataSketch.Hash.XXH3.id()
    :xxhash3

---

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