simple_uuid - RFC 9562 UUID Generation for Eiffel

Overview

simple_uuid is a lightweight UUID generation library for Eiffel supporting UUID v4 (random), UUID v5 (namespace SHA-1), and UUID v7 (timestamp-based) as specified in RFC 9562 (the successor to RFC 4122).

Part of the simple_* ecosystem of focused, single-purpose Eiffel libraries.

Quick Start

Installation

Add to your ECF file:

<library name="simple_uuid" location="$SIMPLE_UUID/simple_uuid.ecf"/>

Set environment variable:

set SIMPLE_UUID=D:\path\to\simple_uuid

Generate UUID v4 (Random)

local
    gen: SIMPLE_UUID
    uuid: STRING
do
    create gen.make

    -- Generate random UUID
    uuid := gen.new_v4_string
    -- Result: "550e8400-e29b-41d4-a716-446655440000"
end

Generate UUID v5 (Namespace SHA-1)

-- UUID v5 generates deterministic UUIDs from namespace + name
-- Same inputs always produce the same UUID

-- Using DNS namespace
uuid := gen.new_v5_dns ("example.com")
-- Result: "cfbff0d1-9375-5685-968c-48ce8b15ae17"

-- Using URL namespace
uuid := gen.new_v5_url ("https://example.com/path")
-- Deterministic - same URL always gives same UUID

Generate UUID v7 (Timestamp)

-- UUID v7 is sortable by creation time
uuid := gen.new_v7_string
-- Result: "0190a926-3b00-7abc-8def-123456789abc"
-- First 48 bits encode Unix milliseconds timestamp

Features

UUID v4 (Random)

122 random bits providing 5.3 x 10^36 unique identifiers. Most common UUID format.

UUID v5 (Namespace SHA-1)

Deterministic UUIDs from namespace + name using SHA-1. Same input always produces same UUID.

UUID v7 (Timestamp)

Millisecond-precision timestamp + random bits. Sortable by creation time for database efficiency.

String Formatting

Standard hyphenated format (36 chars) or compact format (32 chars) for storage efficiency.

Parsing

Parse UUID strings (with or without hyphens) back to byte arrays for processing.

Validation

Validate UUID strings before parsing with is_valid_uuid and is_valid_uuid_compact.

Version Detection

Detect UUID version from bytes or string with version and version_from_string.

UUID Format

UUIDs follow the format: xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

M = Version (4 for random, 7 for timestamp)
N = Variant (8, 9, a, or b for RFC 4122/9562)

UUID v4 Example

550e8400-e29b-41d4-a716-446655440000
                ^    ^
                |    +-- Variant (RFC 4122)
                +------- Version 4 (Random)

UUID v7 Example

0190a926-3b00-7abc-8def-123456789abc
|____________|  ^    ^
      |         |    +-- Variant (RFC 4122)
      |         +------- Version 7 (Timestamp)
      +----------------- Unix ms timestamp (48 bits)

API Summary

Feature	Description
`new_v4`	Generate random UUID v4 as byte array
`new_v4_string`	Generate random UUID v4 as hyphenated string
`new_v4_compact`	Generate random UUID v4 without hyphens
`new_v5_dns (a_domain)`	Generate UUID v5 using DNS namespace
`new_v5_url (a_url)`	Generate UUID v5 using URL namespace
`new_v5_string (a_namespace, a_name)`	Generate UUID v5 with custom namespace
`new_v7`	Generate timestamp UUID v7 as byte array
`new_v7_string`	Generate timestamp UUID v7 as hyphenated string
`new_v7_compact`	Generate timestamp UUID v7 without hyphens
`from_string (a_string)`	Parse UUID string to byte array
`to_string (a_uuid)`	Format byte array as hyphenated string
`is_valid_uuid (a_string)`	Validate hyphenated UUID format
`version (a_uuid)`	Get version number from UUID bytes

View complete API reference →

When to Use Each Version

Use Case	Recommended	Why
Database primary keys	UUID v7	Sortable, reduces index fragmentation
Session tokens	UUID v4	Maximum randomness, no timestamp leakage
Distributed systems	UUID v7	Time-ordered, good for event sourcing
Security tokens	UUID v4	Unpredictable, no information leakage
Content addressing	UUID v5	Deterministic, same content = same UUID
URL/DNS identifiers	UUID v5	Namespace-based, reproducible
Log correlation IDs	UUID v7	Sortable by time for log analysis

Testing

The library includes a comprehensive test suite with 45 tests covering:

UUID v4 generation (length, version, variant, uniqueness)
UUID v5 generation (determinism, namespace, known vectors)
UUID v7 generation (length, version, variant, sortability)
String formatting (hyphenated and compact)
Parsing and roundtrip conversion
Validation of valid and invalid inputs
Nil and Max UUID handling

-- Run tests
ec.exe -batch -config simple_uuid.ecf -target simple_uuid_tests -tests