Adds ISO 8601 / RFC 3339 date parsing to the Javascript Date object. References:

• ISO 8601
• RFC 3339

Many server-side languages (e.g. Ruby and Python JSON encoders) and data transfer formats (e.g. ATOM) emit RFC 3339 / ISO 8601 date formats but the standard Javascript Date object cannot parse these values, making client-side scripting involving dates a pain.

There have been snippets of code floating around the net for ages. rfc3339date.js is my attempt at rolling the best into an unobtrusive Date extension that also plays well with other libraries that also extend the Date class.

rfc3339date.js is hosted on GitHub, with downloads available from https://github.com/tardate/rfc3339date.js/downloads.

The parseRFC3339 class method provides direct access to the date parser:

 var d = Date.parseRFC3339( "2010-07-20T15:00:00Z" );
 // d is a Date object

Alternatively (and preferably), use the standard Date.parse method:

 var d = Date.parse( "2010-07-20T15:00:00Z" );
 // d is a Date object

When using Date.parse, date strings that do not match ISO 8601 / RFC 3339 will fall through to the default Date.parse implementation:

 var d = Date.parse( "Jul 9, 2010" );
 // NB: if handled by the default Javascript Date.parse implementation, this
 // will return the number of milliseconds since midnight of January 1, 1970

Two methods are provided for formatting dates as ISO 8601 / RFC 3339 date strings: toRFC3339UTCString converts to UTC format, and toRFC3339LocaleString converts with the current locale/timezone.

 var d = Date.parse( "2010-07-20T15:00:00Z" );
 d.toRFC3339UTCString();
 => "2010-07-20T15:00:00Z"
 d.toRFC3339LocaleString();
 => "2010-07-20T23:00:00+08:00" // assuming current timezone is GMT+8

You can suppress date/time formatting in the toRFC3339 methods by passing a first parameter:

 var d = Date.parse( "2010-07-20T15:00:00.333Z" );
 d.toRFC3339UTCString();
 => "2010-07-20T15:00:00.333Z"
 d.toRFC3339UTCString(true);
 => "20100720T150000.333Z"
 d.toRFC3339LocaleString(true);
 => "20100720T230000.333+0800" // assuming current timezone is GMT+8

You can also suppress millisecond display in the toRFC3339 methods by passing a second parameter:

 var d = Date.parse( "2010-07-20T15:00:00.333Z" );
 d.toRFC3339UTCString();
 => "2010-07-20T15:00:00.333Z"
 d.toRFC3339UTCString(true,true);
 => "20100720T150000Z"
 d.toRFC3339LocaleString(true,true);
 => "20100720T230000+0800" // assuming current timezone is GMT+8

== Supported Date Formats

• The default UTC representation: 2010年07月20日T15:00:00Z
• Dates with timezone offset are handled correctly: 2010年07月20日T15:00:00+08:00
• Without timezone, local time is assumed: 2010年07月20日T15:00:00
• Minutes and seconds are optional: 2010年07月20日T15Z
• Fractional seconds supported: 2010年07月20日T15:00:00.559Z
• Alternate fractional seconds separator as allowed by ISO 8601: 2010年07月20日T15:00:00,559Z
• Separators are optional: 20100720T150000Z
• Not case-sensitive: 2010年07月20日t15:00:00z

• ISO 8601 Durations (e.g. P0003-06-04T12:30:05) are not supported
• ISO 8601 Time intervals (e.g. 2007年03月01日T13:00:00Z/2008-05-11T15:30:00Z) are not supported
• ISO 8601 Repeating intervals (e.g. R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M) are not supported
• ISO 8601 Ordinal dates (e.g. YYYY-DDD) are not supported
• ISO Week Dates (e.g. YYYY-Www) are not supported
• ISO 8601:2000 truncated year formats are not supported

Tested for compatibility/coexistence with:

• jQuery
• datejs

If you are loading any javascript library that also overloads the Date.parse method, it is recommended that you load rfc3339date.js LAST. Any dates that rfc3339date cannot understand will be passed through to underlying Date.parse implementation.

• rfc3339date.js - main javascript source file; all you need to run with
• LICENSE - official license file
• README.md - this help file
• rfc3339date-test.htm - main unit test for core functionality
• rfc3339date_with_datejs-test.htm - unit test to verify compatibility when used with datejs
• unit_test_assets/ - files only needed to support the unit tests

Inspired by http://dansnetwork.com/2008/11/01/javascript-iso8601rfc3339-date-parser/

Thanks to contributions from:

• Shane Jonas [https://github.com/polarmobile]

See LICENSE for details.