Struct hifitime::Duration

#[repr(C)]
pub struct Duration { /* private fields */ }

Defines generally usable durations for nanosecond precision valid for 32,768 centuries in either direction, and only on 80 bits / 10 octets.

Important conventions:

1. The negative durations can be mentally modeled “BC” years. One hours before 01 Jan 0000, it was “-1” years but 365 days and 23h into the current day. It was decided that the nanoseconds corresponds to the nanoseconds into the current century. In other words, a duration with centuries = -1 and nanoseconds = 0 is a greater duration (further from zero) than centuries = -1 and nanoseconds = 1. Duration zero minus one nanosecond returns a century of -1 and a nanosecond set to the number of nanoseconds in one century minus one. That difference is exactly 1 nanoseconds, where the former duration is “closer to zero” than the latter. As such, the largest negative duration that can be represented sets the centuries to i16::MAX and its nanoseconds to NANOSECONDS_PER_CENTURY.
2. It was also decided that opposite durations are equal, e.g. -15 minutes == 15 minutes. If the direction of time matters, use the signum function.

Implementations

impl Duration

pub fn new(centuries: i16, nanoseconds: u64) -> Self

👎Deprecated since 3.6.0: Prefer from_parts()

Builds a new duration from the number of centuries and the number of nanoseconds

pub fn from_parts(centuries: i16, nanoseconds: u64) -> Self

Create a normalized duration from its parts

pub fn from_total_nanoseconds(nanos: i128) -> Self

Converts the total nanoseconds as i128 into this Duration (saving 48 bits)

pub fn from_truncated_nanoseconds(nanos: i64) -> Self

Create a new duration from the truncated nanoseconds (+/- 2927.1 years of duration)

pub fn from_f64(value: f64, unit: Unit) -> Self

Creates a new duration from the provided unit

pub fn from_days(value: f64) -> Self

Creates a new duration from the provided number of days

pub fn from_hours(value: f64) -> Self

Creates a new duration from the provided number of hours

pub fn from_seconds(value: f64) -> Self

Creates a new duration from the provided number of seconds

pub fn from_milliseconds(value: f64) -> Self

Creates a new duration from the provided number of milliseconds

pub fn from_microseconds(value: f64) -> Self

Creates a new duration from the provided number of microsecond

pub fn from_nanoseconds(value: f64) -> Self

Creates a new duration from the provided number of nanoseconds

pub fn compose( sign: i8, days: u64, hours: u64, minutes: u64, seconds: u64, milliseconds: u64, microseconds: u64, nanoseconds: u64 ) -> Self

Creates a new duration from its parts. Set the sign to a negative number for the duration to be negative.

pub fn compose_f64( sign: i8, days: f64, hours: f64, minutes: f64, seconds: f64, milliseconds: f64, microseconds: f64, nanoseconds: f64 ) -> Self

Creates a new duration from its parts. Set the sign to a negative number for the duration to be negative.

pub fn from_tz_offset(sign: i8, hours: i64, minutes: i64) -> Self

Initializes a Duration from a timezone offset

impl Duration

pub const fn to_parts(&self) -> (i16, u64)

Returns the centuries and nanoseconds of this duration NOTE: These items are not public to prevent incorrect durations from being created by modifying the values of the structure directly.

pub fn total_nanoseconds(&self) -> i128

Returns the total nanoseconds in a signed 128 bit integer

pub fn try_truncated_nanoseconds(&self) -> Result<i64, Errors>

Returns the truncated nanoseconds in a signed 64 bit integer, if the duration fits.

pub fn truncated_nanoseconds(&self) -> i64

Returns the truncated nanoseconds in a signed 64 bit integer, if the duration fits. WARNING: This function will NOT fail and will return the i64::MIN or i64::MAX depending on the sign of the centuries if the Duration does not fit on aa i64

pub fn to_seconds(&self) -> f64

Returns this duration in seconds f64. For high fidelity comparisons, it is recommended to keep using the Duration structure.

pub fn to_unit(&self, unit: Unit) -> f64

pub fn abs(&self) -> Self

Returns the absolute value of this duration

pub const fn signum(&self) -> i8

Returns the sign of this duration

• 0 if the number is zero
• 1 if the number is positive
• -1 if the number is negative

pub fn decompose(&self) -> (i8, u64, u64, u64, u64, u64, u64, u64)

Decomposes a Duration in its sign, days, hours, minutes, seconds, ms, us, ns

pub fn floor(&self, duration: Self) -> Self

Floors this duration to the closest duration from the bottom

Example

use hifitime::{Duration, TimeUnits};

