From f2649cb9613e14a5737334b264f1c0d6cdbfde60 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 27 Mar 2023 12:32:06 +0100 Subject: [PATCH 1/3] Add note about clone-and-hack to the two UNIX_EPOCH definitions I edited one of these and looked at the formatted docs for the other. This confused me for a while; I suspected a build system bug. I don't see an easy and neat way to unify these. So let's just document it instead. --- library/std/src/time.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/library/std/src/time.rs b/library/std/src/time.rs index 5c2e9da70fb21..1aa98436ef69c 100644 --- a/library/std/src/time.rs +++ b/library/std/src/time.rs @@ -461,6 +461,9 @@ impl fmt::Debug for Instant { impl SystemTime { /// An anchor in time which can be used to create new `SystemTime` instances or /// learn about where in time a `SystemTime` lies. + // + // NOTE! this documentation is duplicated, here and in std::time::UNIX_EPOCH. + // The two copies are not quite identical, because of the difference in naming. /// /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with /// respect to the system clock. Using `duration_since` on an existing @@ -617,6 +620,9 @@ impl fmt::Debug for SystemTime { /// An anchor in time which can be used to create new `SystemTime` instances or /// learn about where in time a `SystemTime` lies. +// +// NOTE! this documentation is duplicated, here and in SystemTime::UNIX_EPOCH. +// The two copies are not quite identical, because of the difference in naming. /// /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with /// respect to the system clock. Using `duration_since` on an existing From e329b23104177561a11bb675ea8c77553f2fbcc7 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 27 Mar 2023 12:33:20 +0100 Subject: [PATCH 2/3] Document that SystemTime does not count leap seconds Fixes #77994 --- library/std/src/time.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/library/std/src/time.rs b/library/std/src/time.rs index 1aa98436ef69c..fae677e572909 100644 --- a/library/std/src/time.rs +++ b/library/std/src/time.rs @@ -176,6 +176,14 @@ pub struct Instant(time::Instant); /// The size of a `SystemTime` struct may vary depending on the target operating /// system. /// +/// A `SystemTime` does not count leap seconds. +/// `SystemTime::now()`'s behaviour around a leap second +/// is the same as the operating system's wall clock. +/// The precise behaviour near a leap second +/// (e.g. whether the clock appears to run slow or fast, or stop, or jump) +/// depends on platform and configuration, +/// so should not be relied on. +/// /// Example: /// /// ```no_run @@ -471,6 +479,12 @@ impl SystemTime { /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a /// `SystemTime` instance to represent another fixed point in time. /// + /// `duration_since(UNIX_EPOCH).unwrap().as_secs()` + /// returns a POSIX `time_t` (as a `u64`): + /// the number of non-leap seconds since the start of 1970 UTC. + /// This is the same time representation as used in many Internet protocols, + /// for example: JWT, CBOR, TOTP, certificate transparency and DNS TSIG/DNSSEC. + /// /// # Examples /// /// ```no_run @@ -630,6 +644,12 @@ impl fmt::Debug for SystemTime { /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a /// [`SystemTime`] instance to represent another fixed point in time. /// +/// `duration_since(UNIX_EPOCH).unwrap().as_secs()` +/// returns a POSIX `time_t` (as a `u64`): +/// the number of non-leap seconds since the start of 1970 UTC. +/// This is the same time representation as used in many Internet protocols, +/// for example: JWT, CBOR, TOTP, certificate transparency and DNS TSIG/DNSSEC. +/// /// # Examples /// /// ```no_run From c4bc16c5d60ccaebbd975ce5e7bcde661045951c Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Mon, 7 Aug 2023 15:45:47 +0100 Subject: [PATCH 3/3] Adjust the duration_since(UNIX_EPOCH) docs * Make the description primary, not the definition in terms of time_t * Remove the list of Internet protocols As per https://github.com/rust-lang/rust/pull/109660#pullrequestreview-1414613118 --- library/std/src/time.rs | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/library/std/src/time.rs b/library/std/src/time.rs index fae677e572909..63f04bb88291e 100644 --- a/library/std/src/time.rs +++ b/library/std/src/time.rs @@ -479,11 +479,10 @@ impl SystemTime { /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a /// `SystemTime` instance to represent another fixed point in time. /// - /// `duration_since(UNIX_EPOCH).unwrap().as_secs()` - /// returns a POSIX `time_t` (as a `u64`): + /// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns /// the number of non-leap seconds since the start of 1970 UTC. - /// This is the same time representation as used in many Internet protocols, - /// for example: JWT, CBOR, TOTP, certificate transparency and DNS TSIG/DNSSEC. + /// This is a POSIX `time_t` (as a `u64`), + /// and is the same time representation as used in many Internet protocols. /// /// # Examples /// @@ -644,11 +643,10 @@ impl fmt::Debug for SystemTime { /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a /// [`SystemTime`] instance to represent another fixed point in time. /// -/// `duration_since(UNIX_EPOCH).unwrap().as_secs()` -/// returns a POSIX `time_t` (as a `u64`): +/// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns /// the number of non-leap seconds since the start of 1970 UTC. -/// This is the same time representation as used in many Internet protocols, -/// for example: JWT, CBOR, TOTP, certificate transparency and DNS TSIG/DNSSEC. +/// This is a POSIX `time_t` (as a `u64`), +/// and is the same time representation as used in many Internet protocols. /// /// # Examples ///