d8.js

d8 is a date parsing and formatting micro-framework for modern JavaScript engines.

d8 formats Dates into Strings and conversley turns Strings into Dates based on php formatting options.

As d8 extends JavaScript's native Date & Date.prototype – the CORRECT way – there is no actual global called d8. Instead all static and instance methods are available on the native Date & Date.prototype respectively.

currently the only locales available are:

• en-GB (0.9kb gzipped)
• en-US (0.9kb gzipped)
• GR (1.1kb gzipped) this still needs some work as my Greek is — how you say — "hella-rusty"

but feel free to create a locale for your specific nationality and submit a pull request! :D

File size

• d8.js ≅ 8.8kb (gzipped)
• d8.min.js ≅ 5.2kb (minzipped)

Dependencies

d8.js only has one dependency m8.js.

NOTE: If you are using d8 within a commonjs module, you don't need to require m8 before requiring d8 as this is done internally.

Also, since d8.js simply extends the Native Date Class, a reference to m8 IS NOT stored.

browser usage

   <script src="/path/to/m8/m8.js" type="text/javascript"></script>

   <script src="/path/to/d8/d8.min.js" type="text/javascript"></script>
<!-- This should now come after the actual library, since it is now possible to have use locales at once -->
   <script src="/path/to/d8/locale/en-GB.js" type="text/javascript"></script>

nodejs usage

    require( 'd8' );
    require( 'd8/locale/en-GB' ); // NOTE: This should now come after the actual library, since it is now possible to have use locales at once

 // if running in a sandboxed environment remember to:
    require( 'm8' ).x( Date/*[, Object, Array, Boolean Function]*/ ); // and/ or any other Types that require extending.

As mentioned above d8 extends JavaScript's native Date & Date.prototype, so when requiring d8, you don't need to assign it to a variable to use d8's features.

Support

Tested to work with nodejs, FF4+, Safari 5+, Chrome 7+, IE9+ and Opera — with one exception: ( new Date( [] ) ).valid() ) returns true in Opera and false in every other browser — technically d8 should work in any JavaScript parser that supports ecma 5 without throwing any JavaScript errors.

API

Static methods

isLeapYear( year:String ):Boolean

Returns true if the passed 4 digit year is a leap year.

NOTE: This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to only return false.

getOrdinal( date:Number ):String

Returns the ordinal for a given date.

Example:

     Date.getOrdinal( 1 );  // returns => "st"
     Date.getOrdinal( 10 ); // returns => "th"
     Date.getOrdinal( 22 ); // returns => "nd"
     Date.getOrdinal( 33 ); // returns => "rd"

NOTE: Ordinals and the getOrdinal This method is located in the locale file. You can simply change the ordinal Array to your specific language; overwrite the getOrdinal method or both.

setLeapYear( date:Date ):Void

Sets the inlcuded locale's February day count to the correct number of days, based on whether or not the date is a leap year or not.

NOTE: This method is located in the locale file. If your calendar system does not contain leap years, you can simply change the method to do nothing.

toDate( date:String, format:String ):Date

Takes a date String and a format String based on the Date formatting and parsing options described below and returns a – hopefully – correct and valid Date.

    Date.toDate( 'Sunday, the 1st of January 2012', 'l, <the> jS <of> F Y' ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }
    Date.toDate( '2012-01-01T00:00:00+00:00',        Date.formats.ISO_8601 ); // returns => Date { Sun Jan 01 2012 00:00:00 GMT+0000 (GMT) }

Static properties

filters

An Object of all the available filters for formatting a Date.

IMPORTANT: Don't change these unless you know what you are doing!

formats

An Object containing some default date formats:

<table border="0" cellpadding="0" cellspacing="0" width="100%"> <tr><td width="96">ISO_8601</td><td>Y-m-d<T>H:i:sP</td> <tr><td width="96">ISO_8601_SHORT</td><td>Y-m-d</td> <tr><td width="96">RFC_850</td><td>l, d-M-y H:i:s T</td> <tr><td width="96">RFC_2822</td><td>D, d M Y H:i:s O</td> <tr><td width="96">sortable</td><td>Y-m-d H:i:sO</td> </table>

Instance methods

adjust( interval:Object|String[, value:Number] ):Date

