Expand description
§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,days,weeks) and month intervals (months,years). 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.
§API
There are two entry points: parse_date_string and parse_duration. The
first 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;
extern crate chrono;
use chrono_english::{parse_date_string,Dialect};
use chrono::prelude::*;
let date_time = parse_date_string("next friday 8pm", Local::now(), Dialect::Uk)?;
println!("{}",date_time.format("%c"));There is a little command-line program parse-date in the examples folder which can be used to play
with these expressions.
The other function, parse_duration, lets you access just the relative part
of a string like ‘two days ago’ or ‘12 hours’. If successful, returns an
Interval, which is a number of seconds, days, or months.
use chrono_english::{parse_duration,Interval};
assert_eq!(parse_duration("15m ago").unwrap(), Interval::Seconds(-15 * 60));Structs§
Enums§
- A generic amount of time, in either seconds, days, or months.