impl Duration

const fn new(secs: u64, nanos: u32) -> Duration

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);

const fn from_secs(secs: u64) -> Duration

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());

const fn from_millis(millis: u64) -> Duration

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());

const fn from_micros(micros: u64) -> Duration

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());

const fn from_nanos(nanos: u64) -> Duration

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());

const fn from_nanos_u128(nanos: u128) -> Duration

Creates a new Duration from the specified number of nanoseconds.

Panics

Panics if the given number of nanoseconds is greater than Duration::MAX.

Examples

use std::time::Duration;

let nanos = 10_u128.pow(24) + 321;
let duration = Duration::from_nanos_u128(nanos);

assert_eq!(10_u64.pow(15), duration.as_secs());
assert_eq!(321, duration.subsec_nanos());

const fn from_weeks(weeks: u64) -> Duration

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());

const fn from_days(days: u64) -> Duration

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());

const fn from_hours(hours: u64) -> Duration

Creates a new Duration from the specified number of hours.

Panics

Panics if the given number of hours overflows the Duration size.

Examples

use std::time::Duration;

let duration = Duration::from_hours(6);

assert_eq!(6 * 60 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());

const fn from_mins(mins: u64) -> Duration

Creates a new Duration from the specified number of minutes.

Panics

Panics if the given number of minutes overflows the Duration size.

Examples

use std::time::Duration;

let duration = Duration::from_mins(10);

assert_eq!(10 * 60, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());

const fn is_zero(self: &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());

const fn as_secs(self: &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

const fn subsec_millis(self: &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);

const fn subsec_micros(self: &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);

const fn subsec_nanos(self: &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);

const fn as_millis(self: &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);

const fn as_micros(self: &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);

const fn as_nanos(self: &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);

const fn abs_diff(self: 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));

const fn checked_add(self: Self, rhs: Duration) -> Option<Duration>

Checked Duration addition. Computes self + other, returning None if 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);

const fn saturating_add(self: Self, rhs: Duration) -> Duration

Saturating 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);

const fn checked_sub(self: 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);

const fn saturating_sub(self: 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);

const fn checked_mul(self: Self, rhs: u32) -> Option<Duration>

Checked Duration multiplication. Computes self * other, returning None 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);

const fn saturating_mul(self: Self, rhs: u32) -> Duration

Saturating 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);

const fn checked_div(self: 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);

const fn as_secs_f64(self: &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);

const fn as_secs_f32(self: &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);

const fn as_millis_f64(self: &Self) -> f64

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);

const fn as_millis_f32(self: &Self) -> f32

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);

fn from_secs_f64(secs: f64) -> Duration

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));

fn from_secs_f32(secs: f32) -> Duration

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));

fn mul_f64(self: 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));

fn mul_f32(self: Self, rhs: f32) -> Duration

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));

fn div_f64(self: 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));

fn div_f32(self: Self, rhs: f32) -> Duration

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));

const fn div_duration_f64(self: 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);

const fn div_duration_f32(self: 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);

const fn div_duration_floor(self: Self, rhs: Duration) -> u128

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);

const fn div_duration_ceil(self: Self, rhs: Duration) -> u128

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);

impl Duration

fn try_from_secs_f32(secs: f32) -> Result<Duration, TryFromFloatSecsError>

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)));

fn try_from_secs_f64(secs: f64) -> Result<Duration, TryFromFloatSecsError>

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)));

impl Add for Duration

fn add(self: Self, rhs: Duration) -> Duration

impl AddAssign for Duration

fn add_assign(self: &mut Self, rhs: Duration)

impl Clone for Duration

fn clone(self: &Self) -> Duration

impl Copy for Duration

impl Debug for Duration

fn fmt(self: &Self, f: &mut fmt::Formatter<'_>) -> fmt::Result

impl Default for Duration

fn default() -> Duration

impl Div for Duration

fn div(self: Self, rhs: u32) -> Duration

impl DivAssign for Duration

fn div_assign(self: &mut Self, rhs: u32)

impl Eq for Duration

impl Freeze for Duration

impl Hash for Duration

fn hash<__H: $crate::hash::Hasher>(self: &Self, state: &mut __H)

impl Mul for Duration

fn mul(self: Self, rhs: u32) -> Duration

impl MulAssign for Duration

fn mul_assign(self: &mut Self, rhs: u32)

impl Ord for Duration

fn cmp(self: &Self, other: &Duration) -> $crate::cmp::Ordering

impl PartialEq for Duration

fn eq(self: &Self, other: &Duration) -> bool

impl PartialOrd for Duration

fn partial_cmp(self: &Self, other: &Duration) -> $crate::option::Option<$crate::cmp::Ordering>

impl RefUnwindSafe for Duration

impl Send for Duration

impl StructuralPartialEq for Duration

impl Sub for Duration

fn sub(self: Self, rhs: Duration) -> Duration

impl SubAssign for Duration

fn sub_assign(self: &mut Self, rhs: Duration)

impl Sum for Duration

fn sum<I: Iterator<Item = Duration>>(iter: I) -> Duration

impl Sync for Duration

impl Unpin for Duration

impl UnwindSafe for Duration

impl<'a> Sum for Duration

fn sum<I: Iterator<Item = &'a Duration>>(iter: I) -> Duration

impl<T> Any for Duration

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Duration

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Duration

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for Duration

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Duration

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Duration

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Duration

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Duration

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>