silk.encoding.uuid.

When to use#

Use Uuid.v4 for random identifiers and Uuid.v7 for identifiers ordered by Unix milliseconds. Use Uuid.v3 or Uuid.v5 for names in an existing namespace.

Details#

Values store 16 bytes in network order. Parsing preserves every bit, including unknown versions and variants. Constructors set the RFC variant. Version 2 uses the legacy DCE Security layout, outside RFC 9562. Operations do not allocate. formatInto returns a borrowed text view into the supplied buffer.

Gotchas#

UUIDs are identifiers, not secrets or authorization tokens. Name hashes do not resist deliberate collisions. Time-based constructors do not persist a clock sequence or enforce monotonicity.

Examples#

Create a stable identifier for a DNS name#

import silk.core.result { Result }
import silk.encoding.uuid { Uuid, UuidError }

pub fn main() -> i32 {
  let namespace = Uuid.namespaceDns()
  let id = Uuid.v5(&namespace, "www.example.com")
  let mut output: [u8; 36] = [0; 36]
  return match Uuid.formatInto(&id, &mut output) {
    Result<string, UuidError>.Success { value } => {
      if value != "2ed6657d-e927-568b-95e1-2665a8aea6a2" {
        return 1
      }
      return 0
    }
    Result<string, UuidError>.Failure { error: _ } => 1
  }
}

See also#

RFC 9562 defines the UUID layouts and namespace rules.

Import as Uuid with import silk.encoding.uuid { Uuid }.

Public declarations: 3.

Uuid#

pub struct Uuid

A UUID as 16 bytes in network order. All bit patterns, including Nil and Max, are representable.

Equality and ordering compare the unsigned bytes in network order. Version 1 is not ordered by time.

UuidError#

pub enum UuidError

A rejected UUID input or a field that exceeds its format's bit width.

InvalidText#

InvalidText

Text is not exactly 36 ASCII characters in the 8-4-4-4-12 hexadecimal form.

BufferTooSmall#

BufferTooSmall

An output buffer has fewer than the required 36 or 45 bytes.

TimestampOutOfRange#

TimestampOutOfRange

A timestamp exceeds 60 bits for versions 1, 2, and 6, or 48 bits for version 7.

ClockSequenceOutOfRange#

ClockSequenceOutOfRange

A clock sequence exceeds 14 bits, or 6 bits for version 2.

InvalidDomain#

InvalidDomain

A DCE local domain is not person (0), group (1), or organization (2).

Implementation Debug for UuidError#

impl Debug for UuidError

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as InvalidText.

UuidVariant#

pub enum UuidVariant

The UUID variant, determined by the leading bits of byte 8.

Ncs#

Ncs

The legacy Apollo NCS variant, with leading bit 0. This includes Nil.

Rfc#

Rfc

The RFC 9562 variant, with leading bits 10.

Microsoft#

Microsoft

The legacy Microsoft variant, with leading bits 110.

Reserved#

Reserved

The reserved variant, with leading bits 111. This includes Max.

Implementation Copy for Uuid#

impl Copy for Uuid

Implementation Uuid#

impl Uuid

Associated function nil#

pub fn nil() -> Self

Returns the all-zero UUID, which has no version.

Associated function max#

pub fn max() -> Self

Returns the all-one UUID, which has no version.

Associated function namespaceDns#

pub fn namespaceDns() -> Self

Returns the standard DNS namespace. Names use canonical DNS text chosen by the caller.

Associated function namespaceUrl#

pub fn namespaceUrl() -> Self

Returns the standard URL namespace. The caller supplies the canonical URL spelling.

Associated function namespaceOid#

pub fn namespaceOid() -> Self

Returns the standard ISO OID namespace. Names use canonical OID text chosen by the caller.

Associated function namespaceX500#

pub fn namespaceX500() -> Self

Returns the standard X.500 distinguished-name namespace. The caller chooses the canonical name encoding.

Associated function fromBytes#

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

Copies all 16 bytes in network order without validation or bit changes.

Method toBytes#

pub fn toBytes(self: &Self) -> [u8; 16]

Returns all 16 bytes in network order. No mixed-endian GUID conversion occurs.

Method isNil#

pub fn isNil(self: &Self) -> bool

