UUID

UUID module: RFC 4122 UUID generation and manipulation.

The UUID type wraps a canonical string representation: "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx" where M is the version digit and N is the variant digit (8, 9, a, or b).

Supported versions: v4 — randomly generated (RFC 4122 §4.4) v5 — name-based using SHA-1 (RFC 4122 §4.3) NOTE: v5 uses the first 16 bytes of a SHA-1 hash with version/ variant bits set; the resulting UUID is RFC-compliant. v7 — Unix-millisecond timestamp + random bits (RFC 9562)

The nil UUID ("00000000-0000-0000-0000-000000000000") is the all-zeros UUID. version/1 returns 0 for the nil UUID.

Types

typeUUIDUUID = UUID(String)#

Functions

fnis_validis_valid(s)#

Return true if the string is a valid UUID in xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx form.

march> UUID.is_valid("f47ac10b-58cc-4372-a567-0e02b2c3d479")
true
march> UUID.is_valid("00000000-0000-0000-0000-000000000000")
true
march> UUID.is_valid("not-a-uuid")
false

fnnilnil()#

The nil UUID: all 128 bits are zero.

march> UUID.to_string(UUID.nil())
"00000000-0000-0000-0000-000000000000"

fnparseparse(s)#

Parse a UUID string, returning Ok(UUID) or Err(:invalid).

Accepts both upper and lower case hex digits; validates the xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx format (36 characters, 4 dashes).

march> Result.map(UUID.parse("F47AC10B-58CC-4372-A567-0E02B2C3D479"), UUID.to_string)
Ok("f47ac10b-58cc-4372-a567-0e02b2c3d479")
march> UUID.parse("not-a-uuid") == Err(:invalid)
true

fntimestamp_mstimestamp_ms(uuid)#

Extract the Unix timestamp (milliseconds) embedded in a v7 UUID.

Returns Some(ms) for valid v7 UUIDs; None for other versions or unparseable strings. The inverse of v7_at: for any m in a reasonable range, timestamp_ms(v7_at(m)) == Some(m).

UUID.timestamp_ms(UUID.v7_at(1700000000000))  -- Some(1700000000000)

march> UUID.timestamp_ms(UUID.nil())  -- not a v7 UUID
None

fnto_stringto_string(uuid)#

Convert a UUID to its canonical lowercase string representation.

march> UUID.to_string(UUID.nil())
"00000000-0000-0000-0000-000000000000"

fnv4v4()#

Generate a random UUID v4.

UUID.v4()  -- e.g. UUID("f47ac10b-58cc-4372-a567-0e02b2c3d479")

Uses the runtime's CSPRNG. Version bits (4) and variant bits (RFC 4122) are set correctly; the string is lowercase. The result is random, so there is no executable example; UUID.version(UUID.v4()) is 4.

fnv5v5(namespace, name)#

Generate a name-based UUID v5 (SHA-1, RFC 4122 §4.3).

march> let dns = Result.unwrap(UUID.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
march> UUID.to_string(UUID.v5(dns, "www.example.com"))
"2ed6657d-e927-568b-95e1-2665a8aea6a2"

The namespace must be a valid UUID. The name is an arbitrary string. The result is deterministic: the same namespace + name always produce the same UUID.

fnv7v7()#

Generate a time-ordered UUID v7 (RFC 9562).

UUID.v7()  -- e.g. UUID("018e7c9b-2a55-7890-9d51-...")

The leading 48 bits are the current Unix timestamp in milliseconds; the remaining 74 bits are random (CSPRNG). Version bits (7) and variant bits (RFC 4122) are set correctly.

v7 UUIDs are sortable by generation time, which dramatically improves B-tree locality when used as database primary keys versus v4. Prefer v7 over v4 for new schemas. Two UUIDs made in the same millisecond are not ordered relative to each other (there is no monotonic counter). Reads the clock and the CSPRNG, so there is no executable example.

fnv7_atv7_at(unix_ms : Int) : UUID#

Generate a v7 UUID at a specific Unix timestamp (milliseconds).

UUID.v7_at(1700000000000)  -- UUID with timestamp pinned to 2023-11-14

Useful for backfilling historical records with time-ordered UUIDs and for deterministic tests that want to control the timestamp portion. The random bits are still CSPRNG-generated on every call, so two calls with the same timestamp give different UUIDs (no executable example for that reason). Only the low 48 bits of unix_ms are encoded: a value of

Panics if unix_ms is negative.

fnversionversion(uuid)#

Return the version digit of a UUID (e.g. 4, 5 or 7), or 0 for unrecognised/nil.

UUID.version(UUID.v4())  -- 4
UUID.version(UUID.v7())  -- 7

march> UUID.version(UUID.v5(UUID.nil(), "x"))
5
march> UUID.version(UUID.nil())
0