Struct TimeDelta 

pub struct TimeDelta { /* private fields */ }

🕘 A signed duration of time, stored as an (i64, i32) pair of secs and nanos.

---

^{📍 phys/time}

---

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

Vendored

This is adapted work from jiff.

Implementations

impl TimeDelta

Additional APIs involving SystemInstant.

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

Available on crate feature std only.

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

Panics

Panics if the result is outside the valid range of SystemInstant.

pub fn checked_after(&self, instant: SystemInstant) -> Option<SystemInstant>

Available on crate feature std only.

Adds a TimeDelta to an instant

Returns None if the result is outside the valid range.

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

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 time delta.

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

Panics

This panics when the seconds component of this time delta is equal to i64::MIN.

pub const fn neg_abs(self) -> TimeDelta

Returns the negative absolute value of this time delta.

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

Panics

This panics when the seconds component of this time delta 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

Operations.

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

Add two time deltas together. If overflow occurs, then None is returned.

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

Add two time deltas together. If overflow occurs, then arithmetic saturates.

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

Subtract one time delta from another. If overflow occurs, then None is returned.

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

Add two time deltas together. If overflow occurs, then arithmetic saturates.

impl TimeDelta

Operations involving integers.

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

Multiply this time delta by an integer. If the multiplication overflows, then None is returned.

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

Multiply this time delta 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 const fn as_secs_f64(&self) -> f64

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

pub const fn as_secs_f32(&self) -> f32

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

pub const fn from_secs_f64(secs: f64) -> TimeDelta

Returns a time delta 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 time delta values.

pub const fn from_secs_f32(secs: f32) -> TimeDelta

Returns a time delta 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 time delta values.

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

Returns a time delta corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

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

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

Returns a time delta corresponding to the number of seconds.

The number given may have a fractional nanosecond component.

Returns an error if the given float overflows the minimum or maximum time delta values.

pub const fn as_millis_f64(&self) -> f64

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

pub const fn as_millis_f32(&self) -> f32

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

pub const fn from_millis_f64(millis: f64) -> TimeDelta

Returns a time delta corresponding to the number of milliseconds.

The number given may have a fractional nanosecond component.

Panics

Panics if the given float overflows the minimum or maximum time delta values.

pub const fn try_from_millis_f64(millis: f64) -> Result<TimeDelta, &'static str>

Returns a time delta corresponding to the number of milliseconds.

The number given may have a fractional nanosecond component.

Returns an error if the given float overflows the minimum or maximum time delta values.

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

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 const fn mul_f32(self, rhs: f32) -> TimeDelta

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 const fn div_f64(self, rhs: f64) -> TimeDelta

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 const fn div_f32(self, rhs: f32) -> TimeDelta

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 const fn div_delta_f64(self, rhs: TimeDelta) -> f64

Divides this time delta by another time delta.

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

Divides this time delta by another time delta.

impl TimeDelta

Additional APIs involving Duration

.

pub const fn from_duration(duration: Duration) -> Self

Converts a Duration to a TimeDelta.

pub const fn to_duration(&self) -> Option<Duration>

Converts a TimeDelta to a Duration if it is non-negative. Returns None if the TimeDelta is negative.

pub const fn abs_duration(self) -> Duration

Returns the absolute value of this time delta as a Duration.

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

pub const fn checked_add_duration(&self, duration: Duration) -> Option<Self>

Adds a Duration to this TimeDelta. Returns None if the result overflows.

pub const fn checked_sub_duration(&self, duration: Duration) -> Option<Self>

Subtracts a Duration from this TimeDelta. Returns None if the result underflows.

impl TimeDelta

pub const fn from_js(js: JsInstant) -> Self

Available on crate feature js only.

Converts a JsInstant into a TimeDelta relative to the time origin.

pub const fn to_js(self) -> JsInstant

Available on crate feature js only.

Converts a TimeDelta into a JsInstant, interpreting it as an absolute timestamp.

impl TimeDelta

pub const fn from_jiff(from: SignedDuration) -> TimeDelta

Available on crate feature dep_jiff only.

Converts [SignedDuration] into TimeDelta.

pub const fn to_jiff(self) -> SignedDuration

Available on crate feature dep_jiff only.

Converts TimeDelta into [SignedDuration].

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 Add<TimeDelta> for SystemInstant

Available on crate feature std only.

Shifts Instant forward or backward.

type Output = Instant

The resulting type after applying the + operator.

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

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 duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for TimeDelta

impl Debug for TimeDelta

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

Formats the value using the given formatter.

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 Eq for TimeDelta

impl From<SignedDuration> for TimeDelta

Available on crate feature dep_jiff only.

fn from(from: SignedDuration) -> TimeDelta

Converts to this type from the input type.

impl From<TimeDelta> for SignedDuration

Available on crate feature dep_jiff only.

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 StructuralPartialEq for TimeDelta

impl Sub for TimeDelta

type Output = TimeDelta

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Instant> for TimeDelta

Available on crate feature std only.

Returns a signed TimeDelta.

type Output = Instant

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<TimeDelta> for SystemInstant

Available on crate feature std only.

Moves Instant backward or forward.

type Output = Instant

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for TimeDelta

fn sub_assign(&mut self, rhs: TimeDelta)

Performs the -= operation.

impl TimeSpan for TimeDelta

const TIME_ZERO: Self = TimeDelta::ZERO

The additive zero span.

fn time_add_checked(self, other: Self) -> Option<Self>

Returns the sum of two spans, or None if it is not representable.

fn time_sub_checked(self, other: Self) -> Option<Self>

Returns the difference of two spans, or None if it is not representable.

fn time_is_zero(self) -> bool

Returns whether this span is zero.

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

Returns the sum of two spans.

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

Returns the difference of two spans.

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<LinuxTimespec> for TimeDelta

Available on crate feature linux only.

type Error = Overflow

The type returned in the event of a conversion error.

fn try_from(timespec: LinuxTimespec) -> Result<Self, 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 TryFrom<TimeDelta> for LinuxTimespec

Available on crate feature linux only.

type Error = Overflow

The type returned in the event of a conversion error.

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

Performs the conversion.