Uuid58 (uuid58 v0.1.1)

Copy Markdown View Source

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

Types

A spec error kind.

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

kind()

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

A spec error kind.

Functions

alphabet()

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

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

decode(str)

@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!(str)

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

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

decode_bytes(str)

@spec decode_bytes(binary()) :: {:ok, <<_::128>>} | {: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!(str)

@spec decode_bytes!(binary()) :: <<_::128>>

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

decode_integer(str)

@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!(str)

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

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

encode(int)

@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!(int)

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

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

encode_bytes(bytes)

@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!(bytes)

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

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

encode_integer(int)

@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!(int)

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

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

generate()

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

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

Uses :crypto.strong_rand_bytes/1.

max_integer()

@spec max_integer() :: non_neg_integer()

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

max_uuid58()

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

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

valid?(str)

@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