#date-time #english #chrono #pattern #day #next #month


parses simple English dates, inspired by Linux date command

8 releases

Uses old Rust 2015

0.1.7 Dec 9, 2021
0.1.6 Mar 30, 2021
0.1.4 Nov 4, 2018
0.1.3 Sep 15, 2018
0.1.1 Mar 24, 2018

#57 in Date and time

Download history 2223/week @ 2023-12-18 1312/week @ 2023-12-25 2971/week @ 2024-01-01 3069/week @ 2024-01-08 4263/week @ 2024-01-15 3624/week @ 2024-01-22 3328/week @ 2024-01-29 4443/week @ 2024-02-05 3737/week @ 2024-02-12 2861/week @ 2024-02-19 3298/week @ 2024-02-26 3341/week @ 2024-03-04 3279/week @ 2024-03-11 3722/week @ 2024-03-18 4152/week @ 2024-03-25 2274/week @ 2024-04-01

13,530 downloads per month
Used in 34 crates (21 directly)

MIT license

996 lines

Parsing English Dates

I've always admired the ability of the GNU date command to convert "English" expressions to dates and times with date -d expr. chrono-english does similar expressions, although with extensions, so that for instance you can specify both the day and the time "next friday 8pm". No attempt at full natural language parsing is made - only a limited set of patterns is supported.

Supported Formats

chrono-english does absolute dates: ISO-like dates "2018-04-01" and the month name forms "1 April 2018" and "April 1, 2018". (There's no ambiguity so both of these forms are fine)

The informal "01/04/18" or American form "04/01/18" is supported. There is a Dialect enum to specify what kind of date English you would like to speak. Both short and long years are accepted in this form; short dates pivot between 1940 and 2040.

Then there are are relative dates like 'April 1' and '9/11' (this if using Dialect::Us). The current year is assumed, but this can be modified by 'next' and 'last'. For instance, it is now the 13th of March, 2018: 'April 1' and 'next April 1' are in 2018; 'last April 1' is in 2017.

Another relative form is simply a month name like 'apr' or 'April' (case-insensitive, only first three letters significant) where the day is assumed to be the 1st.

A week-day works in the same way: 'friday' means this coming Friday, relative to today. 'last Friday' is unambiguous, but 'next Friday' has different meanings; in the US it means the same as 'Friday' but otherwise it means the Friday of next week (plus 7 days)

Date and time can be specified also by a number of time units. So "2 days", "3 hours". Again, first three letters, but 'd','m' and 'y' are understood (so "3h"). We make a distinction between second intervals (seconds,minutes,hours), day intervals (days,weeks) and month intervals (months,years).

Second intervals are not followed by a time, but day and month intervals can be. Without a time, a day interval has the same time as the base time (which defaults to 'now')

Month intervals always give us the same date, if possible But adding a month to "30 Jan" will give "28 Feb" or "29 Feb" depending if a leap year.

Finally, dates may be followed by time. Either 'formal' like 18:03, with optional second (like 18:03:40) or 'informal' like 6.03pm. So one gets "next friday 8pm' and so forth.


There is exactly one entry point, which is given the date string, a DateTime from which relative dates and times operate, and a dialect (either Dialect::Uk or Dialect::Us currently.) The base time also specifies the desired timezone.

extern crate chrono_english;
use chrono_english::{parse_date_string,Dialect};

extern crate chrono;
use chrono::prelude::*;

let date_time = parse_date_string("next friday 8pm", Local::now(), Dialect::Uk)?;

There is a little command-line program parse-date in examples which can be used to play with these expressions:

$ alias p='cargo run --quiet --example parse-date --'
$ p 'next April'
base Wed Mar 14 20:10:37 2018 +0200
calc Sun Apr  1 00:00:00 2018 +0200
$ p '20/03/18 12:04'
base Wed Mar 14 20:12:44 2018 +0200
calc Tue Mar 20 12:04:00 2018 +0200
$ p '9/11/01' --american
base Wed Mar 14 20:13:08 2018 +0200
calc Tue Sep 11 00:00:00 2001 +0200
$ p 'next fri 8pm' '2018-03-14'
base Wed Mar 14 00:00:00 2018 +0200
calc Fri Mar 16 20:00:00 2018 +0200


~19K SLoC