Parse and Format Date and Time in Erlang

This library implements basic functionality to parse and format date and time in Erlang.

Usage

Parsing

The datestring module exposes three functions for parsing:

• parse_date/2
• parse_time/2
• parse_datetime/2

All three functions take a format string as the first argument. The second argument should be a string containing the date to be parsed.

Note that time is not returned as a standard time-tuple ({H, M, S}), but a tuple containing a time-tuple and microseconds as an integer.

Examples:

{ok,{2012,12,24}} = datestring:parse_date("Y-m-d", "2012-12-24").

{ok,{{23,12,0},0}} = datestring:parse_time("I:M P", "11:12 p.m.").

{ok,{{2012,12,24},{{23,12,0},0}}} =
    datestring:parse_datetime("Y-m-d H:M", "2012-12-24 23:12").

{error,invalid_date} = datestring:parse_date("Y-m-d", "2012-13-24").

{error,no_match} = datestring:parse_date("d-m-Y", "2012-12-24").

Formatting Dates

• format/2

Format tuple containing date and/or time (with or without microseconds) according to a format string. format/2 takes a format string as it's first argument. The second argument can be either one of:

• A tuple containing a date ({2012, 12, 24}).
• A tuple of two tuples (time and microseconds) ({{23, 12, 0}, 0}).
• A tuple of two tuples (date and time) {{2012, 12, 24}, {23, 12, 0}})
• A tuple of two tuples (date and time+ms) {{2012, 12, 24}, {{23, 12, 0}, 0}})

Examples:

{ok,"2012-12-24"} = datestring:format("Y-m-d", {2012, 12, 24}).

{ok,"11:59 p.m."} = datestring:format("I:M P", {{23, 59, 30}, 0}).

{ok,"Monday, 24th December 2012"} =
    datestring:format("A, eo B Y", {2012, 12, 24}).

{ok,"2012-12-24 at 13:12"} =
    datestring:format("Y-m-d \\a\\t H:M", {{2012, 12, 24}, {13, 12, 32}}). 

Conversion Specification

The format used to parse and format dates closely resembles the one used in strftime()1. The most notable exception is that meaningful characters are not prefixed with a percentage sign (%) in datestring.

Characters not matching a conversion specification will be copied to the output verbatim when formatting and matched against input when parsing. Meaningful characters can be escaped with a backslash (\).

Character Sequence	Parsing	Formatting	Description
a	Yes*	Yes	Abbreviated weekday name ("Mon", "Tue")
A	Yes	Yes	Weekday name ("Monday", "Tuesday")
b	Yes*	Yes	Abbreviated month name ("Jan", "Feb")
B	Yes*	Yes	Month name ("January", "February")
d	Yes	Yes	Day of month with leading zero ("01", "31")
e	Yes	Yes	Day of month without leading zero ("1", "31")
F	No	Yes	ISO 8601 date format (shortcut for "Y-m-d")
H	Yes	Yes	Hour (24 hours) with leading zero ("01", "23")
I	Yes	Yes	Hour (12 hours) with leading zero ("01", "11")
k	Yes	Yes	Hour (24 hours) without leading zero ("1", "23")
l	Yes	Yes	Hour (12 hours) without leading zero ("1", "11")
m	Yes	Yes	Month with leading zero ("1", "12")
M	Yes	Yes	Minute with leading zero ("00", "59")
n	Yes	Yes	Month without leading zero ("1", "12")
o	Yes	Yes	Ordinal number suffix abbreviation (st, nd, rd, th)
p	Yes*	Yes	AM/PM
P	Yes*	Yes	a.m./p.m.
R	No	Yes	The time as H:M (24 hour format) ("23:59")
S	Yes	Yes	Seconds with leading zero ("00", "59")
T	No	Yes	The time as H:M:S (24 hour format) ("23:49:49")
u	Yes	Yes	Microseconds, 6 digits with leading zero ("000034")
y	Yes**	Yes	Year without century ("02", "12")
Y	Yes	Yes	Year including century ("2002", "2012")
z	Yes	No	UTC offset (+0100, +01:00, +01, -0100, -01:00, -01)
Z	Yes	No	Abbreviated timezone (UTC, GMT, CET etc)

* Case-insensitive when parsing

** Falls back on current century of system when parsing years without century.

Current Status

I wrote this library a ages ago. It was left forgotten in the darkest corners of my hdd until recently, when I needed to parse dates in a new project.

Everything has been working fine for the formats I've thrown at it, but the library needs more extensive testing. I'm also not sure about the API design.

Anyway, a little todo-list:

• More testcases.
• Convert TZ -> offset (probably just a translation table).
• Format offset (three notations "+HH", "+HHMM" and "+HH:MM") and TZs.
• Maybe add locale to the mix.
• Add specs, refactor a little, re-order patterns etc.