Steve's Ultimate JavaScript Date Library

The JavaScript Date object is the best way to handle all your date manipulations within your JavaScript processing. The actual code that you need to use to perform some tasks though can range from sightly cumbersome to rather obscure. Well this library will solve all that. Here are all the additional methods that you need to add to your JavaScript date objects to make anything that you want to do with dates extremely easy. The library contains a range of methods including those to make adding (and subtracting) various periods of time easy, those to make date comparisons easy, and also a date format method that is based on the PHP option but provides more alternatives than the PHP one on which it is based.

The purpose of this page is to describe all of the methods that this library adds to your dates in JavaScript and how to use them. Note that I have included all the date methods that I can think of that would be useful so if you can think of a useful one that I have left out, please let me know so that I can add it. I also have some live examples of how to use these methods.

Update Dates and Times

This group of methods allow you to add a specified period to a date or time. You can also subtract periods just by making the value to be added negative.

There are a number of methods that I have added to the date object to make these additions and subtractions easy. Firstly there are those that only add or subtract one part of the date or time. The purpose of these methods is obvious from their names and each takes one parameter which is a number representing the period in the units that the method names indicate.

There is also one method that allows you to update all six of these at the same time using one call and passing the six values.

Compare Dates and Times

This group of methods will make many of the date comparisons that you are likely to need a much easier prospect. In each case since we are comparing dates the parameters that these methods expect are themselves date objects. These first two compare dates anre return the number of days between them. The difference between the two is that the business day version doesn't count Saturdays and Sundays. Note that the result will be a positive number of days regardless of which of the two dates comes first.

This next method is the one to use for determining someone's age on any date. Simply pass in their date of birth as the date object parameter and the function returns their age in whole years without the imprecision that some people end up with in their calculations. This method will increase their age by one only on their birthday.

Another useful comparison is to be able to test if one date/time is between two other date/times and so this method takes two date objects as parameters and returns true if the value of this date object is between them and false if it isn't.

Date Formatting

The biggest part of this library deals with the extraction of information about the date/time and formatting it. The easiest way to use this part of the library is to use the format method which takes one parameter which identifies to the method what information to retrieve and what format to retrieve it in. Most of the values that go in this character string are based on those that PHP uses for its equivalent method. The differences from the PHP one relate to the fact that JavaScript has no access to information about the current timezone to which the compter is set and therefore can't actually return the timezone name. As there are a number of additional pieces of information that can be relatively easily obtained and which the PHP version leaves out, I have added those as well.

The following characters have the specified meanings when included in the format_string.

  • d Day of the month, 2 digits with leading zeros 1-31
  • D A textual representation of a day, three letters Mon through Sun
  • j Day of the month without leading zeros 1 to 31
  • l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday
  • N ISO-8601 numeric representation of the day of the week 1 (for Monday) through 7 (for Sunday)
  • S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
  • w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
  • z The day of the year (starting from 0) 0 through 365
  • W ISO-8601 week number of year, weeks starting on Monday Example: 42 (the 42nd week in the year)
  • F A full textual representation of a month, such as January or March January through December
  • m Numeric representation of a month, with leading zeros 01 through 12
  • M A short textual representation of a month, three letters Jan through Dec
  • n Numeric representation of a month, without leading zeros 1 through 12
  • t Number of days in the given month 28 through 31
  • L Whether it's a leap year 1 if it is a leap year, 0 otherwise.
  • 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 Examples: 1999 or 2003
  • y A two digit representation of a year Examples: 99 or 03
  • a Lowercase Ante meridiem and Post meridiem am or pm
  • A Uppercase Ante meridiem and Post meridiem AM or PM
  • B Swatch Internet time 000 through 999
  • g 12-hour format of an hour without leading zeros 1 through 12
  • G 24-hour format of an hour without leading zeros 0 through 23
  • h 12-hour format of an hour with leading zeros 01 through 12
  • H 24-hour format of an hour with leading zeros 00 through 23
  • i Minutes with leading zeros 00 to 59
  • s Seconds, with leading zeros 00 through 59
  • u Microseconds (as JavaScript only calculates milliseconds the last three digits will always be zero)
  • e Timezone identifier (does nothing as JavaScript has no access to this info)
  • I (capital i) Whether or not the date is in daylight saving time 1 if Daylight Saving Time, 0 otherwise.
  • O Difference to Greenwich time (GMT) in hours Example: +0200
  • P Difference to Greenwich time (GMT) with colon between hours and minutes Example: +02:00
  • T Timezone abbreviation (does nothing as JavaScript has no access to this info)
  • Z Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive. -43200 through 50400
  • c ISO 8601 date Example: 2004-02-12T15:19:21+00:00
  • r RFC 2822 formatted date Example: Thu, 21 Dec 2000 16:01:07 +0200
  • U Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)

and the following additions just for JavaScript

  • X week number where weeks run Sunday to Saturday and 1st Jan is always in week 1
  • x as X bit with a leading zero where the week number is less than 10
  • R day of year with 1st Jan = 001 (always 3 digits including leading zeroes).
  • J Julian Day number
  • K returns 'DST for daylight saving time, otherwise returns 'Std'
  • ^ escapes the meaning of the following character so that it will display in the string returned instead of being interpreted as above

The following methods can also be called separately when you do not need the full power of the format method.

Get the Library

Simply download and unzip Steve's Ultimate JavaScript Date Library to use on your own site. All that I ask is that you keep the code including the copyright notice intact so that other people can find the library and these instructions on how to use it.


This article written by Stephen Chapman, Felgall Pty Ltd.

go to top

FaceBook Follow
Twitter Follow