d8

d8.js

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

d8 uses Templ8 to output a String representation of a Date, 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 from the native Date & Date.prototype respectively.

currently the only locales available are:

• en-GB
• en-US

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

WARNING!

This is an, as yet, untested and incompletely documented framework. Use at your own risk.

browser usage

<!-- IMPORTANT: Templ8 must be loaded before d8 -->
   <script src="/path/to/Templ8/Templ8.client.min.js" type="text/javascript"></script>
<!-- IMPORTANT: The correct locale must ALSO be loaded before d8! -->
   <script src="/path/to/d8/locale/en-GB.js" type="text/javascript"></script>
   <script src="/path/to/d8/d8.min.js" type="text/javascript"></script>

nodejs usage

   require( 'd8/locale/en-GB.js' ); // IMPORTANT: The correct locale must ALSO be loaded before d8!!
   require( 'd8' );

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.

API

Static methods

isLeapYear( year:String ):Boolean

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

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.

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.

Static properties

filters

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

Don't change this unless you know what you are doing!

formats

An Object containing some default date formats:

ISO_8601	Y-m-dH:i:sP
ISO_8601_SHORT	Y-m-d
RFC_850	l, d-M-y H:i:s T
RFC_2822	D, d M Y H:i:s O
sortable	Y-m-d H:i:sO

Instance methods

GMTOffset( colon:Boolean ):String

Returns the Date instances offset from GMT.

ISODay():Number

Returns the ISO day of the week.

ISODaysInYear():Number

Returns the ISO number of days in the year.

ISOFirstMondayOfYear():Date

Returns the ISO first Monday of the year.

ISOWeek():Number

Returns the ISO week of the year

ISOWeeksInYear():Number

Returns the number of weeks in the ISO year.

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

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, day, hr, min, sec, ms.

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

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

clearTime():Date

Clears the time from the Date instance.

clone():Date

Returns a clone of the current Date.

dayOfYear():Number

Returns the zero based day of the year.

firstOfTheMonth():Date

Returns a Date instance of the first day of this Date instance's month.

format( format:String ):String

Returns a string representation of the Date instance, based on the passed format. See the Date formatting and parsing options below.

isDST():Boolean

Returns true if the Date instance is within daylight savings time.

isLeapYear():Boolean

Returns true if the Date instance is a leap year.

lastOfTheMonth():Date

Returns a Date instance of the last day of this Date instance's month.

timezone():String

Returns the JavaScript engine's Date.prototype.toString() timezone abbreviation.

Date formatting and parsing options

day

d	Day of the month, 2 digits with leading zeros
D	A textual representation of a day, three letters
j	Day of the month without leading zeros
l	A full textual representation of the day of the week
N	ISO-8601 numeric representation of the day of the week
S	English ordinal suffix for the day of the month, 2 characters
w	Numeric representation of the day of the week
z	The day of the year (starting from 0)

### week

W	ISO-8601 week number of year, weeks starting on Monday

### month

F	A full textual representation of a month
m	Numeric representation of a month, with leading zeros
M	A short textual representation of a month, three letters
n	Numeric representation of a month, without leading zeros
t	Number of days in the given month

### year

L	Whether it's a leap year
o	ISO-8601 year number. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
Y	A full numeric representation of a year, 4 digits
y	A two digit representation of a year

### time

a	Lowercase Ante meridiem and Post meridiem
A	Uppercase Ante meridiem and Post meridiem
g	12-hour format of an hour without leading zeros
G	24-hour format of an hour without leading zeros
h	12-hour format of an hour with leading zeros
H	24-hour format of an hour with leading zeros
i	Minutes with leading zeros
s	Seconds, with leading zeros
u	Milliseconds

### timezone

O	Difference to Greenwich time (GMT) in hours
P	Difference to Greenwich time (GMT) with colon between hours and minutes
T	Timezone abbreviation
Z	Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.

### full date/time

c	ISO 8601 date
r	RFC 2822 formatted date
U	Seconds since the Unix Epoch January 1 1970 00:00:00 GMT