feat(tick): implement display extension for SystemTime (#169)

I found multiple cases when the consumer wants to display `SystemTime`
but currently there is no way to do it easily. One can construct
`Iso8601` from SystemTime manually that implements the `Display` but
it's too verbose.

This PR adds an `display` extension to simplify the scenario. To fulfill
the format requirements we do not fail of `SystemTime` is out of range,
but rather display values saturated at boundaries
`-009999-01-02T01:59:59Z` and `9999-12-30T22:00:00.999999999Z`.

This is because we are limited by the jiff MIN/MAX values.

Before:

```rust
    println!("Current time: {}", Iso8601::try_from(clock.system_time()).unwrap_or(Iso8601::MAX));
```

After:
```rust
    println!("Current time: {}", clock.system_time().display_iso_8601());
```

Author: martintmk

Cargo.lock

@@ -37,7 +37,7 @@ testing_aids = { path = "crates/testing_aids", default-features = false }
 thread_aware = { path = "crates/thread_aware", default-features = false, version = "0.6.0" }
 thread_aware_macros = { path = "crates/thread_aware_macros", default-features = false, version = "0.6.0" }
 thread_aware_macros_impl = { path = "crates/thread_aware_macros_impl", default-features = false, version = "0.6.0" }
-tick = { path = "crates/tick", default-features = false, version = "0.1.1" }
+tick = { path = "crates/tick", default-features = false, version = "0.1.2" }
 
 # external dependencies
 alloc_tracker = { version = "0.5.9", default-features = false }

Cargo.toml

@@ -6,7 +6,7 @@
 # Rust toolchain versions
 RUST_MSRV = "1.88"                                  # used for testing, ensures the MSRV promise is kept; must match Cargo.toml [workspace.package].rust-version
 RUST_LATEST = "1.92"                                # used for static analysis & mutation testing; must match rust-toolchain.toml
-RUST_NIGHTLY = "nightly-2025-12-20"                 # used for coverage and extended analysis; update on a regular basis
+RUST_NIGHTLY = "nightly-2025-12-29"                 # used for coverage and extended analysis; update on a regular basis
 RUST_NIGHTLY_EXTERNAL_TYPES = "nightly-2025-10-18"  # used for external type exposure checks; update alongside updates to cargo-check-external-types
 
 # Cargo tools

constants.toml

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.1.2] - 2026-01-05
+
+- ✨ Features
+
+  - implement display extension for SystemTime
+
 ## [0.1.1] - 2025-12-29
 
 - 🐛 Bug Fixes

crates/tick/CHANGELOG.md

@@ -4,7 +4,7 @@
 [package]
 name = "tick"
 description = "Provides primitives to interact with and manipulate machine time."
-version = "0.1.1"
+version = "0.1.2"
 readme = "README.md"
 keywords = ["time", "clock", "tick", "stopwatch"]
 categories = ["data-structures"]

crates/tick/Cargo.toml

@@ -75,12 +75,16 @@ in production and tests, with zero runtime overhead when `test-util` is disabled
 * [`Stopwatch`][__link4] - Measures elapsed time.
 * [`Delay`][__link5] - Delays the execution for a specified duration.
 * [`PeriodicTimer`][__link6] - Schedules a task to run periodically.
-* [`FutureExt`][__link7] - Extensions for the `Future` trait.
-* [`Error`][__link8] - Represents an error that can occur when working with time. Provides limited
+* [`Error`][__link7] - Represents an error that can occur when working with time. Provides limited
   introspection capabilities.
-* [`fmt`][__link9] - Utilities for formatting `SystemTime` into various formats. Available when
+* [`fmt`][__link8] - Utilities for formatting `SystemTime` into various formats. Available when
   the `fmt` feature is enabled.
-* [`runtime`][__link10] - Infrastructure for integrating time primitives into async runtimes.
+* [`runtime`][__link9] - Infrastructure for integrating time primitives into async runtimes.
+
+## Extensions
+
+* [`FutureExt`][__link10] - Extensions for the `Future` trait, providing timeout functionality.
+* [`SystemTimeExt`][__link11] - Extensions for [`SystemTime`][__link12].
 
 ## Machine-Centric vs. Human-Centric Time
 
@@ -94,7 +98,7 @@ When working with time, two different use cases are considered:
   Dealing with human-centric time involves significant ambiguity.
 
 This crate is designed for machine-centric time. For human-centric time manipulation,
