Duration in std::time - Rust (original) (raw)
Struct Duration
1.3.0 · Source
pub struct Duration { /* private fields */ }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 otherops 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);§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. Durationprovides 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.
🔬This is a nightly-only experimental API. (duration_constants #57391)
The duration of one second.
§Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::SECOND, Duration::from_secs(1));🔬This is a nightly-only experimental API. (duration_constants #57391)
The duration of one millisecond.
§Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::MILLISECOND, Duration::from_millis(1));🔬This is a nightly-only experimental API. (duration_constants #57391)
The duration of one microsecond.
§Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::MICROSECOND, Duration::from_micros(1));🔬This is a nightly-only experimental API. (duration_constants #57391)
The duration of one nanosecond.
§Examples
#![feature(duration_constants)]
use std::time::Duration;
assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1));1.53.0 · Source
A duration of zero time.
§Examples
use std::time::Duration;
let duration = Duration::ZERO;
assert!(duration.is_zero());
assert_eq!(duration.as_nanos(), 0);1.53.0 · Source
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));1.3.0 (const: 1.58.0) · Source
Creates 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);1.3.0 (const: 1.32.0) · Source
Creates a new Duration from the specified number of whole seconds.
§Examples
use std::time::Duration;
let duration = Duration::from_secs(5);
assert_eq!(5, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());1.3.0 (const: 1.32.0) · Source
Creates a new Duration from the specified number of milliseconds.
§Examples
use std::time::Duration;
let duration = Duration::from_millis(2_569);
assert_eq!(2, duration.as_secs());
assert_eq!(569_000_000, duration.subsec_nanos());1.27.0 (const: 1.32.0) · Source
Creates a new Duration from the specified number of microseconds.
§Examples
use std::time::Duration;
let duration = Duration::from_micros(1_000_002);
assert_eq!(1, duration.as_secs());
assert_eq!(2_000, duration.subsec_nanos());1.27.0 (const: 1.32.0) · Source
Creates a new Duration from the specified number of nanoseconds.
Note: Using this on the return value of as_nanos() might cause unexpected behavior:as_nanos() returns a u128, and can return values that do not fit in u64, e.g. 585 years. Instead, consider using the pattern Duration::new(d.as_secs(), d.subsec_nanos())if you cannot copy/clone the Duration directly.
§Examples
use std::time::Duration;
let duration = Duration::from_nanos(1_000_000_123);
assert_eq!(1, duration.as_secs());
assert_eq!(123, duration.subsec_nanos());🔬This is a nightly-only experimental API. (duration_constructors #120301)
Creates a new Duration from the specified number of weeks.
§Panics
Panics if the given number of weeks overflows the Duration size.
§Examples
#![feature(duration_constructors)]
use std::time::Duration;
let duration = Duration::from_weeks(4);
assert_eq!(4 * 7 * 24 * 60 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());🔬This is a nightly-only experimental API. (duration_constructors #120301)
Creates a new Duration from the specified number of days.
§Panics
Panics if the given number of days overflows the Duration size.
§Examples
#![feature(duration_constructors)]
use std::time::Duration;
let duration = Duration::from_days(7);
assert_eq!(7 * 24 * 60 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());🔬This is a nightly-only experimental API. (duration_constructors #120301)
Creates a new Duration from the specified number of hours.
§Panics
Panics if the given number of hours overflows the Duration size.
§Examples
#![feature(duration_constructors)]
use std::time::Duration;
let duration = Duration::from_hours(6);
assert_eq!(6 * 60 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());🔬This is a nightly-only experimental API. (duration_constructors #120301)
Creates a new Duration from the specified number of minutes.
§Panics
Panics if the given number of minutes overflows the Duration size.
§Examples
#![feature(duration_constructors)]
use std::time::Duration;
let duration = Duration::from_mins(10);
assert_eq!(10 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());1.53.0 (const: 1.53.0) · Source
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 (const: 1.32.0) · Source
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 Durationincluding the fractional part, use as_secs_f64 or as_secs_f32
1.27.0 (const: 1.32.0) · Source
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 (const: 1.32.0) · Source
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 (const: 1.32.0) · Source
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 (const: 1.33.0) · Source
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 (const: 1.33.0) · Source
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 (const: 1.33.0) · Source
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 (const: 1.81.0) · Source
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 (const: 1.58.0) · Source
Checked Duration addition. Computes self + other, returning Noneif overflow occurred.
§Examples
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);1.53.0 (const: 1.58.0) · Source
Saturating Duration addition. Computes self + other, returning Duration::MAXif 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);1.16.0 (const: 1.58.0) · Source
Checked Duration subtraction. Computes self - other, returning Noneif 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 (const: 1.58.0) · Source
Saturating Duration subtraction. Computes self - other, returning Duration::ZEROif 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 (const: 1.58.0) · Source
Checked Duration multiplication. Computes self * other, returningNone if overflow occurred.
§Examples
use std::time::Duration;
assert_eq!(Duration::new(0, 500_000_001).checked_mul(2), Some(Duration::new(1, 2)));
assert_eq!(Duration::new(u64::MAX - 1, 0).checked_mul(2), None);1.53.0 (const: 1.58.0) · Source
Saturating Duration multiplication. Computes self * other, returningDuration::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);1.16.0 (const: 1.58.0) · Source
Checked Duration division. Computes self / other, returning Noneif 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 (const: 1.83.0) · Source
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 (const: 1.83.0) · Source
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);🔬This is a nightly-only experimental API. (duration_millis_float #122451)
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);🔬This is a nightly-only experimental API. (duration_millis_float #122451)
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 · Source
Creates a new Duration from the specified number of seconds represented as f64.
§Panics
This constructor will panic if secs is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let res = Duration::from_secs_f64(0.0);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f64(1e-20);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f64(4.2e-7);
assert_eq!(res, Duration::new(0, 420));
let res = Duration::from_secs_f64(2.7);
assert_eq!(res, Duration::new(2, 700_000_000));
let res = Duration::from_secs_f64(3e10);
assert_eq!(res, Duration::new(30_000_000_000, 0));
// subnormal float
let res = Duration::from_secs_f64(f64::from_bits(1));
assert_eq!(res, Duration::new(0, 0));
// conversion uses rounding
let res = Duration::from_secs_f64(0.999e-9);
assert_eq!(res, Duration::new(0, 1));1.38.0 · Source
Creates a new Duration from the specified number of seconds represented as f32.
§Panics
This constructor will panic if secs is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let res = Duration::from_secs_f32(0.0);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f32(1e-20);
assert_eq!(res, Duration::new(0, 0));
let res = Duration::from_secs_f32(4.2e-7);
assert_eq!(res, Duration::new(0, 420));
let res = Duration::from_secs_f32(2.7);
assert_eq!(res, Duration::new(2, 700_000_048));
let res = Duration::from_secs_f32(3e10);
assert_eq!(res, Duration::new(30_000_001_024, 0));
// subnormal float
let res = Duration::from_secs_f32(f32::from_bits(1));
assert_eq!(res, Duration::new(0, 0));
// conversion uses rounding
let res = Duration::from_secs_f32(0.999e-9);
assert_eq!(res, Duration::new(0, 1));1.38.0 · Source
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));1.38.0 · Source
Multiplies Duration by f32.
§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_f32(3.14), Duration::new(8, 478_000_641));
assert_eq!(dur.mul_f32(3.14e5), Duration::new(847_800, 0));1.38.0 · Source
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));1.38.0 · Source
Divides Duration by f32.
§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 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));
assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_599));1.80.0 (const: 1.83.0) · Source
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 (const: 1.83.0) · Source
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);1.66.0 · Source
The checked version of from_secs_f32.
This constructor will return an Err if secs is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let res = Duration::try_from_secs_f32(0.0);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(1e-20);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(4.2e-7);
assert_eq!(res, Ok(Duration::new(0, 420)));
let res = Duration::try_from_secs_f32(2.7);
assert_eq!(res, Ok(Duration::new(2, 700_000_048)));
let res = Duration::try_from_secs_f32(3e10);
assert_eq!(res, Ok(Duration::new(30_000_001_024, 0)));
// subnormal float:
let res = Duration::try_from_secs_f32(f32::from_bits(1));
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f32(-5.0);
assert!(res.is_err());
let res = Duration::try_from_secs_f32(f32::NAN);
assert!(res.is_err());
let res = Duration::try_from_secs_f32(2e19);
assert!(res.is_err());
// the conversion uses rounding with tie resolution to even
let res = Duration::try_from_secs_f32(0.999e-9);
assert_eq!(res, Ok(Duration::new(0, 1)));
// this float represents exactly 976562.5e-9
let val = f32::from_bits(0x3A80_0000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(0, 976_562)));
// this float represents exactly 2929687.5e-9
let val = f32::from_bits(0x3B40_0000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(0, 2_929_688)));
// this float represents exactly 1.000_976_562_5
let val = f32::from_bits(0x3F802000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(1, 976_562)));
// this float represents exactly 1.002_929_687_5
let val = f32::from_bits(0x3F806000);
let res = Duration::try_from_secs_f32(val);
assert_eq!(res, Ok(Duration::new(1, 2_929_688)));1.66.0 · Source
The checked version of from_secs_f64.
This constructor will return an Err if secs is negative, overflows Duration or not finite.
§Examples
use std::time::Duration;
let res = Duration::try_from_secs_f64(0.0);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(1e-20);
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(4.2e-7);
assert_eq!(res, Ok(Duration::new(0, 420)));
let res = Duration::try_from_secs_f64(2.7);
assert_eq!(res, Ok(Duration::new(2, 700_000_000)));
let res = Duration::try_from_secs_f64(3e10);
assert_eq!(res, Ok(Duration::new(30_000_000_000, 0)));
// subnormal float
let res = Duration::try_from_secs_f64(f64::from_bits(1));
assert_eq!(res, Ok(Duration::new(0, 0)));
let res = Duration::try_from_secs_f64(-5.0);
assert!(res.is_err());
let res = Duration::try_from_secs_f64(f64::NAN);
assert!(res.is_err());
let res = Duration::try_from_secs_f64(2e19);
assert!(res.is_err());
// the conversion uses rounding with tie resolution to even
let res = Duration::try_from_secs_f64(0.999e-9);
assert_eq!(res, Ok(Duration::new(0, 1)));
let res = Duration::try_from_secs_f64(0.999_999_999_499);
assert_eq!(res, Ok(Duration::new(0, 999_999_999)));
let res = Duration::try_from_secs_f64(0.999_999_999_501);
assert_eq!(res, Ok(Duration::new(1, 0)));
let res = Duration::try_from_secs_f64(42.999_999_999_499);
assert_eq!(res, Ok(Duration::new(42, 999_999_999)));
let res = Duration::try_from_secs_f64(42.999_999_999_501);
assert_eq!(res, Ok(Duration::new(43, 0)));
// this float represents exactly 976562.5e-9
let val = f64::from_bits(0x3F50_0000_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(0, 976_562)));
// this float represents exactly 2929687.5e-9
let val = f64::from_bits(0x3F68_0000_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(0, 2_929_688)));
// this float represents exactly 1.000_976_562_5
let val = f64::from_bits(0x3FF0_0400_0000_0000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(1, 976_562)));
// this float represents exactly 1.002_929_687_5
let val = f64::from_bits(0x3_FF00_C000_0000_000);
let res = Duration::try_from_secs_f64(val);
assert_eq!(res, Ok(Duration::new(1, 2_929_688)));§Panics
This function may panic if the resulting point in time cannot be represented by the underlying data structure. See Instant::checked_add for a version without panic.
The resulting type after applying the + operator.
§Panics
This function may panic if the resulting point in time cannot be represented by the underlying data structure. See SystemTime::checked_add for a version without panic.
The resulting type after applying the + operator.
The resulting type after applying the + operator.
The resulting type after applying the / operator.
The resulting type after applying the * operator.
The resulting type after applying the * operator.
Tests for self and other values to be equal, and is used by ==.
Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
This method returns an ordering between self and other values if one exists. Read more
Tests less than (for self and other) and is used by the < operator. Read more
Tests less than or equal to (for self and other) and is used by the<= operator. Read more
Tests greater than (for self and other) and is used by the >operator. Read more
Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
The resulting type after applying the - operator.
The resulting type after applying the - operator.
The resulting type after applying the - operator.
Takes an iterator and generates Self from the elements by “summing up” the items.
Takes an iterator and generates Self from the elements by “summing up” the items.