Struct UUID 

pub struct UUID { /* private fields */ }

A UUID represented as a 16-byte array

Implementations

impl UUID

pub const fn as_bytes(&self) -> &[u8; 16]

impl UUID

pub const fn as_mut_bytes(&mut self) -> &mut [u8; 16]

impl UUID

pub const fn duration_to_ticks( duration: Duration, ) -> Result<u64, DurationToTicksError>

Generates an RFC 4122 timestamp from a Duration.

The timestamp represents the number of 100-nanosecond intervals since the Gregorian epoch (1582-10-15 00:00:00 UTC).

Returns

The number of full 100-ns segments is returned as a u64.

Errors

• DurationToTicksError::TimestampOverflow is returned if the duration corresponds to a value of ( 2^{60} ) or greater, which would overflow the 60 bits available for the timestamp. This occurs for dates beyond 5236-03-31.

impl UUID

pub const fn from_bytes(bytes: [u8; 16]) -> Self

impl UUID

pub fn from_parts_dcom( time_low: u32, time_mid: u16, time_hi_and_version: u16, clock_seq: u16, node: [u8; 6], ) -> Self

Creates a new DCOM UUID with the specified time_low, time_mid, time_hi_and_version, clock_seq, and node fields.

Arguments

• time_low - The low field of the timestamp (32 bits)
• time_mid - The middle field of the timestamp (16 bits)
• time_hi_and_version - The high field of the timestamp and version (16 bits)
• clock_seq - The clock sequence (14 bits, but passed as 16 bits)
• node - The node ID (48 bits, passed as 6 bytes)

Returns

A UUID with the DCOM variant (0b110) set

impl UUID

pub fn from_parts_ncs( timestamp: &[u8; 6], address_family: u8, address: &[u8; 7], ) -> Self

Constructs a new NCS UUID (Variant 0) from pre-computed timestamp bytes, address family, and address.

Parameters

• timestamp: 6-byte timestamp in 4-microsecond units since 1980-01-01 00:00 UTC (big-endian).
• address_family: Network address family (0-13).
• address: 7-byte node ID (e.g., extended MAC address or unique host identifier).

NCS UUID Structure

• Timestamp (48 bits): Raw timestamp bytes in 4-microsecond units since 1980-01-01 00:00 UTC.
• Reserved (16 bits): Set to 0.
• Address Family (8 bits): Network type identifier.
• Node ID (56 bits): Unique host identifier.

Returns

A new NCS UUID with the specified components.

Example

let timestamp = [93, 16, 39, 53, 62, 58]; // Pre-computed timestamp bytes
let address = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07];
let uuid = ps_uuid::UUID::from_parts_ncs(&timestamp, 2, &address);

impl UUID

pub fn from_parts_v1( time_low: u32, time_mid: u16, time_hi: u16, clock_seq: u16, node_id: [u8; 6], ) -> Self

Build a RFC 4122 version-1 (time-based) UUID from its individual wire-format fields.

Arguments must already be laid out exactly as described in RFC 4122 §4.1 (big-endian/network order):

• time_low: 32 least-significant bits of the 60-bit timestamp
• time_mid: next 16 bits of the timestamp
• time_hi: next 12 bits of the timestamp (upper 4 bits will be overwritten with the version by with_version)
• clock_seq: 14-bit clock sequence; the two variant control bits are set by with_version
• node_id: 48-bit IEEE 802 MAC address (or random host id)

The function never fails; all bit fiddling is guaranteed to be valid by construction. The returned value satisfies uuid.version() == Version::Time and uuid.variant() == Variant::OSF.

impl UUID

pub fn from_parts_v2( domain: u8, local_id: u32, time_mid: u16, time_hi: u16, clock_seq: u16, node_id: [u8; 6], ) -> Self

Build a DCE Security (v2) UUID from its individual fields.

impl UUID

pub const fn from_parts_v3(digest: [u8; 16]) -> Self

Builds an RFC-4122 Version-3 UUID from a raw 16-byte MD5 digest.

The caller must supply the digest that results from hashing namespace.bytes || name. The function overwrites the version and variant fields via .with_version(3) and returns the finished UUID.

impl UUID