let two_hours_three_min = 2.hours() + 3.minutes();
assert_eq!(two_hours_three_min.floor(1.hours()), 2.hours());
assert_eq!(two_hours_three_min.floor(30.minutes()), 2.hours());
// This is zero because we floor by a duration longer than the current duration, rounding it down
assert_eq!(two_hours_three_min.floor(4.hours()), 0.hours());
assert_eq!(two_hours_three_min.floor(1.seconds()), two_hours_three_min);
assert_eq!(two_hours_three_min.floor(1.hours() + 1.minutes()), 2.hours() + 2.minutes());
assert_eq!(two_hours_three_min.floor(1.hours() + 5.minutes()), 1.hours() + 5.minutes());

pub fn ceil(&self, duration: Self) -> Self

Ceils this duration to the closest provided duration

This simply floors then adds the requested duration

Example

use hifitime::{Duration, TimeUnits};

let two_hours_three_min = 2.hours() + 3.minutes();
assert_eq!(two_hours_three_min.ceil(1.hours()), 3.hours());
assert_eq!(two_hours_three_min.ceil(30.minutes()), 2.hours() + 30.minutes());
assert_eq!(two_hours_three_min.ceil(4.hours()), 4.hours());
assert_eq!(two_hours_three_min.ceil(1.seconds()), two_hours_three_min + 1.seconds());
assert_eq!(two_hours_three_min.ceil(1.hours() + 5.minutes()), 2.hours() + 10.minutes());

pub fn round(&self, duration: Self) -> Self

Rounds this duration to the closest provided duration

This performs both a ceil and floor and returns the value which is the closest to current one.

Example

use hifitime::{Duration, TimeUnits};

let two_hours_three_min = 2.hours() + 3.minutes();
assert_eq!(two_hours_three_min.round(1.hours()), 2.hours());
assert_eq!(two_hours_three_min.round(30.minutes()), 2.hours());
assert_eq!(two_hours_three_min.round(4.hours()), 4.hours());
assert_eq!(two_hours_three_min.round(1.seconds()), two_hours_three_min);
assert_eq!(two_hours_three_min.round(1.hours() + 5.minutes()), 2.hours() + 10.minutes());

pub fn approx(&self) -> Self

Rounds this duration to the largest units represented in this duration.

This is useful to provide an approximate human duration. Under the hood, this function uses round, so the “tipping point” of the rounding is half way to the next increment of the greatest unit. As shown below, one example is that 35 hours and 59 minutes rounds to 1 day, but 36 hours and 1 minute rounds to 2 days because 2 days is closer to 36h 1 min than 36h 1 min is to 1 day.

Example

use hifitime::{Duration, TimeUnits};

assert_eq!((2.hours() + 3.minutes()).approx(), 2.hours());
assert_eq!((24.hours() + 3.minutes()).approx(), 1.days());
assert_eq!((35.hours() + 59.minutes()).approx(), 1.days());
assert_eq!((36.hours() + 1.minutes()).approx(), 2.days());
assert_eq!((47.hours() + 3.minutes()).approx(), 2.days());
assert_eq!((49.hours() + 3.minutes()).approx(), 2.days());

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

Returns the minimum of the two durations.

use hifitime::TimeUnits;

let d0 = 20.seconds();
let d1 = 21.seconds();

assert_eq!(d0, d1.min(d0));
assert_eq!(d0, d0.min(d1));

Note: this uses a pointer to self which will be copied immediately because Python requires a pointer.

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

Returns the maximum of the two durations.

use hifitime::TimeUnits;

let d0 = 20.seconds();
let d1 = 21.seconds();

assert_eq!(d1, d1.max(d0));
assert_eq!(d1, d0.max(d1));

Note: this uses a pointer to self which will be copied immediately because Python requires a pointer.

pub const fn is_negative(&self) -> bool

Returns whether this is a negative or positive duration.

pub const ZERO: Self = _

A duration of exactly zero nanoseconds

pub const MAX: Self = _

Maximum duration that can be represented

pub const MIN: Self = _

Minimum duration that can be represented

pub const EPSILON: Self = _

Smallest duration that can be represented

pub const MIN_POSITIVE: Self = Self::EPSILON

Minimum positive duration is one nanoseconds

pub const MIN_NEGATIVE: Self = _

Minimum negative duration is minus one nanosecond

impl Duration

pub fn in_seconds(&self) -> f64

👎Deprecated since 3.5.0: Prefer to_seconds()

pub fn in_unit(&self, unit: Unit) -> f64

👎Deprecated since 3.5.0: Prefer to_unit()

