View Source jhn_uuid (jhn_stdlib v5.3.2)
A UUID library based on: Universally Unique IDentifiers (UUIDs) (rfc9562) Uniform Resource Names (URNs) (rfc8141)
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.
Support for non-standard UUIDs with no dashes are provided using hex option
Summary
Functions
Decodes the binary or integer into a map representing an UUID.
Decodes the binary or integer into a map representing an UUID.
Encodes the map represention of an UUID as an iolist.
Encodes the map represention of an UUID or URN as required the options.
Generates the an UUID as an iolist of Type (type v3, v5 and v8 not applicable)
Generates the an UUID or URN of Type
Types
-type custom_opt() :: {custom, non_neg_integer() | binary()}.
-type format_opt() :: iolist | binary | list | hex | uuid | urn | human.
-type mac_address() :: binary().
-type node_type() :: undefined | random | non_neg_integer() | mac_address().
-type opt() :: v1_opt() | name_opt() | format_opt() | custom_opt().
-type opts() :: [opt()].
-type posix() :: non_neg_integer().
-type type() :: v1 | v3 | v4 | v5 | v6 | v7 | v8.
-type 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.
-type v1_opt() :: {node, node_type()} | {clock_sequence, non_neg_integer()}.
Functions
Decodes the binary or integer into a map representing an UUID.
Decode will raise an exception if the binary is not well formed UUID.
Equivalent of decode(Binary, []) -> UUID.
-spec decode(binary() | integer(), 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, hex :: boolean(), human :: boolean(), urn :: boolean(), return_type :: iolist | binary | list | hex | uuid}) -> uuid().
Decodes the binary or integer 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 v7
Encodes the map represention of an UUID as an iolist.
Equivalent of encode(UUID, [])
-spec encode(uuid(), 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, hex :: boolean(), human :: boolean(), urn :: boolean(), return_type :: iolist | binary | list | hex | 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
hex -> the raw hex format without the dashes (this is outside the spec).
urn -> the URN is returned (can be combined with binary, iolist, list)
-spec gen(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.
-spec gen(type() | nil | max, 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, hex :: boolean(), human :: boolean(), urn :: boolean(), return_type :: iolist | binary | list | hex | 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
hex -> the raw hex format without the dashes (this is outside the spec).
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