r4gus/uuid-zig

A UUID library written in Zig

UUID Zig

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

Getting started

Copy this library into your project or add it as a Git-submodule:

git submodule add https://github.com/r4gus/uuid-zig.git

Then add the following to your build.zig:

exe.addPackagePath("uuid-zig", "path/to/uuid-zig/src/main.zig");

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

const uuid = @import("uuid-zig");

const id = uuid.v4.new();

You can serialize a UUID into a URN:

const uuid = @import("uuid-zig");

const id = uuid.v7.new();

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

You can also parse URNs (UUID strings):

const uuid = @import("uuid-zig");

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.

Supported versions

• v4 - UUIDs using random 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).

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 595.063ms
v7: 10000000 UUIDs in 892.564ms

References

• RFC4122: A Universally Unique IDentifier (UUID) URN Namespace
• New UUID Formats: draft-peabody-dispatch-new-uuid-format-04