uuid

stable

UUID generation and manipulation plugin supporting v4 (random) and v5 (SHA-1 name-based) UUIDs, along with parsing, validation, comparison, and well-known namespace constants.

use plugin uuid::{v4, v4_bytes, parse, …}

16 functions Utilities

/ filter jk navigate Esc clear

Functions (16)

v4 Generate a random UUID v4 string
v4_bytes Generate a random UUID v4 as raw bytes
parse Parse a UUID string into its components
is_valid Check if a string is a valid UUID
nil Return the nil UUID (all zeros)
format Format 16 bytes as a UUID string
version Extract the version number from a UUID
compare Lexicographically compare two UUIDs
equals Check if two UUID strings are identical
is_nil Check if a UUID is the nil UUID
max Return the max UUID (all f's)
v5 Generate a name-based UUID v5
namespace_dns Return the DNS namespace UUID
namespace_url Return the URL namespace UUID
namespace_oid Return the OID namespace UUID
namespace_x500 Return the X.500 namespace UUID

Overview

uuid generates and manipulates universally unique identifiers without any external dependencies. It produces two kinds: v4 UUIDs are random (great for database keys, request IDs, and anything that just needs to be unique), while v5 UUIDs are deterministic — hashing a namespace UUID together with a name so the same inputs always yield the same identifier. UUIDs are passed around as ordinary hyphenated strings (or as 16 raw bytes via v4_bytes/format), so you can store, compare, and print them like any other value.

The mental model: mint an identifier with v4 (or v5 for reproducible ones), validate untrusted input with is_valid, inspect a UUID with parse/version, and compare or sort with equals/compare. The nil, max, and namespace_* helpers return well-known constant UUIDs.

Common patterns

Generate an identifier and confirm it round-trips through validation:

use plugin uuid::{v4, is_valid, version}

let id = v4()
print("id: {id}")
print("valid: {is_valid(id)}")
print("version: {version(id)}")

Produce a stable, reproducible UUID for a named resource with v5:

use plugin uuid::{v5, namespace_dns, equals}

let a = v5(namespace_dns(), "example.com")
let b = v5(namespace_dns(), "example.com")
print("deterministic: {equals(a, b)}")
print(a)

Work with the binary form and convert back to text:

use plugin uuid::{v4_bytes, format, is_valid}

let raw = v4_bytes()
let text = format(raw)
print("formatted: {text}")
print("valid: {is_valid(text)}")

v4() → string

Generate a random UUID v4 string

Generates a cryptographically random UUID v4 string in standard hyphenated format (xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx).

use plugin uuid::{v4}

let id = v4()
print(id)

v4_bytes() → any

Generate a random UUID v4 as raw bytes

Generates a UUID v4 and returns it as 16 raw bytes instead of a string. Useful when you need a binary representation for storage or wire protocols.

use plugin uuid::{v4_bytes, format}

let raw = v4_bytes()
let str = format(raw)
print(str)

parse(uuid_str) → table

Parse a UUID string into its components

Parses a UUID string into a table with fields: time_low, time_mid, time_hi, clock_seq, node, version, and variant.

use plugin uuid::{v4, parse}

let id = v4()
let parts = parse(id)
print("Version: {parts["version"]}")
print("Variant: {parts["variant"]}")

The node and time_* fields expose the raw integer components, handy for inspecting a known UUID:

use plugin uuid::{parse}

let parts = parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
print("time_low: {parts["time_low"]}")
print("node: {parts["node"]}")

is_valid(uuid_str) → bool

Check if a string is a valid UUID

Returns true if the string matches the 8-4-4-4-12 hex UUID format, false otherwise.

use plugin uuid::{is_valid}

print(is_valid("6ba7b810-9dad-11d1-80b4-00c04fd430c8"))
print(is_valid("not-a-uuid"))

Use it as a guard before trusting external input:

use plugin uuid::{is_valid, version}

let input = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"
if is_valid(input) {
  print("ok, version {version(input)}")
} else {
  print("rejected")
}

nil() → string

Return the nil UUID (all zeros)

Returns the nil UUID string "00000000-0000-0000-0000-000000000000", which represents the absence of a UUID.

use plugin uuid::{nil, is_nil}

let empty = nil()
print(is_nil(empty))

format(bytes) → string

Format 16 bytes as a UUID string

Converts exactly 16 raw bytes into a standard UUID hyphenated string. Use this after v4_bytes or when working with binary UUID storage.

use plugin uuid::{v4_bytes, format}

let raw = v4_bytes()
print(format(raw))

version(uuid_str) → int

Extract the version number from a UUID

Extracts and returns the version number from a UUID string (e.g. 4 for v4, 5 for v5).

use plugin uuid::{v4, version}

let id = v4()
print(version(id))

compare(a, b) → int

Lexicographically compare two UUIDs

Compares two UUID strings byte-by-byte. Returns -1 if a < b, 0 if equal, 1 if a > b. Useful for sorting UUIDs.

use plugin uuid::{v4, compare}

let a = v4()
let b = v4()
print(compare(a, b))

Comparing against the nil and max UUIDs shows the ordering extremes:

use plugin uuid::{compare, nil, max, v4}

let id = v4()
print(compare(id, nil()))
print(compare(id, max()))

equals(a, b) → bool

Check if two UUID strings are identical

Returns true if both UUID strings represent the same UUID (byte-by-byte equality).

use plugin uuid::{v4, equals}

let id = v4()
print(equals(id, id))

is_nil(uuid_str) → bool

Check if a UUID is the nil UUID

Returns true if the UUID string is the nil UUID (all bytes are zero).

use plugin uuid::{nil, is_nil, v4}

print(is_nil(nil()))
print(is_nil(v4()))

max() → string

Return the max UUID (all f's)

Returns the maximum UUID string "ffffffff-ffff-ffff-ffff-ffffffffffff".

use plugin uuid::{max}

print(max())

v5(namespace, name) → string

Generate a name-based UUID v5

Generates a deterministic UUID v5 using SHA-1 hashing of the namespace UUID and name string. The same namespace and name always produce the same UUID.

use plugin uuid::{v5, namespace_dns, namespace_url}

let dns_id = v5(namespace_dns(), "example.com")
print(dns_id)

let url_id = v5(namespace_url(), "https://example.com/page")
print(url_id)

namespace_dns() → string

Return the DNS namespace UUID

Returns the well-known DNS namespace UUID "6ba7b810-9dad-11d1-80b4-00c04fd430c8" for use with v5.

use plugin uuid::{namespace_dns}

print(namespace_dns())

namespace_url() → string

Return the URL namespace UUID

Returns the well-known URL namespace UUID "6ba7b811-9dad-11d1-80b4-00c04fd430c8" for use with v5.

use plugin uuid::{namespace_url}

print(namespace_url())

namespace_oid() → string

Return the OID namespace UUID

Returns the well-known OID namespace UUID "6ba7b812-9dad-11d1-80b4-00c04fd430c8" for use with v5.

use plugin uuid::{namespace_oid}

print(namespace_oid())

namespace_x500() → string

Return the X.500 namespace UUID

Returns the well-known X.500 namespace UUID "6ba7b814-9dad-11d1-80b4-00c04fd430c8" for use with v5.

use plugin uuid::{namespace_x500}

print(namespace_x500())

View source code