Uuid

uuid — API Reference

Import: std/uuid.axs

RFC 4122 UUID v4 generation, parsing, formatting, and inspection.

UUIDs are stored as two i64 values (128 bits total) packed in a (ptr i64) header:

• header[0] = uuid_hi (bits 127..64)
• header[1] = uuid_lo (bits 63..0)

All functions are implemented in pure Axon using existing runtime primitives — no additional C FFI beyond what std/string and std/mem already provide.

---

UUID Generation

uuid_nil

uuid_nil() → (ptr i64)

Returns the nil UUID: 00000000-0000-0000-0000-000000000000. Both hi and lo are zero.

(let (nil (call uuid_nil))
  (call uuid_to_string nil))
;; → "00000000-0000-0000-0000-000000000000"

uuid_v4

uuid_v4() → (ptr i64)

Generate a random UUID v4. Uses xorshift64 PRNG seeded from the malloc’d pointer address for entropy. Sets version nibble to 4 and variant bits to 10 per RFC 4122.

(let (id (call uuid_v4))
  (call uuid_to_string id))
;; → "a1b2c3d4-e5f6-4789-abcd-ef0123456789" (example)

uuid_v4_seeded

uuid_v4_seeded(seed1: i64, seed2: i64) → (ptr i64)

Generate a UUID v4 from two explicit seed values. Deterministic — same seeds produce the same UUID. Sets version and variant bits per RFC 4122.

(let (id (call uuid_v4_seeded (i64 12345) (i64 67890)))
  (call uuid_to_string id))

---

Accessors

uuid_hi

uuid_hi(hdr: (ptr i64)) → i64

Extract the high 64 bits (bits 127..64) from a UUID header.

uuid_lo

uuid_lo(hdr: (ptr i64)) → i64

Extract the low 64 bits (bits 63..0) from a UUID header.

---

Formatting & Parsing

uuid_to_string

uuid_to_string(hdr: (ptr i64)) → string

Format a UUID as a lowercase hyphenated string in the standard 8-4-4-4-12 format.

(call uuid_to_string (call uuid_v4))
;; → "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx"

uuid_from_string

uuid_from_string(s: string) → (ptr i64)

Parse a UUID string back to hi/lo representation. Handles both uppercase and lowercase hex digits. Returns the nil UUID on invalid input (wrong length).

(let (id (call uuid_from_string (str "550e8400-e29b-41d4-a716-446655440000")))
  (call uuid_version id))
;; → 4

---

Inspection

uuid_version

uuid_version(hdr: (ptr i64)) → i64

Extract the version nibble (bits 76-79 of the 128-bit UUID). For v4 UUIDs, returns 4.

uuid_variant

uuid_variant(hdr: (ptr i64)) → i64

Extract the variant bits (bits 62-63 of the 128-bit UUID). For RFC 4122 UUIDs, returns 2 (binary 10).

uuid_is_nil

uuid_is_nil(hdr: (ptr i64)) → i64

Check if a UUID is the nil UUID (all zeros). Returns 1 if nil, 0 otherwise.

uuid_eq

uuid_eq(a: (ptr i64), b: (ptr i64)) → i64

Compare two UUIDs for equality. Returns 1 if both hi and lo values match, 0 otherwise.

---

Public Functions Summary (10)

Function	Signature	Return Type
uuid_nil	()	(ptr i64)
uuid_hi	(hdr: (ptr i64))	i64
uuid_lo	(hdr: (ptr i64))	i64
uuid_v4	()	(ptr i64)
uuid_v4_seeded	(seed1: i64, seed2: i64)	(ptr i64)
uuid_to_string	(hdr: (ptr i64))	string
uuid_from_string	(s: string)	(ptr i64)
uuid_version	(hdr: (ptr i64))	i64
uuid_variant	(hdr: (ptr i64))	i64
uuid_eq	(a: (ptr i64), b: (ptr i64))	i64
uuid_is_nil	(hdr: (ptr i64))	i64

---

FFI Extern Declarations (5)

These are private C/system function bindings used internally by the module.

Symbol	Parameters	Return Type
malloc	i64	(ptr u8)
str_len	string	i64
str_char_at	string, i64	i64
str_from_buf	(ptr void), i64	string
str_concat	string, string	string

---

Internal Functions (9)

These functions are module-private and not accessible via import.

Function	Parameters	Return Type
char_to_str	(c: i64)	string
hex_nibble	(n: i64)	i64
hex_val	(c: i64)	i64
make_uuid_header	(hi: i64, lo: i64)	(ptr i64)
xorshift64	(state: i64)	i64
prng_seed	()	(ptr i64)
prng_next	(state: (ptr i64))	i64
prng_next2	(state: (ptr i64))	i64
format_hex4	(val: i64)	string
format_hex8	(val: i64)	string
format_hex12	(val: i64)	string
parse_hex_range	(s: string, start: i64, end: i64)	i64

---

UUID v4 Bit Layout

Bits 127..96: time_low      (32 bits) — random
Bits  95..80: time_mid      (16 bits) — random
Bits  79..64: time_hi_ver   (16 bits) — bits 15..12 = 0100 (version 4), rest random
Bits  63..48: clk_seq       (16 bits) — bits 15..14 = 10 (variant), rest random
Bits  47..0:  node          (48 bits) — random

Total random bits: 122 (128 − 4 version − 2 variant).

---

Performance Notes

The current implementation uses xorshift64 PRNG seeded from malloc pointer addresses for entropy. This provides good uniqueness for application use but is not cryptographically secure. For security-sensitive UUID generation, consider using system randomness (/dev/urandom).

String formatting uses repeated str_concat which is O(n²). For typical UUID use (single values, not bulk generation), this is adequate.

---

Auto-generated from std/uuid.axs