-consider using other crates such as [jiff][__link11], [chrono][__link12], or [time][__link13]. The time primitives in
+consider using other crates such as [jiff][__link13], [chrono][__link14], or [time][__link15]. The time primitives in
 this crate are designed for easy interoperability with these crates. See the `time_interop*`
 examples for more details.
 
@@ -110,7 +114,7 @@ type, which is exposed when the `test-util` feature is enabled.
 
 ### Use `Clock` to retrieve absolute time
 
-The clock provides absolute time as `SystemTime`. See [`Clock`][__link14] documentation for detailed
+The clock provides absolute time as `SystemTime`. See [`Clock`][__link16] documentation for detailed
 information.
 
 ```rust
@@ -129,7 +133,7 @@ assert!(time1 <= time2);
 
 ### Use `Clock` to retrieve relative time
 
-The clock provides relative time via [`Clock::instant`][__link15] and [`Stopwatch`][__link16].
+The clock provides relative time via [`Clock::instant`][__link17] and [`Stopwatch`][__link18].
 
 ```rust
 use std::time::{Duration, Instant};
@@ -184,18 +188,18 @@ timer
 
 This crate provides several optional features that can be enabled in your `Cargo.toml`:
 
-* **`tokio`** - Integration with the [Tokio][__link17] runtime. Enables
-  [`Clock::new_tokio`][__link18] for creating clocks that use Tokio’s time facilities.
-* **`test-util`** - Enables the [`ClockControl`][__link19] type for controlling the passage of time
+* **`tokio`** - Integration with the [Tokio][__link19] runtime. Enables
+  [`Clock::new_tokio`][__link20] for creating clocks that use Tokio’s time facilities.
+* **`test-util`** - Enables the [`ClockControl`][__link21] type for controlling the passage of time
   in tests. This allows you to pause time, advance it manually, or automatically advance
   timers for fast, deterministic testing. **Only enable this in `dev-dependencies`.**
-* **`serde`** - Adds serialization and deserialization support via [serde][__link20].
-* **`fmt`** - Enables the [`fmt`][__link21] module with utilities for formatting `SystemTime` into
+* **`serde`** - Adds serialization and deserialization support via [serde][__link22].
+* **`fmt`** - Enables the [`fmt`][__link23] module with utilities for formatting `SystemTime` into
   various formats (e.g., ISO 8601, RFC 2822).
 
 ## Additional Examples
 
-The [time examples][__link22]
+The [time examples][__link24]
 contain additional examples of how to use the time primitives.
 
 
@@ -204,27 +208,29 @@ contain additional examples of how to use the time primitives.
 This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/oxidizer/tree/main/crates/tick">source code</a>.
 </sub>
 
