Value-typed RFC 4122 UUID. More...

#include <uuid.h>

Collaboration diagram for vlink::Uuid:

Public Types
enum class	Variant : uint8_t { kNcs = 0 , kRfc = 1 , kMicrosoft = 2 , kReserved = 3 }
	UUID variant inferred from the high bits of octet 8. More...

enum class	Version : uint8_t { kNone = 0 , kTimeBased = 1 , kDceSecurity = 2 , kNameBasedMd5 = 3 , kRandomBased = 4 , kNameBasedSha1 = 5 }
	UUID version inferred from the high nibble of octet 6. More...

using	value_type = uint8_t
	Underlying byte type used by the 16-byte payload. More...

Public Member Functions
constexpr	Uuid () noexcept
	Default-constructs a nil UUID (all 16 bytes zero). More...

constexpr	Uuid (const std::array< value_type, kByteSize > &data) noexcept
	Constructs from a 16-byte array. More...

constexpr	Uuid (const value_type(&arr)[kByteSize]) noexcept
	Constructs from a raw C array reference of exactly 16 bytes. More...

template<typename ForwardIteratorT >
	Uuid (ForwardIteratorT first, ForwardIteratorT last)
	Constructs from a forward-iterator range of exactly 16 bytes. More...

constexpr Variant	variant () const noexcept
	Returns the variant field inferred from octet 8. More...

constexpr Version	version () const noexcept
	Returns the version field inferred from the high nibble of octet 6. More...

constexpr bool	is_nil () const noexcept
	Reports whether every byte is zero (the nil UUID). More...

constexpr const std::array< value_type, kByteSize > &	bytes () const noexcept
	Provides read-only access to the underlying 16-byte payload. More...

std::string	to_string () const noexcept
	Formats the UUID as the canonical 36-character lowercase hyphenated string. More...

std::string	to_compact_string () const noexcept
	Formats the UUID as a 32-character lowercase hex string without hyphens. More...

void	swap (Uuid &other) noexcept
	Swaps contents with `other` in `noexcept` fashion. More...

Static Public Member Functions
static bool	is_valid (std::string_view str) noexcept
	Validates whether `str` is a well-formed UUID literal. More...

static bool	is_valid (const char *str) noexcept
	Null-safe C-string overload of `is_valid()`. More...

static std::optional< Uuid >	from_string (std::string_view str) noexcept
	Parses a UUID literal and returns the resulting value. More...

static std::optional< Uuid >	from_string (const char *str) noexcept
	Null-safe C-string overload of `from_string()`. More...

static Uuid	generate_random () noexcept
	Generates a random v4 UUID using a thread-local seeded engine. More...

static Uuid	generate_random (std::mt19937 &engine) noexcept
	Generates a random v4 UUID from a caller-managed engine. More...

static std::vector< value_type >	random_bytes (size_t count) noexcept
	Produces `count` random-device-seeded pseudo-random bytes. More...

static std::string	random_hex (size_t byte_count=16U) noexcept
	Produces `byte_count` pseudo-random bytes encoded as a lowercase hex string. More...

Static Public Attributes
static constexpr size_t	kByteSize = 16U
	UUID payload length (16 bytes per RFC 4122). More...

static constexpr size_t	kStringSize = 36U
	Canonical 36-character textual length: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. More...

Friends
bool	operator== (const Uuid &lhs, const Uuid &rhs) noexcept
	Equality comparison over the 16-byte payload. More...

bool	operator!= (const Uuid &lhs, const Uuid &rhs) noexcept
	Inequality comparison over the 16-byte payload. More...

bool	operator< (const Uuid &lhs, const Uuid &rhs) noexcept
	Lexicographic less-than comparison over the 16-byte payload. More...

VLINK_EXPORT friend std::ostream &	operator<< (std::ostream &ostream, const Uuid &id)
	Stream insertion delegating to `to_string()`. More...

Detailed Description

Value-typed RFC 4122 UUID.

Stores 16 bytes in network byte order. Trivially copyable and comparable; provides canonical/compact text I/O and a v4 random generator built on top of a thread-local std::mt19937 engine.

Member Typedef Documentation

◆ value_type

using vlink::Uuid::value_type = uint8_t

Underlying byte type used by the 16-byte payload.

Member Enumeration Documentation

◆ Variant

enum vlink::Uuid::Variant : uint8_t

strong

UUID variant inferred from the high bits of octet 8.

Enumerator
kNcs	NCS backward compatibility (`0xxx`).
kRfc	RFC 4122 / DCE 1.1 (`10xx`).
kMicrosoft	Microsoft GUID (`110x`).
kReserved	Reserved for future use (`111x`).

