std::time::Duration - Rust
Description: API documentation for the Rust `Duration` struct in crate `std`.
Keywords: rust, rustlang, rust-lang, Duration

# 1.3.0[−][src]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.

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

## Methods

###

`impl Duration`

[src]

####

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

[src]

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

####

`pub const fn from_secs(secs: u64) -> Duration`

[src]

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

####

`pub const fn from_millis(millis: u64) -> Duration`

[src]

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

####

`pub const fn from_micros(micros: u64) -> Duration`

1.27.0
[src]

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

####

`pub const fn from_nanos(nanos: u64) -> Duration`

1.27.0
[src]

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

####

`pub const fn as_secs(&self) -> u64`

[src]

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

####

`pub const fn subsec_millis(&self) -> u32`

1.27.0
[src]

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

####

`pub const fn subsec_micros(&self) -> u32`

1.27.0
[src]

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

####

`pub const fn subsec_nanos(&self) -> u32`

[src]

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

####

`pub const fn as_millis(&self) -> u128`

[src]

🔬 This is a nightly-only experimental API. (`duration_as_u128` #50202)

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

####

`pub const fn as_micros(&self) -> u128`

[src]

🔬 This is a nightly-only experimental API. (`duration_as_u128` #50202)

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

####

`pub const fn as_nanos(&self) -> u128`

[src]

🔬 This is a nightly-only experimental API. (`duration_as_u128` #50202)

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

####

`pub fn checked_add(self, rhs: Duration) -> Option<Duration>`

1.16.0
[src]

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(std::u64::MAX, 0)), None);Run

####

`pub fn checked_sub(self, rhs: Duration) -> Option<Duration>`

1.16.0
[src]

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

####

`pub fn checked_mul(self, rhs: u32) -> Option<Duration>`

1.16.0
[src]

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(std::u64::MAX - 1, 0).checked_mul(2), None);Run

####

`pub fn checked_div(self, rhs: u32) -> Option<Duration>`

1.16.0
[src]

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

####

`pub const fn as_float_secs(&self) -> f64`

[src]

