# Module uuid

- Description
- Data Types
- Function Index
- Function Details

### Erlang UUID Generation

`http://www.ietf.org/rfc/rfc4122.txt` is the reference for official UUIDs. This implementation provides a version 1 UUID that includes both the Erlang pid identifier (ID, Serial, Creation) and the distributed Erlang node name within the 48 bit node ID. To make room for the Erlang pid identifier, the 48 bits from the MAC address (i.e., 3 OCI (Organizationally Unique Identifier) bytes and 3 NIC (Network Interface Controller) specific bytes) and the distributed Erlang node name are bitwise-XORed down to 16 bits. The Erlang pid is bitwise-XORed from 72 bits down to 32 bits. The version 3 (MD5), version 4 (random), and version 5 (SHA) methods are provided as specified within the RFC.

The ordered version 1 variant is not present in the RFC, though it is the most standards-compliant way of providing timestamp UUID ordering.

Copyright © 2011-2020 Michael Truog

Version: 2.0.1 Nov 26 2020 14:44:38 ------------------------------------------------------------------------

Authors: Michael Truog (`mjtruog at protonmail dot com`).

## Description

### Erlang UUID Generation

`http://www.ietf.org/rfc/rfc4122.txt` is the reference for official UUIDs. This implementation provides a version 1 UUID that includes both the Erlang pid identifier (ID, Serial, Creation) and the distributed Erlang node name within the 48 bit node ID. To make room for the Erlang pid identifier, the 48 bits from the MAC address (i.e., 3 OCI (Organizationally Unique Identifier) bytes and 3 NIC (Network Interface Controller) specific bytes) and the distributed Erlang node name are bitwise-XORed down to 16 bits. The Erlang pid is bitwise-XORed from 72 bits down to 32 bits. The version 3 (MD5), version 4 (random), and version 5 (SHA) methods are provided as specified within the RFC.

