pub struct Duration(/* private fields */);Expand description
A wrapper for duration that has FromStr implementation
This is useful if you want to use it somewhere where FromStr is
expected.
See parse_duration for the description of the format.
§Example
use std::time::Duration;
let x: Duration;
x = "12h 5min 2ns".parse::<humantime::Duration>().unwrap().into();
assert_eq!(x, Duration::new(12*3600 + 5*60, 2))Implementations§
Source§impl Duration
impl Duration
Sourcepub const fn new(value: StdDuration) -> Self
pub const fn new(value: StdDuration) -> Self
Create a new instance from a StdDuration. This can be used in a const context.
const DEFAULT_TIMEOUT: Duration = Duration::new(core::time::Duration::from_secs(60));Methods from Deref<Target = StdDuration>§
1.53.0 · Sourcepub fn is_zero(&self) -> bool
pub fn is_zero(&self) -> bool
Returns true if this Duration spans no time.
§Examples
use std::time::Duration;
assert!(Duration::ZERO.is_zero());
assert!(Duration::new(0, 0).is_zero());
assert!(Duration::from_nanos(0).is_zero());
assert!(Duration::from_secs(0).is_zero());
assert!(!Duration::new(1, 1).is_zero());
assert!(!Duration::from_nanos(1).is_zero());
assert!(!Duration::from_secs(1).is_zero());1.3.0 · Sourcepub fn as_secs(&self) -> u64
pub fn as_secs(&self) -> u64
Returns the number of whole seconds contained by this Duration.
The returned value does not include the fractional (nanosecond) part of the
duration, which can be obtained using subsec_nanos.
§Examples
use std::time::Duration;
let duration = Duration::new(5, 730_023_852);
assert_eq!(duration.as_secs(), 5);To determine the total number of seconds represented by the Duration
including the fractional part, use as_secs_f64 or as_secs_f32
1.27.0 · Sourcepub fn subsec_millis(&self) -> u32
pub fn subsec_millis(&self) -> u32
Returns the fractional part of this Duration, in whole milliseconds.
This method does not return the length of the duration when represented by milliseconds. The returned number always represents a fractional portion of a second (i.e., it is less than one thousand).
§Examples
use std::time::Duration;
let duration = Duration::from_millis(5_432);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_millis(), 432);1.27.0 · Sourcepub fn subsec_micros(&self) -> u32
pub fn subsec_micros(&self) -> u32
Returns the fractional part of this Duration, in whole microseconds.
This method does not return the length of the duration when represented by microseconds. The returned number always represents a fractional portion of a second (i.e., it is less than one million).
§Examples
use std::time::Duration;
let duration = Duration::from_micros(1_234_567);
assert_eq!(duration.as_secs(), 1);
assert_eq!(duration.subsec_micros(), 234_567);1.3.0 · Sourcepub fn subsec_nanos(&self) -> u32
pub fn subsec_nanos(&self) -> u32
Returns the fractional part of this Duration, in nanoseconds.
This method does not return the length of the duration when represented by nanoseconds. The returned number always represents a fractional portion of a second (i.e., it is less than one billion).
§Examples
use std::time::Duration;
let duration = Duration::from_millis(5_010);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_nanos(), 10_000_000);1.33.0 · Sourcepub fn as_millis(&self) -> u128
pub fn as_millis(&self) -> u128
Returns the total number of whole milliseconds contained by this Duration.
§Examples
use std::time::Duration;
let duration = Duration::new(5, 730_023_852);
assert_eq!(duration.as_millis(), 5_730);1.33.0 · Sourcepub fn as_micros(&self) -> u128
pub fn as_micros(&self) -> u128
Returns the total number of whole microseconds contained by this Duration.
§Examples
use std::time::Duration;
let duration = Duration::new(5, 730_023_852);
assert_eq!(duration.as_micros(), 5_730_023);1.33.0 · Sourcepub fn as_nanos(&self) -> u128
pub fn as_nanos(&self) -> u128
Returns the total number of nanoseconds contained by this Duration.
§Examples
use std::time::Duration;
let duration = Duration::new(5, 730_023_852);
assert_eq!(duration.as_nanos(), 5_730_023_852);1.81.0 · Sourcepub fn abs_diff(self, other: Duration) -> Duration
pub fn abs_diff(self, other: Duration) -> Duration
Computes the absolute difference between self and other.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(100, 0).abs_diff(Duration::new(80, 0)), Duration::new(20, 0));
assert_eq!(Duration::new(100, 400_000_000).abs_diff(Duration::new(110, 0)), Duration::new(9, 600_000_000));1.16.0 · Sourcepub fn checked_add(self, rhs: Duration) -> Option<Duration>
pub fn checked_add(self, rhs: Duration) -> Option<Duration>
1.53.0 · Sourcepub fn saturating_add(self, rhs: Duration) -> Duration
pub fn saturating_add(self, rhs: Duration) -> Duration
Saturating Duration addition. Computes self + other, returning Duration::MAX
if overflow occurred.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1));
assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX);1.16.0 · Sourcepub fn checked_sub(self, rhs: Duration) -> Option<Duration>
pub fn checked_sub(self, rhs: Duration) -> Option<Duration>
Checked Duration subtraction. Computes self - other, returning None
if the result would be negative or if overflow occurred.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 1).checked_sub(Duration::new(0, 0)), Some(Duration::new(0, 1)));
assert_eq!(Duration::new(0, 0).checked_sub(Duration::new(0, 1)), None);1.53.0 · Sourcepub fn saturating_sub(self, rhs: Duration) -> Duration
pub fn saturating_sub(self, rhs: Duration) -> Duration
Saturating Duration subtraction. Computes self - other, returning Duration::ZERO
if the result would be negative or if overflow occurred.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 1).saturating_sub(Duration::new(0, 0)), Duration::new(0, 1));
assert_eq!(Duration::new(0, 0).saturating_sub(Duration::new(0, 1)), Duration::ZERO);1.16.0 · Sourcepub fn checked_mul(self, rhs: u32) -> Option<Duration>
pub fn checked_mul(self, rhs: u32) -> Option<Duration>
1.53.0 · Sourcepub fn saturating_mul(self, rhs: u32) -> Duration
pub fn saturating_mul(self, rhs: u32) -> Duration
Saturating Duration multiplication. Computes self * other, returning
Duration::MAX if overflow occurred.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 500_000_001).saturating_mul(2), Duration::new(1, 2));
assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX);1.16.0 · Sourcepub fn checked_div(self, rhs: u32) -> Option<Duration>
pub fn checked_div(self, rhs: u32) -> Option<Duration>
Checked Duration division. Computes self / other, returning None
if other == 0.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0)));
assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000)));
assert_eq!(Duration::new(2, 0).checked_div(0), None);1.38.0 · Sourcepub fn as_secs_f64(&self) -> f64
pub fn as_secs_f64(&self) -> f64
Returns the number of seconds contained by this Duration as f64.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
assert_eq!(dur.as_secs_f64(), 2.7);1.38.0 · Sourcepub fn as_secs_f32(&self) -> f32
pub fn as_secs_f32(&self) -> f32
Returns the number of seconds contained by this Duration as f32.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
assert_eq!(dur.as_secs_f32(), 2.7);Sourcepub fn as_millis_f64(&self) -> f64
🔬This is a nightly-only experimental API. (duration_millis_float)
pub fn as_millis_f64(&self) -> f64
duration_millis_float)Returns the number of milliseconds contained by this Duration as f64.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
#![feature(duration_millis_float)]
use std::time::Duration;
let dur = Duration::new(2, 345_678_000);
assert_eq!(dur.as_millis_f64(), 2_345.678);Sourcepub fn as_millis_f32(&self) -> f32
🔬This is a nightly-only experimental API. (duration_millis_float)
pub fn as_millis_f32(&self) -> f32
duration_millis_float)Returns the number of milliseconds contained by this Duration as f32.
The returned value includes the fractional (nanosecond) part of the duration.
§Examples
#![feature(duration_millis_float)]
use std::time::Duration;
let dur = Duration::new(2, 345_678_000);
assert_eq!(dur.as_millis_f32(), 2_345.678);1.38.0 · Sourcepub fn mul_f64(self, rhs: f64) -> Duration
pub fn mul_f64(self, rhs: f64) -> Duration
Multiplies Duration by f64.
§Panics
This method will panic if result is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
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.
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));// In the extreme, rounding can even overflow `Duration`, which panics.
let _ = Duration::from_secs(u64::MAX).mul_f64(1.0);1.38.0 · Sourcepub fn mul_f32(self, rhs: f32) -> Duration
pub fn mul_f32(self, rhs: f32) -> 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 for greater accuracy.
§Panics
This method will panic if result is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
// 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));1.38.0 · Sourcepub fn div_f64(self, rhs: f64) -> Duration
pub fn div_f64(self, rhs: f64) -> Duration
Divides Duration by f64.
§Panics
This method will panic if result is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
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.
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));// In the extreme, rounding can even overflow `Duration`, which panics.
let _ = Duration::from_secs(u64::MAX).div_f64(1.0);1.38.0 · Sourcepub fn div_f32(self, rhs: f32) -> Duration
pub fn div_f32(self, rhs: f32) -> 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 for greater accuracy.
§Panics
This method will panic if result is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
// 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));1.80.0 · Sourcepub fn div_duration_f64(self, rhs: Duration) -> f64
pub fn div_duration_f64(self, rhs: Duration) -> f64
Divides Duration by Duration and returns f64.
§Examples
use std::time::Duration;
let dur1 = Duration::new(2, 700_000_000);
let dur2 = Duration::new(5, 400_000_000);
assert_eq!(dur1.div_duration_f64(dur2), 0.5);1.80.0 · Sourcepub fn div_duration_f32(self, rhs: Duration) -> f32
pub fn div_duration_f32(self, rhs: Duration) -> f32
Divides Duration by Duration and returns f32.
§Examples
use std::time::Duration;
let dur1 = Duration::new(2, 700_000_000);
let dur2 = Duration::new(5, 400_000_000);
assert_eq!(dur1.div_duration_f32(dur2), 0.5);Sourcepub fn div_duration_floor(self, rhs: Duration) -> u128
🔬This is a nightly-only experimental API. (duration_integer_division)
pub fn div_duration_floor(self, rhs: Duration) -> u128
duration_integer_division)Divides Duration by Duration and returns u128, rounding the result towards zero.
§Examples
#![feature(duration_integer_division)]
use std::time::Duration;
let dur = Duration::new(2, 0);
assert_eq!(dur.div_duration_floor(Duration::new(1, 000_000_001)), 1);
assert_eq!(dur.div_duration_floor(Duration::new(1, 000_000_000)), 2);
assert_eq!(dur.div_duration_floor(Duration::new(0, 999_999_999)), 2);Sourcepub fn div_duration_ceil(self, rhs: Duration) -> u128
🔬This is a nightly-only experimental API. (duration_integer_division)
pub fn div_duration_ceil(self, rhs: Duration) -> u128
duration_integer_division)Divides Duration by Duration and returns u128, rounding the result towards positive infinity.
§Examples
#![feature(duration_integer_division)]
use std::time::Duration;
let dur = Duration::new(2, 0);
assert_eq!(dur.div_duration_ceil(Duration::new(1, 000_000_001)), 2);
assert_eq!(dur.div_duration_ceil(Duration::new(1, 000_000_000)), 2);
assert_eq!(dur.div_duration_ceil(Duration::new(0, 999_999_999)), 3);Sourcepub fn display_seconds(&self) -> DisplaySeconds
🔬This is a nightly-only experimental API. (duration_display_seconds)
pub fn display_seconds(&self) -> DisplaySeconds
duration_display_seconds)Displays Duration in seconds, even if it only contains the nanosecond part.
Unlike Duration::as_secs_f32 or Duration::as_secs_f64, which convert
to floating-point numbers and may lose precision, this method displays a precise
value. If the formatting precision {:.N} is explicitly specified:
N< 9: it rounds the subsecond part with tie resolution to even.N= 9: it displays the precise 9-digit subsecond part.N> 9: it appends trailing zeros to the subsecond part.
§Examples
#![feature(duration_display_seconds)]
use std::time::Duration;
// Display a duration longer than a second as seconds.
assert_eq!(Duration::new(2, 0).display_seconds().to_string(), "2s");
// Display a duration shorter than a second as seconds.
assert_eq!(Duration::new(0, 2).display_seconds().to_string(), "0.000000002s");
// `display_seconds` displays a precise value.
assert_eq!(
format!("{}", Duration::new(1_000_000_000_000, 1).display_seconds()),
"1000000000000.000000001s",
);
// If formatting precision (< 9) is explicitly specified, it rounds
// the subsecond part with tie resolution to even.
assert_eq!(
format!("{:.0}", Duration::new(1_000_000_000_000, 1).display_seconds()),
"1000000000000s",
);
// If formatting precision (> 9) is explicitly specified, it appends
// trailing zeros to the subsecond part.
assert_eq!(
format!("{:.10}", Duration::new(1_000_000_000_000, 1).display_seconds()),
"1000000000000.0000000010s",
);
// In contrast, `as_secs_f64` converts it to a floating-point number
// and may introduce floating-point computation errors.
assert_eq!(
format!("{}", Duration::new(1_000_000_000_000, 1).as_secs_f64()),
"1000000000000",
);