A Modern JavaScript Date Library

XDate is a thin wrapper around JavaScript's native Date object that provides enhanced functionality for parsing, formatting, and manipulating dates. It implements the same methods as the native Date, so it should seem very familiar.

Also, it is non-destructive to the DOM, so it can safely be included in third party libraries without fear of side effects.

Constructors

new XDate()

Creates a new XDate with the current date and time

new XDate(xdate)

Creates a copy of the given XDate

new XDate(nativeDate)

Creates a new XDate from a native Date

new XDate(milliseconds)

Creates a new XDate that is milliseconds since the UTC epoch.

new XDate(year, month, date, hours, minutes, seconds, milliseconds)

Creates a new XDate from the given values.

new XDate(dateString)

Read more about date-string parsing

With all the constructors, a final utcMode parameter can be appended as the last argument. If true, the XDate will be in UTC Mode.

The constuctors can be called without the new operator, as a function.

Getters

.getFullYear()

Returns the 4-digit year (ex: 2012)

.getMonth()

Returns the month of the year. (0-11)
Value is zero-index, meaning Jan=0, Feb=1, Mar=2, etc.

.getWeek()

Returns the ISO week number of the year. (1-53)

.getDate()

Returns the date of the month. (1-31)

.getDay()

Returns the day-of-week as a number. (0-6)
Sun=0, Mon=1, Tue=2, etc.

.getHours()

Returns the hour of the day. (0-23)

.getMinutes()

Returns the minute of the hour. (0-59)

.getSeconds()

Returns the second of the minute. (0-59)

.getMilliseconds()

Returns the millisecond of the second. (0-999)

.getTime()

Returns the number of milliseconds since the epoch.

.valueOf()

Returns the number of milliseconds since the epoch. Identical to getTime.

Setters

.setFullYear(year, preventOverflow)

year is a 4-digit year

.setMonth(month, preventOverflow)

month is zero-indexed, meaning Jan=0, Feb=1, Mar=2, etc.

.setWeek(week, year)

Moves the xdate to the Monday of the given week with time 00:00:00. The week is represented by a given ISO week number and an optional year. If year is omitted, the xdate's year with be used.

.setDate(date)

Sets the date of the month. (1-31)

.setHours(hours)

Sets the hour of the day. (0-23)

.setMinutes(minutes)

Sets the minute of the hour. (0-59)

.setSeconds(seconds)

Sets the second of the minute. (0-59)

.setMilliseconds(milliseconds)

Sets the millisecond of the second. (0-999)

.setTime(milliseconds)

Sets the number of milliseconds since the epoch.

Setting preventOverflow to true prevents a date from "overflowing" into the next month. Example:

d = new XDate(2011, 7, 31); // August 31
d.setMonth(8); // September
d.toString(); // October 1st!!! because there are only 30 says in September

// let's try this with preventOverflow...
d = new XDate(2011, 7, 31); // August 31
d.setMonth(8, true); // September
d.toString(); // September 30!

Setting preventOverflow to true guarantees the date will be in desired month. It is optional and defaults to false.

Adding

The following methods add or subtract time from the XDate:

.addYears(years, preventOverflow)

.addMonths(months, preventOverflow)

.addWeeks(weeks)

.addDays(days)

.addHours(hours)

.addMinutes(minutes)

.addSeconds(seconds)

.addMilliseconds(milliseconds)

If a value is negative, subtraction will occur. Values may be floating-point numbers.

Please note, these methods directly modify the object. Use clone if you need a copy.

Diffing

The following methods return the amount of time that must be added to the XDate in order to arrive at otherDate.

.diffYears(otherDate)

.diffMonths(otherDate)

.diffWeeks(otherDate)

.diffDays(otherDate)

.diffHours(otherDate)

.diffMinutes(otherDate)

.diffSeconds(otherDate)

.diffMilliseconds(otherDate)

otherDate can be an XDate, a native Date, a milliseconds time, or a date-string.

The results will be positive or negative depending on the ordering of the dates:

var thanksgiving = new XDate(2011, 10, 24);
var christmas = new XDate(2011, 11, 25);
thanksgiving.diffDays(christmas); // 31
christmas.diffDays(thanksgiving); // -31

Also, the result can potentially be a floating-point number:

var jan2011 = new XDate(2011, 0, 1);
var jul2012 = new XDate(2012, 6, 1);
jan2011.diffYears(jul2012); // 1.5

You'll have to do the rounding or flooring yourself.

Parsing

Date-strings must either be in ISO8601 format or IETF format (like "Mon Sep 05 2011 12:30:00 GMT-0700 (PDT)")

ISO8601 is the preferred format. Examples:

• "2011-09-05"
• "2011-09-05T12:30:00"
• "2011-09-05T12:30:00-07:00"
• "2011-09-05T12:30:00Z"

Advanced: extending the parser

Formatting

.toString(formatString, settings)

If formatString is not specified, a browser-produced IETF string will be returned. settings can be a name of an available locale or an object that overrides the default locale's settings.

.toUTCString(formatString, settings)

Same as toString but gets its values from the UTC version of the date. As a result, "Z" will be displayed as the timezone.

.toISOString()

Returns an ISO8601 string that has been normalized to UTC. Will have a "Z" timezone indicator. See the native Date's specs for toISOString.

.toDateString()

Same as native Date's toDateString

.toTimeString()

Same as native Date's toTimeString

