From 8fd2f0c81f95eeb9440369ac046124d8dbd85a31 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Thu, 28 Jan 2021 00:51:31 -0800 Subject: [PATCH] Add documentation about formatting `Duration` values Explain why Duration has a Debug impl but not a Display impl, and mention the use of Unicode. --- library/core/src/time.rs | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/library/core/src/time.rs b/library/core/src/time.rs index 88b4e2a2436..b9ee931eeec 100644 --- a/library/core/src/time.rs +++ b/library/core/src/time.rs @@ -48,6 +48,17 @@ const MICROS_PER_SEC: u64 = 1_000_000; /// /// let ten_millis = Duration::from_millis(10); /// ``` +/// +/// # Formatting `Duration` values +/// +/// `Duration` intentionally does not have a `Display` impl, as there are a +/// variety of ways to format spans of time for human readability. `Duration` +/// provides a `Debug` impl that shows the full precision of the value. +/// +/// The `Debug` output uses the non-ASCII "µs" suffix for microseconds. If your +/// program output may appear in contexts that cannot rely on full Unicode +/// compatibility, you may wish to format `Duration` objects yourself or use a +/// crate to do so. #[stable(feature = "duration", since = "1.3.0")] #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] pub struct Duration {