- [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEGye19xWMtftNG5SBR1lSQd0HG1O5g9a9CyQOG5sh2LWD3CBTYWSBgmR0aWNrZTAuMS4x
- [__link0]: https://docs.rs/tick/0.1.1/tick/?search=ClockControl
- [__link1]: https://docs.rs/tick/0.1.1/tick/?search=Clock
- [__link10]: https://docs.rs/tick/0.1.1/tick/runtime/index.html
- [__link11]: https://crates.io/crates/jiff
- [__link12]: https://crates.io/crates/chrono
- [__link13]: https://crates.io/crates/time
- [__link14]: https://docs.rs/tick/0.1.1/tick/?search=Clock
- [__link15]: https://docs.rs/tick/0.1.1/tick/?search=Clock::instant
- [__link16]: https://docs.rs/tick/0.1.1/tick/?search=Stopwatch
- [__link17]: https://tokio.rs/
- [__link18]: https://docs.rs/tick/0.1.1/tick/?search=Clock::new_tokio
- [__link19]: https://docs.rs/tick/0.1.1/tick/?search=ClockControl
- [__link2]: https://docs.rs/tick/0.1.1/tick/?search=Clock
- [__link20]: https://serde.rs/
- [__link21]: https://docs.rs/tick/0.1.1/tick/fmt/index.html
- [__link22]: https://github.com/microsoft/oxidizer/tree/main/crates/tick/examples
- [__link3]: https://docs.rs/tick/0.1.1/tick/?search=ClockControl
- [__link4]: https://docs.rs/tick/0.1.1/tick/?search=Stopwatch
- [__link5]: https://docs.rs/tick/0.1.1/tick/?search=Delay
- [__link6]: https://docs.rs/tick/0.1.1/tick/?search=PeriodicTimer
- [__link7]: https://docs.rs/tick/0.1.1/tick/?search=FutureExt
- [__link8]: https://docs.rs/tick/0.1.1/tick/?search=Error
- [__link9]: https://docs.rs/tick/0.1.1/tick/fmt/index.html
+ [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG7RNcoP3blXnG4CHqkinKPcBG0KvcQDgsaxXGxhnbuGo0h6JYWSBgmR0aWNrZTAuMS4y
+ [__link0]: https://docs.rs/tick/0.1.2/tick/?search=ClockControl
+ [__link1]: https://docs.rs/tick/0.1.2/tick/?search=Clock
+ [__link10]: https://docs.rs/tick/0.1.2/tick/?search=FutureExt
+ [__link11]: https://docs.rs/tick/0.1.2/tick/?search=SystemTimeExt
+ [__link12]: https://doc.rust-lang.org/stable/std/?search=time::SystemTime
+ [__link13]: https://crates.io/crates/jiff
+ [__link14]: https://crates.io/crates/chrono
+ [__link15]: https://crates.io/crates/time
+ [__link16]: https://docs.rs/tick/0.1.2/tick/?search=Clock
+ [__link17]: https://docs.rs/tick/0.1.2/tick/?search=Clock::instant
+ [__link18]: https://docs.rs/tick/0.1.2/tick/?search=Stopwatch
+ [__link19]: https://tokio.rs/
+ [__link2]: https://docs.rs/tick/0.1.2/tick/?search=Clock
+ [__link20]: https://docs.rs/tick/0.1.2/tick/?search=Clock::new_tokio
+ [__link21]: https://docs.rs/tick/0.1.2/tick/?search=ClockControl
+ [__link22]: https://serde.rs/
+ [__link23]: https://docs.rs/tick/0.1.2/tick/fmt/index.html
+ [__link24]: https://github.com/microsoft/oxidizer/tree/main/crates/tick/examples
+ [__link3]: https://docs.rs/tick/0.1.2/tick/?search=ClockControl
+ [__link4]: https://docs.rs/tick/0.1.2/tick/?search=Stopwatch
+ [__link5]: https://docs.rs/tick/0.1.2/tick/?search=Delay
+ [__link6]: https://docs.rs/tick/0.1.2/tick/?search=PeriodicTimer
+ [__link7]: https://docs.rs/tick/0.1.2/tick/?search=Error
+ [__link8]: https://docs.rs/tick/0.1.2/tick/fmt/index.html
+ [__link9]: https://docs.rs/tick/0.1.2/tick/runtime/index.html

crates/tick/README.md

@@ -27,6 +27,8 @@
 //!
 //! # Examples
 //!
+//! ## Using format types
+//!
 //! ```
 //! use tick::fmt::{Iso8601, Rfc2822, UnixSeconds};
 //!
@@ -44,6 +46,17 @@
 //!
 //! # Ok::<(), Box<dyn std::error::Error>>(())
 //! ```
+//!
+//! ## Using `SystemTimeExt`
+//!
+//! ```
+//! use std::time::{Duration, SystemTime};
+//! use tick::SystemTimeExt;
+//!
+//! let time = SystemTime::UNIX_EPOCH + Duration::from_secs(3600);
+//! println!("Time: {}", time.display_iso_8601());
+//! // Output: Time: 1970-01-01T01:00:00Z
+//! ```
 
 mod iso_8601;
 mod rfc_2822;

crates/tick/src/fmt/mod.rs

@@ -38,7 +38,7 @@ pub trait FutureExt: Future {
     }
 }
 
-impl<T> FutureExt for T where T: Future {}
+impl<T: Future> FutureExt for T {}
 
 #[cfg_attr(coverage_nightly, coverage(off))]
 #[cfg(test)]

crates/tick/src/future_ext.rs

@@ -76,13 +76,17 @@
 //! - [`Stopwatch`] - Measures elapsed time.
 //! - [`Delay`] - Delays the execution for a specified duration.
 //! - [`PeriodicTimer`] - Schedules a task to run periodically.
-//! - [`FutureExt`] - Extensions for the `Future` trait.
 //! - [`Error`] - Represents an error that can occur when working with time. Provides limited
 //!   introspection capabilities.
 //! - [`fmt`] - Utilities for formatting `SystemTime` into various formats. Available when
 //!   the `fmt` feature is enabled.
 //! - [`runtime`] - Infrastructure for integrating time primitives into async runtimes.
 //!
+//! # Extensions
+//!
+//! - [`FutureExt`] - Extensions for the `Future` trait, providing timeout functionality.
+//! - [`SystemTimeExt`] - Extensions for [`SystemTime`][`std::time::SystemTime`].
+//!
 //! # Machine-Centric vs. Human-Centric Time
 //!
 //! When working with time, two different use cases are considered:
@@ -223,6 +227,7 @@ mod future_ext;
 mod periodic_timer;
 mod state;
 mod stopwatch;
+mod system_time_ext;
 mod timers;
 
 pub mod runtime;
@@ -235,4 +240,5 @@ pub use error::{Error, Result};
 pub use future_ext::FutureExt;
 pub use periodic_timer::PeriodicTimer;
 pub use stopwatch::Stopwatch;
+pub use system_time_ext::SystemTimeExt;
 pub use timeout::Timeout;

crates/tick/src/lib.rs

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use std::time::SystemTime;
+
+/// Extension trait for [`SystemTime`] that provides formatting capabilities.
+pub trait SystemTimeExt: sealed::Sealed {
+    /// Returns a value that formats the [`SystemTime`] in ISO 8601 format.
+    ///
+    /// Times outside the valid range (before year -9999 or after year 9999) are saturated
+    /// to the nearest boundary.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use std::time::{Duration, SystemTime};
+    /// use tick::SystemTimeExt;
+    ///
+    /// let time = SystemTime::UNIX_EPOCH + Duration::from_secs(3600);
+    /// assert_eq!(time.display_iso_8601().to_string(), "1970-01-01T01:00:00Z");
+    /// ```
+    #[cfg(any(feature = "fmt", test))]
+    fn display_iso_8601(&self) -> impl std::fmt::Display;
+}
+
+impl SystemTimeExt for SystemTime {
+    #[cfg(any(feature = "fmt", test))]
+    fn display_iso_8601(&self) -> impl std::fmt::Display {
+        // jiff's Timestamp implements Display that outputs ISO 8601 format
+        to_timestamp(*self)
+    }
+}
+
+#[cfg(any(feature = "fmt", test))]
+fn to_timestamp(system_time: SystemTime) -> jiff::Timestamp {
+    match jiff::Timestamp::try_from(system_time) {
+        Ok(timestamp) => timestamp,
+        Err(_) => to_timestamp_min_max(system_time),
+    }
+}
+
+#[cfg(any(feature = "fmt", test))]
+fn to_timestamp_min_max(system_time: SystemTime) -> jiff::Timestamp {
+    if system_time.duration_since(SystemTime::UNIX_EPOCH).is_ok() {
+        jiff::Timestamp::MAX
+    } else {
+        jiff::Timestamp::MIN
+    }
+}
+
+mod sealed {
+    pub trait Sealed {}
+    impl Sealed for std::time::SystemTime {}
+}
+
+#[cfg_attr(coverage_nightly, coverage(off))]
+#[cfg(test)]
+mod tests {
+    use std::time::Duration;
+
+    use jiff::Timestamp;
+
+    use super::*;
+
+    #[test]
+    fn display_ok() {
+        assert_eq!(SystemTime::UNIX_EPOCH.display_iso_8601().to_string(), "1970-01-01T00:00:00Z");
+
+        assert_eq!(
+            (SystemTime::UNIX_EPOCH + Duration::from_secs(3600)).display_iso_8601().to_string(),
+            "1970-01-01T01:00:00Z"
+        );
+    }
+
+    #[test]
+    fn display_out_of_range() {
+        let time = SystemTime::from(Timestamp::MAX) + Duration::from_secs(12345);
+        assert_eq!(time.display_iso_8601().to_string(), "9999-12-30T22:00:00.999999999Z");
+    }
+
+    #[test]
+    fn to_timestamp_fallback_ok() {
+        let now = SystemTime::UNIX_EPOCH + Duration::from_secs(12345);
+        assert_eq!(to_timestamp_min_max(now), jiff::Timestamp::MAX);
+
+        let past = SystemTime::UNIX_EPOCH - Duration::from_secs(12345);
+        assert_eq!(to_timestamp_min_max(past), jiff::Timestamp::MIN);
+    }
+}