.toLocaleString()

Same as native Date's toLocaleString

.toLocaleDateString()

Same as native Date's toLocaleDateString

.toLocaleTimeString()

Same as native Date's toLocaleTimeString

A formatString can contain any of the following tokens:

Example:

var d = new XDate(2012, 5, 8);
d.toString("MMM d, yyyy"); // "Jun 8, 2012"
d.toString("i");           // "2012-06-08T00:00:00"
d.toString("u");           // "2012-06-08T00:00:00-07:00"

If you want to have literal text in your formatString, enclose it in single quotes:

var d = new XDate(2012, 5, 8);
d.toString("'the month is' MMMM"); // "the month is June"

A literal single quote is represented by two consecutive single quotes.

If you want to output text only if certain values are non-zero, enclose your tokens in parenthesis:

new XDate(2011, 0, 1, 6, 0).toString('M/d/yy h(:mm)TT'); // "1/1/11 6AM"
new XDate(2011, 0, 1, 6, 30).toString('M/d/yy h(:mm)TT'); // "1/1/11 6:30AM"

Advanced:

• changing locale
• extending the formatter

UTC Methods

The following methods are similar to previously mentioned methods but operate on the UTC values of the date:

.getUTCFullYear()

.getUTCMonth()

.getUTCWeek()

.getUTCDate()

.getUTCDay()

.getUTCHours()

.getUTCMinutes()

.getUTCSeconds()

.getUTCMilliseconds()

.setUTCFullYear(year)

.setUTCMonth(month)

.setUTCWeek(week, year)

.setUTCDate(date)

.setUTCHours(hours)

.setUTCMinutes(minutes)

.setUTCSeconds(seconds)

.setUTCMilliseconds(milliseconds)

UTC Mode

Just like a native Date, an XDate is represented by its number of milliseconds since the epoch. Also like a native Date, methods like getDate and getHours are dependant upon the client computer's timezone.

However, you can remove this reliance on the client computer's timezone and make a UTC date, a date without a timezone. A date in UTC-mode will have all of its "get" methods identical to its "getUTC" methods and won't experience any daylight-savings time.

A true argument can be appended to any of the constructors to make an XDate in UTC-mode:

d = new XDate(true); // the current date, in UTC-mode
d.toString(); // "Mon, 24 Oct 2011 08:42:08 GMT"

d = new XDate(2012, 5, 8, true); // values will be interpreted as UTC
d.toString(); // "Fri, 08 Jun 2012 00:00:00 GMT"

d = new XDate('2012-06-08', true); // ambiguous timezone, so will be parsed as UTC
d.toString(); // "Fri, 08 Jun 2012 00:00:00 GMT"

Here are methods that relate to UTC-mode:

.getUTCMode()

Returns true if the date is in UTC-mode and false otherwise

.setUTCMode(utcMode, doCoercion)

utcMode must be either true or false. If the optional doCoercion parameters is set to true, the underlying millisecond time of the date will be coerced in such a way that methods like getDate and getHours will have the same values before and after the conversion.

.getTimezoneOffset()

Returns the number of minutes from UTC, just like the native Date's getTimezoneOffset. However, if the XDate is in UTC-mode, 0 will be returned.

Please note, these methods directly modify the object. Use clone if you need a copy.

Utilities

.clone()

returns a copy of the XDate

.clearTime()

sets the hours, minutes, seconds, and milliseconds to zero

.valid()

return true if the XDate is a valid date, false otherwise

.toDate()

Returns a conversion to a native Date

The following utilities are members of the XDate class and are not associated with a specific XDate instance:

XDate.getDaysInMonth(year, month)

Returns the number of days in the given month

XDate.parse(dateString)

Parses a date-string and returns milliseconds since the epoch. You'll probably want to use new XDate(dateString) instead.

XDate.now()

Returns the current date, as milliseconds since the epoch. You'll probably want to use new XDate() instead.

XDate.today()

Returns the current date with time cleared, as an XDate object

XDate.UTC(year, month, date, hours, minutes, seconds, milliseconds)

Returns a milliseconds time since the epoch for the given UTC date

Chaining

Many of XDate's methods return a reference to the same XDate object. This allows you to "chain" operations together and makes for more concise code:

d1 = new XDate();
d2 = d1.clone()
       .setUTCMode(true)
       .setDate(1)
       .addMonths(1)
       .addYears(2);

Inconsistencies with Native Date

XDate attempts to be "backwards-compatible" with the native Date object. However, there are two small departures that were made:

If you've never noticed, a native Date object returns it's millisecond value every time there is a "set" method. This is not very helpful. In the same situations, an XDate will return a reference to itself to allow for chaining. This is much more useful, but does not match the way the native Date works.

Also, when a native Date is concatenated with a string (with the + operator), the object will produce a date-string. However, this behavior was impossible to emulate with XDate, so please always explicitly use toString before concatenating with a string:

var nativeDate = new Date();
alert("my date: " + nativeDate); // "my date: Mon Sep 05 2011 13:12:23 GMT-0700 (PDT)"

var xdate = new XDate();
alert("my date: " + xdate); // "my date: 1315253543319"  <-- probably not what you wanted!
alert("my date: " + xdate.toString()); // "my date: Mon Sep 05 2011 13:12:23 GMT-0700 (PDT)"

Deprecated

The following methods are available, but please don't use them:

.getYear()

.setYear(twoDigitYear)