Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

uuid - generate and parse UUIDs

Enable with use uuid;. RFC 9562 UUIDs: version 4 (random) and version 7 (time-ordered), the 8-4-4-4-12 hex form, and parse / validate helpers. Self-contained and TinyGo-clean.

Surface

CallReturnsNotes
uuid.generate(v)stringNew UUID; v is "v4" (random) or "v7" (time-ordered).
uuid.parse(s)bytesThe 16 bytes of a well-formed UUID string; errors on malformed input.
uuid.isValid(s)boolWhether s is a well-formed UUID string.
uuid.version(s)intThe version digit (4, 7, …; 0 for uuid.NIL); errors on malformed input.
uuid.NILstringThe all-zero UUID "00000000-0000-0000-0000-000000000000".

The version is a string argument ("v4" / "v7"), not a uuid.v4() method - Jennifer identifiers are letters-only, so the variant lives in an argument, the same shape as hash.compute(b, "sha-256") or encoding.toText(b, "base64").

use io;
use uuid;

def id as string init uuid.generate("v4");
io.printf("%s (v%d)\n", $id, uuid.version($id));   # e.g. 524f1d03-...-042736d40bd9 (v4)

if (uuid.isValid($id)) {
    def raw as bytes init uuid.parse($id);         # 16 bytes
}

v4 vs v7

  • "v4" - fully random. Use for opaque identifiers with no ordering.
  • "v7" - a 48-bit millisecond timestamp in the leading bytes, random after. Two v7s created later sort lexically after earlier ones, so they make good database keys (index locality) while staying globally unique.
def a as string init uuid.generate("v7");
# ... later ...
def b as string init uuid.generate("v7");
# $a < $b  (string comparison reflects creation order)

Randomness caveat

v4/v7 randomness comes from math’s shared pseudo-random source - the same stream as math.rand, seedable with math.randSeed, and therefore predictable. Fine for identifiers; not for security tokens, session keys, or anything an attacker must not guess. A crypto-grade source lands with the future crypto library.

See also