v0.0.1

This release is the first stable release of UUID.zig, a production ready, high performance UUID library for Zig 0.16.0 or later.

UUID.zig provides complete UUID generation, parsing, formatting, validation, comparison, hashing, sorting, timestamp extraction, namespace support, and UUID inspection with zero external dependencies and a zero allocation core.

UUID Generation

Supports UUID versions v1 through v8.

UUID v1

Time based UUID generation with custom timestamp, clock sequence, and node identifier.

UUID v2

DCE Security UUID generation for POSIX UID, GID, domain, and local identifiers.

UUID v3

Deterministic UUID generation using MD5 namespace hashing.

UUID v4

Cryptographically secure random UUID generation using Zig 0.16.0 std.Io.

UUID v5

Deterministic UUID generation using SHA 1 namespace hashing.

UUID v6

Reordered time based UUID generation designed for naturally ordered identifiers and database indexing.

UUID v7

Unix epoch based UUID generation with time ordered and monotonic random components.

UUID v8

Application specific UUID generation using a custom 16 byte payload.

Special UUIDs

Includes predefined Nil and Max UUID constants.

00000000-0000-0000-0000-000000000000
ffffffff-ffff-ffff-ffff-ffffffffffff

Helpers are provided for checking whether a UUID is Nil or Max.

Parsing

Strict parsing support for the following formats:

Canonical

550e8400-e29b-41d4-a716-446655440000

Compact

550e8400e29b41d4a716446655440000

Braced

{550e8400-e29b-41d4-a716-446655440000}

URN

urn:uuid:550e8400-e29b-41d4-a716-446655440000

Invalid input is detected and reported through the library error types.

Batch parsing is also supported for processing multiple UUID values.

Formatting

Supports canonical lowercase, canonical uppercase, compact, braced, and URN output.

UUID values can also be written directly into fixed buffers for allocation free formatting.

The UUID type integrates with Zig formatting through format().

std.debug.print("UUID: {}\n", .{id});

UUID Operations

Provides the core operations required when working with UUID values.

Equality comparison with eql

Ordering comparison with compare

Byte conversion with toBytes and fromBytes

u128 conversion with toU128 and fromU128

Hash generation

UUID sorting

Format validation

Nil and Max detection

Version detection

Variant detection

Batch parsing and validation

Hash map support

UUID Inspection

UUID metadata and internal components can be inspected directly.

Version detection identifies UUID versions v1 through v8.

Variant detection identifies the UUID variant.

Timestamp extraction is available for v1, v6, and v7 UUIDs.

Clock sequence and node extraction are available for applicable time based UUIDs.

const version = id.version();
const variant = id.variant();
const timestamp = id.timestampV7();
const sequence = id.clockSeq();
const node = id.node();

Namespace Support

Includes the standard namespace UUID constants used by UUID v3 and v5.

Supported namespaces include DNS, URL, OID, and X.500.

const id = UUID.v5(UUID.namespace_dns, "example.com");

Generator API

Includes a stateful Generator API for applications that need repeated and structured UUID generation.

The Generator API provides a convenient interface for working with the supported UUID generation methods while keeping generation state and configuration together.

Zero Allocation Core

The core UUID operations are designed to work without an allocator.

This includes UUID construction, parsing, comparison, equality checks, version detection, variant detection, byte conversion, u128 conversion, fixed buffer encoding, timestamp extraction, and component extraction.

Allocation is only required by APIs that explicitly return allocated data.

Zig Integration

UUID.zig is built specifically for Zig 0.16.0 or later and integrates with the standard library APIs used by the supported UUID functionality.

Cryptographically secure random UUID generation uses std.Io.

The UUID type also supports direct formatting through Zig's formatting system.

RFC Support

The implementation covers the UUID specifications relevant to versions v1 through v8, including RFC 4122 and RFC 9562.

The test suite includes RFC test vectors for deterministic and time based UUID generation.

Examples

The release includes runnable examples covering basic UUID usage, UUID generation, namespace based UUIDs, parsing, formatting, comparison, sorting, validation, hashing, timestamp extraction, batch operations, the Generator API, and database oriented UUID usage.

Installation

Add UUID.zig to your build.zig.zon:

.{
    .dependencies = .{
        .uuid = .{
            .url = "https://github.com/muhammad-fiaz/uuid.zig/archive/refs/tags/v0.0.1.tar.gz",
            .hash = "...",
        },
    },
}

Then import it in build.zig:

const uuid_dep = b.dependency("uuid", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("uuid", uuid_dep.module("uuid"));

You can also fetch the repository directly:

zig fetch --save git+https://github.com/muhammad-fiaz/uuid.zig.git

Documentation

Documentation

https://muhammad-fiaz.github.io/uuid.zig/

API Reference

https://muhammad-fiaz.github.io/uuid.zig/api/

Examples

https://muhammad-fiaz.github.io/uuid.zig/examples/

Repository

https://github.com/muhammad-fiaz/uuid.zig

Compatibility

Zig 0.16.0 or later

Zero external dependencies

MIT License