ShortUUID

v1.0.1

ShortUUID v1.0.1 ShortUUID

ShortUUID is a simple UUID shortener library.

Installation

Add ShortUUID to your list of dependencies in mix.exs:

def deps do
  [{:shortuuid, "~> 1.0.1"}]
end

Optionally configure the alphabet to be used for encoding in config.exs:

  config :shortuuid,
    alphabet: "23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"

Note that for this to take effect currently requires recompiling the dependency. The default alphabet (above) will translate UUIDs to base57 using lowercase and uppercase letters and digits while avoiding similar-looking characters such as l, 1, I, O and 0.

Typical usage

Use ShortUUID to shorten UUID strings generated by other libraries such as Ecto, Elixir UUID and Erlang UUID.

Notes

For compatibility with the python version we also pad values to the length it takes to store a UUID in the chosen alphabet.

Any UUID will be padded to length 22 in case of the default base 57 alphabet. The pad character is always the first character of the alphabet which represents zero. In the default alphabet that character is 2 since it doesn’t include 0 and 1.

iex> ShortUUID.encode!("00000000-0000-0000-0000-000000000000")
"2222222222222222222222"


iex> ShortUUID.encode!("00000001-0001-0001-0001-000000000001")
"UD6ibhr3V4YXvriP822222"


iex> ShortUUID.decode!("UD6ibhr3V4YXvriP822222")
"00000001-0001-0001-0001-000000000001"

If we didn’t do the padding the nil UUID for example would simply encode into an empty string since it’s int value is 0.

Some supported UUID input formats are:

  • 2a162ee5-02f4-4701-9e87-72762cbce5e2
  • 2a162ee502f447019e8772762cbce5e2
  • {2a162ee5-02f4-4701-9e87-72762cbce5e2}

Letter case is not relevant.

Acknowledgments

This project was inspired by skorokithakis/shortuuid.

Link to this section Summary

Functions

decode(string)

Decode a shortened UUID

decode!(string)

Decode a shortened UUID

encode(uuid)

Encode a UUID using the chosen alphabet

encode!(uuid)

Encode a UUID using the chosen alphabet

Link to this section Functions

Link to this function decode(string) 
decode(String.t) :: {:ok, String.t} | {:error, String.t}

Decode a shortened UUID.

Examples 

iex> ShortUUID.decode!("keATfB8JP2ggT7U9JZrpV9")
"2a162ee5-02f4-4701-9e87-72762cbce5e2"
Link to this function decode!(string) 
decode!(String.t) :: String.t

Decode a shortened UUID.

Similar to decode/1 but raises an ArgumentError if the encoded UUID is invalid.

Link to this function encode(uuid) 
encode(String.t) :: {:ok, String.t} | {:error, String.t}

Encode a UUID using the chosen alphabet.

Examples 

iex> ShortUUID.encode("2a162ee5-02f4-4701-9e87-72762cbce5e2")
{:ok, "keATfB8JP2ggT7U9JZrpV9"}
Link to this function encode!(uuid) 
encode!(String.t) :: String.t

Encode a UUID using the chosen alphabet.

Similar to encode/1 but raises an ArgumentError if it cannot process the UUID.

Examples 

iex> ShortUUID.encode!("2a162ee5-02f4-4701-9e87-72762cbce5e2")
"keATfB8JP2ggT7U9JZrpV9"