Struct Duration

pub struct Duration { /* private fields */ }

The duration which is returned by the parser

The Duration of this library implements conversions to a std::time::Duration and if the feature is activated into a time::Duration respectively chrono::Duration. This crates duration is a superset of the aforementioned durations, so converting to fundu’s duration with From or Into is lossless. Converting from crate::time::Duration to the other durations can overflow the other duration’s value range, but TryFrom is implement for all of these durations. Note that fundu’s duration also implements SaturatingInto for the above durations which performs the conversion saturating at the maximum or minimum of these durations.

Examples

Basic conversions from Duration to std::time::Duration.

use std::time::Duration as StdDuration;

use fundu_core::error::TryFromDurationError;
use fundu_core::time::{Duration, SaturatingInto};

let result: Result<StdDuration, TryFromDurationError> = Duration::positive(1, 2).try_into();
assert_eq!(result, Ok(StdDuration::new(1, 2)));

let result: Result<StdDuration, TryFromDurationError> = Duration::negative(1, 2).try_into();
assert_eq!(result, Err(TryFromDurationError::NegativeDuration));

let duration: StdDuration = Duration::negative(1, 2).saturating_into();
assert_eq!(duration, StdDuration::ZERO);

let duration: StdDuration = Duration::MAX.saturating_into();
assert_eq!(duration, StdDuration::MAX);

Implementations

impl Duration

pub const ZERO: Self

A duration of zero time

Examples

use fundu_core::time::Duration;

let duration = Duration::ZERO;
assert!(duration.is_zero());

pub const MIN: Self

The minimum duration

Examples

use fundu_core::time::Duration;

let duration = Duration::MIN;
assert_eq!(Duration::negative(u64::MAX, 999_999_999), duration);

pub const MAX: Self

The maximum duration

Examples

use fundu_core::time::Duration;

let duration = Duration::MAX;
assert_eq!(Duration::positive(u64::MAX, 999_999_999), duration);

pub const fn from_std(is_negative: bool, inner: Duration) -> Self

Creates a new Duration from a std::time::Duration which can be negative or positive

Examples

use fundu_core::time::Duration;

let duration = Duration::from_std(false, std::time::Duration::new(1, 0));
assert_eq!(Duration::positive(1, 0), duration);

let duration = Duration::from_std(true, std::time::Duration::new(1, 0));
assert_eq!(Duration::negative(1, 0), duration);

pub const fn positive(secs: u64, nanos: u32) -> Self

Creates a new positive Duration

Panics

This constructor will panic if creating a std::time::Duration with the same parameters would panic

Examples

use fundu_core::time::Duration;

let duration = Duration::positive(1, 0);
assert!(duration.is_positive());

let duration = Duration::positive(0, 0);
assert!(duration.is_positive());

pub const fn negative(secs: u64, nanos: u32) -> Self

Creates a new negative Duration

Panics

This constructor will panic if creating a std::time::Duration with the same parameters would panic

Examples

use fundu_core::time::Duration;

let duration = Duration::negative(1, 0);
assert!(duration.is_negative());

pub const fn as_weeks(&self) -> i64

Return the number of whole weeks in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(86400 * 7, 0).as_weeks(), 1);
assert_eq!(Duration::negative(86400 * 7, 0).as_weeks(), -1);
assert_eq!(Duration::positive(1, 0).as_weeks(), 0);
assert_eq!(Duration::positive(1_500_000, 0).as_weeks(), 2);

pub const fn as_days(&self) -> i64

Return the number of whole days in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(86400, 0).as_days(), 1);
assert_eq!(Duration::negative(86400, 0).as_days(), -1);
assert_eq!(Duration::positive(1, 0).as_days(), 0);
assert_eq!(Duration::positive(1_500_000, 0).as_days(), 17);

pub const fn as_hours(&self) -> i64

Return the number of whole hours in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(3600, 0).as_hours(), 1);
assert_eq!(Duration::negative(3600, 0).as_hours(), -1);
assert_eq!(Duration::positive(1, 0).as_hours(), 0);
assert_eq!(Duration::positive(1_500_000, 0).as_hours(), 416);

pub const fn as_minutes(&self) -> i64

Return the number of whole minutes in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(60, 0).as_minutes(), 1);
assert_eq!(Duration::negative(60, 0).as_minutes(), -1);
assert_eq!(Duration::positive(1, 0).as_minutes(), 0);
assert_eq!(Duration::positive(1_500_000, 0).as_minutes(), 25_000);

pub const fn as_seconds(&self) -> i128

Return the number of whole seconds in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(1, 0).as_seconds(), 1);
assert_eq!(Duration::negative(1, 0).as_seconds(), -1);
assert_eq!(Duration::positive(0, 1_000_000).as_seconds(), 0);
assert_eq!(Duration::positive(1_500_000, 0).as_seconds(), 1_500_000);

pub const fn as_millis(&self) -> i128