Returns whether all 128 bits are zero.

Method isMax#

pub fn isMax(self: &Self) -> bool

Returns whether all 128 bits are one.

Method variant#

pub fn variant(self: &Self) -> UuidVariant

Returns the variant, including the NCS and reserved variants of Nil and Max.

Method version#

pub fn version(self: &Self) -> Option<u8>

Returns the version nibble for the RFC variant, including reserved version numbers. Otherwise, returns None.

Associated function parse#

pub fn parse(text: string) -> Result<Self, UuidError>

Parses exactly 36 hexadecimal characters with hyphens at positions 8, 13, 18, and 23.

Uppercase and lowercase digits are accepted. Whitespace, braces, and URN prefixes return InvalidText. All versions and variants are preserved, including Nil and Max.

Associated function parseBytes#

pub fn parseBytes(text: &[u8]) -> Result<Self, UuidError>

Parses the 36-byte ASCII UUID form, accepting both hex cases and preserving every bit.

Invalid length, hex digits, or hyphen positions return InvalidText. Whitespace and prefixes are rejected.

Associated function parseUrn#

pub fn parseUrn(text: string) -> Result<Self, UuidError>

Parses a urn:uuid: prefix, without case sensitivity, followed by the 36-character UUID form.

Invalid syntax returns InvalidText. No percent decoding or whitespace removal occurs.

Method formatInto#

pub fn formatInto<'a>(self: &Self, output: &'a mut [u8]) -> Result<string<'a>, UuidError>

Writes lowercase UUID text and returns a view of the first 36 output bytes.

BufferTooSmall leaves the output unchanged. Bytes after position 35 are unchanged.

Method formatUrnInto#

pub fn formatUrnInto<'a>(self: &Self, output: &'a mut [u8]) -> Result<string<'a>, UuidError>

Writes lowercase urn:uuid: text and returns a view of the first 45 output bytes.

BufferTooSmall leaves the output unchanged. Bytes after position 44 are unchanged.

Associated function v1#

pub fn v1(timestamp: u64, clockSequence: u16, node: [u8; 6]) -> Result<Self, UuidError>

Constructs version 1 from 100-nanosecond ticks since 1582-10-15, a 14-bit sequence, and a network-order node.

Oversized timestamp or sequence fields return their range error. The caller must prevent repeated field combinations. Persist the sequence across restarts and change it when the clock moves backwards. For random nodes, set bit 0 of the first byte.

Associated function v6#

pub fn v6(timestamp: u64, clockSequence: u16, node: [u8; 6]) -> Result<Self, UuidError>

Constructs version 6 from 100-nanosecond ticks since 1582-10-15, a 14-bit sequence, and a network-order node.

Oversized timestamp or sequence fields return their range error. The caller must prevent repeated field combinations. Persist the sequence across restarts and change it when the clock moves backwards. For random nodes, set bit 0 of the first byte.

Associated function v2#

pub fn v2(
    timestamp: u64,
    clockSequence: u8,
    node: [u8; 6],
    localDomain: u8,
    localId: u32
  ) -> Result<Self, UuidError>

Constructs a legacy DCE version 2 UUID with a local identifier and domain 0, 1, or 2.

The timestamp uses Gregorian 100-nanosecond ticks. Its low 32 bits are replaced by the identifier. The sequence has only 6 bits. The caller must prevent repeats within each approximately 429-second timestamp interval. Invalid timestamp, sequence, or domain fields return the corresponding UuidError.

Associated function v3#

pub fn v3(namespace: &Self, name: string) -> Self

Returns version 3 from MD5 of the namespace bytes followed by the name's UTF-8 bytes.

No case folding or Unicode normalization occurs. MD5 does not resist deliberate collisions.

Associated function v3Bytes#

pub fn v3Bytes(namespace: &Self, name: &[u8]) -> Self

Returns version 3 from MD5 of network-order namespace bytes followed by the exact name bytes.

The caller selects the canonical encoding. MD5 does not resist deliberate collisions.

Associated function v5#

pub fn v5(namespace: &Self, name: string) -> Self

Returns version 5 from SHA-1 of the namespace bytes followed by the name's UTF-8 bytes.

