---
layout: site.njk
title: zul.UUID
---

<h1 id=zul.UUID><a href=#zul.UUID aria-hidden=true>zul.UUID</a></h1>
<p>Parse and generate version 4 and version 7 UUIDs.</p>

<h2 id=example><a href=#example aria-hidden=true>Example</a></h2>
{% highlight zig %}
// v4() returns a zul.UUID
const uuid1 = zul.UUID.v4();

// toHex() returns a [36]u8
const hex = uuid1.toHex(.lower);

// returns a zul.UUID (or an error)
const uuid2 = try zul.UUID.parse("761e3a9d-4f92-4e0d-9d67-054425c2b5c3");
std.debug.print("{any}\n", uuid1.eql(uuid2));

// create a UUIDv7
const uuid3 = zul.UUID.v7();

// zul.UUID can be JSON serialized
try std.json.stringify(.{.id = uuid3}, .{}, writer);
{% endhighlight %}

<h2 id=UUID><a href=#UUID aria-hidden=true>UUID struct</a></h2>
<p><code>zul.UUID</code> is a thin wrapper around a <code>[16]u8</code>. Its main purpose is to generate a hex-encoded version of the UUID.</p>

<h3 id=UUID.fields><a href=#UUID.fields aria-hidden=true>Fields</a></h3>
<div>
	<div class=member>
		<code class=name>bin: [16]u8</code>
		<div class=desc>
			<p>The binary representation of the UUID.</p>
		</div>
	</div>
</div>

<h3 id=UUID.functions><a href=#UUID.functions aria-hidden=true>Functions</a></h3>
<div>
	<div class=member>
		<code class=name id=v4>UUID.v4() UUID</code>
		<div class=desc><p>Generate a version 4 (random) UUID.</p></div>
	</div>
	<div class=member>
		<code class=name id=v7>UUID.v7() UUID</code>
		<div class=desc><p>Generate a version 7 UUID.</p></div>
	</div>
	<div class=member>
		<code class=name id=random>UUID.random() UUID</code>
		<div class=desc>
			<p>Non-compliant pseudo-UUID. Does not have a version or variant. Use <a href=#v4>UUID.v4()</a> or <a href=#v7>UUID.v7()</a> unless you have specific reasons not to.</p>
		</div>
	</div>
	<div class=member>
		<code class=name id=parse>UUID.parse(hex: []const u8) !UUID</code>
		<div class=desc>
			<p>Attempts to parse a hex-encoded UUID. Returns <code>error.InvalidUUID</code> is the UUID is not valid.</p>
		</div>
	</div>
	<div class=member>
		<code class=name id=bin2Hex>UUID.bin2Hex(bin: []const u8, case: Case) ![36]iu8</code>
		<div class=desc>
			<p>Hex encodes a 16 byte binary UUID.</p>
		</div>
	</div>
</div>
<h3 id=UUID.methods><a href=#UUID.methods aria-hidden=true>Methods</a></h3>
	<div class=member>
		<code class=name id=UUID.toHex><a href=#UUID.toHex aria-hidden=true>toHex(uuid: UUID, case: Case) [36]u8</a></code>
		<div class=desc>
			<p>Hex-encodes the UUID. The <code>case</code> parameter must be <code>.lower</code> or <code>.upper</code> and controls whether lowercase or uppercase hexadecimal is used.</p>
			<p><strong>This method should be preferred over the other <code>toHex*</code> variants.</strong></p>
		</div>
	</div>
	<div class=member>
		<code class=name id=UUID.toHexAlloc><a href=#UUID.toHexAlloc aria-hidden=true>toHexAlloc(uuid: UUID, allocator: Allocator, case: Case) ![]u8</a></code>
		<div class=desc>
			<p>Hex-encodes the UUID into a heap-allocated buffer. The caller must <code>free</code> the returned value when it is no longer in use.</p>
		</div>
	</div>
	<div class=member>
		<code class=name id=UUID.toHexBuf><a href=#UUID.toHexBuf aria-hidden=true>toHexBuf(uuid: UUID, buf: []u8, case: Case) []u8</a></code>
		<div class=desc>
			<p>Hex-encodes the UUID into <code>buf</code>, which must have a length equal or greater than 36.</p>
	</div>
</div>