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:
but feel free to create a locale for your specific nationality and submit a pull request! :D
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.
<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>
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.
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.
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
.
Returns the ordinal for a given date.
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.
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.
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) }
An Object of all the available filters for formatting a Date.
IMPORTANT: Don't change these unless you know what you are doing!
An Object containing some default date formats:
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.
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)}
Checks to see if the Date instance is in between the two passed Dates.
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;
Clears the time from the Date instance.
Returns a clone of the current Date.
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:
NOTE: If any property — other than tense
& value
— is zero it will be omitted from the diff
Object.
( 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 from the diff
Object.+
will include the time unit in the diff
Object. Note: this is the same as not including the time unit in the exclusions
String.>
will exclude all time units from this time unit down from the diff
Object.
( new Date( 2012, 0, 1 ) ).diff( new Date( 2012, 0, 2 ), '-days' ) // returns => { tense : -1, value : 86400000, hours : 24 } ( new Date( 2012, 0, 2 ) ).diff( new Date( 2012, 0, 1 ), '-days' ) // returns => { tense : 1, value : 86400000, hours : 24 } ( new Date( 2012, 0, 1 ) ).diff( new Date( 2010, 9, 8, 7, 6, 5, 4 ), '-years -weeks >minutes' ) // returns => { tense : 1, value : 38858034996, months : 14, days : 29, hours : 18 }
Returns a string representation of the Date instance, based on the passed format. See the Date formatting and parsing options below.
( new Date( 2012, 0, 1 ) ).format( 'c' ); // returns => "2012-01-01T00:00:00.000Z" // which is a short hand format for: ( new Date( 2012, 0, 1 ) ).format( 'Y-m-d<T>H:i:s.u<Z>' ); // returns => "2012-01-01T00:00:00.000Z" ( new Date( 2012, 0, 1 ) ).format( 'l, <the> nS <of> F Y' ) // returns => "Sunday, the 1st of January 2012"
You can use predefined formats found in Date.formats
. Hint: You can do:
console.dir( Date.formats );
within your browser's JavaScript console to see a list of available formats.
Previously used formats are also cached to save the overhead of having to create a new Function
everytime you want to format a date.
Returns the zero based day of the year.
Returns a Date instance of the first day of this Date instance's month.
Returns the Date instances offset from GMT.
Returns the ISO day of the week.
Returns the ISO number of days in the year.
Returns the ISO first Monday of the year.
Returns the ISO week of the year
Returns the number of weeks in the ISO year.
Returns a Date instance of the last day of this Date instance's month.
Returns the week of the year, based on the dayOfYear
divided by 7.
( new Date( 2012, 0, 1 ) ).getWeek(); // returns => 0 ( new Date( 2012, 2, 13 ) ).getWeek(); // returns => 10 ( new Date( 2012, 11, 31 ) ).getWeek(); // returns => 52
Returns true if the Date instance is within daylight savings time.
Returns true if the Date instance is a leap year.
Returns a String representation of the difference between the date instance and now, or the passed Date
.
The default format is approx
, however this can be over-written by changing the locale file and/ or by passing in the desired format to the method.
var date = new Date( 2012, 0, 1 ); date.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'approx' ); // returns => "just over 2 days ago" date.clone().adjust( { hr : -3, day : -2 } ).lexicalize( date, 'exact' ); // returns => "2 days and 3 hours ago" date.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'approx' ); // returns => "almost 2 and a half days from now" date.lexicalize( date.clone().adjust( { hr : -6, day : -2 } ), 'exact' ); // returns => "2 days and 6 hours from now"
Sets the week of the year from the 1st January.
new Date( ( new Date( 2012, 0, 1 ) ).setWeek( 17 ) ); // returns => Date {Sun Apr 29 2012 00:00:00 GMT+0100 (BST)} ( new Date( 2012, 2, 13 ) ).setWeek( 17 ); // returns => 1335654000000 same as above ( new Date( 2012, 11, 31 ) ).setWeek( 17 ); // returns => 1335654000000
Returns the JavaScript engine's Date.prototype.toString() timezone abbreviation.
If you want to escape characters that are used by the Date parser you can wrap them between <>.
( new Date( 2012, 0, 1 ) ).format( 'l, <the> jS <of> F Y' ); // returns => "Sunday, the 1st of January 2012"
(The MIT License)
Copyright © 2012 christos “constantology” constandinou http://muigui.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.