🔬 This is a nightly-only experimental API. (`duration_float` #54361)

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

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

# Examples

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

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

####

`pub fn from_float_secs(secs: f64) -> Duration`

[src]

🔬 This is a nightly-only experimental API. (`duration_float` #54361)

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

# Panics

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

# Examples

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

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

####

`pub fn mul_f64(self, rhs: f64) -> Duration`

[src]

🔬 This is a nightly-only experimental API. (`duration_float` #54361)

Multiply `Duration` by `f64`.

# Panics

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

# Examples

    #![feature(duration_float)]
    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

####

`pub fn div_f64(self, rhs: f64) -> Duration`

[src]

🔬 This is a nightly-only experimental API. (`duration_float` #54361)

Divide `Duration` by `f64`.

# Panics

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

# Examples

    #![feature(duration_float)]
    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

####

`pub fn div_duration(self, rhs: Duration) -> f64`

[src]

🔬 This is a nightly-only experimental API. (`duration_float` #54361)

Divide `Duration` by `Duration` and return `f64`.

# Examples

    #![feature(duration_float)]
    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(dur2), 0.5);Run

## Trait Implementations

###

`impl Copy for Duration`

[src]

###

`impl MulAssign<u32> for Duration`

1.9.0
[src]

####

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

[src]

Performs the `*=` operation.

###

`impl Sub<Duration> for Duration`

[src]

#### `type Output = Duration`

The resulting type after applying the `-` operator.

####

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

[src]

Performs the `-` operation.

###

`impl Hash for Duration`

[src]

####

`fn hash<__H>(&self, state: &mut __H) where __H: Hasher,`

[src]

Feeds this value into the given [`Hasher`]. Read more

####

`fn hash_slice<H>(data: &[Self], state: &mut H) where H: Hasher,`

[src]

Feeds a slice of this type into the given [`Hasher`]. Read more

###

`impl<'a> Sum<&'a Duration> for Duration`

1.16.0
[src]

####

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

[src]

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

###

`impl Sum<Duration> for Duration`

1.16.0
[src]

####

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

[src]

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

###

`impl SubAssign<Duration> for Duration`

1.9.0
[src]

####

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

[src]

Performs the `-=` operation.

###

`impl Eq for Duration`

[src]

###

`impl Div<u32> for Duration`

[src]

#### `type Output = Duration`

The resulting type after applying the `/` operator.

####

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

[src]

Performs the `/` operation.

###

`impl Clone for Duration`

[src]

####

`fn clone(&self) -> Duration`

[src]

Returns a copy of the value. Read more

####

`fn clone_from(&mut self, source: &Self)`

1.0.0
[src]

Performs copy-assignment from `source`. Read more

###

`impl Debug for Duration`

1.27.0
[src]

####

`fn fmt(&self, f: &mut Formatter) -> Result<(), Error>`

[src]

Formats the value using the given formatter. Read more

###

`impl Default for Duration`

[src]

####

`fn default() -> Duration`

[src]

Returns the "default value" for a type. Read more

###

`impl AddAssign<Duration> for Duration`

1.9.0
[src]

####

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

[src]

Performs the `+=` operation.

###

`impl DivAssign<u32> for Duration`

1.9.0
[src]

####

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

[src]

Performs the `/=` operation.

###

`impl PartialEq<Duration> for Duration`

[src]

####

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

[src]

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

####

`fn ne(&self, other: &Duration) -> bool`

[src]

This method tests for `!=`.

###

`impl Add<Duration> for Duration`

[src]

#### `type Output = Duration`

The resulting type after applying the `+` operator.

####

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

[src]

Performs the `+` operation.

###

`impl Ord for Duration`

[src]

####

`fn cmp(&self, other: &Duration) -> Ordering`

[src]

This method returns an `Ordering` between `self` and `other`. Read more

####

`fn max(self, other: Self) -> Self`

1.21.0
[src]

Compares and returns the maximum of two values. Read more

####

`fn min(self, other: Self) -> Self`

1.21.0
[src]

Compares and returns the minimum of two values. Read more

###

`impl PartialOrd<Duration> for Duration`

[src]

####

`fn partial_cmp(&self, other: &Duration) -> Option<Ordering>`

[src]

This method returns an ordering between `self` and `other` values if one exists. Read more

####

`fn lt(&self, other: &Duration) -> bool`

[src]

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more

####

`fn le(&self, other: &Duration) -> bool`

[src]

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more

####

`fn gt(&self, other: &Duration) -> bool`

[src]

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more

####

`fn ge(&self, other: &Duration) -> bool`

[src]

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more

###

`impl Mul<u32> for Duration`

[src]

#### `type Output = Duration`

The resulting type after applying the `*` operator.

####

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

[src]

Performs the `*` operation.

###

`impl Mul<Duration> for u32`

1.31.0
[src]

#### `type Output = Duration`

The resulting type after applying the `*` operator.

####

`fn mul(self, rhs: Duration) -> Duration`

[src]

Performs the `*` operation.

###

`impl Sub<Duration> for Instant`

1.8.0
[src]

#### `type Output = Instant`

The resulting type after applying the `-` operator.

####

`fn sub(self, other: Duration) -> Instant`

[src]

Performs the `-` operation.

###

`impl Sub<Duration> for SystemTime`

1.8.0
[src]

#### `type Output = SystemTime`

The resulting type after applying the `-` operator.

####

`fn sub(self, dur: Duration) -> SystemTime`

[src]

Performs the `-` operation.

###

`impl Add<Duration> for Instant`

1.8.0
[src]

#### `type Output = Instant`

The resulting type after applying the `+` operator.

####

`fn add(self, other: Duration) -> Instant`

[src]

Performs the `+` operation.

###

`impl Add<Duration> for SystemTime`

1.8.0
[src]

#### `type Output = SystemTime`

The resulting type after applying the `+` operator.

####

`fn add(self, dur: Duration) -> SystemTime`

[src]

Performs the `+` operation.

###

`impl AddAssign<Duration> for Instant`

1.9.0
[src]

####

`fn add_assign(&mut self, other: Duration)`

[src]

Performs the `+=` operation.

###

`impl AddAssign<Duration> for SystemTime`

1.9.0
[src]

####

`fn add_assign(&mut self, other: Duration)`

[src]

Performs the `+=` operation.

###

`impl SubAssign<Duration> for Instant`

1.9.0
[src]

####

`fn sub_assign(&mut self, other: Duration)`

[src]

Performs the `-=` operation.

###

`impl SubAssign<Duration> for SystemTime`

1.9.0
[src]

####

`fn sub_assign(&mut self, other: Duration)`

[src]

Performs the `-=` operation.

## Auto Trait Implementations

###

`impl Send for Duration`

###

`impl Sync for Duration`

## Blanket Implementations

###

`impl<T> From for T`

[src]

####

`fn from(t: T) -> T`

[src]

Performs the conversion.

###

`impl<T, U> TryFrom for T where T: From<U>,`

[src]

#### `type Error = !`

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

####

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

[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

###

`impl<T, U> TryInto for T where U: TryFrom<T>,`

[src]

#### `type Error = <U as TryFrom<T>>::Error`

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

####

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

[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

###

`impl<T, U> Into for T where U: From<T>,`

[src]

####

`fn into(self) -> U`

[src]

Performs the conversion.

###

`impl<T> Borrow for T where T: ?Sized,`

[src]

####
ⓘImportant traits for &'_ mut I

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`fn borrow(&self) -> &T`

[src]

Immutably borrows from an owned value. Read more

###

`impl<T> BorrowMut for T where T: ?Sized,`

[src]

####
ⓘImportant traits for &'_ mut I

### Important traits for &'_ mut I

`impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`fn borrow_mut(&mut self) -> &mut T`

[src]

Mutably borrows from an owned value. Read more

###

`impl<T> Any for T where T: 'static + ?Sized,`

[src]

####

`fn get_type_id(&self) -> TypeId`

[src]

🔬 This is a nightly-only experimental API. (`get_type_id` #27745)

this method will likely be replaced by an associated static

Gets the `TypeId` of `self`. Read more

###

`impl<T> ToOwned for T where T: Clone,`

[src]

#### `type Owned = T`

####

`fn to_owned(&self) -> T`

[src]

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

####

`fn clone_into(&self, target: &mut T)`

[src]

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

recently added

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g. `str,u8` or `String,struct:Vec,test`)