Struct UUID

Source

pub struct UUID { /* private fields */ }

Expand description

A UUID represented as a 16-byte array

Implementations§

Source §

impl UUID

Source

pub const NIL: Self

The nil UUID, where all bits are set to zero.

00000000-0000-0000-0000-000000000000

Source

pub const MAX: Self

The max UUID, where all bits are set to one.

ffffffff-ffff-ffff-ffff-ffffffffffff

Source

pub const NS_DNS: Self

The DNS namespace UUID, for generating v3/v5 UUIDs from domain names.

Defined in RFC 4122 Appendix C.

6ba7b810-9dad-11d1-80b4-00c04fd430c8

Source

pub const NS_URL: Self

The URL namespace UUID, for generating v3/v5 UUIDs from URLs.

Defined in RFC 4122 Appendix C.

6ba7b811-9dad-11d1-80b4-00c04fd430c8

Source

pub const NS_OID: Self

The OID namespace UUID, for generating v3/v5 UUIDs from ISO OIDs.

Defined in RFC 4122 Appendix C.

6ba7b812-9dad-11d1-80b4-00c04fd430c8

Source

pub const NS_X500: Self

The X.500 namespace UUID, for generating v3/v5 UUIDs from X.500 DNs.

Defined in RFC 4122 Appendix C.

6ba7b814-9dad-11d1-80b4-00c04fd430c8

Source

pub const BLUETOOTH_BASE: Self

The Bluetooth Base UUID.

Used to construct full 128-bit UUIDs from 16-bit and 32-bit Bluetooth identifiers. To convert a 16-bit UUID xxxx: 0000xxxx-0000-1000-8000-00805f9b34fb.

Defined in the Bluetooth Core Specification.

00000000-0000-1000-8000-00805f9b34fb

Source

pub const GPT_EFI_SYSTEM: Self

EFI System Partition type GUID.

The FAT-formatted partition containing UEFI bootloaders and drivers.

c12a7328-f81f-11d2-ba4b-00a0c93ec93b

Source

pub const GPT_LINUX_FS: Self

Linux filesystem data partition type GUID.

The generic type for Linux filesystem partitions (ext4, xfs, btrfs, etc.).

0fc63daf-8483-4772-8e79-3d69d8477de4

Source

pub const GPT_LINUX_SWAP: Self

Linux swap partition type GUID.

0657fd6d-a4ab-43c4-84e5-0933c84b4f4f

Source

pub const GPT_LINUX_ROOT_X86_64: Self

Linux root partition (x86-64) type GUID.

Used by systemd-gpt-auto-generator for automatic root discovery.

4f68bce3-e8cd-4db1-96e7-fbcaf984b709

Source

pub const GPT_LINUX_HOME: Self

Linux home partition type GUID.

Used by systemd-gpt-auto-generator for automatic /home discovery.

933ac7e1-2eb4-4f13-b844-0e14e2aef915

Source

pub const GPT_MS_BASIC_DATA: Self

Microsoft Basic Data partition type GUID.

Used for NTFS and FAT partitions on GPT disks.

ebd0a0a2-b9e5-4433-87c0-68b6b72699c7

Source

pub const COM_IUNKNOWN: Self

The IUnknown interface GUID.

The fundamental COM interface that all COM objects must implement.

00000000-0000-0000-c000-000000000046

Source §

impl UUID

Source

pub const fn parse_const(s: &str) -> [u8; 16]

Parse a UUID string at compile time.

This is a const fn used by the uuid! macro. Prefer using the macro for better error messages.

§Panics

Panics at compile time if the string is not a valid UUID.

Source §

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.

Source §

impl UUID

Source

pub const fn braced(self) -> Braced

Returns a formatter for the braced format.

§Example

use ps_uuid::UUID;

let uuid = UUID::nil();
assert_eq!(uuid.braced().to_string(), "{00000000-0000-0000-0000-000000000000}");

Source §

impl UUID

Source

pub const fn hyphenated(self) -> Hyphenated

Returns a formatter for the hyphenated (standard) format.

This produces the same output as the Display implementation.

§Example

use ps_uuid::UUID;

let uuid = UUID::nil();
assert_eq!(uuid.hyphenated().to_string(), "00000000-0000-0000-0000-000000000000");

Source §

impl UUID

Source

pub const fn simple(self) -> Simple

Returns a formatter for the simple (non-hyphenated) format.

§Example

use ps_uuid::UUID;

let uuid = UUID::nil();
assert_eq!(uuid.simple().to_string(), "00000000000000000000000000000000");

Source §

impl UUID

Source

pub const fn urn(self) -> Urn

Returns a formatter for the URN format.

§Example

use ps_uuid::UUID;

let uuid = UUID::nil();
assert_eq!(uuid.urn().to_string(), "urn:uuid:00000000-0000-0000-0000-000000000000");

Source §

impl UUID

Source

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

Source §

impl UUID

Source

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

Source §

impl UUID

Source

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);

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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

§Arguments

node_id - The node ID (6 bytes)

§Errors

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

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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.

Source §

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.

Source §

impl UUID

Source

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

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

Steps

STATE.next_v7 returns a strictly monotonous SystemTime.
That time is converted to a Duration since the Unix epoch.
Range checks ensure the 48-bit millisecond field is valid (epoch … ≈ 10889-08-02 05:31:50.655 UTC).
The remaining 64 random bits (8 bytes) are filled with CSPRNG data.
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⁴⁸.

§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.

Source §

impl UUID

Source

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]);

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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

hashes the concatenation namespace.bytes || name with MD5,
calls from_parts_v3 to set version = 3 + RFC-4122 variant,
returns the finished 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.

Source §

impl UUID

Source

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.

Source §

impl UUID

Source

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));

Source §