Struct time::Duration

Overview

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.

Examples

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

Methods

fn new(secs: u64, nanos: u64) -> 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.

Vm Panics

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

Examples

use time::Duration;

let five_seconds = Duration::new(5, 0);
fn from_secs(secs: u64) -> Duration

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

Examples

use time::Duration;

let duration = Duration::from_secs(5);
fn from_millis(millis: u64) -> Duration

Creates a new Duration from the specified number of milliseconds.

Examples

use time::Duration;

let duration = Duration::from_millis(2569);
fn from_micros(micros: u64) -> Duration

Creates a new Duration from the specified number of microseconds.

Examples

use time::Duration;

let duration = Duration::from_micros(1_000_002);
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 time::Duration;

let duration = Duration::from_nanos(1_000_000_123);
fn is_zero(self) -> bool

Returns true if this Duration spans no time.

Examples

use 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());
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 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 including the fractional part, use as_secs_f64 or as_secs_f32

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 time::Duration;

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

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 time::Duration;

let duration = Duration::from_micros(1_234_567);
assert_eq!(duration.as_secs(), 1);
assert_eq!(duration.subsec_micros(), 234_567);

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 time::Duration;

let duration = Duration::from_millis(5010);
assert_eq!(duration.as_secs(), 5);
assert_eq!(duration.subsec_nanos(), 10_000_000);
fn as_millis(self) -> u64

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

Examples

use time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_millis(), 5730);
fn as_micros(self) -> u64

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

Examples

use time::Duration;

let duration = Duration::new(5, 730023852);
assert_eq!(duration.as_micros(), 5730023);
fn as_nanos(self) -> u64

Returns the total number of nanoseconds contained by this Duration.

Examples

use time::Duration;

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

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 time::Duration;

let duration = Duration::from_secs(60).as_secs_f64();
fn from_secs_f64(secs: f64) -> Duration

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

Examples

use time::Duration;

let duration = Duration::from_secs_f64(0.0);

Trait Implementations

impl PartialEq for Duration
fn eq(value: any, value1: any) -> bool

Compare two values for equality.

Examples

assert_eq!(1.eq(2), false);
assert_eq!(2.eq(2), true);
assert_eq!(2.eq(1), false);
fn ne(value: any, value1: any) -> bool

Compare two values for inequality.

Examples

assert_eq!(1.ne(2), true);
assert_eq!(2.ne(2), false);
assert_eq!(2.ne(1), true);
impl Eq for Duration
impl PartialOrd for Duration
fn partial_cmp(value: any, value1: any) -> Option

Compare two values.

Examples

use std::cmp::Ordering;

assert_eq!(1.partial_cmp(2), Some(Ordering::Less));
assert_eq!(2.partial_cmp(2), Some(Ordering::Equal));
assert_eq!(2.partial_cmp(1), Some(Ordering::Greater));
fn lt(value: any, value1: any) -> bool

Tests less than (for self and other) and is used by the < operator.

Examples

assert_eq!(1.0 < 1.0, false);
assert_eq!(1.0 < 2.0, true);
assert_eq!(2.0 < 1.0, false);
fn le(value: any, value1: any) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

Examples

assert_eq!(1.0 <= 1.0, true);
assert_eq!(1.0 <= 2.0, true);
assert_eq!(2.0 <= 1.0, false);
fn gt(value: any, value1: any) -> bool

Tests greater than (for self and other) and is used by the > operator.

Examples

assert_eq!(1.0 > 1.0, false);
assert_eq!(1.0 > 2.0, false);
assert_eq!(2.0 > 1.0, true);
fn ge(value: any, value1: any) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

Examples

assert_eq!(1.0 >= 1.0, true);
assert_eq!(1.0 >= 2.0, false);
assert_eq!(2.0 >= 1.0, true);
impl Ord for Duration
fn cmp(value: any, value1: any) -> Ordering

Compare two values.

Examples

use std::cmp::Ordering;

assert_eq!(1.cmp(2), Ordering::Less);
assert_eq!(2.cmp(2), Ordering::Equal);
assert_eq!(2.cmp(1), Ordering::Greater);
fn min(value: any, value1: any) -> Ordering