◆ Version

enum vlink::Uuid::Version : uint8_t

strong

UUID version inferred from the high nibble of octet 6.

Enumerator
kNone	Nil UUID or invalid version nibble.
kTimeBased	v1 time-based.
kDceSecurity	v2 DCE Security.
kNameBasedMd5	v3 Name-based MD5.
kRandomBased	v4 random (produced by `generate_random`).
kNameBasedSha1	v5 Name-based SHA-1.

Constructor & Destructor Documentation

◆ Uuid() [1/4]

constexpr vlink::Uuid::Uuid ( )

inlineconstexprdefaultnoexcept

Default-constructs a nil UUID (all 16 bytes zero).

◆ Uuid() [2/4]

constexpr vlink::Uuid::Uuid ( const std::array< value_type, kByteSize > & data )

inlineexplicitconstexprnoexcept

Constructs from a 16-byte array.

Parameters

data	Network-order UUID payload.

◆ Uuid() [3/4]

constexpr vlink::Uuid::Uuid ( const value_type(&) arr[kByteSize] )

inlineexplicitconstexprnoexcept

Constructs from a raw C array reference of exactly 16 bytes.

Parameters

arr	Reference to a 16-byte array.

◆ Uuid() [4/4]

template<typename ForwardIteratorT >

vlink::Uuid::Uuid	(	ForwardIteratorT	first,
		ForwardIteratorT	last
	)

inline

Constructs from a forward-iterator range of exactly 16 bytes.

Details.

When std::distance(first, last) is not 16 the resulting UUID is the nil value. A static_assert enforces forward-iterator capability so input-only iterators do not silently produce a misaligned UUID.

Template Parameters

ForwardIteratorT Forward iterator yielding uint8_t-convertible values.

Parameters

first	Begin iterator.
last	End iterator.

Member Function Documentation

◆ bytes()

constexpr const std::array< Uuid::value_type, Uuid::kByteSize > & vlink::Uuid::bytes ( ) const

inlineconstexprnoexcept

Provides read-only access to the underlying 16-byte payload.

Returns: Const reference to the byte array.

◆ from_string() [1/2]

static std::optional<Uuid> vlink::Uuid::from_string ( const char * str )

staticnoexcept

Null-safe C-string overload of from_string().

Parameters

str	NUL-terminated candidate string, or `nullptr`.

Returns: Parsed UUID, or std::nullopt on malformed/null input.

◆ from_string() [2/2]

static std::optional<Uuid> vlink::Uuid::from_string ( std::string_view str )

staticnoexcept

Parses a UUID literal and returns the resulting value.

Accepts the same shapes as is_valid().

Parameters

str	Candidate string.

Returns: Parsed UUID, or std::nullopt on malformed input.

◆ generate_random() [1/2]

static Uuid vlink::Uuid::generate_random ( )

staticnoexcept

Generates a random v4 UUID using a thread-local seeded engine.

The engine is lazily seeded on first use from eight std::random_device samples fed through a std::seed_seq, then reused for the rest of the thread's lifetime. Sets the RFC variant and v4 version bits before returning.

Returns: Fresh v4 UUID.

◆ generate_random() [2/2]

static Uuid vlink::Uuid::generate_random ( std::mt19937 & engine )

staticnoexcept

Generates a random v4 UUID from a caller-managed engine.

Useful for deterministic test fixtures. Sets the RFC variant and v4 version bits identically to the no-argument overload.

Parameters

engine Caller-managed engine.

Returns: Fresh v4 UUID.

◆ is_nil()

constexpr bool vlink::Uuid::is_nil ( ) const

inlineconstexprnoexcept

Reports whether every byte is zero (the nil UUID).

Returns: true when the payload is all zeros.

◆ is_valid() [1/2]

static bool vlink::Uuid::is_valid ( const char * str )

staticnoexcept

Null-safe C-string overload of is_valid().

Parameters

str	NUL-terminated candidate string, or `nullptr`.

Returns: true when str is non-null and a valid UUID literal.

◆ is_valid() [2/2]

static bool vlink::Uuid::is_valid ( std::string_view str )

staticnoexcept

Validates whether str is a well-formed UUID literal.

Accepts the canonical 36-character form, the 32-character compact form, and either form wrapped in an outer brace pair "{...}". Hyphen positions are not enforced: any 32 hex digits within the allowed shape pass.

Parameters

str	Candidate string.

Returns: true when str is valid.

◆ random_bytes()

static std::vector<value_type> vlink::Uuid::random_bytes ( size_t count )

staticnoexcept

