Struct core::time::Duration 1.3.0[−][src]
pub struct Duration { /* fields omitted */ }Expand description
A Duration type to represent a span of time, typically used for system
timeouts.
Each Duration is composed of a whole number of seconds and a fractional part
represented in nanoseconds. If the underlying system does not support
nanosecond-level precision, APIs binding a system timeout will typically round up
the number of nanoseconds.
Durations implement many common traits, including Add, Sub, and other
ops traits. It implements Default by returning a zero-length Duration.
Examples
use std::time::Duration;
let five_seconds = Duration::new(5, 0);
let five_seconds_and_five_nanos = five_seconds + Duration::new(0, 5);
assert_eq!(five_seconds_and_five_nanos.as_secs(), 5);
assert_eq!(five_seconds_and_five_nanos.subsec_nanos(), 5);
let ten_millis = Duration::from_millis(10);RunFormatting 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.
Implementations
The maximum duration.
May vary by platform as necessary. Must be able to contain the difference between
two instances of Instant or two instances of SystemTime.
This constraint gives it a value of about 584,942,417,355 years in practice,
which is currently used on all platforms.
Examples
use std::time::Duration;
assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1));RunCreates a new Duration from the specified number of whole seconds and
additional nanoseconds.
If the number of nanoseconds is greater than 1 billion (the number of nanoseconds in a second), then it will carry over into the seconds provided.
Panics
This constructor will panic if the carry from the nanoseconds overflows the seconds counter.
Examples
use std::time::Duration;
let five_seconds = Duration::new(5, 0);RunReturns 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());RunReturns 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, 730023852);
assert_eq!(duration.as_secs(), 5);RunTo determine the total number of seconds represented by the Duration,
use as_secs in combination with subsec_nanos:
use std::time::Duration;
let duration = Duration::new(5, 730023852);
assert_eq!(5.730023852,
duration.as_secs() as f64
+ duration.subsec_nanos() as f64 * 1e-9);RunReturns 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(5432);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_millis(), 432);RunReturns 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);RunReturns 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(5010);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_nanos(), 10_000_000);RunChecked Duration addition. Computes self + other, returning None
if overflow occurred.
Examples
Basic usage:
use std::time::Duration;
assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1)));
assert_eq!(Duration::new(1, 0).checked_add(Duration::new(u64::MAX, 0)), None);RunSaturating Duration addition. Computes self + other, returning Duration::MAX
if overflow occurred.
Examples
#![feature(duration_constants)]
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);RunChecked Duration subtraction. Computes self - other, returning None
if the result would be negative or if overflow occurred.
Examples
Basic usage:
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);RunSaturating 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);RunSaturating Duration multiplication. Computes self * other, returning
Duration::MAX if overflow occurred.
Examples
#![feature(duration_constants)]
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);RunChecked Duration division. Computes self / other, returning None
if other == 0.
Examples
Basic usage:
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);RunThe checked version of from_secs_f64.
This constructor will return an Err if secs is not finite, negative or overflows Duration.
Examples
#![feature(duration_checked_float)]
use std::time::Duration;
let dur = Duration::try_from_secs_f64(2.7);
assert_eq!(dur, Ok(Duration::new(2, 700_000_000)));
let negative = Duration::try_from_secs_f64(-5.0);
assert!(negative.is_err());RunThe checked version of from_secs_f32.
This constructor will return an Err if secs is not finite, negative or overflows Duration.
Examples
#![feature(duration_checked_float)]
use std::time::Duration;
let dur = Duration::try_from_secs_f32(2.7);
assert_eq!(dur, Ok(Duration::new(2, 700_000_000)));
let negative = Duration::try_from_secs_f32(-5.0);
assert!(negative.is_err());RunMultiplies Duration by f64.
Panics
This method will panic if result is not finite, negative or overflows Duration.
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));RunMultiplies Duration by f32.
Panics
This method will panic if result is not finite, negative or overflows Duration.
Examples
use std::time::Duration;
let dur = Duration::new(2, 700_000_000);
// note that due to rounding errors result is slightly different
// from 8.478 and 847800.0
assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_640));
assert_eq!(dur.mul_f32(3.14e5), Duration::new(847799, 969_120_256));RunDivide Duration by f64.
Panics
This method will panic if result is not finite, negative or overflows Duration.
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));
// note that truncation is used, not rounding
assert_eq!(dur.div_f64(3.14e5), Duration::new(0, 8_598));RunDivide Duration by f32.
Panics
This method will panic if result is not finite, negative or overflows Duration.
Examples
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_576));
// note that truncation is used, not rounding
assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_598));RunTrait Implementations
Performs the += operation. Read more
Performs the /= operation. Read more
Performs the *= operation. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <=
operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
Performs the -= operation. Read more