6 releases (breaking)

0.9.0 Apr 25, 2025
0.8.0 Feb 17, 2025
0.7.0 Jan 19, 2025
0.6.0 May 21, 2024
0.4.0 Jun 9, 2023

#26 in Date and time

Download history 8396/week @ 2025-01-11 9081/week @ 2025-01-18 5698/week @ 2025-01-25 7955/week @ 2025-02-01 7679/week @ 2025-02-08 5209/week @ 2025-02-15 4196/week @ 2025-02-22 4199/week @ 2025-03-01 5218/week @ 2025-03-08 8697/week @ 2025-03-15 6723/week @ 2025-03-22 8249/week @ 2025-03-29 8027/week @ 2025-04-05 7540/week @ 2025-04-12 8322/week @ 2025-04-19 6790/week @ 2025-04-26

32,449 downloads per month
Used in 11 crates (4 directly)

MIT license

82KB
2K SLoC

parse_datetime

Crates.io License CodeCov

A Rust crate for parsing human-readable relative time strings and human-readable datetime strings and converting them to a DateTime.

Features

  • Parses a variety of human-readable and standard time formats.
  • Supports positive and negative durations.
  • Allows for chaining time units (e.g., "1 hour 2 minutes" or "2 days and 2 hours").
  • Calculate durations relative to a specified date.
  • Relies on Chrono

Usage

Add parse_datetime to your Cargo.toml with:

cargo add parse_datetime

Then, import the crate and use the parse_datetime_at_date function:

use chrono::{Duration, Local};
use parse_datetime::parse_datetime_at_date;

let now = Local::now();
let after = parse_datetime_at_date(now, "+3 days");

assert_eq!(
  (now + Duration::days(3)).naive_utc(),
  after.unwrap().naive_utc()
);

For DateTime parsing, import the parse_datetime function:

use parse_datetime::parse_datetime;
use chrono::{Local, TimeZone};

let dt = parse_datetime("2021-02-14 06:37:47");
assert_eq!(dt.unwrap(), Local.with_ymd_and_hms(2021, 2, 14, 6, 37, 47).unwrap());

Supported Formats

The parse_datetime and parse_datetime_at_date functions support absolute datetime and the following relative times:

  • num unit (e.g., "-1 hour", "+3 days")
  • unit (e.g., "hour", "day")
  • "now" or "today"
  • "yesterday"
  • "tomorrow"
  • use "ago" for the past
  • use "next" or "last" with unit (e.g., "next week", "last year")
  • combined units with "and" or "," (e.g., "2 years and 1 month", "1 day, 2 hours" or "2 weeks 1 second")
  • unix timestamps (for example "@0" "@1344000")

num can be a positive or negative integer. unit can be one of the following: "fortnight", "week", "day", "hour", "minute", "min", "second", "sec" and their plural forms.

Return Values

parse_datetime and parse_datetime_at_date

The parse_datetime and parse_datetime_at_date function return:

  • Ok(DateTime<FixedOffset>) - If the input string can be parsed as a datetime
  • Err(ParseDateTimeError::InvalidInput) - If the input string cannot be parsed

Fuzzer

To run the fuzzer:

$ cd fuzz
$ cargo install cargo-fuzz
$ cargo +nightly fuzz run fuzz_parse_datetime

License

This project is licensed under the MIT License.

Note

At some point, this crate was called humantime_to_duration. It has been renamed to cover more cases.

Dependencies

~4–5.5MB
~97K SLoC