From 20c9f54404453c96e31d83f6587c999f21cbc6dc Mon Sep 17 00:00:00 2001 From: Josh Stone Date: Fri, 10 Apr 2026 16:25:55 -0700 Subject: [PATCH] Document precision considerations of `Duration`-float methods A `Duration` is essentially a 94-bit value (64-bit sec and ~30-bit ns), so there's some inherent loss when converting to floating-point for `mul_f64` and `div_f64`. We could go to greater lengths to compute these with more accuracy, like rust-lang/rust#150933 or rust-lang/rust#154107, but it's not clear that it's worth the effort. The least we can do is document that some rounding is to be expected, which this commit does with simple examples that only multiply or divide by `1.0`. This also changes the `f32` methods to just forward to `f64`, so we keep more of that duration precision, as the range is otherwise much more limited there. --- library/core/src/time.rs | 88 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 6 deletions(-) diff --git a/library/core/src/time.rs b/library/core/src/time.rs index a5b654033ba14..9073131b35b61 100644 --- a/library/core/src/time.rs +++ b/library/core/src/time.rs @@ -1006,6 +1006,7 @@ impl Duration { /// This method will panic if result is negative, overflows `Duration` or not finite. /// /// # Examples + /// /// ``` /// use std::time::Duration; /// @@ -1013,6 +1014,37 @@ impl Duration { /// assert_eq!(dur.mul_f64(3.14), Duration::new(8, 478_000_000)); /// assert_eq!(dur.mul_f64(3.14e5), Duration::new(847_800, 0)); /// ``` + /// + /// Note that `f64` does not have enough bits ([`f64::MANTISSA_DIGITS`]) to represent the full + /// range of possible `Duration` with nanosecond precision, so rounding may occur even for + /// trivial operations like multiplying by 1. + /// + /// ``` + /// # #![feature(float_exact_integer_constants)] + /// use std::time::Duration; + /// + /// // This is about 14.9 weeks, remaining precise to the nanosecond: + /// let weeks = Duration::from_nanos(f64::MAX_EXACT_INTEGER as u64); + /// assert_eq!(weeks, weeks.mul_f64(1.0)); + /// + /// // A larger value incurs rounding in the floating-point operation: + /// let weeks = Duration::from_nanos(u64::MAX); + /// assert_ne!(weeks, weeks.mul_f64(1.0)); + /// + /// // This is over 285 million years, remaining precise to the second: + /// let years = Duration::from_secs(f64::MAX_EXACT_INTEGER as u64); + /// assert_eq!(years, years.mul_f64(1.0)); + /// + /// // And again larger values incur rounding: + /// let years = Duration::from_secs(u64::MAX / 2); + /// assert_ne!(years, years.mul_f64(1.0)); + /// ``` + /// + /// ```should_panic + /// # use std::time::Duration; + /// // In the extreme, rounding can even overflow `Duration`, which panics. + /// let _ = Duration::from_secs(u64::MAX).mul_f64(1.0); + /// ``` #[stable(feature = "duration_float", since = "1.38.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] @@ -1023,6 +1055,10 @@ impl Duration { /// Multiplies `Duration` by `f32`. /// + /// Since the significand of `f32` is quite limited compared to the range of `Duration` + /// -- only about 16.8ms of exact nanosecond precision -- this method currently forwards + /// to [`mul_f64`][Self::mul_f64] for greater accuracy. + /// /// # Panics /// This method will panic if result is negative, overflows `Duration` or not finite. /// @@ -1031,7 +1067,10 @@ impl Duration { /// use std::time::Duration; /// /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_641)); + /// // Note that this `3.14_f32` argument already has more floating-point + /// // representation error than a direct `3.14_f64` would, so the result + /// // is slightly different from the ideal 8.478s. + /// assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_283)); /// assert_eq!(dur.mul_f32(3.14e5), Duration::new(847_800, 0)); /// ``` #[stable(feature = "duration_float", since = "1.38.0")] @@ -1039,7 +1078,7 @@ impl Duration { without modifying the original"] #[inline] pub fn mul_f32(self, rhs: f32) -> Duration { - Duration::from_secs_f32(rhs * self.as_secs_f32()) + self.mul_f64(rhs.into()) } /// Divides `Duration` by `f64`. @@ -1048,6 +1087,7 @@ impl Duration { /// This method will panic if result is negative, overflows `Duration` or not finite. /// /// # Examples + /// /// ``` /// use std::time::Duration; /// @@ -1055,6 +1095,37 @@ impl Duration { /// assert_eq!(dur.div_f64(3.14), Duration::new(0, 859_872_611)); /// assert_eq!(dur.div_f64(3.14e5), Duration::new(0, 8_599)); /// ``` + /// + /// Note that `f64` does not have enough bits ([`f64::MANTISSA_DIGITS`]) to represent the full + /// range of possible `Duration` with nanosecond precision, so rounding may occur even for + /// trivial operations like dividing by 1. + /// + /// ``` + /// # #![feature(float_exact_integer_constants)] + /// use std::time::Duration; + /// + /// // This is about 14.9 weeks, remaining precise to the nanosecond: + /// let weeks = Duration::from_nanos(f64::MAX_EXACT_INTEGER as u64); + /// assert_eq!(weeks, weeks.div_f64(1.0)); + /// + /// // A larger value incurs rounding in the floating-point operation: + /// let weeks = Duration::from_nanos(u64::MAX); + /// assert_ne!(weeks, weeks.div_f64(1.0)); + /// + /// // This is over 285 million years, remaining precise to the second: + /// let years = Duration::from_secs(f64::MAX_EXACT_INTEGER as u64); + /// assert_eq!(years, years.div_f64(1.0)); + /// + /// // And again larger values incur rounding: + /// let years = Duration::from_secs(u64::MAX / 2); + /// assert_ne!(years, years.div_f64(1.0)); + /// ``` + /// + /// ```should_panic + /// # use std::time::Duration; + /// // In the extreme, rounding can even overflow `Duration`, which panics. + /// let _ = Duration::from_secs(u64::MAX).div_f64(1.0); + /// ``` #[stable(feature = "duration_float", since = "1.38.0")] #[must_use = "this returns the result of the operation, \ without modifying the original"] @@ -1065,6 +1136,10 @@ impl Duration { /// Divides `Duration` by `f32`. /// + /// Since the significand of `f32` is quite limited compared to the range of `Duration` + /// -- only about 16.8ms of exact nanosecond precision -- this method currently forwards + /// to [`div_f64`][Self::div_f64] for greater accuracy. + /// /// # Panics /// This method will panic if result is negative, overflows `Duration` or not finite. /// @@ -1073,9 +1148,10 @@ impl Duration { /// use std::time::Duration; /// /// let dur = Duration::new(2, 700_000_000); - /// // note that due to rounding errors result is slightly - /// // different from 0.859_872_611 - /// assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_580)); + /// // Note that this `3.14_f32` argument already has more floating-point + /// // representation error than a direct `3.14_f64` would, so the result + /// // is slightly different from the ideally rounded 0.859_872_611. + /// assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_583)); /// assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_599)); /// ``` #[stable(feature = "duration_float", since = "1.38.0")] @@ -1083,7 +1159,7 @@ impl Duration { without modifying the original"] #[inline] pub fn div_f32(self, rhs: f32) -> Duration { - Duration::from_secs_f32(self.as_secs_f32() / rhs) + self.div_f64(rhs.into()) } /// Divides `Duration` by `Duration` and returns `f64`.