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.

Version: 1.5.1 Sep 17 2015 13:50:24 ------------------------------------------------------------------------

Authors: Michael Truog (mjtruog [at] gmail (dot) com).

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.

Data Types

state()

state() = #uuid_state{}

timestamp_type()

timestamp_type() = erlang | os | warp

uuid()

uuid() = <<_:128>>

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.
get_v1_time/1	Get the current time value in a manner consistent with the v1 UUID. The result is an integer in microseconds.
get_v1_time/1
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_v4_urandom_bigint/0	Get a v4 UUID (using Wichmann-Hill 1982). random:uniform/1 repeats every 2.78e13 (see B.A. Wichmann and I.D.Hill, in 'An efficient and portable pseudo-random number generator', Journal of Applied Statistics. AS183. 1982, or Byte March 1987) a single random:uniform/1 call can provide a maximum of 45 bits (currently this is not significantly faster because multiple function calls are necessary) .
get_v4_urandom_native/0	Get a v4 UUID (using Wichmann-Hill 1982). Attempt to only use native integers (Erlang limits integers to 27 bits before using bigints) to investigate the speed when using HiPE.
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 v1 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(), NewState::state()}

Get a v1 UUID.

get_v1_datetime/1

get_v1_datetime(Value::timestamp_type() | state() | uuid()) -> string()

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(), MicroSecondsOffset::integer()) -> string()

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.

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.

get_v1_time/1

get_v1_time(Uuid_state) -> any()

get_v3/1

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

Get a v3 UUID.

get_v3/2

get_v3(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> 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::binary() | iolist()) -> 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. crypto:rand_bytes/1 repeats in the same way as RAND_pseudo_bytes within OpenSSL. if OpenSSL is configured to use the MD PRNG (default) with SHA1 (in openssl/crypto/rand/md_rand.c), the collisions are between 2^80 and 2^51 (http://eprint.iacr.org/2008/469.pdf). So, that means "weak" would repeat ideally every 1.21e24 and at worst every 2.25e15. if OpenSSL was compiled in FIPS mode, it uses ANSI X9.31 RNG and would have collisions based on 3DES.

get_v4/1

get_v4(X1::strong | weak) -> uuid()

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_v4_urandom_bigint/0

get_v4_urandom_bigint() -> uuid()

Get a v4 UUID (using Wichmann-Hill 1982).

random:uniform/1 repeats every 2.78e13 (see B.A. Wichmann and I.D.Hill, in 'An efficient and portable pseudo-random number generator', Journal of Applied Statistics. AS183. 1982, or Byte March 1987) a single random:uniform/1 call can provide a maximum of 45 bits (currently this is not significantly faster because multiple function calls are necessary)

explain the 45 bits of randomness: random:uniform/0 code: B1 = (A1*171) rem 30269, B2 = (A2*172) rem 30307, B3 = (A3*170) rem 30323, put(random_seed, {B1,B2,B3}), R = A1/30269 + A2/30307 + A3/30323, R - trunc(R).

{B1, B2, B3} becomes the next seed value {A1, A2, A3}, so: R = (918999161 * A1 + 917846887 * A2 + 917362583 * A3) / 27817185604309 Whatever the values for A1, A2, and A3, (918999161 * A1 + 917846887 * A2 + 917362583 * A3) can not exceed 27817185604309 (30269 * 30307 * 30323) because of the previous modulus. So, random:uniform/1 is unable to uniformly sample numbers beyond a N of 27817185604309. The bits required to represent 27817185604309: 1> (math:log(27817185604309) / math:log(2)) + 1. 45.6610416965467

get_v4_urandom_native/0

get_v4_urandom_native() -> uuid()

Get a v4 UUID (using Wichmann-Hill 1982).

Attempt to only use native integers (Erlang limits integers to 27 bits before using bigints) to investigate the speed when using HiPE.

get_v5/1

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

Get a v5 UUID.

get_v5/2

get_v5(Namespace::dns | url | oid | x500 | binary(), Data::binary() | iolist()) -> 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::binary() | iolist()) -> 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 v1 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.

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()]}]) -> 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.