Struct TimeDelta

pub struct TimeDelta { /* private fields */ }

A signed duration of time, stored as an (i64, i32) pair of seconds and nanoseconds.

Supports negative values, allowing representation of both past and future offsets.

Vendored

This is adapted work from jiff.

Implementations

impl TimeDelta

Basic methods

pub const ZERO: TimeDelta

A duration of zero time.

pub const MIN: TimeDelta

The minimum possible duration. Or the “most negative” duration.

pub const MAX: TimeDelta

The maximum possible duration.

pub const fn new(secs: i64, nanos: i32) -> TimeDelta

Creates a new TimeDelta from the given number of whole seconds and additional nanoseconds.

If the absolute value of the nanoseconds is greater than or equal to 1 second, then the excess balances into the number of whole seconds.

Panics

When the absolute value of the nanoseconds is greater than or equal to 1 second and the excess that carries over to the number of whole seconds overflows i64.

This never panics when nanos is less than 1_000_000_000.

pub const fn from_secs(secs: i64) -> TimeDelta

Creates a new TimeDelta from the given number of whole seconds.

pub const fn from_millis(millis: i64) -> TimeDelta

Creates a new TimeDelta from the given number of whole milliseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, TimeDelta::as_millis returns an i128, and this may be a value that would otherwise overflow an i64.

pub const fn from_micros(micros: i64) -> TimeDelta

Creates a new TimeDelta from the given number of whole microseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, TimeDelta::as_micros returns an i128, and this may be a value that would otherwise overflow an i64.

pub const fn from_nanos(nanos: i64) -> TimeDelta

Creates a new TimeDelta from the given number of whole nanoseconds.

Note that since this accepts an i64, this method cannot be used to construct the full range of possible signed duration values. In particular, TimeDelta::as_nanos returns an i128, which may be a value that would otherwise overflow an i64.

pub const fn from_hours(hours: i64) -> TimeDelta

Creates a new TimeDelta from the given number of hours. Every hour is exactly 3,600 seconds.

Panics

Panics if the number of hours, after being converted to nanoseconds, overflows the minimum or maximum TimeDelta values.

pub const fn from_mins(minutes: i64) -> TimeDelta

Creates a new TimeDelta from the given number of minutes. Every minute is exactly 60 seconds.

Panics

Panics if the number of minutes, after being converted to nanoseconds, overflows the minimum or maximum TimeDelta values.

pub const fn is_zero(&self) -> bool

Returns true if this duration spans no time.

pub const fn as_secs(&self) -> i64

Returns the number of whole seconds in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than a second. To access those, use one of the subsec methods such as TimeDelta::subsec_nanos.

pub const fn subsec_millis(&self) -> i32

Returns the fractional part of this duration in whole milliseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999..=999.

To get the length of the total duration represented in milliseconds, use TimeDelta::as_millis.

pub const fn subsec_micros(&self) -> i32

Returns the fractional part of this duration in whole microseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999_999..=999_999.

To get the length of the total duration represented in microseconds, use TimeDelta::as_micros.

pub const fn subsec_nanos(&self) -> i32

Returns the fractional part of this duration in whole nanoseconds.

The value returned is negative when the duration is negative. It is guaranteed that the range of the value returned is in the inclusive range -999_999_999..=999_999_999.

To get the length of the total duration represented in nanoseconds, use TimeDelta::as_nanos.

pub const fn as_millis(&self) -> i128

Returns the total duration in units of whole milliseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole milliseconds, use TimeDelta::subsec_millis.

pub const fn as_micros(&self) -> i128

Returns the total duration in units of whole microseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole microseconds, use TimeDelta::subsec_micros.

pub const fn as_nanos(&self) -> i128

Returns the total duration in units of whole nanoseconds.

The value returned is negative when the duration is negative.

To get only the fractional component of this duration in units of whole nanoseconds, use TimeDelta::subsec_nanos.

impl TimeDelta

Operations.