pub const fn from_parts_v4(bytes: [u8; 16]) -> Self

Constructs a Version 4 (random) UUID from 16 bytes.

The version and variant fields are set according to RFC 4122.

impl UUID

pub fn from_parts_v5<D>(digest: D) -> Self

where D: AsRef<[u8]>,

Builds an RFC-4122 Version-5 UUID from a raw 20-byte SHA-1 digest.

The caller must supply the digest that results from hashing namespace.bytes || name. The first 16 bytes of the digest are copied into the UUID; the version and variant fields are then fixed via .with_version(5).

impl UUID

pub fn from_parts_v6( time_high: u32, time_mid: u16, time_low: u16, clock_seq: u16, node_id: [u8; 6], ) -> Self

Builds an RFC-4122 Version 6 (time-ordered) UUID from its constituent fields.

Timestamp layout (big-endian, network order):

• time_high – most-significant 32 bits of the 60-bit timestamp
• time_mid – next 16 bits of the timestamp
• time_low – least-significant 12 bits of the timestamp

Remaining fields:

• clock_seq – 14-bit clock sequence (high-to-low order)
• node_id – 48-bit node identifier (usually a MAC address)

The function performs all bit manipulation internally, then calls .with_version(6) to patch in the version nibble (0b0110) and the RFC-4122 variant bits (0b10xxxxxx). It never fails.

impl UUID

pub fn from_parts_v7(unix_ts_ms: u64, rand_a: u16, rand_b: u64) -> Self

Build a Version-7 (time-ordered) UUID from its constituent fields.

Arguments

• unix_ts_ms – milliseconds since 1970-01-01 00:00:00 UTC
  (only the least-significant 48 bits are used)
• rand_a – 12 bits of random data
• rand_b – 62 additional random bits

The function never fails; it masks super-fluous upper bits and then calls .with_version(7) which patches in both the version nibble and the RFC-4122 variant.

impl UUID

pub const fn from_parts_v8(bytes: [u8; 16]) -> Self

Constructs a Version 8 (custom) UUID from 16 bytes.

The version and variant fields are set according to RFC 4122.

impl UUID

pub fn gen_dcom(node_id: [u8; 6]) -> Result<Self, UuidConstructionError>

Generates a new DCOM UUID using the current system time and the provided node ID.

Arguments

• node_id - The node ID (6 bytes)

Errors

• UuidConstructionError is returned if the system time is out of range.

impl UUID

pub fn gen_ncs( address_family: u8, address: &[u8; 7], ) -> Result<Self, NcsUuidError>

Generates a new NCS UUID (Variant 0).

Errors

This method returns NcsUuidError::TimestampOverflow after 2015.

impl UUID

pub fn gen_v1() -> Result<Self, UuidConstructionError>

Generate an RFC 4122 version-1 (time-based) UUID.

The current system time and process-wide NodeId and clock sequence are used.

Errors

• TimestampBeforeEpoch is returned if the current time predates 1582-10-15.
• TimestampOverflow is returned if the current time exceeds 5236-03-31.

impl UUID

pub fn gen_v2(domain: u8, local_id: u32) -> Result<Self, UuidConstructionError>

Generate v2 UUID (DCE Security)

Errors

• TimestampBeforeEpoch is returned if the current time predates 1582-10-15.
• TimestampOverflow is returned if the current time exceeds 5236-03-31.

impl UUID

pub fn gen_v4() -> Self

Generates a random (v4) UUID.

impl UUID

pub fn gen_v6() -> Result<Self, UuidConstructionError>

Generate an RFC 4122 version-6 (time-ordered) UUID.

The current system time together with the process-wide NodeId and clock sequence held in the global STATE are used.

Errors

• TimestampBeforeEpoch if the current time predates 1582-10-15.
• TimestampOverflow if the current time exceeds 5236-03-31.

impl UUID

pub fn gen_v7() -> Result<Self, UuidConstructionError>

Generate an RFC-4122 Version 7 (Unix-epoch, time-ordered) UUID.

Steps

