Struct FancyDuration

pub struct FancyDuration<D: AsTimes + Clone>(pub D);

A FancyDuration contains a duration of type that implements AsTimes. It is capable of that point at parsing strings as well as returning the duration value encapsulated. If included in a serde serializing or deserializing workflow, it will automatically construct the appropriate duration as a part of the process.

Support for [time] and [chrono] are available as a part of this library via feature flags.

A duration is “human-readable” when it follows the following format:

<count><timespec>...

This pattern repeats in an expected and prescribed order of precedence based on what duration is supplied. Certain durations are order-dependent (like months and minutes), but most are not; that said it should be desired to represent your durations in precedence order. If you express standard formatting, each unit is separated by whitespace, such as “2m 5s 30ms”, compact formatting removes the whitespace: “2m5s30ms”.

count is simply an integer value with no leading zero-padding. timespec is a one or two character identifier that specifies the unit of time the count represents. The following timespecs are supported, and more may be added in the future based on demand.

The order here is precedence-order. So to express this properly, one might say “5y2d30m” which means “5 years, 2 days and 30 minutes”, but “5y30m2d” means “5 years, 30 months, and 2 days”.

• y: years
• m: months (must appear before minutes)
• w: weeks
• d: days
• h: hours
• m: minutes (must appear after months)
• s: seconds
• ms: milliseconds
• us: microseconds
• ns: nanoseconds

Simplifications:

Some time units have been simplified:

• Years is 365 days
• Months is 30 days

These durations do not account for variations in the potential unit based on the current time. Perhaps in a future release.

Tuple Fields

0: D

Implementations

impl<D> FancyDuration<D>

where D: AsTimes + Clone,

pub fn new(d: D) -> Self

Construct a fancier duration!

Accept input of a Duration type that implements AsTimes. From here, strings containing human-friendly durations can be constructed, or the inner duration can be retrieved.

pub fn duration(&self) -> D

where D: Clone,

Retrieve the inner duration.

pub fn filter(&self, filter: &[DurationPart]) -> Self

Supply a filter of allowed time values, others will be zeroed out and the time recalculated as if they didn’t exist.

pub fn truncate(&self, limit: usize) -> Self

Truncate to the most significant consecutive values. This will take a number like “1y 2m 3w 4d” and with a value of 2 reduce it to “1y 2m”. Since it works consecutively, minor values will also be dropped, such as “1h 2m 30us”, truncated to 3, would still produce “1h 2m” because “30us” is below the seconds value, which is more significant and would have been counted. “1h 2m 3s” would truncate to 3 with “1h 2m 3s”.

pub fn parse(s: &str) -> Result<Self, Error>

Parse a string that contains a human-readable duration. See FancyDuration for more information on how times are represented.

pub fn format(&self) -> String

Supply the standard formatted human-readable representation of the duration. This format contains whitespace.

pub fn format_compact(&self) -> String

Supply the compact formatted human-readable representation of the duration. This format does not contain whitespace.

pub fn parse_to_ns(s: &str) -> Result<(u64, u64), Error>

Parse a string in fancy duration format to a tuple of (seconds, nanoseconds). Nanoseconds is simply a subsecond count and does not contain the seconds represented as nanoseconds. If a parsing error occurs that will appear in the result.

Trait Implementations

impl<D: Clone + AsTimes + Clone> Clone for FancyDuration<D>

fn clone(&self) -> FancyDuration<D>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<D: Debug + AsTimes + Clone> Debug for FancyDuration<D>

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

Formats the value using the given formatter.

impl<D> Display for FancyDuration<D>

where D: AsTimes + Clone,

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

Formats the value using the given formatter.

impl<D> FromStr for FancyDuration<D>

where D: AsTimes + Clone,

type Err = Error

The associated error which can be returned from parsing.

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

Parses a string s to return a value of this type.

impl<D: PartialEq + AsTimes + Clone> PartialEq for FancyDuration<D>

fn eq(&self, other: &FancyDuration<D>) -> 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<D: AsTimes + Clone> StructuralPartialEq for FancyDuration<D>