Struct Duration

pub struct Duration { /* private fields */ }

Available on crate feature dep_bytemuck only.

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

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

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

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

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

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

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

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

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

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

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

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!(2_000, duration.subsec_nanos());

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

pub const fn from_weeks(weeks: u64) -> Duration

🔬This is a nightly-only experimental API. (duration_constructors)

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

pub const fn from_days(days: u64) -> Duration

🔬This is a nightly-only experimental API. (duration_constructors)

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

pub const fn from_hours(hours: u64) -> Duration

🔬This is a nightly-only experimental API. (duration_constructors)

Creates a new Duration from the specified number of hours.

Panics

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

Examples

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

let duration = Duration::from_hours(6);

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

pub const fn from_mins(mins: u64) -> Duration

🔬This is a nightly-only experimental API. (duration_constructors)

Creates a new Duration from the specified number of minutes.

Panics

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

Examples

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

let duration = Duration::from_mins(10);

assert_eq!(10 * 60, duration.as_secs());
assert_eq!(0, 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, 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

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(5_432);
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(5_010);
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, 730_023_852);
assert_eq!(duration.as_millis(), 5_730);

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, 730_023_852);
assert_eq!(duration.as_micros(), 5_730_023);

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, 730_023_852);
assert_eq!(duration.as_nanos(), 5_730_023_852);

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

pub const fn checked_add(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);

pub const fn saturating_add(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);

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

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

pub const fn checked_mul(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);

pub const fn saturating_mul(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);

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

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

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

pub const fn as_millis_f64(&self) -> f64

🔬This is a nightly-only experimental API. (duration_millis_float)

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

pub const fn as_millis_f32(&self) -> f32

🔬This is a nightly-only experimental API. (duration_millis_float)

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

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

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

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

pub fn mul_f32(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));

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

pub fn div_f32(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));

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

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

impl Duration

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

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

Trait Implementations

impl<'a> Add<Duration> for &'a Zoned

Adds an unsigned duration of time to a zoned datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_add.

type Output = Zoned

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Duration> for Date

Adds an unsigned duration of time to a date.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_add.

type Output = Date

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Duration> for DateTime

Adds an unsigned duration of time to a datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_add.

type Output = DateTime

The resulting type after applying the + operator.

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

Performs the + operation.

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 Offset

Adds an unsigned duration of time to an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

type Output = Offset

The resulting type after applying the + operator.

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

Performs the + operation.

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 Add<Duration> for Time

Adds an unsigned duration of time. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_add.

type Output = Time

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Duration> for Timestamp

Adds an unsigned duration of time to a timestamp.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_add.

type Output = Timestamp

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add for Duration

type Output = Duration

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign<Duration> for Date

Adds an unsigned duration of time to a date in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Duration> for DateTime

Adds an unsigned duration of time to a datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Duration> for Instant

fn add_assign(&mut self, other: Duration)

Performs the += operation.

impl AddAssign<Duration> for Offset

Adds an unsigned duration of time to an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Duration> for SystemTime

fn add_assign(&mut self, other: Duration)

Performs the += operation.

impl AddAssign<Duration> for Time

Adds an unsigned duration of time in place. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Duration> for Timestamp

Adds an unsigned duration of time to a timestamp in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Duration> for Zoned

Adds an unsigned duration of time to a zoned datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_add.

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign for Duration

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl Archive for Duration

type Archived = ArchivedDuration

The archived representation of this type.

type Resolver = ()

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve( &self, _: <Duration as Archive>::Resolver, out: Place<<Duration as Archive>::Archived>, )

Creates the archived version of this value at the given position and writes it to the given output.

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

impl BitSized<128> for Duration

const BIT_SIZE: usize = _

The bit size of this type (only the relevant data part, without padding).

const MIN_BYTE_SIZE: usize = _

The rounded up byte size for this type.

fn bit_size(&self) -> usize

Returns the bit size of this type (only the relevant data part, without padding).

fn min_byte_size(&self) -> usize

Returns the rounded up byte size for this type.

impl Clone for Duration

fn clone(&self) -> Duration

Returns a copy of the value.

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

Performs copy-assignment from source.

impl ConstDefault for Duration

const DEFAULT: Self

Returns the compile-time “default value” for a type.

impl Debug for Duration

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

Formats the value using the given formatter.

impl Default for Duration

fn default() -> Duration

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Duration

fn deserialize<D>( deserializer: D, ) -> Result<Duration, <D as Deserializer<'de>>::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<D> Deserialize<Duration, D> for ArchivedDuration

where D: Fallible + ?Sized,

fn deserialize(&self, _: &mut D) -> Result<Duration, <D as Fallible>::Error>

Deserializes using the given deserializer

impl Div<u32> for Duration

type Output = Duration

The resulting type after applying the / operator.

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

Performs the / operation.

impl DivAssign<u32> for Duration

fn div_assign(&mut self, rhs: u32)

Performs the /= operation.

impl<'a> From<&'a Duration> for DateArithmetic