Produces count random-device-seeded pseudo-random bytes.

Uses the same pipeline as generate_random(): std::seed_seq from eight std::random_device samples, then std::mt19937 plus std::uniform_int_distribution<uint32_t> emitting four bytes per draw. Byte extraction uses explicit shifts so the output is endian-deterministic. Returns an empty vector when count is 0 or allocation fails.

Warning: The underlying std::mt19937 engine is not a CSPRNG. Observing 624 consecutive 32-bit outputs allows the engine state to be reconstructed. Do not use this for long-term secrets; prefer a dedicated CSPRNG (for example OpenSSL RAND_bytes).

Parameters

count Number of bytes to emit.

Returns: Vector containing exactly count pseudo-random bytes.

◆ random_hex()

static std::string vlink::Uuid::random_hex ( size_t byte_count = 16U )

staticnoexcept

Produces byte_count pseudo-random bytes encoded as a lowercase hex string.

Length is always byte_count * 2. The default of 16 bytes matches the 128-bit auth-token width used by the proxy handshake. Returns an empty string when byte_count is 0 or allocation fails. Same non-CSPRNG caveat as random_bytes().

Parameters

byte_count Number of underlying bytes.

Returns: Lowercase hex string.

◆ swap()

void vlink::Uuid::swap ( Uuid & other )

inlinenoexcept

Swaps contents with other in noexcept fashion.

Parameters

other UUID to swap with.

◆ to_compact_string()

std::string vlink::Uuid::to_compact_string ( ) const

noexcept

Formats the UUID as a 32-character lowercase hex string without hyphens.

Returns: Compact text representation.

◆ to_string()

std::string vlink::Uuid::to_string ( ) const

noexcept

Formats the UUID as the canonical 36-character lowercase hyphenated string.

Returns: Canonical text representation.

◆ variant()

constexpr Uuid::Variant vlink::Uuid::variant ( ) const

inlineconstexprnoexcept

Returns the variant field inferred from octet 8.

Returns: Variant enumerator.

◆ version()

constexpr Uuid::Version vlink::Uuid::version ( ) const

inlineconstexprnoexcept

Returns the version field inferred from the high nibble of octet 6.

Returns: Version enumerator.

Friends And Related Function Documentation

◆ operator!=

bool operator!=	(	const Uuid &	lhs,
		const Uuid &	rhs
	)

friend

Inequality comparison over the 16-byte payload.

Parameters

lhs	Left operand.
rhs	Right operand.

Returns: true when the payloads differ in any byte.

◆ operator<

bool operator<	(	const Uuid &	lhs,
		const Uuid &	rhs
	)

friend

Lexicographic less-than comparison over the 16-byte payload.

Parameters

lhs	Left operand.
rhs	Right operand.

Returns: true when lhs sorts strictly before rhs.

◆ operator<<

VLINK_EXPORT friend std::ostream& operator<<	(	std::ostream &	ostream,
		const Uuid &	id
	)

friend

Stream insertion delegating to to_string().

Parameters

ostream	Output stream.
id	UUID to format.

Returns: Reference to ostream.

◆ operator==

bool operator==	(	const Uuid &	lhs,
		const Uuid &	rhs
	)

friend

Equality comparison over the 16-byte payload.

Parameters

lhs	Left operand.
rhs	Right operand.

Returns: true when both payloads compare byte-equal.

Member Data Documentation

◆ kByteSize

constexpr size_t vlink::Uuid::kByteSize = 16U

staticconstexpr

UUID payload length (16 bytes per RFC 4122).

◆ kStringSize

constexpr size_t vlink::Uuid::kStringSize = 36U

staticconstexpr

Canonical 36-character textual length: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

The documentation for this class was generated from the following file:

include/vlink/base/uuid.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ value_type

Member Enumeration Documentation

◆ Variant

◆ Version

Constructor & Destructor Documentation

◆ Uuid() [1/4]

◆ Uuid() [2/4]

◆ Uuid() [3/4]

◆ Uuid() [4/4]

Member Function Documentation

◆ bytes()

◆ from_string() [1/2]

◆ from_string() [2/2]

◆ generate_random() [1/2]

◆ generate_random() [2/2]

◆ is_nil()

◆ is_valid() [1/2]

◆ is_valid() [2/2]

◆ random_bytes()

◆ random_hex()

◆ swap()

◆ to_compact_string()

◆ to_string()

◆ variant()

◆ version()

Friends And Related Function Documentation

◆ operator!=

◆ operator<

◆ operator<<

◆ operator==

Member Data Documentation

◆ kByteSize

◆ kStringSize