Return the total number of whole milliseconds in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(1, 0).as_millis(), 1_000);
assert_eq!(Duration::negative(1, 0).as_millis(), -1_000);
assert_eq!(Duration::positive(0, 1_000_000).as_millis(), 1);
assert_eq!(Duration::positive(12, 3_000_000).as_millis(), 12_003);

pub const fn as_micros(&self) -> i128

Return the total number of whole microseconds in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(1, 0).as_micros(), 1_000_000);
assert_eq!(Duration::negative(1, 0).as_micros(), -1_000_000);
assert_eq!(Duration::positive(0, 1_000).as_micros(), 1);
assert_eq!(Duration::positive(12, 3_000).as_micros(), 12_000_003);

pub const fn as_nanos(&self) -> i128

Return the total number of nanoseconds in the Duration

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(1, 0).as_nanos(), 1_000_000_000);
assert_eq!(Duration::negative(1, 0).as_nanos(), -1_000_000_000);
assert_eq!(Duration::positive(0, 1).as_nanos(), 1);
assert_eq!(Duration::positive(12, 3).as_nanos(), 12_000_000_003);

pub const fn subsec_millis(&self) -> i32

Return the fractional part of the Duration in whole milliseconds

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(0, 123_456_789).subsec_millis(), 123);
assert_eq!(Duration::negative(0, 123_456_789).subsec_millis(), -123);
assert_eq!(Duration::positive(1, 0).subsec_millis(), 0);
assert_eq!(Duration::positive(0, 1).subsec_millis(), 0);

pub const fn subsec_micros(&self) -> i32

Return the fractional part of the Duration in whole microseconds

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(0, 123_456_789).subsec_micros(), 123_456);
assert_eq!(Duration::negative(0, 123_456_789).subsec_micros(), -123_456);
assert_eq!(Duration::positive(1, 0).subsec_micros(), 0);
assert_eq!(Duration::positive(0, 1).subsec_micros(), 0);

pub const fn subsec_nanos(&self) -> i32

Return the fractional part of the Duration in nanoseconds

Examples

use fundu_core::time::Duration;

assert_eq!(Duration::positive(0, 123_456_789).subsec_nanos(), 123_456_789);
assert_eq!(Duration::negative(0, 123_456_789).subsec_nanos(), -123_456_789);
assert_eq!(Duration::positive(1, 0).subsec_nanos(), 0);
assert_eq!(Duration::positive(0, 1).subsec_nanos(), 1);

pub fn extract_weeks(&mut self) -> i64

Return the number of whole weeks in this Duration and reduce it by that amount

Examples

use fundu_core::time::Duration;

let mut duration = Duration::positive(86400 * 7, 0);
assert_eq!(duration.extract_weeks(), 1);
assert_eq!(duration, Duration::ZERO);

let mut duration = Duration::positive(123, 456);
assert_eq!(duration.extract_weeks(), 0);
assert_eq!(duration, Duration::positive(123, 456));

pub fn extract_days(&mut self) -> i64

Return the number of whole days in this Duration and reduce it by that amount

Examples

use fundu_core::time::Duration;

let mut duration = Duration::positive(86400, 0);
assert_eq!(duration.extract_days(), 1);
assert_eq!(duration, Duration::ZERO);

let mut duration = Duration::positive(123, 456);
assert_eq!(duration.extract_days(), 0);
assert_eq!(duration, Duration::positive(123, 456));

pub fn extract_hours(&mut self) -> i64

Return the number of whole hours in this Duration and reduce it by that amount

Examples

use fundu_core::time::Duration;

let mut duration = Duration::positive(3600, 0);
assert_eq!(duration.extract_hours(), 1);
assert_eq!(duration, Duration::ZERO);

let mut duration = Duration::positive(123, 456);
assert_eq!(duration.extract_hours(), 0);
assert_eq!(duration, Duration::positive(123, 456));

pub fn extract_minutes(&mut self) -> i64

Return the number of whole minutes in this Duration and reduce it by that amount

Examples

use fundu_core::time::Duration;

let mut duration = Duration::positive(60, 0);
assert_eq!(duration.extract_minutes(), 1);
assert_eq!(duration, Duration::ZERO);

let mut duration = Duration::positive(12, 456);
assert_eq!(duration.extract_minutes(), 0);
assert_eq!(duration, Duration::positive(12, 456));

pub fn extract_seconds(&mut self) -> i128

Return the number of seconds in this Duration and reduce it by that amount

Examples

use fundu_core::time::Duration;

let mut duration = Duration::positive(1, 0);
assert_eq!(duration.extract_seconds(), 1);
assert_eq!(duration, Duration::ZERO);

let mut duration = Duration::positive(12, 456);
assert_eq!(duration.extract_seconds(), 12);
assert_eq!(duration, Duration::positive(0, 456));

pub const fn is_negative(&self) -> bool

Returns true if the Duration is negative

Examples

use fundu_core::time::Duration;

let duration = Duration::MIN;
assert!(duration.is_negative());

