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.

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.

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

fnnilnil()#

The nil UUID: all 128 bits are zero.

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

    UUID.parse("f47ac10b-58cc-4372-a567-0e02b2c3d479")  -- Ok(UUID(...))
    UUID.parse("not-a-uuid")                             -- Err(:invalid)

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

fnto_stringto_string(uuid)#

Convert a UUID to its canonical lowercase string representation.

    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.

fnv5v5(namespace, name)#

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

    let dns = UUID.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
    UUID.v5(dns, "www.example.com")  -- deterministic UUID

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.

fnv7_atv7_at(unix_ms : Int) : UUID#

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

    UUID.v7_at(1_700_000_000_000)  -- 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.

fnversionversion(uuid)#

Return the version number of a UUID (1–5), or 0 for unrecognised/nil.

    UUID.version(UUID.v4())  -- 4
    UUID.version(UUID.nil()) -- 0