Search documentation of jhn_stdlib

# jhn_uuid (jhn_stdlib v5.10.3)

View Source

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

## Types

custom_opt/0
format_opt/0
mac_address/0
name_opt/0
node_type/0
opt/0
opts/0
posix/0
type/0
uuid/0
v1_opt/0

## Functions

decode(Binary)

Decodes the binary or integer into a map representing an UUID.

decode(Binary, Opts)

Decodes the binary or integer into a map representing an UUID.

encode(UUID)

Encodes the map represention of an UUID as an iolist.

encode(UUID, Opts)

Encodes the map represention of an UUID or URN as required the options.

gen(X)

Generates the an UUID as an iolist of Type (type v3, v5 and v8 not applicable)

gen(Type, Opts)

Generates the an UUID or URN of Type

# Types

# custom_opt/0

    -type custom_opt() :: {custom, non_neg_integer() | binary()}.

# format_opt/0

    -type format_opt() :: iolist | binary | list | hex | uuid | urn | human.

# mac_address/0

    -type mac_address() :: binary().

# name_opt/0

    -type name_opt() :: {name_space, iodata()} | {name, iodata()}.

# node_type/0

    -type node_type() :: undefined | random | non_neg_integer() | mac_address().

# opt/0

    -type opt() :: v1_opt() | name_opt() | format_opt() | custom_opt().

# opts/0

    -type opts() :: [opt()].

# posix/0

    -type posix() :: non_neg_integer().

# type/0

    -type type() :: v1 | v3 | v4 | v5 | v6 | v7 | v8.

# uuid/0

    -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.

# v1_opt/0

    -type v1_opt() :: {node, node_type()} | {clock_sequence, non_neg_integer()}.

# Functions

# decode(Binary)

    -spec decode(binary() | integer()) -> 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.

Equivalent of decode(Binary, []) -> UUID.

# decode(Binary, Opts)

    -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

# encode(UUID)

    -spec encode(uuid()) -> iolist().

Encodes the map represention of an UUID as an iolist.

Equivalent of encode(UUID, [])

# encode(UUID, Opts)

    -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)

# gen(X)

    -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.

# gen(Type, Opts)

    -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