Shorten UUIDs to 22-character Base58 strings, and back.
Implements the uuid58 specification. 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.
Summary
Functions
The Bitcoin Base58 alphabet. The character at position i (zero-based) is
the digit with value i.
Decodes a uuid58 string to the lowercase hyphenated UUID.
Like decode/1, but returns the UUID string or raises Uuid58.Error.
Decodes a uuid58 string to 16 big-endian bytes.
Like decode_bytes/1, but returns the bytes or raises Uuid58.Error.
Decodes a uuid58 string to an integer in 0..2**128 - 1.
Like decode_integer/1, but returns the integer or raises Uuid58.Error.
Encodes a UUID string or an integer in 0..2**128 - 1.
Like encode/1, but returns the uuid58 string or raises Uuid58.Error.
Encodes 16 bytes, read as an unsigned big-endian integer (RFC 9562 order,
the same order Ecto.UUID.dump/1 produces).
Like encode_bytes/1, but returns the uuid58 string or raises Uuid58.Error.
Encodes an integer in 0..2**128 - 1.
Like encode_integer/1, but returns the uuid58 string or raises Uuid58.Error.
Generates a random UUID version 4 and returns its uuid58 encoding.
The largest 128-bit value, 2**128 - 1.
The largest valid uuid58 string, the encoding of
ffffffff-ffff-ffff-ffff-ffffffffffff.
Returns true exactly when decode/1 would succeed.
Types
@type kind() :: Uuid58.Error.kind()
A spec error kind.
Functions
@spec alphabet() :: String.t()
The Bitcoin Base58 alphabet. The character at position i (zero-based) is
the digit with value i.
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}
Like decode/1, but returns the UUID string or raises Uuid58.Error.
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"
@spec decode_bytes!(binary()) :: <<_::128>>
Like decode_bytes/1, but returns the bytes or raises Uuid58.Error.
@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}
@spec decode_integer!(binary()) :: non_neg_integer()
Like decode_integer/1, but returns the integer or raises Uuid58.Error.
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}
Like encode/1, but returns the uuid58 string or raises Uuid58.Error.
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}
Like encode_bytes/1, but returns the uuid58 string or raises Uuid58.Error.
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"}
Like encode_integer/1, but returns the uuid58 string or raises Uuid58.Error.
@spec generate() :: String.t()
Generates a random UUID version 4 and returns its uuid58 encoding.
@spec max_integer() :: non_neg_integer()
The largest 128-bit value, 2**128 - 1.
@spec max_uuid58() :: String.t()
The largest valid uuid58 string, the encoding of
ffffffff-ffff-ffff-ffff-ffffffffffff.
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