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`.