Your one stop shop for all Date arithmetic. Adjusts the Date based on the passed interval, by the passed numeric value.

Note: The method also accepts a single Object param where each key is the interval and each value is the number to adjust the Date by.

Valid intervals are: year, month, week, day, hr, min, sec, ms.

Example:

    var date = new Date( 2012, 0, 1 ); // Date {Sun Jan 01 2012 00:00:00 GMT+0000 (GMT)}

    date.adjust( Date.DAY,   1 );      // Date {Mon Jan 02 2012 00:00:00 GMT+0000 (GMT)}
    date.adjust( Date.HOUR, -1 );      // Date {Sun Jan 01 2012 23:00:00 GMT+0000 (GMT)}
    date.adjust( {
       year : -1, month : -1, day : 24,
       hr   :  1, sec   : -1
    } );                               // Date {Sat Dec 25 2010 23:59:59 GMT+0000 (GMT)}

between( date_lower:Date, date_higher:Date ):Boolean

Checks to see if the Date instance is in between the two passed Dates.

Example:

    var date = new Date( 2012, 0, 1 );

    date.between( new Date( 2011, 0, 1 ), new Date( 2013, 0, 1 ) ); // returns => true;

    date.between( new Date( 2013, 0, 1 ), new Date( 2011, 0, 1 ) ); // returns => false;

clearTime():Date

Clears the time from the Date instance.

clone():Date

Returns a clone of the current Date.

diff( [date:Date, exclude:String] ):Object

Returns an Object describing the difference between the Date instance and now — or the optionally passed Date.

The Object will contain any or all of the following properties:

<table border="0" cellpadding="0" cellspacing="0" width="100%"> <thead> <tr><th width="32">Prop</th><th width="48">Type</th><th>Description</th></tr> </thead> <tbody> <tr><td width="48"><code>tense</code></td><td width="48">Number</td><td>This will either be: <dl> <dt><code>-1</code></dt><dd>The Date instance is less than now or the passed Date, i.e. in the past</dd> <dt><code>0</code></dt><dd>The Date instance is equal to now or the passed Date, i.e. in the present.<br /><strong>NOTE:</strong> If <code>tense</code> is <code>0</code> then the Object will most probably have no other properties, except <code>value</code>, which will be zero.</dd> <dt><code>1</code></dt><dd>The Date instance is greater than now or the passed Date, i.e. in the future</dd> </dl> <strong>NOTE:</strong> To make the <code>diff</code> Object's values easier to work with all other properties will be positive Numbers. You should use the <code>tense</code> property as your reference for the <code>diff</code> being in the past, present or future. </td></tr> <tr><td width="48"><code>value</code></td><td width="48">Number</td><td>The — absolute — number of milliseconds difference between the two Dates.</td></tr> <tr><td width="48"><code>years</code></td><td width="48">Number</td><td>The number of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>months</code></td><td width="48">Number</td><td>The months of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>weeks</code></td><td width="48">Number</td><td>The weeks of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>days</code></td><td width="48">Number</td><td>The days of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>hours</code></td><td width="48">Number</td><td>The hours of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>minutes</code></td><td width="48">Number</td><td>The minutes of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>seconds</code></td><td width="48">Number</td><td>The seconds of years the Date instance is ahead or behind the passed Date.</td></tr> <tr><td width="48"><code>milliseconds</code></td><td width="48">Number</td><td>The milliseconds of years the Date instance is ahead or behind the passed Date.</td></tr> </tbody> </table>

NOTE: If any property — other than tense & value — is zero it will be omitted from the diff Object.

Example:

     ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 1 ) )             // returns => { tense :  0 }

     ( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ) )             // returns => { tense : -1, value : 86400000,    days  : 1 }

     ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ) )             // returns => { tense :  1, value : 86400000,    days  : 1 }

     ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ) ) // returns => { tense :  1, value : 38858034996, years : 1, months : 2, weeks : 3, days : 3, hours : 17, minutes : 53, seconds : 54, ms : 995 }

NOTE: You can supply a space delimited String defining which properties you want to exclude from the result and diff will either pass the current calculation to the next time unit or, if there are none will round off — up if over .5 or down if less, uses Math.round to figure this out — to the previous time unit.

Exclusion codes:

• - will exclude the time unit f