/ 
Horus-0.03
/ Horus

NAME

Horus - XS UUID/GUID generator supporting all RFC 9562 versions

SYNOPSIS

use Horus qw(:all);

# Generate UUIDs (default: lowercase hyphenated string)
my $v4  = uuid_v4();
my $v7  = uuid_v7();
my $v1  = uuid_v1();

# Namespace-based (deterministic)
my $v3 = uuid_v3(UUID_NS_DNS, 'example.com');
my $v5 = uuid_v5(UUID_NS_DNS, 'example.com');

# Different output formats
my $hex    = uuid_v4(UUID_FMT_HEX);        # no hyphens
my $braces = uuid_v4(UUID_FMT_BRACES);     # {..}
my $urn    = uuid_v4(UUID_FMT_URN);         # urn:uuid:..
my $b64    = uuid_v4(UUID_FMT_BASE64);      # 22-char base64
my $b32    = uuid_v4(UUID_FMT_BASE32);      # 26-char base32
my $crk    = uuid_v4(UUID_FMT_CROCKFORD);   # 26-char Crockford
my $bin    = uuid_v4(UUID_FMT_BINARY);       # raw 16 bytes

# Batch generation (single Perl/C crossing)
my @uuids = uuid_v4_bulk(1000);

# Special UUIDs
my $nil = uuid_nil();
my $max = uuid_max();

# Utilities
my $valid   = uuid_validate($string);
my $ver     = uuid_version($string);
my $cmp     = uuid_cmp($uuid_a, $uuid_b);
my $epoch   = uuid_time($v7);
my $binary  = uuid_parse($string);
my $other   = uuid_convert($string, UUID_FMT_BASE64);

# OO interface
my $gen = Horus->new(format => UUID_FMT_STR, version => 4);
my $uuid  = $gen->generate;
my @batch = $gen->bulk(1000);

DESCRIPTION

Horus is a pure XS UUID generator with no external C library dependencies. It supports all UUID versions defined in RFC 9562 (v1-v8) plus NIL and MAX, with 10 output format options.

Performance target: 5M+ v4 UUIDs/sec via random pool buffering, pre-computed hex lookup tables, and minimal Perl/C boundary crossings.

UUID VERSIONS

v1 - Time-based (Gregorian timestamp + clock sequence + node)
v2 - DCE Security (like v1, with local domain identifiers)
v3 - MD5 namespace (deterministic: MD5 of namespace + name)
v4 - Random (122 random bits)
v5 - SHA-1 namespace (deterministic: SHA-1 of namespace + name)
v6 - Reordered time (v1 reorganised for lexical sorting)
v7 - Unix epoch time (48-bit ms timestamp + random, monotonic)
v8 - Custom (application-defined data with version/variant stamped)
NIL - All zeros (00000000-0000-0000-0000-000000000000)
MAX - All ones (ffffffff-ffff-ffff-ffff-ffffffffffff)

OUTPUT FORMATS

UUID_FMT_STR - Lowercase hyphenated (default): 550e8400-e29b-41d4-a716-446655440000
UUID_FMT_HEX - Lowercase no hyphens: 550e8400e29b41d4a716446655440000
UUID_FMT_BRACES - Braces: {550e8400-e29b-41d4-a716-446655440000}
UUID_FMT_URN - URN: urn:uuid:550e8400-e29b-41d4-a716-446655440000
UUID_FMT_BASE64 - Base64 (22 chars, no padding)
UUID_FMT_BASE32 - Base32 RFC 4648 (26 chars)
UUID_FMT_CROCKFORD - Crockford Base32 (26 chars, sortable)
UUID_FMT_BINARY - Raw 16 bytes
UUID_FMT_UPPER_STR - Uppercase hyphenated
UUID_FMT_UPPER_HEX - Uppercase no hyphens

NAMESPACE CONSTANTS

UUID_NS_DNS - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
UUID_NS_URL - 6ba7b811-9dad-11d1-80b4-00c04fd430c8
UUID_NS_OID - 6ba7b812-9dad-11d1-80b4-00c04fd430c8
UUID_NS_X500 - 6ba7b814-9dad-11d1-80b4-00c04fd430c8

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)