Copyright © (C) 2020-2024, Jan Henry Nystrom <JanHenryNystrom@gmail.com> -------------------------------------------------------------------
Authors: Jan Henry Nystrom (JanHenryNystrom@gmail.com).
A UUID library based on: Universally Unique IDentifiers (UUIDs) (rfc9562)
A library for generating UUIDs of all versions defined in rfc9562.
Functions for encoding/decoding UUIDs are provided for completness and testing purposes and the select few occations they are actually needed.
N.B. Does not support Version 2, no support currently planned.custom_opt() = {custom, non_neg_integer() | binary()}
format_opt() = iolist | binary | list | uuid | urn | human
mac_address() = binary()
name_opt() = {name_space, iodata()} | {name, iodata()}
node_type() = undefined | random | non_neg_integer() | mac_address()
opt() = v1_opt() | name_opt() | format_opt() | custom_opt()
opts() = [opt()]
posix() = non_neg_integer()
type() = v1 | v3 | v4 | v5 | v6 | v7 | v8
uuid() = #{version => 1, node => node_type(), clock_sequence => non_neg_integer(), timestamp => non_neg_integer() | binary()} | #{version => 3, name_space => atom() | iodata(), name => iodata(), hash => binary()} | #{version => 4, random => non_neg_integer()} | #{version => 5, name_space => atom() | iodata(), name => iodata(), hash => binary()} | #{version => 6, node => node_type(), clock_sequence => non_neg_integer(), timestamp => non_neg_integer() | binary()} | #{version => 7, random => non_neg_integer(), timestamp => posix() | binary()} | #{version => 8, custom => non_neg_integer() | binary()} | nil | max
v1_opt() = {node, node_type()} | {clock_sequence, non_neg_integer()}
decode/1 | Decodes the binary into a map representing an UUID. |
decode/2 | Decodes the binary into a map representing an UUID. |
encode/1 | Encodes the map represention of an UUID as an iolist. |
encode/2 | Encodes the map represention of an UUID or URN as required the options. |
gen/1 | Generates the an UUID as an iolist of Type (type v3, v5 and v8 not applicable). |
gen/2 | Generates the an UUID or URN of Type. |
decode(Binary::binary() | integer()) -> uuid()
Decodes the binary into a map representing an UUID.
Decode will raise an exception if the binary is not well formed UUID.
Equivalent of decode(Binary, []) -> UUID.decode(Binary::binary() | integer(), Opts::opts() | #opts{node = node_type(), clock_sequence = non_neg_integer() | undefined, name = iodata() | undefined, name_space = atom() | iodata() | undefined, custom = non_neg_integer() | bitstring() | undefined, human = boolean(), urn = boolean(), return_type = iolist | binary | list | uuid}) -> uuid()
Decodes the binary into a map representing an UUID.
Decode will raise an exception if the binary is not well formed UUID.
Options are:
human -> a human readable timestamp is generated for types v1, v6 and v7encode(UUID::uuid()) -> iolist()
Encodes the map represention of an UUID as an iolist.
Equivalent of encode(UUID, [])encode(UUID::uuid(), Opts::opts() | #opts{node = node_type(), clock_sequence = non_neg_integer() | undefined, name = iodata() | undefined, name_space = atom() | iodata() | undefined, custom = non_neg_integer() | bitstring() | undefined, human = boolean(), urn = boolean(), return_type = iolist | binary | list | uuid}) -> iolist() | binary() | list()
Encodes the map represention of an UUID or URN as required the options.
Encode will give an exception if the UUID is not well formed.
Options are:
iolist (default) -> an iolist is returned
binary -> a binary is returned
list -> a flat list is returned
urn -> the URN is returned (can be combined with binary, iolist, list)gen(X::v1 | v4 | v6 | v7 | nil | max) -> iolist() | nil | max
Generates the an UUID as an iolist of Type (type v3, v5 and v8 not applicable)
Equivalent of gen(Type, []) -> UUID for applicable types.gen(Type::type() | nil | max, Opts::opts() | #opts{node = node_type(), clock_sequence = non_neg_integer() | undefined, name = iodata() | undefined, name_space = atom() | iodata() | undefined, custom = non_neg_integer() | bitstring() | undefined, human = boolean(), urn = boolean(), return_type = iolist | binary | list | uuid}) -> uuid() | binary() | list() | iolist() | nil | max
Generates the an UUID or URN of Type
This is normally the only function used. To quote rfc9562 "As general guidance, avoiding parsing UUID values unnecessarily is recommended; instead, treat UUIDs as opaquely as possible".
Types are: v1, v3, v4, v5, v6, v7, v8, nil, max
Options are:
General format:
iolist (default) -> an iolist is returned
binary -> a binary is returned
list -> a flat list is returned
uuid -> a map representing the UUID is generated that can be passed to encode but can differ from the one generated from decode since some information may have been lost.
human -> when combined with uuid provides human readable timstamps for v1, v6 and v7
urn -> the URN is returned (can be combined with binary, iolist, list)
Type specific options. They are all optional if not marked as required:
v1:
{node, Node} -> binary MAC, integer or the atoms random and undefined
{clock_sequence, CSeq} -> integer
v3:
{name, Name} (required) -> iodata representing the name
{name_space, NameSpace} -> iodata representing namespace or an atom representing one of the predefined namespaces: dns, url, oid, x500, nil and max
v5:
{name, Name} (required) -> same as for v3
{name_space, NameSpace} -> same as for v3
v6:
{node, Node} -> same as for v1
{clock_sequence, CSeq} -> same as for v1
v8:
{custom, Custom} (required) -> an integer or 122 bit binary
Generated by EDoc