pub const fn checked_add(self, rhs: TimeDelta) -> Option<TimeDelta>

Add two signed durations together. If overflow occurs, then None is returned.

pub const fn saturating_add(self, rhs: TimeDelta) -> TimeDelta

Add two signed durations together. If overflow occurs, then arithmetic saturates.

pub const fn checked_sub(self, rhs: TimeDelta) -> Option<TimeDelta>

Subtract one signed duration from another. If overflow occurs, then None is returned.

pub const fn saturating_sub(self, rhs: TimeDelta) -> TimeDelta

Add two signed durations together. If overflow occurs, then arithmetic saturates.

impl TimeDelta

Operations involving integers.

pub const fn checked_mul(self, rhs: i32) -> Option<TimeDelta>

Multiply this signed duration by an integer. If the multiplication overflows, then None is returned.

pub const fn saturating_mul(self, rhs: i32) -> TimeDelta

Multiply this signed duration by an integer.

If the multiplication overflows, then the result saturates to either the minimum or maximum duration depending on the sign of the product.

pub const fn checked_div(self, rhs: i32) -> Option<TimeDelta>

Divide this duration by an integer. If the division overflows, then None is returned.

impl TimeDelta

Operations involving floating-point numbers.

pub fn as_secs_f64(&self) -> f64

Returns the number of seconds, with a possible fractional nanosecond component.

pub fn as_secs_f32(&self) -> f32

Returns the number of seconds, with a possible fractional nanosecond component.

pub fn as_millis_f64(&self) -> f64

Returns the number of milliseconds, with a possible fractional nanosecond component.

pub fn as_millis_f32(&self) -> f32

Returns the number of milliseconds, with a possible fractional nanosecond component.

pub fn from_secs_f64(secs: f64) -> TimeDelta

Available on crate features std or _float_f64 only.

Returns a signed duration corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

Panics

Panics if the given float overflows the minimum or maximum signed duration values.

pub fn from_secs_f32(secs: f32) -> TimeDelta

Available on crate features std or _float_f32 only.

Returns a signed duration corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

Panics

Panics if the given float overflows the minimum or maximum signed duration values.

pub fn try_from_secs_f64(secs: f64) -> Result<TimeDelta, &'static str>

Available on crate features std or _float_f64 only.

Returns a signed duration corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

If the given float overflows the minimum or maximum signed duration values, then an error is returned.

pub fn try_from_secs_f32(secs: f32) -> Result<TimeDelta, &'static str>

Available on crate features std or _float_f32 only.

Returns a signed duration corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

If the given float overflows the minimum or maximum signed duration values, then an error is returned.

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

Available on crate features std or _float_f64 only.

Returns the result of multiplying this duration by the given 64-bit float.

Panics

This panics if the result is not finite or overflows a TimeDelta.

pub fn mul_f32(self, rhs: f32) -> TimeDelta

Available on crate features std or _float_f32 only.

Returns the result of multiplying this duration by the given 32-bit float.

Panics

This panics if the result is not finite or overflows a TimeDelta.

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

Available on crate features std or _float_f64 only.

Returns the result of dividing this duration by the given f64.

Panics

This panics if the result is not finite or overflows a TimeDelta.

pub fn div_f32(self, rhs: f32) -> TimeDelta

Available on crate features std or _float_f32 only.

Returns the result of dividing this duration by the given f32.

Panics

This panics if the result is not finite or overflows a TimeDelta.

pub fn div_duration_f64(self, rhs: TimeDelta) -> f64

Divides this signed duration by another signed duration.

pub fn div_duration_f32(self, rhs: TimeDelta) -> f32

Divides this signed duration by another signed duration.

impl TimeDelta

Additional methods not found in the standard library.

In most cases, these APIs exist as a result of the fact that this duration is signed.

pub const fn as_hours(&self) -> i64

Returns the number of whole hours in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than an hour.

pub const fn as_mins(&self) -> i64