Returns the value of this duration in the requested unit.

Trait Implementations

impl Add<Duration> for Epoch

type Output = Epoch

The resulting type after applying the + operator.

fn add(self, duration: Duration) -> Self

Performs the + operation.

impl Add<Unit> for Duration

type Output = Duration

The resulting type after applying the + operator.

fn add(self, rhs: Unit) -> Self

Performs the + operation.

impl Add for Duration

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

Addition of Durations

Durations are centered on zero duration. Of the tuple, only the centuries may be negative, the nanoseconds are always positive and represent the nanoseconds into the current centuries.

Examples

• Duration { centuries: 0, nanoseconds: 1 } is a positive duration of zero centuries and one nanosecond.
• Duration { centuries: -1, nanoseconds: 1 } is a negative duration representing “one century before zero minus one nanosecond”

type Output = Duration

The resulting type after applying the + operator.

impl AddAssign<Duration> for Epoch

fn add_assign(&mut self, duration: Duration)

Performs the += operation.

impl AddAssign<Unit> for Duration

fn add_assign(&mut self, rhs: Unit)

Performs the += operation.

impl AddAssign for Duration

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

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 Debug for Duration

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

Formats the value using the given formatter.

impl Default for Duration

fn default() -> Self

Returns the “default value” for a type.

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

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Duration

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

Formats the value using the given formatter.

impl Div<f64> for Duration

type Output = Duration

The resulting type after applying the / operator.

fn div(self, q: f64) -> Self::Output

Performs the / operation.

impl Div<i64> for Duration

type Output = Duration

The resulting type after applying the / operator.

fn div(self, q: i64) -> Self::Output

Performs the / operation.

impl From<Duration> for Duration

fn from(hf_duration: Duration) -> Self

Converts a duration into an std::time::Duration

Limitations

1. If the duration is negative, this will return a std::time::Duration::ZERO.
2. If the duration larger than the MAX duration, this will return std::time::Duration::MAX

impl From<Duration> for Duration

fn from(std_duration: Duration) -> Self

Converts a duration into an std::time::Duration

Limitations

1. If the duration is negative, this will return a std::time::Duration::ZERO.
2. If the duration larger than the MAX duration, this will return std::time::Duration::MAX

impl FromStr for Duration

fn from_str(s_in: &str) -> Result<Self, Self::Err>

Attempts to convert a simple string to a Duration. Does not yet support complicated durations.

Identifiers:

• d, days, day
• h, hours, hour
• min, mins, minute
• s, second, seconds
• ms, millisecond, milliseconds
• us, microsecond, microseconds
• ns, nanosecond, nanoseconds
• + or - indicates a timezone offset

Example

use hifitime::{Duration, Unit};
use std::str::FromStr;

assert_eq!(Duration::from_str("1 d").unwrap(), Unit::Day * 1);
assert_eq!(Duration::from_str("10.598 days").unwrap(), Unit::Day * 10.598);
assert_eq!(Duration::from_str("10.598 min").unwrap(), Unit::Minute * 10.598);
assert_eq!(Duration::from_str("10.598 us").unwrap(), Unit::Microsecond * 10.598);
assert_eq!(Duration::from_str("10.598 seconds").unwrap(), Unit::Second * 10.598);
assert_eq!(Duration::from_str("10.598 nanosecond").unwrap(), Unit::Nanosecond * 10.598);
assert_eq!(Duration::from_str("5 h 256 ms 1 ns").unwrap(), 5 * Unit::Hour + 256 * Unit::Millisecond + Unit::Nanosecond);
assert_eq!(Duration::from_str("-01:15:30").unwrap(), -(1 * Unit::Hour + 15 * Unit::Minute + 30 * Unit::Second));
assert_eq!(Duration::from_str("+3615").unwrap(), 36 * Unit::Hour + 15 * Unit::Minute);

type Err = Errors

The associated error which can be returned from parsing.

impl Hash for Duration

fn hash<H: Hasher>(&self, hasher: &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 LowerExp for Duration

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

Formats the value using the given formatter.

impl Mul<Duration> for f64

type Output = Duration

The resulting type after applying the * operator.

fn mul(self, q: Self::Output) -> Self::Output

Performs the * operation.

impl Mul<Duration> for i64

type Output = Duration

The resulting type after applying the * operator.

fn mul(self, q: Self::Output) -> Self::Output

Performs the * operation.

impl Mul<f64> for Duration

type Output = Duration

The resulting type after applying the * operator.

fn mul(self, q: f64) -> Self::Output

Performs the * operation.

impl Mul<i64> for Duration

type Output = Duration

The resulting type after applying the * operator.

fn mul(self, q: i64) -> Self::Output

Performs the * operation.

impl Neg for Duration

type Output = Duration

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - 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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq<Unit> for Duration

fn eq(&self, unit: &Unit) -> bool

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

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

This method 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: &Self) -> bool

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

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

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