The ordered version 1 variant is not present in the RFC, though it is the most standards-compliant way of providing timestamp UUID ordering. Timestamp ordering has been used in many non-standard UUID formats based on version 1 and typically limited to the same data present in the version 1 UUID (e.g., "Version 6" at http://gh.peabody.io/uuidv6/).

## Data Types

### iso8601()

`iso8601() = [48..57 | 84 | 45 | 58 | 46 | 90, ...]`

### state()

`state() = #uuid_state{variant = v1_variant(), node_id = <<_:48>>, clock_seq = 0..16383, timestamp_type = timestamp_type_internal(), timestamp_last = integer()}`

### timestamp_type()

`timestamp_type() = erlang | os | warp`

### timestamp_type_internal()

`timestamp_type_internal() = erlang_timestamp | os | warp`

### uuid()

`uuid() = <<_:128>>`

### uuid_string()

`uuid_string() = uuid_string_list() | uuid_string_binary()`

### uuid_string_binary()

`uuid_string_binary() = <<_:256>> | <<_:288>>`

### uuid_string_list()

`uuid_string_list() = [48..57 | 97..102 | 45, ...]`

### v1_variant()

`v1_variant() = rfc4122 | ordered`

## Function Index

get_v1/1 | #### Get a v1 UUID. .
get_v1_datetime/1 | #### Get an ISO8601 datetime in UTC from a v1 UUID's time value. http://www.w3.org/TR/NOTE-datetime.
get_v1_datetime/2 | #### Get an ISO8601 datetime in UTC from a v1 UUID's time value with an offset in microseconds. http://www.w3.org/TR/NOTE-datetime.
get_v1_time/0 | #### Get the current time value in a manner consistent with the v1 UUID. The result is an integer in microseconds since the UNIX epoch.
get_v1_time/1 | #### Get the current time value in a manner consistent with the v1 UUID. The result is an integer in microseconds since the UNIX epoch.
get_v3/1 | #### Get a v3 UUID. .
get_v3/2 | #### Get a v3 UUID in a particular namespace. .
get_v3_compat/1 | #### Get a compatible v3 UUID. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v3_compat/2 | #### Get a compatible v3 UUID in a particular namespace. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v4/0 | #### Get a v4 UUID (using crypto/openssl). crypto:strong_rand_bytes/1 repeats in the same way as RAND_bytes within OpenSSL.
get_v4/1 |
get_v4_urandom/0 | #### Get a v4 UUID (using Wichmann-Hill 2006). random_wh06_int:uniform/1 repeats every 2.66e36 (2^121) approx.
get_v5/1 | #### Get a v5 UUID. .
get_v5/2 | #### Get a v5 UUID in a particular namespace. .
get_v5_compat/1 | #### Get a compatible v5 UUID. Do not use all bits from the checksum so that the UUID matches external implementations.
get_v5_compat/2 | #### Get a compatible v5 UUID in a particular namespace. Do not use all bits from the checksum so that the UUID matches external implementations.
increment/1 | #### Increment the clock sequence of v1 UUID state or a UUID. Call to increment the clock sequence counter after the system clock has been set backwards (see the RFC).
is_uuid/1 | #### Is the term a UUID? .
is_v1/1 | #### Is the binary a v1 UUID? .
is_v3/1 | #### Is the binary a v3 UUID? .
is_v4/1 | #### Is the binary a v4 UUID? .
is_v5/1 | #### Is the binary a v5 UUID? .
mac_address/0 | #### Provide a usable network interface MAC address. .
new/1 | #### Create new UUID state for v1 UUID generation. .
new/2 | #### Create new UUID state for v1 UUID generation using a specific type of timestamp. The timestamp can either be based on erlang's adjustment of time (for only strictly monotonically increasing time values) or the operating system's time without any adjustment (with timestamp_type values `erlang` and `os`, respectively).
string_to_uuid/1 | #### Convert a string representation to a UUID. .
test/0 | #### Regression test. .
uuid_to_list/1 | #### Convert a UUID to a list. .
uuid_to_string/1 | #### Convert a UUID to a string representation. .
uuid_to_string/2 | #### Convert a UUID to a string representation based on an option. .

## Function Details

### get_v1/1

`get_v1(State::state()) -> {uuid(), StateNew::state()}`

#### Get a v1 UUID.

### get_v1_datetime/1

`get_v1_datetime(Value::timestamp_type() | state() | uuid() | erlang:timestamp()) -> iso8601()`

#### Get an ISO8601 datetime in UTC from a v1 UUID's time value.

http://www.w3.org/TR/NOTE-datetime

### get_v1_datetime/2

`get_v1_datetime(Value::timestamp_type() | state() | uuid() | erlang:timestamp(), MicroSecondsOffset::integer()) -> iso8601()`

#### Get an ISO8601 datetime in UTC from a v1 UUID's time value with an offset in microseconds.

http://www.w3.org/TR/NOTE-datetime

### get_v1_time/0

`get_v1_time() -> non_neg_integer()`

#### Get the current time value in a manner consistent with the v1 UUID.

The result is an integer in microseconds since the UNIX epoch. (The UNIX epoch is 1970-01-01T00:00:00Z)

### get_v1_time/1

`get_v1_time(Uuid_state::timestamp_type() | state() | uuid()) -> non_neg_integer()`

#### Get the current time value in a manner consistent with the v1 UUID.

The result is an integer in microseconds since the UNIX epoch. (The UNIX epoch is 1970-01-01T00:00:00Z)

### get_v3/1

`get_v3(Data::binary()) -> uuid()`

#### Get a v3 UUID.

### get_v3/2

`get_v3(Namespace::dns | url | oid | x500 | binary(), Data::iodata()) -> uuid()`

#### Get a v3 UUID in a particular namespace.

### get_v3_compat/1

`get_v3_compat(Data::binary()) -> uuid()`

#### Get a compatible v3 UUID.

Do not use all bits from the checksum so that the UUID matches external implementations.

### get_v3_compat/2

`get_v3_compat(Namespace::dns | url | oid | x500 | binary(), Data::iodata()) -> uuid()`

#### Get a compatible v3 UUID in a particular namespace.

Do not use all bits from the checksum so that the UUID matches external implementations.

### get_v4/0

`get_v4() -> uuid()`

#### Get a v4 UUID (using crypto/openssl).

crypto:strong_rand_bytes/1 repeats in the same way as RAND_bytes within OpenSSL.

### get_v4/1

`get_v4(Cache::strong | cached | quickrand_cache:state()) -> uuid() | {uuid(), quickrand_cache:state()}`

### get_v4_urandom/0

`get_v4_urandom() -> uuid()`

#### Get a v4 UUID (using Wichmann-Hill 2006).

random_wh06_int:uniform/1 repeats every 2.66e36 (2^121) approx. (see B.A. Wichmann and I.D.Hill, in 'Generating good pseudo-random numbers', Computational Statistics and Data Analysis 51 (2006) 1614-1622) a single random_wh06_int:uniform/1 call can provide a maximum of 124 bits (see random_wh06_int.erl for details)

### get_v5/1

`get_v5(Data::binary()) -> uuid()`

#### Get a v5 UUID.

### get_v5/2

`get_v5(Namespace::dns | url | oid | x500 | binary(), Data::iodata()) -> uuid()`

#### Get a v5 UUID in a particular namespace.

### get_v5_compat/1

`get_v5_compat(Data::binary()) -> uuid()`

#### Get a compatible v5 UUID.

Do not use all bits from the checksum so that the UUID matches external implementations.

### get_v5_compat/2

`get_v5_compat(Namespace::dns | url | oid | x500 | binary(), Data::iodata()) -> uuid()`

#### Get a compatible v5 UUID in a particular namespace.

Do not use all bits from the checksum so that the UUID matches external implementations.

### increment/1

`increment(Uuid_state::state() | uuid()) -> state() | uuid()`

#### Increment the clock sequence of v1 UUID state or a UUID.

Call to increment the clock sequence counter after the system clock has been set backwards (see the RFC). This is only necessary if the `os` or `warp` timestamp_type is used with a v1 UUID. The v3, v4 and v5 UUIDs are supported for completeness.

### is_uuid/1

`is_uuid(X1::any()) -> boolean()`

#### Is the term a UUID?

### is_v1/1

`is_v1(Value::any()) -> boolean()`

#### Is the binary a v1 UUID?

### is_v3/1

`is_v3(Value::any()) -> boolean()`

#### Is the binary a v3 UUID?

### is_v4/1

`is_v4(Value::any()) -> boolean()`

#### Is the binary a v4 UUID?

### is_v5/1

`is_v5(Value::any()) -> boolean()`

#### Is the binary a v5 UUID?

### mac_address/0

`mac_address() -> [non_neg_integer(), ...]`

#### Provide a usable network interface MAC address.

### new/1

`new(Pid::pid()) -> state()`

#### Create new UUID state for v1 UUID generation.

### new/2

`new(Pid::pid(), Options::timestamp_type() | [{timestamp_type, timestamp_type()} | {mac_address, [non_neg_integer()]} | {variant, v1_variant()}]) -> state()`

#### Create new UUID state for v1 UUID generation using a specific type of timestamp.

The timestamp can either be based on erlang's adjustment of time (for only strictly monotonically increasing time values) or the operating system's time without any adjustment (with timestamp_type values `erlang` and `os`, respectively). If you want erlang's adjustment of time without enforcement of increasing time values, use the `warp` timestamp_type value with Erlang >= 18.0.

### string_to_uuid/1

`string_to_uuid(X1::uuid_string()) -> uuid()`

#### Convert a string representation to a UUID.

### test/0

`test() -> ok`

#### Regression test.

### uuid_to_list/1

`uuid_to_list(X1::uuid()) -> [non_neg_integer(), ...]`

#### Convert a UUID to a list.

### uuid_to_string/1

`uuid_to_string(Value::uuid()) -> uuid_string_list()`

#### Convert a UUID to a string representation.

### uuid_to_string/2

`uuid_to_string(Value::uuid(), Option::standard | nodash | list_standard | list_nodash | binary_standard | binary_nodash) -> uuid_string()`

#### Convert a UUID to a string representation based on an option.

Generated by EDoc