let duration = Duration::negative(0, 1);
assert!(duration.is_negative());

pub const fn is_positive(&self) -> bool

Returns true if the Duration is positive

Examples

use fundu_core::time::Duration;

let duration = Duration::ZERO;
assert!(duration.is_positive());

let duration = Duration::positive(0, 1);
assert!(duration.is_positive());

pub const fn is_zero(&self) -> bool

Returns true if the Duration is zero

Examples

use fundu_core::time::Duration;

let duration = Duration::ZERO;
assert!(duration.is_zero());

let duration = Duration::positive(0, 0);
assert!(duration.is_zero());

let duration = Duration::negative(0, 0);
assert!(duration.is_zero());

pub const fn abs(&self) -> Self

Returns the absolute value of the duration

This operation is lossless.

Examples

use fundu_core::time::Duration;

let duration = Duration::MIN;
assert_eq!(duration.abs(), Duration::MAX);

let duration = Duration::negative(1, 0);
assert_eq!(duration.abs(), Duration::positive(1, 0));

let duration = Duration::positive(1, 0);
assert_eq!(duration.abs(), Duration::positive(1, 0));

pub fn checked_add(&self, other: Self) -> Option<Self>

Sums this duration with the other duration, returning None if an overflow occurred

Examples

use fundu_core::time::Duration;

assert_eq!(
    Duration::positive(1, 0).checked_add(Duration::positive(1, 0)),
    Some(Duration::positive(2, 0))
);
assert_eq!(
    Duration::positive(u64::MAX, 0).checked_add(Duration::positive(1, 0)),
    None
);
assert_eq!(
    Duration::negative(u64::MAX, 0).checked_add(Duration::negative(1, 0)),
    None
);

pub fn checked_sub(&self, other: Self) -> Option<Self>

Subtracts this duration with the other duration, returning None if an overflow occurred

Examples

use fundu_core::time::Duration;

assert_eq!(
    Duration::positive(1, 0).checked_sub(Duration::positive(1, 0)),
    Some(Duration::ZERO)
);
assert_eq!(
    Duration::negative(u64::MAX, 0).checked_sub(Duration::positive(1, 0)),
    None
);

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

Saturating Duration addition. Computes self + other, returning Duration::MAX or Duration::MIN if an overflow occurred.

Examples

use fundu_core::time::Duration;

assert_eq!(
    Duration::positive(1, 0).saturating_add(Duration::positive(0, 1)),
    Duration::positive(1, 1)
);
assert_eq!(
    Duration::positive(u64::MAX, 0).saturating_add(Duration::positive(1, 0)),
    Duration::MAX
);

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

Saturating Duration subtraction. Computes self - other, returning Duration::MAX or Duration::MIN if an overflow occurred.

Examples

use fundu_core::time::Duration;

assert_eq!(
    Duration::positive(1, 0).saturating_sub(Duration::positive(1, 0)),
    Duration::ZERO
);
assert_eq!(
    Duration::negative(u64::MAX, 0).saturating_sub(Duration::positive(1, 0)),
    Duration::MIN
);

Trait Implementations

impl Add for Duration

type Output = Duration

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign for Duration

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl Clone for Duration

fn clone(&self) -> Duration

Returns a duplicate 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() -> Duration

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

Convert a std::time::Duration into a Duration

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<Duration> for Duration

Available on crate feature time only.

Convert a time::Duration into a Duration

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<TimeDelta> for Duration

Available on crate feature chrono only.

Convert a chrono::Duration into a Duration

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl Hash for Duration

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 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: &Self) -> 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 Duration

fn eq(&self, other: &Self) -> 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: &Self) -> 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 SaturatingInto<Duration> for Duration

fn saturating_into(self) -> Duration

Performs the saturating conversion

impl SaturatingInto<Duration> for Duration

Available on crate feature time only.

fn saturating_into(self) -> Duration

Performs the saturating conversion

impl SaturatingInto<TimeDelta> for Duration

Available on crate feature chrono only.

fn saturating_into(self) -> Duration

Performs the saturating conversion

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

type Output = Duration

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign for Duration

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl TryFrom<&Duration> for Duration

Available on crate feature time only.

Convert a Duration into a time::Duration

type Error = TryFromDurationError

The type returned in the event of a conversion error.

fn try_from(duration: &Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<&Duration> for Duration

Available on crate feature chrono only.

Convert a Duration into a chrono::Duration

type Error = TryFromDurationError

The type returned in the event of a conversion error.

fn try_from(duration: &Duration) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<Duration> for Duration

Convert a Duration into a std::time::Duration

type Error = TryFromDurationError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Duration> for Duration

Available on crate feature time only.

Convert a Duration into a time::Duration

type Error = TryFromDurationError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<Duration> for Duration

Available on crate feature chrono only.

Convert a Duration into a chrono::Duration

type Error = TryFromDurationError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Copy for Duration

impl Eq for Duration