Watch
1
0
Fork
You've already forked uuid-zig
0
mirror of https://codeberg.org/r4gus/uuid-zig.git synced 2026-11-17 03:10:47 +00:00
A UUID library written in Zig
  • Zig 98.5%
  • C 1.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-20 00:15:38 +02:00
bench merge PR 2026-10-09 02:31:16 +02:00
examples merge PR 2026-10-09 02:31:16 +02:00
src merge PR 2026-10-09 02:31:16 +02:00
.gitignore update to support new Zig version 0.17.0 2026-10-09 02:07:08 +02:00
build.zig update to support new Zig version 0.17.0 2026-10-09 02:07:08 +02:00
build.zig.zon update to support new Zig version 0.17.0 2026-10-09 02:07:08 +02:00
license Create license 2022-10-30 21:34:02 +01:00
README.md added sponsor buttons 2026-10-20 00:15:38 +02:00

UUID Zig

Donate using Liberapay ko-fi

Universally Unique IDentifiers (UUIDs) are 128 bit long IDs that do not require a central registration process.

Versions:

Zig version uuid-zig version fetch command
0.13.0 0.2.x
0.14.x 0.3.x
0.15.x 0.4.x
0.16.x 0.5.x, 0.6.x zig fetch --save https://codeberg.org/r4gus/uuid-zig/archive/0.6.0.tar.gz
0.17.0 0.7.x zig fetch --save https://codeberg.org/r4gus/uuid-zig/archive/0.7.0.tar.gz

To add the uuid-zig package to your build.zig.zon run:

# Replace <VERSION TAG> with the version you want to use
zig fetch --save https://codeberg.org/r4gus/uuid-zig/archive/<VERSION>.tar.gz

// e.g., zig fetch --save https://codeberg.org/r4gus/uuid-zig/archive/0.7.0.tar.gz

Then import the UUID module within your build.zig, e.g.:

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

const exe: *Compile = b.addExecutable(.{
    // ...
    .root_module: ?*Module = b.createModule(.{
        .imports: []const Import = &.{
            // ...
            .{ .name: []const u8 = "uuid", .module: *Module = uuid_dep.module("uuid") },
            // ...
        },
    }),
});
// ...

Getting started

Some functions, like v4.fromIo expect a argument of type std.Io.

This can be obtained, e.g., by using juicy main released with Zig version 0.16.0.

Alternatively, you can use the following code snippet to get an Io interface:

var io_impl = std.Io.Threaded.init_single_threaded;
const io = io_impl.io();

All io are assumed to be of type std.Io.

v4

To generate a version 4 (random) UUID you can use:

const uuid = @import("uuid");

const id = uuid.v4.fromIo(io);

If you prefer to use a custom (CS)PRNG, you can use the v4.fromRandom function:

const uuid = @import("uuid");

const rng: std.Random.IoSource = .{ .io = io };
const id = uuid.v4.fromRandom(rng.interface());

v5

To generate a version 5 (name-based) UUID you can use:

const uuid = @import("uuid");

const namespace = uuid.v4.new(io); // Namespace can be any valid uuid
const id = uuid.v5.new(namespace, "name");

v7

You can serialize a UUID into a URN:

const uuid = @import("uuid");

const id = uuid.v7.new(io);

const urn = uuid.urn.serialize(id);

URN

You can also parse URNs (UUID strings):

const uuid = @import("uuid");

const id = try uuid.urn.deserialize("6ba7b811-9dad-11d1-80b4-00c04fd430c8");

Which UUID version should I use?

Consider version 4 (v4) UUIDs if you just need unique identifiers and version 7 (v7) if you want to use UUIDs as database keys or need to sort them. Use version 5 (v5) if you need deterministic ids based on the data they refer to.

Supported versions

  • v4 - UUIDs using random data.
  • v5 - UUIDs that are deterministic for a given namespace and data.
  • v7 - UUIDs using a Epoch timestamp in combination with random data.

Encoding

This library encodes UUIDs in big-endian format, e.g. 00112233-4455-6677-8899-aabbccddeeff is encoded as 00 11 22 33 44 55 66 77 88 99 aa bb cc dd ee ff where 00 is the least and ff is the most significant byte (see RFC4122 4.1.2 Layout and Byte Order).

C Library

Run zig build -Doptimize=ReleaseFast to build the C-Library. You will find the library in zig-out/lib and the header in zig-out/include.

You can find a C-example in the examples folder.

Benchmark

To run a simple benchmark execute:

zig build bench -- 10000000 v7

Example: ThinkPad X1 Yoga 3rd with an i7-8550U

v4: 10000000 UUIDs in 134.057ms
v7: 10000000 UUIDs in 399.558ms

Example: Macbook Pro with M3 Pro

v4: 10000000 UUIDs in 1.666s
v7: 10000000 UUIDs in 546.736ms

Example: Ninkear N16Pro with an Intel Ultra 5 125H

v4: 10000000 UUIDs in 186 ms (186563513 ns). 18 ns/op.
v5: 10000000 UUIDs in 11 ms (11576084 ns). 1 ns/op.
v7: 10000000 UUIDs in 375 ms (375165226 ns). 37 ns/op.

References