fn from(udur: &'a Duration) -> DateArithmetic

Converts to this type from the input type.

impl<'a> From<&'a Duration> for DateTimeArithmetic

fn from(udur: &'a Duration) -> DateTimeArithmetic

Converts to this type from the input type.

impl<'a> From<&'a Duration> for OffsetArithmetic

fn from(udur: &'a Duration) -> OffsetArithmetic

Converts to this type from the input type.

impl<'a> From<&'a Duration> for TimeArithmetic

fn from(udur: &'a Duration) -> TimeArithmetic

Converts to this type from the input type.

impl<'a> From<&'a Duration> for TimestampArithmetic

fn from(udur: &'a Duration) -> TimestampArithmetic

Converts to this type from the input type.

impl<'a> From<&'a Duration> for ZonedArithmetic

fn from(udur: &'a Duration) -> ZonedArithmetic

Converts to this type from the input type.

impl From<ArchivedDuration> for Duration

fn from(duration: ArchivedDuration) -> Duration

Converts to this type from the input type.

impl From<Duration> for DateArithmetic

fn from(udur: Duration) -> DateArithmetic

Converts to this type from the input type.

impl From<Duration> for DateTimeArithmetic

fn from(udur: Duration) -> DateTimeArithmetic

Converts to this type from the input type.

impl From<Duration> for LinuxTimespec

Available on crate feature linux only.

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<Duration> for OffsetArithmetic

fn from(udur: Duration) -> OffsetArithmetic

Converts to this type from the input type.

impl From<Duration> for SpanArithmetic<'static>

fn from(duration: Duration) -> SpanArithmetic<'static>

Converts to this type from the input type.

impl From<Duration> for StartTime

fn from(v: Duration) -> StartTime

Converts to this type from the input type.

impl From<Duration> for Time

fn from(duration: Duration) -> Time

Converts to this type from the input type.

impl From<Duration> for TimeArithmetic

fn from(udur: Duration) -> TimeArithmetic

Converts to this type from the input type.

impl From<Duration> for TimestampArithmetic

fn from(udur: Duration) -> TimestampArithmetic

Converts to this type from the input type.

impl From<Duration> for Value<Duration>

fn from(value: Duration) -> Value<Duration>

Converts to this type from the input type.

impl From<Duration> for ZonedArithmetic

fn from(udur: Duration) -> ZonedArithmetic

Converts to this type from the input type.

impl From<Time> for Duration

fn from(time: Time) -> Duration

Converts to this type from the input type.

impl FromPyObject<'_> for Duration

fn extract_bound(obj: &Bound<'_, PyAny>) -> Result<Duration, PyErr>

Extracts Self from the bound smart pointer obj.

impl Hash for Duration

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

where __H: Hasher,

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IntoPy<Py<PyAny>> for Duration

fn into_py(self, py: Python<'_>) -> Py<PyAny>

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Performs the conversion.

impl<'py> IntoPyObject<'py> for &Duration

type Target = PyDelta

The Python output type

type Output = Bound<'py, <&Duration as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<&Duration as IntoPyObject<'py>>::Output, <&Duration as IntoPyObject<'py>>::Error>

Performs the conversion.

impl<'py> IntoPyObject<'py> for Duration

type Target = PyDelta

The Python output type

type Output = Bound<'py, <Duration as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Duration as IntoPyObject<'py>>::Output, <Duration as IntoPyObject<'py>>::Error>

Performs the conversion.

impl Mul<Duration> for u32

type Output = Duration

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<u32> for Duration

type Output = Duration

The resulting type after applying the * operator.

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

Performs the * operation.

impl MulAssign<u32> for Duration

fn mul_assign(&mut self, rhs: u32)

Performs the *= operation.

impl Ord for Duration

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<ArchivedDuration> for Duration

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Duration> for ArchivedDuration

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Duration

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Duration

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

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

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

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

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

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

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

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

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

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

impl<S> Serialize<S> for Duration

where S: Fallible + ?Sized,

fn serialize( &self, _: &mut S, ) -> Result<<Duration as Archive>::Resolver, <S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl Serialize for Duration

fn serialize<S>( &self, serializer: S, ) -> Result<<S as Serializer>::Ok, <S as Serializer>::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'a> Sub<Duration> for &'a Zoned

Subtracts an unsigned duration of time from a zoned datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_sub.

type Output = Zoned

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for Date

Subtracts an unsigned duration of time from a date.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_sub.

type Output = Date

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for DateTime

Subtracts an unsigned duration of time from a datetime.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_sub.

type Output = DateTime

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for Instant

type Output = Instant

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for Offset

Subtracts an unsigned duration of time from an offset. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

type Output = Offset

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for SystemTime

type Output = SystemTime

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for Time

Subtracts an unsigned duration of time. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_sub.

type Output = Time

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Duration> for Timestamp

Subtracts an unsigned duration of time from a timestamp.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_sub.

type Output = Timestamp

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub for Duration

type Output = Duration

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign<Duration> for Date

Subtracts an unsigned duration of time from a date in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Date::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Duration> for DateTime

Subtracts an unsigned duration of time from a datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use DateTime::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Duration> for Instant

fn sub_assign(&mut self, other: Duration)

Performs the -= operation.

impl SubAssign<Duration> for Offset

Subtracts an unsigned duration of time from an offset in place. This panics on overflow.

For checked arithmetic, see Offset::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Duration> for SystemTime

fn sub_assign(&mut self, other: Duration)

Performs the -= operation.

impl SubAssign<Duration> for Time

Subtracts an unsigned duration of time in place. This uses wrapping arithmetic.

For checked arithmetic, see Time::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Duration> for Timestamp

Subtracts an unsigned duration of time from a timestamp in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Timestamp::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Duration> for Zoned

Subtracts an unsigned duration of time from a zoned datetime in place.

This uses checked arithmetic and panics on overflow. To handle overflow without panics, use Zoned::checked_sub.

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign for Duration

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

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

fn sum<I>(iter: I) -> Duration

where I: Iterator<Item = &'a Duration>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl Sum for Duration

fn sum<I>(iter: I) -> Duration

where I: Iterator<Item = Duration>,

Takes an iterator and generates Self from the elements by “summing up” the items.

impl ToPyObject for Duration

fn to_object(&self, py: Python<'_>) -> Py<PyAny>

👎Deprecated since 0.23.0: ToPyObject is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Converts self into a Python object.

impl TryFrom<Duration> for SignedDuration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(d: Duration) -> Result<SignedDuration, Error>

Performs the conversion.

impl TryFrom<Duration> for Span

Converts a std::time::Duration to a Span.

The span returned from this conversion will only ever have non-zero units of seconds or smaller.

Errors

This only fails when the given Duration overflows the maximum number of seconds representable by a Span.

Example

This shows a basic conversion:

use std::time::Duration;

use jiff::{Span, ToSpan};

let duration = Duration::new(86_400, 123_456_789);
let span = Span::try_from(duration)?;
// A duration-to-span conversion always results in a span with
// non-zero units no bigger than seconds.
assert_eq!(
    span,
    86_400.seconds().milliseconds(123).microseconds(456).nanoseconds(789),
);

Example: rounding

This example shows how to convert a Duration to a Span, and then round it up to bigger units given a relative date:

use std::time::Duration;

use jiff::{civil::date, Span, SpanRound, ToSpan, Unit};

let duration = Duration::new(450 * 86_401, 0);
let span = Span::try_from(duration)?;
// We get back a simple span of just seconds:
assert_eq!(span, Span::new().seconds(450 * 86_401));
// But we can balance it up to bigger units:
let options = SpanRound::new()
    .largest(Unit::Year)
    .relative(date(2024, 1, 1));
assert_eq!(
    span.round(options)?,
    1.year().months(2).days(25).minutes(7).seconds(30),
);

type Error = Error

The type returned in the event of a conversion error.

fn try_from(d: Duration) -> Result<Span, Error>

Performs the conversion.

impl TryFrom<SignedDuration> for Duration

type Error = Error

The type returned in the event of a conversion error.

fn try_from(sd: SignedDuration) -> Result<Duration, Error>

Performs the conversion.

impl TryFrom<Span> for Duration

Converts a Span to a std::time::Duration.

Note that this assumes that days are always 24 hours long.

Errors

This can fail for only two reasons:

• The span is negative. This is an error because a std::time::Duration is unsigned.)
• The span has any non-zero units greater than days. This is an error because it’s impossible to determine the length of, e.g., a month without a reference date.

This can never result in overflow because a Duration can represent a bigger span of time than Span when limited to units of days or lower.

If you need to convert a Span to a Duration that has non-zero units bigger than days (or a Span with days of non-uniform length), then please use Span::to_duration with a corresponding relative date.

Example: maximal span

This example shows the maximum possible span using units of days or smaller, and the corresponding Duration value:

use std::time::Duration;

use jiff::Span;

let sp = Span::new()
    .days(7_304_484)
    .hours(175_307_616)
    .minutes(10_518_456_960i64)
    .seconds(631_107_417_600i64)
    .milliseconds(631_107_417_600_000i64)
    .microseconds(631_107_417_600_000_000i64)
    .nanoseconds(9_223_372_036_854_775_807i64);
let duration = Duration::try_from(sp)?;
assert_eq!(duration, Duration::new(3_795_867_877_636, 854_775_807));

Example: converting a negative span

Since a Span is signed and a Duration is unsigned, converting a negative Span to Duration will always fail. One can use Span::signum to get the sign of the span and Span::abs to make the span positive before converting it to a Duration:

use std::time::Duration;

use jiff::{Span, ToSpan};

let span = -86_400.seconds().nanoseconds(1);
let (sign, duration) = (span.signum(), Duration::try_from(span.abs())?);
assert_eq!((sign, duration), (-1, Duration::new(86_400, 1)));

type Error = Error

The type returned in the event of a conversion error.

fn try_from(sp: Span) -> Result<Duration, Error>

Performs the conversion.

impl Tweenable for Duration

fn interpolate(a: Duration, b: Duration, amount: f64) -> Duration

Returns an linearly interpolated value between a and b.

impl Copy for Duration

impl Eq for Duration

impl StructuralPartialEq for Duration