1. STATE.next_v7 returns a strictly monotonous SystemTime.
2. That time is converted to a Duration since the Unix epoch.
3. Range checks ensure the 48-bit millisecond field is valid (epoch … ≈ 10889-08-02 05:31:50.655 UTC).
4. The remaining 64 random bits (8 bytes) are filled with CSPRNG data.
5. UUID::new_v7 assembles the final UUID and patches version & variant bits.

Errors

• TimestampBeforeEpoch if the system clock is before 1970-01-01.
• TimestampOverflow if the millisecond counter ≥ 2⁴⁸.

impl UUID

pub const fn get_clock_seq(&self) -> Option<u16>

impl UUID

pub const fn get_node_id(&self) -> Option<NodeId>

impl UUID

pub fn get_timestamp(&self) -> Option<SystemTime>

Extract the embedded timestamp as a SystemTime, if present.

Returns None if the UUID does not encode a timestamp.

impl UUID

pub const fn get_variant(&self) -> Variant

impl UUID

pub const fn get_version(&self) -> Option<u8>

impl UUID

pub const fn max() -> Self

impl UUID

pub fn new_dcom( timestamp: SystemTime, node_id: [u8; 6], ) -> Result<Self, UuidConstructionError>

Creates a new DCOM UUID using the specified timestamp and node ID.

This generates a DCOM UUID following Microsoft’s DCOM specification, which predates RFC 4122 and uses its own format and algorithms.

Arguments

• timestamp - The system time to use for the UUID
• node_id - The node ID (6 bytes)

Errors

• UuidConstructionError is returned if timestamp is out of range.

impl UUID

pub fn new_ncs( timestamp: SystemTime, address_family: u8, address: &[u8; 7], ) -> Result<Self, NcsUuidError>

Generates a new NCS UUID (Variant 0) from a timestamp, address family, and node ID.

Parameters

• timestamp: System time for UUID generation.
• address_family: Network address family (0–13, per NCS specification).
• address: 7-byte node ID (e.g., extended MAC address or unique host ID).

NCS UUID Structure

• Timestamp (48 bits): 4-microsecond units since 1980-01-01 00:00 UTC.
• Reserved (16 bits): Set to 0.
• Address Family (8 bits): Network type (0–13).
• Node ID (56 bits): Unique host identifier.

Returns

• Ok(UUID) on success.
• Err(GenNcsError) if the timestamp is invalid or the address family is out of range.

Errors

• AddressFamilyOutOfRange is returned if address_family doesn’t satisfy 0..=13
• TimestampBeforeEpoch is returned if timestamp is before 1980-01-01
• TimestampOverflow is returned if timestamp is after 2015-09-05T05:58:26.842Z

Example

use std::time::{SystemTime, Duration};
let time = SystemTime::UNIX_EPOCH + Duration::from_secs(315532800 + 3600);
let uuid = ps_uuid::UUID::new_ncs(time, 2, &[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]);

impl UUID

pub fn new_v1( time: SystemTime, clock_seq: u16, node_id: [u8; 6], ) -> Result<Self, UuidConstructionError>

Create an RFC 4122 version-1 (time-based) UUID from a SystemTime, clock sequence, and a 48-bit node identifier.

Errors

• TimestampBeforeEpoch is returned if time predates 1582-10-15.
• TimestampOverflow is returned if time exceeds 5236-03-31.

impl UUID

pub fn new_v2( domain: u8, local_id: u32, time: SystemTime, clock_seq: u16, node_id: [u8; 6], ) -> Result<Self, UuidConstructionError>

Generate a v2 UUID from wall-clock time plus the extra DCE fields.

Errors

• TimestampBeforeEpoch is returned if time predates 1582-10-15.
• TimestampOverflow is returned if time exceeds 5236-03-31.

impl UUID

pub fn new_v3<N>(namespace: &Self, name: N) -> Self

where N: AsRef<[u8]>,

Builds an RFC-4122 Version-3 UUID from namespace || name.

The function

1. hashes the concatenation namespace.bytes || name with MD5,
2. calls from_parts_v3 to set version = 3 + RFC-4122 variant,
3. returns the finished UUID.

impl UUID

pub fn new_v4<R: RngCore + ?Sized>(rng: &mut R) -> Self

Generates a random (v4) UUID using the provided random number generator.

impl UUID

pub fn new_v5<N>(namespace: &Self, name: N) -> Self

