Module: encoding.uuid

Source: ./encoding/uuid.reef

Overview

encoding/uuid - UUIDs (RFC 9562): v4, v7, v8, v5, nil, max, parse, format

A Uuid holds its 16 bytes in RFC 9562 (network, big-endian) order, the same order as Linux's uuid_t and the ext2/ext4 superblock's s_uuid, so to_bytes(u) can be written to disk as it is.

v4() 122 secure random bits (random.random) v7(unix_ms) 48-bit Unix milliseconds + 74 secure random bits; sorts by time across milliseconds (not within one) v8(custom) your 16 bytes with the version (8) and variant (RFC, 0b10) bits set over them v5(ns, name) SHA-1 name-based, deterministic (crypto.sha1) nil_uuid(), max_uuid() all zeroes, all ones

v4 and v7 take their randomness from the operating system and return a Result: Err(Unsupported) on a target with no entropy source (bare metal before the OS provides reef_rt_entropy), never a predictable UUID. v5, v8, nil_uuid and max_uuid need no entropy.

Text form: parse() accepts exactly the canonical 36-character form 8-4-4-4-12, hex digits in either case; format() writes it in lower case. Braces, "urn:uuid:" and dash-less forms are rejected.

Usage: import encoding.uuid match uuid.v4() Result_Ok(u) => println(uuid.format(u)) end Result_Err(e) => println(e.message) end end match

Types

Uuid

16 bytes, RFC 9562 order. Always exactly 16 (every constructor copies).

Fields:

Functions

fn invalid(msg: string): error.Error

Messages are whole literals (no concatenation or interpolation) so the module also compiles for bare metal, which has no string concat.

fn wrap(bytes: [uint8]): Uuid

fn copy16(src: [uint8]): [uint8]

fn v4(): result.Result[Uuid, error.Error]

Random UUID (version 4): 122 bits from the secure source.

fn v7(unix_ms: uint64): result.Result[Uuid, error.Error]

Time-ordered UUID (version 7): unix_ms (milliseconds since the Unix epoch, at most 2^48 - 1) big-endian in bytes 0-5, then 74 secure random bits. UUIDs from different milliseconds sort by time (compare / byte order); two from the SAME millisecond are in random order.

fn v8(custom: [uint8]): result.Result[Uuid, error.Error]

Custom UUID (version 8): the caller's 16 bytes with the version and variant bits set over them (6 bits replaced, 122 kept). The caller's array is not modified. Err(InvalidInput) unless exactly 16 bytes.

fn v5(namespace: Uuid, name: string): Uuid

Name-based UUID (version 5): SHA-1 of the namespace's 16 bytes followed by the name's bytes, first 16 bytes of the digest, version/variant set. Deterministic; the same (namespace, name) always gives the same UUID. SHA-1 here is an identifier hash, not a security property.

fn nil_uuid(): Uuid

The Nil UUID, 00000000-0000-0000-0000-000000000000.

fn max_uuid(): Uuid

The Max UUID, ffffffff-ffff-ffff-ffff-ffffffffffff.

fn constant(s: string): Uuid

fn namespace_dns(): Uuid

RFC 9562 section 6.6 namespace IDs.

fn namespace_url(): Uuid

fn namespace_oid(): Uuid

fn namespace_x500(): Uuid

fn hex_val(c: char): int

0-15 for a hex digit (either case), -1 otherwise.

fn parse(s: string): result.Result[Uuid, error.Error]

The canonical form, 8-4-4-4-12 hex digits (36 characters), either case. Anything else is Err(InvalidInput).

fn hex_digit(n: int): char

fn format(u: Uuid): string

Lower-case canonical form, e.g. "919108f7-52d1-4320-9bac-f847db4148a8".

fn from_bytes(b: [uint8]): result.Result[Uuid, error.Error]

A Uuid from exactly 16 bytes in RFC order (copied; no bits changed).

fn to_bytes(u: Uuid): [uint8]

A copy of the 16 bytes in RFC order (safe to modify).

fn version(u: Uuid): int

The version field, the high 4 bits of byte 6 (4 for v4, 7 for v7 ...).

fn variant(u: Uuid): int

The variant field (RFC 9562 section 4.1), from the top bits of byte 8: 0 = 0xxx (NCS), 2 = 10xx (RFC 9562 / 4122), 6 = 110x (Microsoft), 7 = 111x (reserved). Every UUID this module generates is 2.

fn is_nil(u: Uuid): bool

fn is_max(u: Uuid): bool

fn eq(a: Uuid, b: Uuid): bool

fn compare(a: Uuid, b: Uuid): int

-1, 0 or 1 by unsigned byte order, which for v7 is time order.

Procedures

proc stamp(b: [uint8], ver: int)

Set the 4-bit version and the RFC 9562 variant (0b10) in place.

Generated by reefc doc