Returns the number of whole minutes in this duration.

The value returned is negative when the duration is negative.

This does not include any fractional component corresponding to units less than a minute.

pub const fn abs(self) -> TimeDelta

Returns the absolute value of this signed duration.

If this duration is positive, then this returns the original duration unchanged.

Panics

This panics when the seconds component of this signed duration is equal to i64::MIN.

pub const fn abs_duration(self) -> Duration

Returns the absolute value of this signed duration as a Duration.

This method cannot panic because the absolute value of TimeDelta::MIN is always representable in a Duration.

pub const fn neg_abs(self) -> TimeDelta

Returns the negative absolute value of this signed duration.

If this duration is negative, then this returns the original duration unchanged.

Panics

This panics when the seconds component of this signed duration is equal to i64::MIN.

pub const fn checked_neg(self) -> Option<TimeDelta>

Returns this duration with its sign flipped.

If this duration is zero, then this returns the duration unchanged.

This returns none if the negation does not exist. This occurs in precisely the cases when TimeDelta::as_secs is equal to i64::MIN.

pub const fn signum(self) -> i8

Returns a number that represents the sign of this duration.

• When TimeDelta::is_zero is true, this returns 0.
• When TimeDelta::is_positive is true, this returns 1.
• When TimeDelta::is_negative is true, this returns -1.

The above cases are mutually exclusive.

pub const fn is_positive(&self) -> bool

Returns true when this duration is positive. That is, greater than TimeDelta::ZERO.

pub const fn is_negative(&self) -> bool

Returns true when this duration is negative. That is, less than TimeDelta::ZERO.

impl TimeDelta

Additional APIs involving SystemInstant.

pub fn after(&self, _instant: SystemInstant) -> SystemInstant

Adds a TimeDelta to an instant, moving forward or backward in time.

Trait Implementations

impl Add for TimeDelta

type Output = TimeDelta

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for TimeDelta

fn add_assign(&mut self, rhs: TimeDelta)

Performs the += operation.

impl Clone for TimeDelta

fn clone(&self) -> TimeDelta

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for TimeDelta

fn default() -> TimeDelta

Returns the “default value” for a type.

impl Div<i32> for TimeDelta

type Output = TimeDelta

The resulting type after applying the / operator.

fn div(self, rhs: i32) -> TimeDelta

Performs the / operation.

impl DivAssign<i32> for TimeDelta

fn div_assign(&mut self, rhs: i32)

Performs the /= operation.

impl From<SignedDuration> for TimeDelta

fn from(from: SignedDuration) -> TimeDelta

Converts to this type from the input type.

impl From<TimeDelta> for SignedDuration

fn from(from: TimeDelta) -> SignedDuration

Converts to this type from the input type.

impl Hash for TimeDelta

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

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 Mul<TimeDelta> for i32

type Output = TimeDelta

The resulting type after applying the * operator.

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

Performs the * operation.

impl Mul<i32> for TimeDelta

type Output = TimeDelta

The resulting type after applying the * operator.

fn mul(self, rhs: i32) -> TimeDelta

Performs the * operation.

impl MulAssign<i32> for TimeDelta

fn mul_assign(&mut self, rhs: i32)

Performs the *= operation.

impl Neg for TimeDelta

type Output = TimeDelta

The resulting type after applying the - operator.

fn neg(self) -> TimeDelta

Performs the unary - operation.

impl Ord for TimeDelta

fn cmp(&self, other: &TimeDelta) -> 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 for TimeDelta

fn eq(&self, other: &TimeDelta) -> 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 TimeDelta

fn partial_cmp(&self, other: &TimeDelta) -> 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 Sub for TimeDelta

type Output = TimeDelta

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for TimeDelta

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl TryFrom<Duration> for TimeDelta

type Error = &'static str

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<TimeDelta> for Duration

type Error = &'static str

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Copy for TimeDelta

impl Eq for TimeDelta

impl StructuralPartialEq for TimeDelta