Skip to content

Home

Jump to bottom Edit New page
Adam Shaw edited this page Sep 14, 2011 · 7 revisions

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, hasTimezone)
Creates a new XDate that is milliseconds since the UTC epoch.
new XDate(year, month, date, hours, minutes, seconds, milliseconds, hasTimezone)
hasTimezone can be specified even if previous arguments are not.
new XDate(dateString)
read more about date-string parsing

hasTimezone is a boolean that defaults to true.

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

Timezones

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's timezone and essentially make a UTC date, a date without a timezone.

A date without a timezone will have all of its "get" methods be identical to its "getUTC" methods, won't experience any daylight-savings time, and won't have timezone information in its to-string methods.

.removeTimezone()
.addTimezone()
Forces the date to be in the client computer's timezone
.hasTimezone()
Returns true if there is a timezone, false otherwise
.getTimezoneOffset()
Returns the number of minutes from GMT, just like the native Date's getTimezoneOffset. However, if the XDate has no timezone, 0 will be returned.

These methods coerce the date in such a way that methods like getDate and getHours will have the same values both before and after the conversion. Example:

d = new XDate(2012, 0, 1);
d.toString();          // "Sun Jan 01 2012 00:00:00 GMT-0800 (PST)"
d.getHours();          // 0
d.getUTCHours();       // 8
d.getTimezoneOffset(); // 480
d.removeTimezone();
d.toString();          // "Sun Jan 01 2012 00:00:00"
d.getHours();          // 0
d.getUTCHours();       // 0
d.getTimezoneOffset(); // 0

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

Getters

.getFullYear()
Returns the 4-digit year
.getMonth()
Value is zero-index, meaning Jan=0, Feb=1, Mar=2, etc.
.getWeek()
Returns the ISO week of the year
.getDate()
Returns the date of the month
.getDay()
Returns the day-of-week as a number. Sun=0, Mon=1, Tue=2, etc.
.getHours()
.getMinutes()
.getSeconds()
.getMilliseconds()
.getTime()
Milliseconds since the epoch.
.valueOf()
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.
.setDate(date)
Set the date of the month
.setHours(hours)
.setMinutes(minutes)
.setSeconds(seconds)
.setMilliseconds(milliseconds)
Milliseconds since the epoch
.setTime(milliseconds)
Milliseconds since the epoch. Identical to setMilliseconds.

Setting preventOverflow to true prevents a date from overflowing into the next month. An example of an "overflow" would be setting August 31's month to September. The resulting date would October 1st since there are only 30 days in September.

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. Also, the 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 results can potentially be floating-point numbers:

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 IETF format (like "Mon Sep 05 2011 12:30:00 GMT-0700 (PDT)") or in ISO8601 format. 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"

For ISO8601 dates, timezones are parsed in certain ways:

  • If there is a timezone like "-07:00", the date will be converted to the client's timezone.
  • If "Z" is specified as the timezone, the date will be parsed as a UTC time but will still respect the client's timezone.
  • If no timezone is specified, the resulting date will have NO TIMEZONE (as if removeTimezone had been called).

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. Also, will display "Z" as the timezone.
.toISOString(displayOriginalTimezone)
Returns an ISO8601 string. By default, if the date has a timezone, the string will be displayed in UTC. However, if displayOriginalTimezone is true, the date will be displayed in the client's timezone.
.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:

fff milliseconds, 3-digits
s seconds
ss seconds, 2-digits
m minutes
mm minutes, 2-digits
h hours, 12-hour clock
hh hours, 12-hour clock, 2-digits
H hours, 24-hour clock
HH hours, 24-hour clock, 2-digits
d date number
dd date number, 2-digits
ddd day name, 3-characters (like "Sun")
dddd day name, full (like "Sunday")
M month number (Jan=1, Feb=2, etc)
MM month number, 2-digits
MMM month name, 3-characters (like "Jan")
MMMM month name, full (like "January")
yy year, 2-digits
yyyy year, 4-digits
t a/p
tt am/pm
T A/P
TT AM/PM
z timezone offset hour (like "-7")
zz timezone offset hour, 2-digits (like "-07")
zzz timezone offset hour, 2-digits, and minutes (like "-07:00")
w ISO week number
ww ISO week number, 2 digits
S day-of-week ordinal (like "st", "nd", "rd")

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

var d = new XDate(2011, 0, 1);
d.toString("'the month is' MMMM"); // "the month is January"

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:

Utilities

.clone()
returns a copy of the XDate
.clearTime()
sets the hours, minutes, seconds, and milliseconds to zero
.isValid()
return true if the XDate is a valid date, false otherwise
.toDate()
converts the XDate 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
XDate.now()
Returns the current date, as milliseconds since the epoch
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()
       .removeTimezone()
       .setDate(1)
       .addMonths(1)
       .addYears(2);

Incompatibilities with Native Date

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)"

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)
.setUTCDate(date)
.setUTCHours(hours)
.setUTCMinutes(minutes)
.setUTCSeconds(seconds)
.setUTCMilliseconds(milliseconds)

Deprecated

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

.getYear()
.setYear(twoDigitYear)
Add a custom footer
Add a custom sidebar
Clone this wiki locally