# `Uuid58`
[🔗](https://github.com/nakanoasaservice/uuid58/blob/elixir/v0.1.1/elixir/lib/uuid58.ex#L1)

Shorten UUIDs to 22-character Base58 strings, and back.

Implements the [uuid58 specification](https://github.com/nakanoasaservice/uuid58/blob/main/spec/SPEC.md).
The alphabet is the Bitcoin Base58 alphabet, every encoding is exactly 22
characters, and sorting the strings byte by byte sorts the UUIDs.

    iex> Uuid58.encode!("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
    "XDY9dmBbcMBXqcRvYw8xJ2"

    iex> Uuid58.decode!("XDY9dmBbcMBXqcRvYw8xJ2")
    "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"

    iex> Uuid58.valid?("XDY9dmBbcMBXqcRvYw8xJ2")
    true

    iex> Uuid58.decode("nope")
    {:error, :invalid_length}

`encode/1` and `decode/1` return `{:ok, value}` or `{:error, kind}`.
The bang variants raise `Uuid58.Error`. `kind` is `:invalid_length`,
`:invalid_character`, or `:overflow`.

# `kind`

```elixir
@type kind() :: Uuid58.Error.kind()
```

A spec error kind.

# `alphabet`

```elixir
@spec alphabet() :: String.t()
```

The Bitcoin Base58 alphabet. The character at position `i` (zero-based) is
the digit with value `i`.

# `decode`

```elixir
@spec decode(binary()) :: {:ok, String.t()} | {:error, kind()}
```

Decodes a uuid58 string to the lowercase hyphenated UUID.

The input must be exactly 22 characters from `alphabet/0`. Matching is
case-sensitive, and whitespace is not trimmed. A value above `2**128 - 1`
is `{:error, :overflow}`.

Length is measured in bytes. Any non-ASCII byte is rejected.

## Examples

    iex> Uuid58.decode("XDY9dmBbcMBXqcRvYw8xJ2")
    {:ok, "f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf"}

    iex> Uuid58.decode("zzzzzzzzzzzzzzzzzzzzzz")
    {:error, :overflow}

# `decode!`

```elixir
@spec decode!(binary()) :: String.t()
```

Like `decode/1`, but returns the UUID string or raises `Uuid58.Error`.

# `decode_bytes`

```elixir
@spec decode_bytes(binary()) :: {:ok, &lt;&lt;_::128&gt;&gt;} | {:error, kind()}
```

Decodes a uuid58 string to 16 big-endian bytes.

Returns the same errors as `decode/1`.

## Examples

    iex> {:ok, raw} = Uuid58.decode_bytes("XDY9dmBbcMBXqcRvYw8xJ2")
    iex> Base.encode16(raw, case: :lower)
    "f4b247fd1f8745d4aa061c6fc0a8dfaf"

# `decode_bytes!`

```elixir
@spec decode_bytes!(binary()) :: &lt;&lt;_::128&gt;&gt;
```

Like `decode_bytes/1`, but returns the bytes or raises `Uuid58.Error`.

# `decode_integer`

```elixir
@spec decode_integer(binary()) :: {:ok, non_neg_integer()} | {:error, kind()}
```

Decodes a uuid58 string to an integer in `0..2**128 - 1`.

## Examples

    iex> Uuid58.decode_integer("1111111111111111111112")
    {:ok, 1}

# `decode_integer!`

```elixir
@spec decode_integer!(binary()) :: non_neg_integer()
```

Like `decode_integer/1`, but returns the integer or raises `Uuid58.Error`.

# `encode`

```elixir
@spec encode(binary() | integer()) :: {:ok, String.t()} | {:error, kind()}
```

Encodes a UUID string or an integer in `0..2**128 - 1`.

A UUID string is either the hyphenated form
`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` or 32 hexadecimal digits, in any
letter case. Braces, the `urn:uuid:` prefix, whitespace, and hyphens in
other positions are rejected.

A 16-byte binary is not read as raw bytes here. Pass it to `encode_bytes/1`.

Returns `{:error, kind}` for invalid input. Raises `FunctionClauseError`
for any other type.

## Examples

    iex> Uuid58.encode("f4b247fd-1f87-45d4-aa06-1c6fc0a8dfaf")
    {:ok, "XDY9dmBbcMBXqcRvYw8xJ2"}

    iex> Uuid58.encode("F4B247FD1F8745D4AA061C6FC0A8DFAF")
    {:ok, "XDY9dmBbcMBXqcRvYw8xJ2"}

    iex> Uuid58.encode(0)
    {:ok, "1111111111111111111111"}

    iex> Uuid58.encode(-1)
    {:error, :overflow}

# `encode!`

```elixir
@spec encode!(binary() | integer()) :: String.t()
```

Like `encode/1`, but returns the uuid58 string or raises `Uuid58.Error`.

# `encode_bytes`

```elixir
@spec encode_bytes(binary()) :: {:ok, String.t()} | {:error, :invalid_length}
```

Encodes 16 bytes, read as an unsigned big-endian integer (RFC 9562 order,
the same order `Ecto.UUID.dump/1` produces).

Returns `{:error, :invalid_length}` when `bytes` is not exactly 16 bytes.

## Examples

    iex> raw = Base.decode16!("f4b247fd1f8745d4aa061c6fc0a8dfaf", case: :mixed)
    iex> Uuid58.encode_bytes(raw)
    {:ok, "XDY9dmBbcMBXqcRvYw8xJ2"}

    iex> Uuid58.encode_bytes(<<0>>)
    {:error, :invalid_length}

# `encode_bytes!`

```elixir
@spec encode_bytes!(binary()) :: String.t()
```

Like `encode_bytes/1`, but returns the uuid58 string or raises `Uuid58.Error`.

# `encode_integer`

```elixir
@spec encode_integer(integer()) :: {:ok, String.t()} | {:error, :overflow}
```

Encodes an integer in `0..2**128 - 1`.

Returns `{:error, :overflow}` for an integer outside that range.

## Examples

    iex> Uuid58.encode_integer(0xF4B247FD1F8745D4AA061C6FC0A8DFAF)
    {:ok, "XDY9dmBbcMBXqcRvYw8xJ2"}

# `encode_integer!`

```elixir
@spec encode_integer!(integer()) :: String.t()
```

Like `encode_integer/1`, but returns the uuid58 string or raises `Uuid58.Error`.

# `generate`

```elixir
@spec generate() :: String.t()
```

Generates a random UUID version 4 and returns its uuid58 encoding.

Uses `:crypto.strong_rand_bytes/1`.

# `max_integer`

```elixir
@spec max_integer() :: non_neg_integer()
```

The largest 128-bit value, `2**128 - 1`.

# `max_uuid58`

```elixir
@spec max_uuid58() :: String.t()
```

The largest valid uuid58 string, the encoding of
`ffffffff-ffff-ffff-ffff-ffffffffffff`.

# `valid?`

```elixir
@spec valid?(term()) :: boolean()
```

Returns `true` exactly when `decode/1` would succeed.

Never raises. Any non-binary returns `false`.

## Examples

    iex> Uuid58.valid?("XDY9dmBbcMBXqcRvYw8xJ2")
    true

    iex> Uuid58.valid?("zzzzzzzzzzzzzzzzzzzzzz")
    false

    iex> Uuid58.valid?(nil)
    false

---

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