uuid
UUIDs as specified by RFC 9562. The package generates random (v4) and time-ordered (v7) IDs, parses every common spelling, and formats the canonical lower-case form. It also gives you the nil and max UUIDs, version and variant fields, the v7 timestamp, and ordering. Tested against the RFC 9562 Appendix A examples.
Effects: rand, and only the generators need it (v4, v7, v7_after). Random bits come from core's cryptographic rand.bytes, so rand.seed has no effect on them. Parsing, formatting and comparison are pure. v7 takes the clock as an argument, so the package never needs time.
fn main(): int! uses rand, time {
let id = uuid.v4()
print("{id}") // e.g. 3f1c2a9e-5b7d-4e0f-9a21-6c8d4b2e7f10
let ev = uuid.v7(time.now()) // sortable: newer IDs compare greater
let u = uuid.parse("{{919108F7-52D1-4320-9BAC-F847DB4148A8}}")?
print(u) // 919108f7-52d1-4320-9bac-f847db4148a8
print("{u.version()} {u.variant()}") // 4 Rfc
print(ev.timestamp()) // some(ms)
var last = uuid.nil()
for _ in 0..3 { last = uuid.v7_after(last, time.now()) } // strictly increasing
match uuid.parse("not-a-uuid") {
err(e) => print(uuid.message(e)) // bad length 10 (want 36 chars ...)
ok(_) => {}
}
0
}
API
Types:
struct Uuid { bytes: [int] }: 16 bytes in network order.==compares bytes.<andsortorder the bytes left to right, which for v7 means creation time (the canonical text sorts the same way). Build values withparse,from_bytesor a generator.enum Variant { Ncs, Rfc, Microsoft, Future }: the variant bits. Everything this package generates isRfc.enum UuidErr { BadLength(len: int), BadChar(at: int, c: char) }(atis a 0-based char index), andmessage(e): str.
Generating:
v4(): Uuid uses rand: 122 random bits.v7(ms: int): Uuid uses rand: a 48-bit Unix millisecond timestamp (time.now()) plus 74 random bits (RFC 9562 §5.7). IDs from different milliseconds sort by time. Requires0 <= ms <= MAX_MS(2^48 - 1, which lasts until the year 10889).v7_after(prev: Uuid, ms: int): Uuid uses rand: a v7 that sorts strictly afterprev. Ifmsis pastprev's timestamp this is justv7(ms). Otherwise (the same millisecond, or a clock that stepped back) it keepsprev's timestamp and adds a random 1..2^32 to its 74 random bits (RFC 9562 §6.2, method 2). If those bits run out it moves to the next millisecond. Ifprevisn't a v7, it returnsv7(ms).v4_from(random: [int])(16 bytes) andv7_from(ms, random: [int])(10 bytes): the same layouts built from bytes you supply, for reproducible tests. The version and variant bits are overwritten.nil(),max():00000000-…-000000000000andffffffff-…-ffffffffffff.from_bytes(bs): Uuid!UuidErr(16 bytes, kept as they are).
Reading:
version(u): int(4, 7, ...; only meaningful when the variant isRfc),variant(u): Varianttimestamp(u): int?: the Unix ms of a v7,nonefor any other kindis_nil(u),is_max(u),cmp(a, b)
Text:
show(u), i.e."{u}":919108f7-52d1-4320-9bac-f847db4148a8simple(u):919108f752d143209bacf847db4148a8.urn(u):urn:uuid:919108f7-…parse(s): Uuid!UuidErraccepts upper or lower case in four spellings: canonical 8-4-4-4-12, braced{…},urn:uuid:…and 32 bare hex digits. It rejects everything else, including surrounding whitespace.
Notes
- v1, v3, v5, v6 and v8 UUIDs parse and report their version, but this package can't generate them. v3 and v5 need MD5 or SHA-1, which
hash0.1 doesn't have. v1 and v6 need a MAC address or node ID. Use v7 for new time-ordered IDs, as RFC 9562 recommends. v4andv7are unguessable because they use the OS generator. Even so, don't use a UUID as a secret or a session token; use 32 bytes fromrand.bytesfor that.