Struct TimestampId

pub struct TimestampId { /* private fields */ }

A time-prefixed timestamp identifier for ordering events and records.

TimestampId combines a UTC timestamp with a UUID to create a globally unique, time-ordered identifier. This is the primary mechanism for ordering patient records in the VPR system.

Format

YYYYMMDDTHHMMSS.mmmZ-<uuid>

Where:

• YYYYMMDD - Date (year, month, day)
• T - ISO 8601 separator
• HHMMSS - Time (hours, minutes, seconds in 24-hour format)
• .mmm - Milliseconds (3 digits)
• Z - UTC timezone indicator
• - - Separator between timestamp and UUID
• <uuid> - Standard hyphenated UUID (8-4-4-4-12 format)

Example

20260113T143522.045Z-550e8400-e29b-41d4-a716-446655440000
└─────────┬────────┘ └──────────────┬───────────────────┘
      timestamp                    UUID

Design Properties

This is a value object with the following guarantees:

• Immutable: Once created, the timestamp and UUID cannot be changed
• Comparable: Implements PartialEq and Eq for equality checks
• Hashable: Can be used as a key in hash maps and sets
• Parseable: Can be constructed from a string representation
• Clock-free: Does not access the system clock; use TimestampIdGenerator for generation
• Thread-safe: Can be safely shared across threads (Send + Sync)

Value Object Pattern

TimestampId follows the value object pattern from Domain-Driven Design:

• It represents a conceptual whole (a point in time with unique identity)
• It has no identity separate from its attributes
• It is compared by value, not reference
• It is immutable after construction

Usage

• Use TimestampId::new when you already have a timestamp and UUID
• Use FromStr or TimestampId::from_str to parse a string representation
• Use TimestampIdGenerator::generate to create new IDs with monotonicity guarantees

Monotonicity

When using TimestampIdGenerator, timestamps are guaranteed to be strictly increasing even if the system clock hasn’t advanced or moves backward. This is essential for:

• Maintaining correct event ordering in distributed systems
• Ensuring audit log integrity
• Preventing timestamp collisions in high-frequency scenarios

Thread Safety

TimestampId itself is thread-safe, but monotonicity guarantees require external synchronization (e.g., per-patient locks) when generating new IDs.

Display and Parsing

The string representation uses hyphens in the UUID part for better readability. Format: 20260113T143522.045Z-550e8400-e29b-41d4-a716-446655440000

Parsing accepts the same format and validates both timestamp and UUID components.

See Also

• TimestampIdGenerator - For generating new IDs with monotonicity
• Uuid - For the UUID component

Implementations

impl TimestampId

pub fn new(timestamp: DateTime<Utc>, uuid: Uuid) -> TimestampId

Constructs a TimestampId from explicit components.

This is a low-level constructor that assumes ordering and monotonicity have already been handled by the caller. For generating new IDs, prefer using TimestampIdGenerator::generate which provides monotonicity guarantees.

Arguments

• timestamp - The UTC timestamp for this identifier
• uuid - The unique identifier component

Returns

A new TimestampId with the specified components.

pub fn timestamp(&self) -> DateTime<Utc>

Returns the timestamp component.

This is the logical time associated with this identifier. In cases where monotonicity adjustments were applied, this may be slightly ahead of the actual system clock time.

Returns

The UTC timestamp as a DateTime<Utc>.

pub fn uuid(&self) -> &Uuid

Returns a reference to the UUID component.

The UUID provides global uniqueness even when multiple events share the same timestamp.

Returns

A reference to the Uuid component.

Trait Implementations

impl Clone for TimestampId

fn clone(&self) -> TimestampId

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TimestampId

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

Formats the value using the given formatter.

impl Display for TimestampId

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

Formats the TimestampId as a string.

The format is: YYYYMMDDTHHMMSS.mmmZ-<uuid>

Where the UUID is rendered in standard hyphenated format (8-4-4-4-12) for better readability compared to VPR’s canonical unhyphenated UUID format.

impl FromStr for TimestampId

fn from_str(s: &str) -> Result<TimestampId, <TimestampId as FromStr>::Err>

Parses a TimestampId from its string representation.

The string must be in the format: YYYYMMDDTHHMMSS.mmmZ-<uuid>

Format Requirements

• Timestamp part must end with ‘Z’ (UTC timezone indicator)
• Must contain a hyphen separator between timestamp and UUID
• Timestamp must be valid (no invalid dates like Feb 30)
• UUID must be in standard hyphenated format (8-4-4-4-12)

Arguments

• s - String slice to parse

Returns

• Ok(TimestampId) - Successfully parsed identifier
• Err(UuidError::InvalidInput) - If the format is invalid

Errors

Returns [UuidError::InvalidInput] if:

• The string doesn’t contain a hyphen separator
• The timestamp doesn’t end with ‘Z’
• The timestamp format is invalid (e.g., “20260199” for invalid day)
• The UUID is malformed

type Err = UuidError

The associated error which can be returned from parsing.

impl Hash for TimestampId

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

where __H: Hasher,

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 PartialEq for TimestampId

fn eq(&self, other: &TimestampId) -> 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 Eq for TimestampId

impl StructuralPartialEq for TimestampId