Crate fancy_duration

A “fancy duration” is a text description of the duration. For example, “1h 20m 30s” which might be read as “one hour, twenty minutes and thirty seconds”. Expression in a duration type is transparent through a variety of means; chrono and the time crate are supported, as well as serialization into and from string types with serde. Time support starts in years and funnels down to nanoseconds.

Feature matrix:

• serde: enables serde support including serialization and deseralization from strings
• time: enables traits that implement fancy duration features for the time crate
• chrono: enables traits that implement fancy duration features for the chrono crate

What follows are some usage examples. You can either wrap your duration-like type in a FancyDuration struct, or use types which allow for monkeypatched methods that allow you to work directly on the target type. For example, use AsFancyDuration to inject fancy_duration calls to perform the construction (which can be formatted or converted to string) and ParseFancyDuration to inject parse_fancy_duration constructors to accept strings into your favorite type. std::time::Duration, time::Duration, and chrono::Duration are all supported (some features may need to be required) and you can make more types eligible by implementing the AsTimes trait.

use std::time::Duration;
use fancy_duration::FancyDuration;

pub fn main() {
    // use struct-wrapped or monkeypatched approaches with fancy_duration::AsFancyDuration;
    assert_eq!(FancyDuration(Duration::new(20, 0)).to_string(), "20s");
    assert_eq!(FancyDuration(Duration::new(600, 0)).to_string(), "10m");
    assert_eq!(FancyDuration(Duration::new(120, 0)).to_string(), "2m");
    assert_eq!(FancyDuration(Duration::new(185, 0)).to_string(), "3m 5s");
    assert_eq!(FancyDuration::<Duration>::parse("3m 5s").unwrap().duration(), Duration::new(185, 0));
    assert_eq!(FancyDuration(Duration::new(185, 0)).to_string(), "3m 5s");

    // these traits are also implemented for chrono and time
    use fancy_duration::{ParseFancyDuration, AsFancyDuration};
    assert_eq!(Duration::new(20, 0).fancy_duration().to_string(), "20s");
    assert_eq!(Duration::new(600, 0).fancy_duration().to_string(), "10m");
    assert_eq!(Duration::new(120, 0).fancy_duration().to_string(), "2m");
    assert_eq!(Duration::new(185, 0).fancy_duration().to_string(), "3m 5s");
    assert_eq!(Duration::parse_fancy_duration("3m 5s".to_string()).unwrap(), Duration::new(185, 0));
    assert_eq!(Duration::new(185, 0).fancy_duration().to_string(), "3m 5s");

    #[cfg(feature = "time")]
    {
        // also works with time::Duration from the `time` crate
        assert_eq!(FancyDuration(time::Duration::new(20, 0)).to_string(), "20s");
        assert_eq!(FancyDuration(time::Duration::new(600, 0)).to_string(), "10m");
        assert_eq!(FancyDuration(time::Duration::new(120, 0)).to_string(), "2m");
        assert_eq!(FancyDuration(time::Duration::new(185, 0)).to_string(), "3m 5s");
        assert_eq!(FancyDuration::<time::Duration>::parse("3m 5s").unwrap().duration(), time::Duration::new(185, 0));
        assert_eq!(FancyDuration(time::Duration::new(185, 0)).to_string(), "3m 5s");
    }

    #[cfg(feature = "chrono")]
    {
        // also works with chrono!
        assert_eq!(FancyDuration(chrono::TimeDelta::try_seconds(20).unwrap_or_default()).to_string(), "20s");
        assert_eq!(FancyDuration(chrono::TimeDelta::try_seconds(600).unwrap_or_default()).to_string(), "10m");
        assert_eq!(FancyDuration(chrono::TimeDelta::try_seconds(120).unwrap_or_default()).to_string(), "2m");
        assert_eq!(FancyDuration(chrono::TimeDelta::try_seconds(185).unwrap_or_default()).to_string(), "3m 5s");
        assert_eq!(FancyDuration::<chrono::Duration>::parse("3m 5s").unwrap().duration(), chrono::TimeDelta::try_seconds(185).unwrap_or_default());
        assert_eq!(FancyDuration(chrono::TimeDelta::try_seconds(185).unwrap_or_default()).to_string(), "3m 5s");
    }
}

Structs

FancyDuration

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.

Enums

DurationPart

Traits

AsFancyDuration

Implement AsFancyDuration for your Duration type, it will annotate those types with the fancy_duration function which allows trivial and explicit conversion into a fancy duration.

AsTimes

AsTimes is the trait that allows FancyDuration to represent durations. Implementing these methods will allow any compatible type to work with FancyDuration.

ParseFancyDuration

Implement ParseFancyDuration for your Duration type to implement parsing constructors for your Duration. A more generic parse implementation for String and &str may come in a future version.