rfc3339date.js¶ ↑

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

• ISO 8601

• RFC 3339

The Problem¶ ↑

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.

Obtaining¶ ↑

rfc3339date.js is hosted on github, with downloads available from [github.com/tardate/rfc3339date.js/downloads].

Usage¶ ↑

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 implamentation:

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 formating 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 supress date/time formating 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 supress 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 represention: 2010-07-20T15:00:00Z

• Dates with timezone offset are handled correctly: 2010-07-20T15:00:00+08:00

• Without timezone, local time is assumed: 2010-07-20T15:00:00

• Minutes and seconds are optional: 2010-07-20T15Z

• Fractional seconds supported: 2010-07-20T15:00:00.559Z

• Alternate fractional seconds separator as allowed by ISO 8601: 2010-07-20T15:00:00,559Z

• Separators are optional: 20100720T150000Z

• Not case-sensitive: 2010-07-20t15:00:00z

Limitations¶ ↑

• ISO 8601 Durations (e.g. P0003-06-04T12:30:05) are not supported

• ISO 8601 Time intervals (e.g. 2007-03-01T13: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

Compatibility¶ ↑

Tested for compatibilty/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.

Files in the Distribution¶ ↑

• rfc3339date.js - main javascript source file; all you need to run with

• MIT-LICENSE - official license file

• README.rdoc - 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

Kudos and Copyright¶ ↑

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

Thanks to contributions from:

• Shane Jonas [github.com/polarmobile]

Copyright © 2010 Paul GALLAGHER [tardate.com] Licensed under the MIT license: [www.opensource.org/licenses/mit-license.php]