humantime Rust Library

The humantime crate provides high-performance parsing and formatting for human-readable durations and timestamps. It is designed for speed, particularly for fixed-format timestamp operations.

Key Features:

• Duration Parsing: Parses free-form duration strings like 15days 2min 2s.
• Duration Formatting: Formats durations into human-readable strings like 2years 2min 12us.
• RFC3339 Timestamps: Parses and formats timestamps in the rfc3339 format (e.g., 2018-01-01T12:53:00Z).
• Flexible Timestamp Parsing: Supports parsing timestamps in a weaker format (e.g., 2018-01-01 12:53:00).

The humantime::Duration struct is a wrapper around std::time::Duration that implements FromStr. This allows you to parse human-readable duration strings (e.g., "12h 5min") directly into a type that can be easily converted back to a standard std::time::Duration.

To use it, call .parse::<humantime::Duration>() on your string. The resulting humantime::Duration can be converted to a std::time::Duration using .into() or by dereferencing.

use std::time::Duration as StdDuration;
let x: StdDuration;
// Parse a human-readable string and convert to standard Duration
x = "12h 5min 2ns".parse::<humantime::Duration>().unwrap().into();
assert_eq!(x, StdDuration::new(12*3600 + 5*60, 2));

The library provides high-performance parsing and formatting for RFC3339 timestamps (e.g., 2018-01-01T12:53:00Z).

• Parsing: Use parse_rfc3339 for standard RFC3339 or parse_rfc3339_weak for a looser format like 2018-01-01 12:53:00.
• Formatting: Use specific functions to control precision: format_rfc3339, format_rfc3339_seconds, format_rfc3339_millis, format_rfc3339_micros, or format_rfc3339_nanos.

// Example usage pattern
let timestamp = parse_rfc3339("2018-01-01T12:53:00Z").unwrap();
let formatted = format_rfc3339(timestamp);

The humantime::Timestamp struct is a wrapper around std::time::SystemTime that implements FromStr. It uses a "weak" RFC 3339 parser, which is more permissive to accommodate human input (common in command-line interfaces).

To use it, call .parse::<humantime::Timestamp>() on your string. The resulting humantime::Timestamp can be converted to a standard std::time::SystemTime using .into() or by dereferencing.

use std::time::SystemTime;
let x: SystemTime;
// Parse a weak RFC 3339 string and convert to standard SystemTime
x = "2018-02-16T00:31:37Z".parse::<humantime::Timestamp>().unwrap().into();
// Verification using format_rfc3339
assert_eq!(humantime::format_rfc3339(x).to_string(), "2018-02-16T00:31:37Z");

Use parse_rfc3339 to parse strictly formatted RFC3339 strings (e.g., 2018-02-14T00:28:07Z).

Supported features:

• Any precision of fractional digits (e.g., 2018-02-14T00:28:07.133Z).
• UTC timezone indicated by Z or +00:00.

Unsupported features:

• Localized timestamps. Only UTC is supported.
• The 'weak' format (space instead of 'T').

use std::time::SystemTime;
use humantime::parse_rfc3339;

let time = parse_rfc3339("2018-02-14T00:28:07Z").unwrap();

Use parse_duration to convert a string containing human-friendly time spans (e.g., "2h 37min", "32ms", "4.2s") into a std::time::Duration. The input can be a concatenation of multiple time spans. Supported units include nanoseconds, microseconds, milliseconds, seconds, minutes, hours, days, weeks, months (defined as 30.44 days), and years (defined as 365.25 days).

use std::time::Duration;
use humantime::parse_duration;

assert_eq!(parse_duration("2h 37min"), Ok(Duration::new(9420, 0)));
assert_eq!(parse_duration("32ms"), Ok(Duration::new(0, 32_000_000)));
assert_eq!(parse_duration("4.2s"), Ok(Duration::new(4, 200_000_000)));

You can create a humantime::Duration from a standard std::time::Duration using the new method. This method is const, allowing it to be used in constant contexts.

# use humantime::Duration;
# use std::time::Duration as StdDuration;
const DEFAULT_TIMEOUT: Duration = Duration::new(StdDuration::from_secs(60));

Use format_duration to wrap a std::time::Duration in a FormattedDuration type. When this type is displayed (e.g., via .to_string()), it produces a human-readable string representation of the duration. The output format is designed to be reversible by parse_duration.

use std::time::Duration;
use humantime::format_duration;

let val1 = Duration::new(9420, 0);
assert_eq!(format_duration(val1).to_string(), "2h 37m");

let val2 = Duration::new(0, 32_000_000);
assert_eq!(format_duration(val2).to_string(), "32ms");

Use parse_duration to convert free-form duration strings (e.g., 15days 2min 2s) into a Duration object. Use format_duration to convert a Duration back into a human-readable string (e.g., 2years 2min 12us).

// Example usage pattern
let duration = parse_duration("15days 2min 2s").unwrap();
let formatted = format_duration(duration);

Use parse_rfc3339_weak for parsing human-input strings that may use a space instead of T as a separator (e.g., 2018-02-14 00:28:07). This function is more permissive than parse_rfc3339.

Supported features:

• Any precision of fractional digits.
• Supports timestamps with or without T, Z, or +00:00.
• Anything valid for parse_rfc3339 is also valid here.

Unsupported features:

• Localized timestamps. Only UTC is supported, even if Z is not specified.

use std::time::SystemTime;
use humantime::parse_rfc3339_weak;

// Works with space separator
let time = parse_rfc3339_weak("2018-02-14 00:28:07").unwrap();

// Works with T and Z
let time2 = parse_rfc3339_weak("2018-02-14T00:28:07Z").unwrap();