Partial cross-browser polyfill to add ISO 8601 support to Date.parse and Date.prototype.toISOString as defined in ECMAScript 5.1. Originally based on Paul Gallagher's rfc3339date.js library.
Supports only the subset of ISO 8601 described in ECMAScript 5.1 section 15.9.4.2, RFC 3339, and the Date and Time Formats W3C NOTE.
Download iso8601.js and include before other scripts:
<script src="iso8601.min.js"></script>Using Sprockets 2? There's a gem version. Add to your Gemfile:
gem 'iso8601-js'For Rails 3.1+, the library is automatically added to your asset paths. For
other frameworks, add ISO8601JS.assets_path to your Sprockets environment:
env = Sprockets::Environment.new # or however you initialize Sprockets
env.append_path ISO8601JS.assets_pathInclude it in your JavaScript or CoffeeScript files with the = require
Sprockets directive:
JavaScript:
//= require iso8601CoffeeScript:
#= require iso8601Parse ISO 8601 date/time strings two ways:
- Date.parseISO8601 creates a Date instance from a ISO 8601 date string.
- Date.parse is polyfilled to attempt ISO 8601 parsing before using the
browser's native
Date.parse. Returns the number of milliseconds between the Unix epoch and the date. EC5 15.9.4.2
Examples:
Date.parseISO8601("2010-07-20T15:00:00Z")
// => Tue Jul 20 2010 08:00:00 GMT-0700 (PDT)
Date.parse("2010-07-20T15:00:00Z")
// => 1307834445456Format ISO 8601 date strings directly from Date instances:
- Date.prototype.toISOString generates an ISO 8601 UTC string.
EC5 15.9.5.32. Throws
RangeErrorfor invalid dates. - Date.prototype.toJSON generates an ISO 8601 UTC string for use by
JSON.stringify. Returns
nullfor invalid dates. EC5 15.9.5.44 - Date.prototype.toISO8601String generates an ISO 8601 string with
formatting options:
- localTimezone: Use local timezone with offset or UTC? Defaults to false.
- separators: Include date/time separator? Defaults to true.
- milliseconds: Include milliseconds? Defaults to true.
Examples:
var date = Date.parseISO8601("2010-07-20T15:00:00Z")
date.toISOString()
// => "2010-07-20T15:00:00.000Z"
date.toJSON()
// => "2010-07-20T15:00:00.000Z"
date.toISO8601String(true, true, false)
// => "2010-07-20T08:00:00-07:00"Other EC5 Date-related polyfills:
- Date.now returns the number of milliseconds since the Unix epoch. EC5 15.9.4.4
Examples:
Date.now()
// => 1325174662624The Date constructor is not polyfilled to support ISO 8601. Avoid using new Date("...") to parse strings.
iso8601.js is written in CoffeeScript. Use npm install to
install required development packages. Compile minified JavaScript output with
make. Run the test suite via make test.
Patches and bug reports are always welcome. Just send a pull request or file an issue.