Struct std::time::Duration
pub struct Duration { /* fields omitted */ }
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.
Duration
s 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);
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. 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
impl Duration
pub const SECOND: Duration
The duration of one second.
Examples
#![feature(duration_constants)] use std::time::Duration; assert_eq!(Duration::SECOND, Duration::from_secs(1));
pub const MILLISECOND: Duration
The duration of one millisecond.
Examples
#![feature(duration_constants)] use std::time::Duration; assert_eq!(Duration::MILLISECOND, Duration::from_millis(1));
pub const MICROSECOND: Duration
The duration of one microsecond.
Examples
#![feature(duration_constants)] use std::time::Duration; assert_eq!(Duration::MICROSECOND, Duration::from_micros(1));
pub const NANOSECOND: Duration
The duration of one nanosecond.
Examples
#![feature(duration_constants)] use std::time::Duration; assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1));
pub const ZERO: Duration
A duration of zero time.
Examples
use std::time::Duration; let duration = Duration::ZERO; assert!(duration.is_zero()); assert_eq!(duration.as_nanos(), 0);
pub const MAX: Duration
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));
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);
pub 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());
pub 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(2569); assert_eq!(2, duration.as_secs()); assert_eq!(569_000_000, duration.subsec_nanos());
pub 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!(2000, duration.subsec_nanos());
pub const fn from_nanos(nanos: u64) -> Duration
Creates a new Duration
from the specified number of nanoseconds.
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());
pub const 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());
pub const 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, 730023852); assert_eq!(duration.as_secs(), 5);
To 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);
pub const 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(5432); assert_eq!(duration.as_secs(), 5); assert_eq!(duration.subsec_millis(), 432);
pub const 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);
pub const 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(5010); assert_eq!(duration.as_secs(), 5); assert_eq!(duration.subsec_nanos(), 10_000_000);
pub const 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, 730023852); assert_eq!(duration.as_millis(), 5730);
pub const 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, 730023852); assert_eq!(duration.as_micros(), 5730023);
pub const 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, 730023852); assert_eq!(duration.as_nanos(), 5730023852);
Checked 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);
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);
Checked 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);
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);
Checked Duration
multiplication. Computes self * other
, returning None
if overflow occurred.
Examples
Basic usage:
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);
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);
Checked 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);
Returns the number of seconds contained by this Duration
as f64
.
The returned value does include 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);
Returns the number of seconds contained by this Duration
as f32
.
The returned value does include 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);
Creates a new Duration
from the specified number of seconds represented as f64
.
Panics
This constructor will panic if secs
is not finite, negative or overflows Duration
.
Examples
use std::time::Duration; let dur = Duration::from_secs_f64(2.7); assert_eq!(dur, Duration::new(2, 700_000_000));
pub const fn try_from_secs_f64(secs: f64) -> Result<Duration, FromSecsError>
The 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());
Creates a new Duration
from the specified number of seconds represented as f32
.
Panics
This constructor will panic if secs
is not finite, negative or overflows Duration
.
Examples
use std::time::Duration; let dur = Duration::from_secs_f32(2.7); assert_eq!(dur, Duration::new(2, 700_000_000));
pub const fn try_from_secs_f32(secs: f32) -> Result<Duration, FromSecsError>
The 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());
Multiplies 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));
Multiplies 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));
Divide 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));
Divide 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));
pub fn div_duration_f64(self, rhs: Duration) -> f64
Divide Duration
by Duration
and return f64
.
Examples
#![feature(div_duration)] 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);
pub fn div_duration_f32(self, rhs: Duration) -> f32
Divide Duration
by Duration
and return f32
.
Examples
#![feature(div_duration)] 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);
Trait Implementations
impl Add<Duration> for Duration
type Output = Duration
The resulting type after applying the +
operator.
pub fn add(self, rhs: Duration) -> Duration
Performs the +
operation. Read more
impl Add<Duration> for Instant
fn add(self, other: Duration) -> Instant
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.
type Output = Instant
The resulting type after applying the +
operator.
impl Add<Duration> for SystemTime
fn add(self, dur: Duration) -> SystemTime
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.
type Output = SystemTime
The resulting type after applying the +
operator.
impl AddAssign<Duration> for Duration
impl AddAssign<Duration> for Instant
impl AddAssign<Duration> for SystemTime
impl Clone for Duration
pub fn clone(&self) -> Duration
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Debug for Duration
pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>
Formats the value using the given formatter. Read more
impl Default for Duration
impl Div<u32> for Duration
type Output = Duration
The resulting type after applying the /
operator.
pub fn div(self, rhs: u32) -> Duration
Performs the /
operation. Read more
impl DivAssign<u32> for Duration
impl Hash for Duration
impl Mul<Duration> for u32
type Output = Duration
The resulting type after applying the *
operator.
pub fn mul(self, rhs: Duration) -> Duration
Performs the *
operation. Read more
impl Mul<u32> for Duration
type Output = Duration
The resulting type after applying the *
operator.
pub fn mul(self, rhs: u32) -> Duration
Performs the *
operation. Read more
impl MulAssign<u32> for Duration
impl Ord for Duration
pub fn cmp(&self, other: &Duration) -> Ordering
fn max(self, other: Self) -> Self
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
Compares and returns the minimum of two values. Read more
fn clamp(self, min: Self, max: Self) -> Self
Restrict a value to a certain interval. Read more
impl PartialEq<Duration> for Duration
pub fn eq(&self, other: &Duration) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
pub fn ne(&self, other: &Duration) -> bool
This method tests for !=
.
impl PartialOrd<Duration> for Duration
pub fn partial_cmp(&self, other: &Duration) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
This method tests greater than or equal to (for self
and other
) and is used by the >=
operator. Read more
impl Sub<Duration> for Duration
type Output = Duration
The resulting type after applying the -
operator.
pub fn sub(self, rhs: Duration) -> Duration
Performs the -
operation. Read more
impl Sub<Duration> for Instant
type Output = Instant
The resulting type after applying the -
operator.
fn sub(self, other: Duration) -> Instant
Performs the -
operation. Read more
impl Sub<Duration> for SystemTime
type Output = SystemTime
The resulting type after applying the -
operator.
fn sub(self, dur: Duration) -> SystemTime
Performs the -
operation. Read more
impl SubAssign<Duration> for Duration
impl SubAssign<Duration> for Instant
impl SubAssign<Duration> for SystemTime
impl<'a> Sum<&'a Duration> for Duration
Method which takes an iterator and generates Self
from the elements by “summing up” the items. Read more
impl Sum<Duration> for Duration
Method which takes an iterator and generates Self
from the elements by “summing up” the items. Read more
impl Copy for Duration
impl Eq for Duration
impl StructuralEq for Duration
impl StructuralPartialEq for Duration
Auto Trait Implementations
impl RefUnwindSafe for Duration
impl Send for Duration
impl Sync for Duration
impl Unpin for Duration
impl UnwindSafe for Duration
Blanket Implementations
impl<T> From<T> for T
pub fn from(t: T) -> T
Performs the conversion.
pub fn into(self) -> U
Performs the conversion.
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
pub fn clone_into(&self, target: &mut T)
toowned_clone_into
#41263)recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/time/struct.Duration.html