impl PartialOrd<Unit> for Duration

fn partial_cmp(&self, unit: &Unit) -> Option<Ordering>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

impl Serialize for Duration

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<Duration> for Epoch

type Output = Epoch

The resulting type after applying the - operator.

fn sub(self, duration: Duration) -> Self

Performs the - operation.

impl Sub<Unit> for Duration

type Output = Duration

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub for Duration

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

Subtraction

This operation is a notch confusing with negative durations. As described in the Duration structure, a Duration of (-1, NANOSECONDS_PER_CENTURY-1) is closer to zero than (-1, 0).

Algorithm

A > B, and both are positive

If A > B, then A.centuries is subtracted by B.centuries, and A.nanoseconds is subtracted by B.nanoseconds. If an overflow occurs, e.g. A.nanoseconds < B.nanoseconds, the number of nanoseconds is increased by the number of nanoseconds per century, and the number of centuries is decreased by one.

use hifitime::{Duration, NANOSECONDS_PER_CENTURY};

let a = Duration::from_parts(1, 1);
let b = Duration::from_parts(0, 10);
let c = Duration::from_parts(0, NANOSECONDS_PER_CENTURY - 9);
assert_eq!(a - b, c);

A < B, and both are positive

In this case, the resulting duration will be negative. The number of centuries is a signed integer, so it is set to the difference of A.centuries - B.centuries. The number of nanoseconds however must be wrapped by the number of nanoseconds per century. For example:, let A = (0, 1) and B = (1, 10), then the resulting duration will be (-2, NANOSECONDS_PER_CENTURY - (10 - 1)). In this case, the centuries are set to -2 because B is two centuries into the future (the number of centuries into the future is zero-indexed).

use hifitime::{Duration, NANOSECONDS_PER_CENTURY};

let a = Duration::from_parts(0, 1);
let b = Duration::from_parts(1, 10);
let c = Duration::from_parts(-2, NANOSECONDS_PER_CENTURY - 9);
assert_eq!(a - b, c);

A > B, both are negative

In this case, we try to stick to normal arithmatics: (-9 - -10) = (-9 + 10) = +1. In this case, we can simply add the components of the duration together. For example, let A = (-1, NANOSECONDS_PER_CENTURY - 2), and B = (-1, NANOSECONDS_PER_CENTURY - 1). Respectively, A is two nanoseconds before Duration::ZERO and B is one nanosecond before Duration::ZERO. Then, A-B should be one nanoseconds before zero, i.e. (-1, NANOSECONDS_PER_CENTURY - 1). This is because we subtract “negative one nanosecond” from a “negative minus two nanoseconds”, which corresponds to adding the opposite, and the opposite of “negative one nanosecond” is “positive one nanosecond”.

use hifitime::{Duration, NANOSECONDS_PER_CENTURY};

let a = Duration::from_parts(-1, NANOSECONDS_PER_CENTURY - 9);
let b = Duration::from_parts(-1, NANOSECONDS_PER_CENTURY - 10);
let c = Duration::from_parts(0, 1);
assert_eq!(a - b, c);

A < B, both are negative

Just like in the prior case, we try to stick to normal arithmatics: (-10 - -9) = (-10 + 9) = -1.

use hifitime::{Duration, NANOSECONDS_PER_CENTURY};

let a = Duration::from_parts(-1, NANOSECONDS_PER_CENTURY - 10);
let b = Duration::from_parts(-1, NANOSECONDS_PER_CENTURY - 9);
let c = Duration::from_parts(-1, NANOSECONDS_PER_CENTURY - 1);
assert_eq!(a - b, c);

MIN is the minimum

One cannot subtract anything from the MIN.

use hifitime::Duration;

let one_ns = Duration::from_parts(0, 1);
assert_eq!(Duration::MIN - one_ns, Duration::MIN);

type Output = Duration

The resulting type after applying the - operator.

impl SubAssign<Duration> for Epoch

fn sub_assign(&mut self, duration: Duration)

Performs the -= operation.

impl SubAssign<Unit> for Duration

fn sub_assign(&mut self, rhs: Unit)

Performs the -= operation.

impl SubAssign for Duration

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl Copy for Duration

impl Eq for Duration

impl StructuralEq for Duration