From 3d5384da4bfb2f35ad4426440d285e4a13c8c011 Mon Sep 17 00:00:00 2001 From: KodrAus Date: Tue, 9 Jul 2024 08:35:04 +1000 Subject: [PATCH] update docs and deprecation messages for timestamp fns --- src/builder.rs | 9 ++++----- src/timestamp.rs | 33 +++++++++++++-------------------- 2 files changed, 17 insertions(+), 25 deletions(-) diff --git a/src/builder.rs b/src/builder.rs index 4bef7421..6a07a303 100644 --- a/src/builder.rs +++ b/src/builder.rs @@ -549,7 +549,7 @@ impl Builder { Builder(Uuid::from_bytes_le(b)) } - /// Creates a `Builder` for a version 1 UUID using the supplied timestamp and node ID. + /// Creates a `Builder` for a version 1 UUID using the supplied timestamp, counter, and node ID. pub const fn from_gregorian_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self { Builder(timestamp::encode_gregorian_timestamp( ticks, counter, node_id, @@ -598,7 +598,7 @@ impl Builder { .with_version(Version::Sha1) } - /// Creates a `Builder` for a version 6 UUID using the supplied timestamp and node ID. + /// Creates a `Builder` for a version 6 UUID using the supplied timestamp, counter, and node ID. /// /// This method will encode the ticks, counter, and node ID in a sortable UUID. pub const fn from_sorted_gregorian_timestamp( @@ -906,12 +906,11 @@ impl Builder { } } -// Deprecations. Remove when major version changes (2.0.0) #[doc(hidden)] impl Builder { #[deprecated( since = "1.10.0", - note = "Deprecated! Use `from_gregorian_timestamp()` instead!" + note = "use `Builder::from_gregorian_timestamp(ticks, counter, node_id)`" )] pub const fn from_rfc4122_timestamp(ticks: u64, counter: u16, node_id: &[u8; 6]) -> Self { Builder::from_gregorian_timestamp(ticks, counter, node_id) @@ -919,7 +918,7 @@ impl Builder { #[deprecated( since = "1.10.0", - note = "Deprecated! Use `from_sorted_gregorian_timestamp()` instead!" + note = "use `Builder::from_sorted_gregorian_timestamp(ticks, counter, node_id)`" )] pub const fn from_sorted_rfc4122_timestamp( ticks: u64, diff --git a/src/timestamp.rs b/src/timestamp.rs index 5db89ac3..a17aedc0 100644 --- a/src/timestamp.rs +++ b/src/timestamp.rs @@ -51,10 +51,6 @@ impl Timestamp { /// Get a timestamp representing the current system time and up to a 128-bit counter. /// /// This method defers to the standard library's `SystemTime` type. - /// - /// # Panics - /// - /// This method will panic if calculating the elapsed time since the Unix epoch fails. #[cfg(feature = "std")] pub fn now(context: impl ClockSequence>) -> Self { let (seconds, subsec_nanos) = now(); @@ -72,8 +68,9 @@ impl Timestamp { } } - /// Construct a `Timestamp` from an RFC 9562 timestamp and 14-bit counter, as used - /// in versions 1 and 6 UUIDs. + /// Construct a `Timestamp` from the number of 100 nanosecond ticks since 00:00:00.00, + /// 15 October 1582 (the date of Gregorian reform to the Christian calendar) and a 14-bit + /// counter, as used in versions 1 and 6 UUIDs. /// /// # Overflow /// @@ -124,13 +121,15 @@ impl Timestamp { } } - /// Get the value of the timestamp as an RFC 9562 timestamp and counter, - /// as used in versions 1 and 6 UUIDs. + /// Get the value of the timestamp as the number of 100 nanosecond ticks since 00:00:00.00, + /// 15 October 1582 and a 14-bit counter, as used in versions 1 and 6 UUIDs. /// /// # Overflow /// - /// If conversion from RFC 9562 ticks to the internal timestamp format would overflow - /// it will wrap. + /// If conversion from the internal timestamp format to ticks would overflow + /// then it will wrap. + /// + /// If the internal counter is wider than 14 bits then it will be truncated to 14 bits. pub const fn to_gregorian(&self) -> (u64, u16) { ( Self::unix_to_gregorian_ticks(self.seconds, self.subsec_nanos), @@ -164,27 +163,21 @@ impl Timestamp { } } -// Deprecations. Remove when major version changes (2.0.0) #[doc(hidden)] impl Timestamp { - #[deprecated(since = "1.10.0", note = "Deprecated! Use `from_gregorian()` instead!")] + #[deprecated(since = "1.10.0", note = "use `Timestamp::from_gregorian(ticks, counter)`")] pub const fn from_rfc4122(ticks: u64, counter: u16) -> Self { Timestamp::from_gregorian(ticks, counter) } - #[deprecated(since = "1.10.0", note = "Deprecated! Use `to_gregorian()` instead!")] + #[deprecated(since = "1.10.0", note = "use `Timestamp::to_gregorian()`")] pub const fn to_rfc4122(&self) -> (u64, u16) { self.to_gregorian() } - /// Get the number of fractional nanoseconds in the Unix timestamp. - /// - /// This method is deprecated and probably doesn't do what you're expecting it to. - /// It doesn't return the timestamp as nanoseconds since the Unix epoch, it returns - /// the fractional seconds of the timestamp. - #[deprecated(since = "1.2.0", note = "Deprecated! Use `to_unix()` instead!")] + #[deprecated(since = "1.2.0", note = "`Timestamp::to_unix_nanos()` is deprecated and will be removed: use `Timestamp::to_unix()`")] pub const fn to_unix_nanos(&self) -> u32 { - panic!("`Timestamp::to_unix_nanos` is deprecated and will be removed: use `Timestamp::to_unix` instead") + panic!("`Timestamp::to_unix_nanos()` is deprecated and will be removed: use `Timestamp::to_unix()`") } }