Return the minimum of two values.

Examples

assert_eq!(1.min(2), 1);
assert_eq!(2.min(2), 2);
assert_eq!(2.min(1), 1);
fn max(value: any, value1: any) -> Ordering

Return the maximum of two values.

Examples

assert_eq!(1.max(2), 2);
assert_eq!(2.max(2), 2);
assert_eq!(2.max(1), 2);
impl Clone for Duration
fn clone(value: any) -> any

Clone the specified value.

Examples

let a = 42;
let b = a;
let c = a.clone();

a += 1;

assert_eq!(a, 43);
assert_eq!(b, 42);
assert_eq!(c, 42);

Protocols

protocol ADD 
let $out = value + $b

Add a duration to this instant and return a new instant.

Examples

use time::Duration;

let first = Duration::SECOND;
let second = first + Duration::SECOND;

assert!(first < second);
protocol ADD_ASSIGN 
value += $b

Add a duration to this instant and return a new instant.

Examples

use time::Duration;

let first = Duration::SECOND;
let second = first.clone();
second += Duration::SECOND;

assert!(first < second);
protocol PARTIAL_EQ 
if value == b { }

Test two durations for partial equality.

Examples

use std::ops::partial_eq;

use time::Duration;

let millis = Duration::MILLISECOND;
let second = Duration::SECOND;

assert_eq!(partial_eq(millis, millis), true);
assert_eq!(partial_eq(millis, second), false);
assert_eq!(partial_eq(second, millis), false);
protocol EQ 
if value == b { }

Test two durations for total equality.

Examples

use std::ops::eq;

use time::Duration;

let millis = Duration::MILLISECOND;
let second = Duration::SECOND;

assert_eq!(eq(millis, millis), true);
assert_eq!(eq(millis, second), false);
assert_eq!(eq(second, millis), false);
protocol PARTIAL_CMP 
if value < b { }

Perform a partial ordered comparison between two durations.

Examples

use time::Duration;

let millis = Duration::MILLISECOND;
let second = Duration::SECOND;

assert!(millis < second);
assert!(second > millis);
assert!(millis == millis);

Using explicit functions:

use std::cmp::Ordering;
use std::ops::partial_cmp;

use time::Duration;

let millis = Duration::MILLISECOND;
let second = Duration::SECOND;

assert_eq!(partial_cmp(millis, second), Some(Ordering::Less));
assert_eq!(partial_cmp(second, millis), Some(Ordering::Greater));
assert_eq!(partial_cmp(millis, millis), Some(Ordering::Equal));
protocol CMP 
if value < b { }

Perform a totally ordered comparison between two durations.

Examples

use std::cmp::Ordering;
use std::ops::cmp;

use time::Duration;

let millis = Duration::MILLISECOND;
let second = Duration::SECOND;

assert_eq!(cmp(millis, second), Ordering::Less);
assert_eq!(cmp(second, millis), Ordering::Greater);
assert_eq!(cmp(millis, millis), Ordering::Equal);
protocol HASH 
let $out = hash(value)

Hash the duration.

Examples

use std::ops::hash;

use time::Duration;

let second = Duration::SECOND;

assert_eq!(hash(second), hash(second));
protocol DEBUG_FMT 
format!("{:?}", value)

Write a debug representation of the duration.

Examples

use time::Duration;

let second = Duration::SECOND;

println!("{second:?}");
protocol CLONE 
let $out = clone(value)

Clone the current duration.

Examples

use time::Duration;

let first = Duration::SECOND;
let second = Duration::SECOND;
second += Duration::SECOND;

assert!(first < second);
protocol LT 
if $a < $b { }

The protocol behind the < operator.

protocol LE 
if $a <= $b { }

The protocol behind the <= operator.

protocol GT 
if $a > $b { }

The protocol behind the > operator.

protocol GE 
if $a >= $b { }

The protocol behind the >= operator.

protocol MIN 
$a.min($b)

The implementation protocol for the PartialOrd::min method.

protocol MAX 
$a.max($b)

The implementation protocol for the PartialOrd::max method.