Table of Contents

• Table of Contents
  • Overview
  • Installation
  • Examples
  • Time Units
  • Benchmarks
  • Comparison
  • Platform support
  • Todo
  • License

Overview

fundu provides a parser to convert strings into a std::time::Duration. It tries to improve on the standard methods Duration::from_secs_f64 and Duration::try_from_secs_f64 (which is stable since 1.66.0) with intermediate parsing to a float via f64::from_str by

• Merging the separate steps of parsing float like strings to f64 and parsing of f64 to a Duration
• Providing customizable TimeUnits which are accepted in the input string.
• Using no floating point calculations and precisely parse the input as it is. So, what you put in you is what you get out within the range of a std::time::Duration.
• Evaluating to Duration::MAX if the input number was larger than that maximum or the input string was positive infinity.
• Supporting input strings of arbitrary length.
• Providing better error messages.

This library aims for good performance (See Benchmarks) and being a lightweight crate. fundu is purely built on top of the rust stdlib, and there are no additional dependencies required. The accepted string format is almost the same like the scientific floating point format and compatible to the f64::from_str format. In other words, if the accepted input string could previously converted to an f64 with f64::from_str, no change is needed to accept the same format with fundu. For a direct comparison of fundu vs the rust native methods Duration::(try_)from_secs_f64 see Comparison. For further details see the Documentation!

Installation

Add this to Cargo.toml for fundu with the standard feature.

[dependencies]
fundu = "0.4.3"

fundu is split into two features, standard (providing DurationParser and parse_duration) and custom (providing the CustomDurationParser). The first is described here in in detail, the latter adds fully customizable identifiers for time units. Most of the time only one of the parsers is needed. To include only the CustomDurationParser add the following to Cargo.toml:

[dependencies]
fundu = { version = "0.4.3", default-features = false, features = ["custom"] }

Examples

If only the default parser is required once, then the parse_duration method can be used.

use fundu::parse_duration;
use std::time::Duration;

let input = "1.0e2s";
assert_eq!(parse_duration(input).unwrap(), Duration::new(100, 0));

When a customization of the accepted TimeUnits is required, then the builder DurationParser can be used.

use fundu::DurationParser;
use std::time::Duration;

let input = "3m";
assert_eq!(
    DurationParser::with_all_time_units().parse(input).unwrap(),
    Duration::new(180, 0)
);

When no time units are configured, seconds is assumed.

use fundu::DurationParser;
use std::time::Duration;

let input = "1.0e2";
assert_eq!(
    DurationParser::without_time_units().parse(input).unwrap(),
    Duration::new(100, 0)
);

However, setting the default time unit to something different than seconds can be achieved with

use fundu::{DurationParser, TimeUnit::*};
use std::time::Duration;

assert_eq!(
    DurationParser::without_time_units().default_unit(MilliSecond).parse("1000").unwrap(),
    Duration::new(1, 0)
);

Note the following will return an error because y (Years) is not in the default set of TimeUnits.

use fundu::DurationParser;

let input = "3y";
assert!(DurationParser::new().parse(input).is_err());

The parser is reusable and the set of time units is fully customizable

use fundu::{DurationParser, TimeUnit::*};
use std::time::Duration;

let parser = DurationParser::with_time_units(&[NanoSecond, Minute, Hour]);
for (input, expected) in &[
    ("9e3ns", Duration::new(0, 9000)),
    ("10m", Duration::new(600, 0)),
    ("1.1h", Duration::new(3960, 0)),
    ("7", Duration::new(7, 0)),
] {
    assert_eq!(parser.parse(input).unwrap(), *expected);
}

The identifiers for time units can be fully customized with any number of valid utf-8 sequences if the custom feature is activated:

use fundu::{CustomDurationParser, TimeUnit::*};
use std::time::Duration;

let parser = CustomDurationParser::with_time_units(
    &[
        (MilliSecond, &["χιλιοστό του δευτερολέπτου"]),
        (Second, &["s", "secs", "..."]),
        (Hour, &["⏳"])
    ]
);
for (input, expected) in &[
    (".3χιλιοστό του δευτερολέπτου", Duration::new(0, 300_000)),
    ("1e3...", Duration::new(1000, 0)),
    ("1.1⏳", Duration::new(3960, 0)),
] {
    assert_eq!(parser.parse(input).unwrap(), *expected);
}

Also, fundu tries to give informative error messages

use fundu::DurationParser;
use std::time::Duration;

assert_eq!(
    DurationParser::without_time_units()
        .parse("1y")
        .unwrap_err()
        .to_string(),
    "Time unit error: No time units allowed but found: 'y' at column 1"
);

See also the examples folder for common recipes. Run an example with

cargo run --example $FILE_NAME_WITHOUT_FILETYPE_SUFFIX

Time units

Time units are used to calculate the final Duration. Second is the default time unit (if not specified otherwise) and if no time unit was specified in the input string. The table below gives an overview of the constructor methods and which time units are available. If a custom set of time units is required, DurationParser::with_time_units can be used.

Note that Months and Years are not included in the default set of time units. The current implementation uses an approximate calculation of Months and Years in seconds and if they are included in the final configuration, the Julian year based calculation is used. (See table above)

With the CustomDurationParser in the custom feature, the identifiers for time units can be fully customized.

Benchmarks

To run the benchmarks on your machine, clone the repository

git clone https://github.com/Joining7943/fundu.git
cd fundu

and then run all benchmarks with

cargo bench --all-features

Benchmarks can be filtered for example with

cargo bench --bench benchmarks_standard
cargo bench --bench benchmarks_standard -- 'parsing speed'
cargo bench --features custom --no-default-features --bench benchmarks_custom

For more infos, see the help with

cargo bench --help # The cargo help for bench
cargo bench --bench benchmarks_standard -- --help # The criterion help

To get a rough idea about the parsing times, here the average parsing speed of two inputs on a comparatively slow machine (Quad core 3000Mhz, 8GB DDR3, Linux)

For comparison, fundu's precision and additional features only add a very low performance overhead for small input and outperforms the reference function for larger input (the reference function is Duration::from_secs_f64(input.parse().unwrap())):

Comparison fundu vs Duration::(try_)from_secs_f64

Here's a short incomplete overview of differences and advantages of fundu over using Duration::(try_)from_secs_f64(input.parse().unwrap())

fundu has a small impact on performance when the input is small but performs better for large input (See performance). Depending on the input data and if you need to parse a massive amount of inputs and don't need the full precision or any of fundu's features, you may prefer using the native methods from the rust stdlib.

Platform support

Since fundu is purely built on top of the rust stdlib without platform specific code, this library should be compatible with all platforms. Please open an issue if you find any unsupported platforms which rust itself supports.

See also the CI

TODO

• Provide other year calculations:
  • mean Gregorian year
  • Sidereal year
  • Tropical year

See also Changelog

License

MIT license (LICENSE or http://opensource.org/licenses/MIT)