No case folding or Unicode normalization occurs. SHA-1 does not resist deliberate collisions.

Associated function v5Bytes#

pub fn v5Bytes(namespace: &Self, name: &[u8]) -> Self

Returns version 5 from SHA-1 of network-order namespace bytes followed by the exact name bytes.

The caller selects the canonical encoding. SHA-1 does not resist deliberate collisions.

Associated function v4#

pub effect fn v4() -> Self
    ? &mut Random

Returns version 4 using 16 bytes from Random, retaining 122 random bits after version and variant substitution.

Associated function v4FromRandom#

pub fn v4FromRandom(random: [u8; 16]) -> Self

Constructs version 4 from 16 caller-supplied random bytes, overwriting only version and variant bits.

The caller must supply fresh cryptographically secure randomness for each identifier.

Associated function v7#

pub effect fn v7(unixMilliseconds: u64) -> Result<Self, UuidError>
    ? &mut Random

Returns version 7 with a 48-bit Unix millisecond timestamp and 74 bits from Random.

An oversized timestamp returns TimestampOutOfRange before reading randomness. Calls within one millisecond are randomly ordered. Clock rollback can produce values smaller than earlier values.

Associated function v7FromRandom#

pub fn v7FromRandom(unixMilliseconds: u64, random: [u8; 10]) -> Result<Self, UuidError>

Constructs version 7 from Unix milliseconds and 10 random bytes, retaining 74 random bits.

An oversized timestamp returns TimestampOutOfRange. The caller supplies fresh secure randomness for each identifier. The version replaces the first random byte's high nibble. The variant replaces the third byte's two high bits.

Associated function v8#

pub fn v8(custom: [u8; 16]) -> Self

Constructs version 8 from application-defined bytes, overwriting only the version and variant bits.

The remaining 122 bits have no standard interpretation. The caller defines their encoding and uniqueness policy.

Method gregorianTimestamp#

pub fn gregorianTimestamp(self: &Self) -> Option<u64>

Returns Gregorian 100-nanosecond ticks for RFC versions 1 and 6. Otherwise, returns None.

Version 2 cannot recover the original timestamp because its low 32 bits hold the local identifier.

Method unixMilliseconds#

pub fn unixMilliseconds(self: &Self) -> Option<u64>

Returns the Unix millisecond timestamp for RFC version 7. Otherwise, returns None.

Method clockSequence#

pub fn clockSequence(self: &Self) -> Option<u16>

Returns the 14-bit clock sequence for RFC versions 1 and 6, or the 6-bit sequence for version 2.

Other versions and variants return None.

Method node#

pub fn node(self: &Self) -> Option<[u8; 6]>

Returns the network-order node for RFC versions 1, 2, and 6. Otherwise, returns None.

Method localId#

pub fn localId(self: &Self) -> Option<u32>

Returns the local identifier for RFC version 2. Otherwise, returns None.

Method localDomain#

pub fn localDomain(self: &Self) -> Option<u8>

Returns the local domain byte for RFC version 2, including unknown domains. Otherwise, returns None.

Method toV6#

pub fn toV6(self: &Self) -> Option<Self>

Converts RFC version 1 to version 6 without changing its timestamp, sequence, or node. Otherwise, returns None.

Method toV1#

pub fn toV1(self: &Self) -> Option<Self>

Converts RFC version 6 to version 1 without changing its timestamp, sequence, or node. Otherwise, returns None.

Implementation Equal for Uuid#

impl Equal for Uuid

Operation equals#

equals: Uuid.same

Implementation Order for Uuid#

impl Order for Uuid

Operation compare#

compare: Uuid.compare

Implementation HashKey for Uuid#

impl HashKey for Uuid

Operation equals#

equals: Uuid.same

Operation hash#

hash: Uuid.hash

Implementation Display for Uuid#

impl Display for Uuid

Operation display#

effect fn display(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes the lowercase 36-character UUID form. Writer failures propagate unchanged.

Implementation Debug for Uuid#

impl Debug for Uuid

Operation debug#

effect fn debug(self: &Self, formatter: &mut Formatter) -> ()
    ! WriterError
    ? &mut Writer

Writes the lowercase 36-character UUID form. Writer failures propagate unchanged.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.