where N: AsRef<[u8]>,

Builds an RFC-4122 Version-5 UUID from namespace || name.

Steps

1. Hash namespace.bytes || name with SHA-1.
2. Pass the first 16 bytes of the digest to from_parts_v5.

impl UUID

pub fn new_v6( time: SystemTime, clock_seq: u16, node_id: [u8; 6], ) -> Result<Self, UuidConstructionError>

Create an RFC 4122 version-6 (time-ordered) UUID from a SystemTime, a 14-bit clock sequence and a 48-bit node identifier.

Errors

• TimestampBeforeEpoch if time predates 1582-10-15.
• TimestampOverflow if the 60-bit tick counter would overflow.

impl UUID

pub fn new_v7(timestamp: Duration, random_bytes: [u8; 8]) -> Self

Build an RFC-4122 Version 7 (Unix-epoch, time-ordered) UUID.

Layout (big-endian, draft RFC “UUID Version 7”, 2022-07-07):

• bytes 0‥=5 – 48-bit Unix epoch timestamp in milliseconds
• bytes 6‥=7 – 12 extra timestamp bits derived from the current sub-millisecond nanoseconds
  • upper nibble of byte 6 is the version (7)
• bytes 8‥=15 – 64 bits of caller-supplied randomness
  • two MSBs of byte 8 are the RFC-4122 variant

The timestamp argument expresses the elapsed time since 1970-01-01 00:00:00 UTC (Duration::as_millis() must fit into 48 bits).
random_bytes supplies the final eight random bytes that complete the 128-bit UUID.

The function never fails; any excess upper bits in the timestamp are truncated, and the version (0b0111) and variant (0b10xxxxxx) fields are fixed automatically.

impl UUID

pub fn new_v8<V: Into<u128>>(value: V) -> Self

Build an RFC-4122 Version 8 (custom) UUID from any value convertible to u128.

The caller supplies the complete 128-bit payload (in host order). This function:

• Converts the value to a u128
• Serializes it to big-endian (network order)
• Overwrites the version nibble (bits 48‥=51) with 0b1000
• Overwrites the variant bits (bits 64‥=65) with 0b10
• Leaves all other bits untouched

Example

use ps_uuid::UUID;

let payload: u128 = 0xDEAD_BEEF_DEAD_BEEF_DEAD_BEEF_DEAD_BEEF;
let uuid = UUID::new_v8(payload);

assert_eq!(uuid.get_version(), Some(8));

impl UUID

pub const fn nil() -> Self

impl UUID

pub const fn set_variant(&mut self, variant: Variant)

impl UUID

pub const fn set_version(&mut self, version: u8)

impl UUID

pub fn system_time_to_ticks( time: SystemTime, ) -> Result<u64, UuidConstructionError>

Converts a SystemTime into an RFC 4122 timestamp (ticks).

Arguments

• time - The SystemTime to convert.

Returns

The number of 100-nanosecond intervals between the Gregorian epoch (1582-10-15) and the provided time.

Errors

• UuidConstructionError::TimestampBeforeEpoch if time is before the Gregorian epoch.
• UuidConstructionError::TimestampOverflow if time is so far in the future that the tick count exceeds ( 2^{60} - 1 ).

impl UUID

pub const fn with_variant(self, variant: Variant) -> Self

impl UUID

pub const fn with_version(self, version: u8) -> Self

Trait Implementations

impl Clone for UUID

fn clone(&self) -> UUID

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for UUID

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for UUID

fn default() -> UUID

Returns the “default value” for a type.

impl Display for UUID

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for UUID

fn from_str(s: &str) -> Result<Self, Self::Err>

Accept every standard UUID spelling:

• canonical 36-byte form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• 32 hex digits without hyphens xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
• surrounded by braces {…} (either of the above)
• as an URN urn:uuid:<canonical>

type Err = UuidParseError

The associated error which can be returned from parsing.

impl Hash for UUID

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for UUID

fn cmp(&self, other: &UUID) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for UUID

fn eq(&self, other: &UUID) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for UUID

fn partial_cmp(&self, other: &UUID) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for UUID

impl Eq for UUID

impl StructuralPartialEq for UUID