UUID is an independent copyable first-party value following RFC 9562 . Its implementation is native BASIL, with OS randomness/clocks only at the platform boundary. It needs no UUID, TLS or hashing shared library.
id = UUIDv7()
PRINT FormatUUID(id)
PRINT f"id: {id}"
restored = ParseUUID(FormatUUID(id))
PRINT restored = idWords, bytes and text
| API | Semantics |
|---|---|
UUID(high,low) |
Two 64-bit words; High is the most significant half. INTEGER/UINT64 combinations are accepted; signed inputs preserve their two’s-complement bits. |
UUID(bytes) / UUIDFromBytes(bytes) |
Exactly 16 BYTEs in network/big-endian order; UuidError on wrong length |
UUID(text) / ParseUUID(text) |
Checked text parsing; UuidError on malformed input |
UUIDBytes(value) |
Independent 16-byte list in network order |
UUIDGuidBytes(value) / UUIDFromGuidBytes(bytes) |
Explicit Windows GUID memory order: reverse first 4/2/2 bytes; remaining 8 unchanged |
FormatUUID(value) |
Canonical lowercase 8-4-4-4-12 text; infallible apart from fatal allocation failure |
FormatUUID(value,style) |
UuidFormat.Canonical, Compact, Braced, Parenthesized or Urn |
NilUUID() / MaxUUID() |
All-zero/all-one 128-bit values |
IsNilUUID(value) / IsMaxUUID(value) |
BOOLEAN tests |
UUIDVersion(value) |
Raw version nibble 0–15, including 0 for Nil and 15 for Max |
UUIDVariant(value) |
UUIDVariantKind.NCS, RFC, Microsoft or Reserved |
Parsing accepts canonical 36-character text, compact 32 hex digits, matching braces
or parentheses around canonical text, and urn:uuid: canonical text. Hex and the
URN prefix are case-insensitive. It does not ignore whitespace, trailing junk,
embedded NUL or malformed separators. UuidError.Offset is a zero-based UTF-8 byte
position where applicable; component/range errors use -1. Code 1 denotes text syntax,
2 binary length, 3 component range, 4 incompatible version/variant and 5 exhausted
clock-generator timestamp space. Message describes the failure.
Construction/parsing preserves all 128 bits, including unknown/reserved version or variant bits. Only version-specific constructors impose their format. Nil and Max are values, distinct from optional NONE. High/Low are PUBLIC opaque fields, hence read-only outside the prelude; raw construction remains through the checked factories.
Equality, ordering and Hash use the two unsigned halves. Sets/dictionaries accept UUID keys; sorting follows network byte order. UUIDs support ordinary string-style f-string padding/precision, not integer numeric presentations. C interoperability uses explicit words/bytes; no C struct ABI is inferred.
Generating versions
| API | Behavior |
|---|---|
UUIDv4() |
122 random bits from the OS source; IoError on failure |
UUIDv7() |
Current Unix milliseconds plus 74 OS-random bits; UuidError/IoError |
UUIDv7(milliseconds) |
Checked unsigned 48-bit timestamp and fresh OS randomness |
UUIDv7(milliseconds,entropy) |
Deterministic construction from exactly 16 entropy bytes; replaces timestamp/version/variant bits |
UUIDv3(namespace,name) |
Deterministic MD5-based name UUID |
UUIDv5(namespace,name) |
Deterministic SHA-1-based name UUID |
UUIDv1() / UUIDv6() |
Current Gregorian timestamp with a fresh random multicast node/clock sequence; no hardware MAC lookup or shared global state |
UUIDv1(ticks,sequence,node) / UUIDv6(ticks,sequence,node) |
Explicit 60-bit Gregorian 100-ns ticks, 14-bit sequence and 48-bit node |
UUIDv8(high,low) |
Explicit custom data; sets RFC variant and version 8, preserving other bits |
Namespace helpers: UUIDNamespaceDNS(), UUIDNamespaceURL(), UUIDNamespaceOID() and UUIDNamespaceX500(). String names hash their exact UTF-8 bytes; there is no implicit case folding, normalization or DNS/URL canonicalization. MD5/SHA-1 helpers are private compatibility implementations for UUIDv3/v5, not authentication/password APIs. V2 generation is not supplied; raw v2 values still parse/round-trip. V8 has no generic random/name format: the caller defines its custom data layout.
V7 uses fresh randomness for every call. It sorts by timestamp across different milliseconds; within one millisecond order is random. It follows the supplied/OS clock on rollback, so it does not promise monotonic creation order. There is no hidden process-wide counter. Applications needing strict monotonic v7 generation need a separately specified generator; do not infer it from the time-ordered layout. Use secure random bytes for secret material rather than assuming deterministic or timestamp UUIDs are secret tokens.
Clock history and timestamp extraction
generator = NewUUIDClockGenerator()
first = NextUUIDv1(BYREF generator)
second = NextUUIDv6(BYREF generator)
PRINT UUIDGregorianTicks(second)UUIDClockGenerator is opaque and noncopyable to prevent duplicating its sequence state. It is exclusively borrowed with BYREF and cleaned automatically. Resource transfer remains explicit. It keeps a random multicast node and 14-bit sequence. NextUUIDv1AtTicks/NextUUIDv6AtTicks accept explicit Gregorian ticks for controlled clocks. Repeated/backward timestamps advance a logical timestamp by one 100-ns tick; backward observations also advance the sequence modulo 16384. Exhaustion fails before changing the state. No ordinary recoverable failure partially commits an ID. The v6 generator uses RFC-permitted legacy v1 state behavior.
UUIDGregorianTicks returns exact v1/v6 ticks. UUIDClockSequence and UUIDNode inspect those layouts. UUIDUnixMilliseconds handles v1/v6/v7 and floors negative fractional milliseconds. UUIDv1ToV6/UUIDv6ToV1 preserve timestamp, sequence and node. Incompatible versions/variants fail with UuidError. Wall-clock convenience functions retain the existing signed-nanosecond clock range and IoError contract; raw constructors cover the full wire timestamp ranges. These functions are not a civil/timezone library.
Serialization and packages
The shared SERIALIZE default is canonical text, inherited by JSON. UUID record fields therefore encode/decode as strings automatically. Invalid wire UUIDs report JsonError with the enclosing field path/location; standalone ParseUUID reports UuidError. Explicit field converters and JsonCodec rules override the default. For example WithJsonFormat(codec,UUIDBytes,UUIDFromBytes) uses a byte-list representation and retains the decoder’s typed UuidError.
Concrete UUID values, rich errors and UUIDClockGenerator owners/BYREF state work through source and moved .blib interfaces. No producer-local semantic type ID is stored in a UUID value. This does not make stored JsonCodec profiles portable; U6 remains a separate contract.
Source , name hashes , time/generator helpers , compiler contracts .
python3 tools/test_uuid.py build/selfhost/stage3