back to Overview


Parses the given string as Date using the given format.
Util module only.


_.parseDate(format, dateString)


the format that describes the output
the string-formatted date to parse
(return value)
the Date; undefined if parsing failed; or null if the string was empty and the date format is flagged as optional ('?' at the beginning)


Parses the given string as Date using the given format. The format specifies which date component is expected where in the string. It can also be used to specify the timezone of the input string, and it may specify whether an empty string (including strings containing only whitespace) is allowed.

In the date format there are a number of reserved characters that are used as placeholders of date components. If you put a single character in the format, this will match numbers of any length. If you have two or more of the same character, this is recognized as fixed-length string.
Some placeholders, such as month names, support translations. To parse dates in other languages, you can specify a comma-separated list of translations in brackets following the placeholder.
The following placeholder characters are supported.

yYear (4 digits)
YYear (2 digits, 2000-based)
MMonth (1-12)
nMonth as short name ('Jan', 'Feb'...). Supports translations.
NMonth as long name ('January', 'February'...). Supports translations.
dDay of month (1-31)
mMinutes (0-59)
HHours in 24h format (0-23)
hHours in 12h format (1-12)
KHours in 0-based 12h format (0-11)
kHours in 1-based 24h format (1-24)
sSeconds (0-59)
SMilliseconds (0-999)
aEither 'am' or 'pm'. Supports translations.
wDay of week as short name ('Sun', 'Mon'...). Supports translations.
WDay of week as long name ('Sunday', 'Monday'...). Supports translations.
zTimezone offset, e.g. '+0700'
If you prefix the input string with a question mark ('?'), this means that the date is optional. If the input string is empty or consists solely of whitespace, parseDate will return null.
parseDate() also supports parsing a date in a different timezone. You only need to put the timezone in brackets at the front of the format, e.g. '[+0100]'.

All other characters are expected to be identical in format and input string, with the exception of whitespace. Each whitespace character in the format can match any number of other whitespace characters in the input string, but at least one.

Any components that are not in the format will be set to 0. For example, if your format has only date, month and day, the resulting date will be at midnight.


Parsing dates in various formats.

var v1  = _.parseDate('y-M-d', '2013-7-9');
var v2  = _.parseDate('?yyyyMMdd', '20130709');
var v3  = _.parseDate('?yyyyMMdd', ' ');  // returns null
var v4  = _.parseDate('yyyy-MM-ddTHH:mm:ss.SS z', '2013-07-09T23:07:38.472 +0700');
var v5  = _.parseDate('MM/dd/YY h:mm:ss a', '07/09/13 11:07:38 pm');
var v6  = _.parseDate('dd.MM.yyyy HH:mm:ss', '09.07.2013 23:07:38');
var v7  = _.parseDate('W, N d y', 'Tuesday, July 9 2013');
var v8  = _.parseDate('d.N[Januar,Februar,Maerz,April,Mai,Juni,Juli,'+
            'August,September,Oktober,November,Dezember] y', '9. Juli 2013'); // parsing german
var v9  = _.parseDate('[+0100]yyyy-MM-dd h:mm a', '2013-07-09 5:07 pm');  // different timezone:

See also..


comments powered by Disqus

back to Overview