Duration in std::time - Rust (original) (raw)

logo

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.

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

Run

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.

#![feature(duration_constants)]
use std::time::Duration;

assert_eq!(Duration::SECOND, Duration::from_secs(1));

Run

🔬 This is a nightly-only experimental API. (duration_constants #57391)

The duration of one millisecond.

#![feature(duration_constants)]
use std::time::Duration;

assert_eq!(Duration::MILLISECOND, Duration::from_millis(1));

Run

🔬 This is a nightly-only experimental API. (duration_constants #57391)

The duration of one microsecond.

#![feature(duration_constants)]
use std::time::Duration;

assert_eq!(Duration::MICROSECOND, Duration::from_micros(1));

Run

🔬 This is a nightly-only experimental API. (duration_constants #57391)

The duration of one nanosecond.

#![feature(duration_constants)]
use std::time::Duration;

assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1));

Run

A duration of zero time.

use std::time::Duration;

let duration = Duration::ZERO;
assert!(duration.is_zero());
assert_eq!(duration.as_nanos(), 0);

Run

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.

use std::time::Duration;

assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1));

Run

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.

This constructor will panic if the carry from the nanoseconds overflows the seconds counter.

use std::time::Duration;

let five_seconds = Duration::new(5, 0);

Run

1.3.0 (const: 1.32.0) · source

Creates a new Duration from the specified number of whole seconds.

use std::time::Duration;

let duration = Duration::from_secs(5);

assert_eq!(5, duration.as_secs());
assert_eq!(0, duration.subsec_nanos());

Run

1.3.0 (const: 1.32.0) · source

Creates a new Duration from the specified number of milliseconds.

use std::time::Duration;

let duration = Duration::from_millis(2569);

assert_eq!(2, duration.as_secs());
assert_eq!(569_000_000, duration.subsec_nanos());

Run

1.27.0 (const: 1.32.0) · source

Creates a new Duration from the specified number of microseconds.

use std::time::Duration;

let duration = Duration::from_micros(1_000_002);

assert_eq!(1, duration.as_secs());
assert_eq!(2000, duration.subsec_nanos());

Run

1.27.0 (const: 1.32.0) · source

Creates a new Duration from the specified number of nanoseconds.

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

Run

1.53.0 (const: 1.53.0) · source

Returns true if this Duration spans no time.

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

Run

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.

use std::time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_secs(), 5);

Run

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

Run

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

use std::time::Duration;

let duration = Duration::from_millis(5432);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_millis(), 432);

Run

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

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

Run

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

use std::time::Duration;

let duration = Duration::from_millis(5010);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_nanos(), 10_000_000);

Run

1.33.0 (const: 1.33.0) · source

Returns the total number of whole milliseconds contained by this Duration.

use std::time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_millis(), 5730);

Run

1.33.0 (const: 1.33.0) · source

Returns the total number of whole microseconds contained by this Duration.

use std::time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_micros(), 5730023);

Run

1.33.0 (const: 1.33.0) · source

Returns the total number of nanoseconds contained by this Duration.

use std::time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_nanos(), 5730023852);

Run

1.16.0 (const: 1.58.0) · source

Checked Duration addition. Computes self + other, returning Noneif overflow occurred.

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

Run

1.53.0 (const: 1.58.0) · source

Saturating Duration addition. Computes self + other, returning Duration::MAXif overflow occurred.

#![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);

Run

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.

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

Run

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.

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

Run

1.16.0 (const: 1.58.0) · source

Checked Duration multiplication. Computes self * other, returningNone if overflow occurred.

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

Run

1.53.0 (const: 1.58.0) · source

Saturating Duration multiplication. Computes self * other, returningDuration::MAX if overflow occurred.

#![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);

Run

1.16.0 (const: 1.58.0) · source

Checked Duration division. Computes self / other, returning Noneif other == 0.

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

Run

Returns the number of seconds contained by this Duration as f64.

The returned value does include the fractional (nanosecond) part of the duration.

use std::time::Duration;

let dur = Duration::new(2, 700_000_000);
assert_eq!(dur.as_secs_f64(), 2.7);

Run

Returns the number of seconds contained by this Duration as f32.

The returned value does include the fractional (nanosecond) part of the duration.

use std::time::Duration;

let dur = Duration::new(2, 700_000_000);
assert_eq!(dur.as_secs_f32(), 2.7);

Run

Creates a new Duration from the specified number of seconds represented as f64.

This constructor will panic if secs is not finite, negative or overflows Duration.

use std::time::Duration;

let dur = Duration::from_secs_f64(2.7);
assert_eq!(dur, Duration::new(2, 700_000_000));

Run

🔬 This is a nightly-only experimental API. (duration_checked_float #83400)

The checked version of from_secs_f64.

This constructor will return an Err if secs is not finite, negative or overflows Duration.

#![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());

Run

Creates a new Duration from the specified number of seconds represented as f32.

This constructor will panic if secs is not finite, negative or overflows Duration.

use std::time::Duration;

let dur = Duration::from_secs_f32(2.7);
assert_eq!(dur, Duration::new(2, 700_000_000));

Run

🔬 This is a nightly-only experimental API. (duration_checked_float #83400)

The checked version of from_secs_f32.

This constructor will return an Err if secs is not finite, negative or overflows Duration.

#![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());

Run

Multiplies Duration by f64.

This method will panic if result is not finite, negative or overflows Duration.

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

Run

Multiplies Duration by f32.

This method will panic if result is not finite, negative or overflows Duration.

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

Run

Divide Duration by f64.

This method will panic if result is not finite, negative or overflows Duration.

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

Run

Divide Duration by f32.

This method will panic if result is not finite, negative or overflows Duration.

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

Run

🔬 This is a nightly-only experimental API. (div_duration #63139)

Divide Duration by Duration and return f64.

#![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);

Run

🔬 This is a nightly-only experimental API. (div_duration #63139)

Divide Duration by Duration and return f32.

#![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);

Run

The resulting type after applying the + operator.

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.

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.

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

The resulting type after applying the / operator.

The resulting type after applying the * operator.

The resulting type after applying the * operator.

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

This method 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.

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

Method which takes an iterator and generates Self from the elements by “summing up” the items. Read more

impl Any for T where

T: 'static + ?Sized,

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

impl From for T

impl<T, U> Into for T where

U: From,

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into #41263)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.