Date Formatting And Format Validation

The date.js library extends the built-in Date object in javascript by adding class methods and instance methods. No global identifiers are used, so the global namespace stays clean. The goal of the library is to provide additional features for Date objects. The available methods are explained in detail below.

Format Strings

The methods to parse and format dates use syntax that is similar to Java's java.text.SimpleDateFormat class with some minor exceptions. In the table below, note the difference between M and m! MM and M are for months, mm and m are for minutes.

Field	Syntax	Parse	Format
Year	yyyy	4 digits	4 digits
Year	yy	2 digits	2 digits
Year	y	2 or 4 digits	4 digits
Month	MMM	Name or Abbreviation	Name
Month	NNN	Abbreviation	Abbreviation
Month	MM	2 digits (01-12)	2 digits (01-12)
Month	M	1 or 2 digits (1-12)	1-2 digits (1-12)
Day of Month	dd	2 digits (01-31)	2 digits (01-31)
Day of Month	d	1 or 2 digits (1-31)	1-2 digits (1-31)
Day of Week	EE	Full name (Sunday-Saturday)	Full name
Day of Week	E	Abbreviation (Sun-Sat)	Abbreviation
Hour	hh	2 digits (01-12)	2 digits (01-12)
Hour	h	1 or 2 digits (1-12)	1-2 digits (1-12)
Hour	HH	2 digits (00-23)	2 digits (00-23)
Hour	H	1 or 2 digits (0-23)	1-2 digits (0-23)
Hour	KK	2 digits (00-11)	2 digits (00-11)
Hour	K	1 or 2 digits (0-11)	1-2 digits (0-11)
Hour	kk	2 digits (01-24)	2 digits (01-24)
Hour	k	1 or 2 digits (1-24)	1-2 digits (1-24)
Minute	mm	2 digits (00-59)	2 digits (00-59)
Minute	m	1 or 2 digits (0-59)	1-2 digits (0-59)
Second	ss	2 digits (00-59)	2 digits (00-59)
Second	s	1 or 2 digits (0-59)	1-2 digits (0-59)
AM/PM	a	AM/am/PM/pm	AM/PM

Class Properties

These properties are added to the Date object for formatting and parsing. For locales other than the default English/American, they should be changed via script. It is not recommended that the values be changed in the js file itself, since that would require the changes to be made to each revision or update of the js file from this site.

monthNames

A 12-element array holding the full month names.

monthAbbreviations

A 12-element array holding month abbreviations

dayNames

A 7-element array holding full day names

dayAbbreviations

A 7-element array holding day abbreviations

preferAmericanFormat

A boolean value used only when parsing date strings when no format is specified. It is used for parsing ambiguous dates like 1/2/2000 - which in 'American' format would mean Jan 2 and in 'European' format would mean Feb 1. The value defaults to 'true' which means to interpret ambiguous dates in American format. Set that value to 'false' to prefer European format.

Class Methods

These methods are added as part of the Date object itself, and do not need an instantiated Date object.

parseString (stringDate [,stringFormat]) : Date

This method takes a string representation of a date and converts it to a Date object.

Argument	Type	Required	Description
stringDate	String	Yes	A date string to be parsed. ex: "January 1, 2000"
stringFormat	String	No	If specified, a format string that must be matched exactly by the stringDate using the available Format Strings, and any other text. If not specified, the method will automatically attempt to match any of the following formats: y-M-d    MMM d, y    MMM d,y    y-MMM-d    d-MMM-y    MMM d    MMM-d    d-MMM    M/d/y    M-d-y    M.d.y    M/d    M-d    d/M/y    d-M-y    d.M.y    d/M    d-M

Returns: Date, or null if the string could not be parsed.

isValid (stringDate [,stringFormat]) : Boolean

This method is a convenience wrapper around parseString. If parseString returns null, this method returns false. Otherwise, it returns true.

Argument	Type	Required	Description
stringDate	String	Yes	A date string to be parsed. ex: "January 1, 2000"
stringFormat	String	No	If specified, a format string that must be matched exactly by the stringDate. If not specified, the method will automatically attempt to match any of the following formats: y-M-d    MMM d, y    MMM d,y    y-MMM-d    d-MMM-y    MMM d    MMM-d    d-MMM    M/d/y    M-d-y    M.d.y    M/d    M-d    d/M/y    d-M-y    d.M.y    d/M    d-M

Returns: Boolean

Instance Methods

These methods are added to created Date objects. For example:

var d = new Date();
d.methodName();

isBefore (date) : Boolean

Compares the Date object with a passed Date object. If the date is before the passed date object, it returns true. Otherwise, returns false.

Argument	Type	Required	Description
date	Date	Yes	A Date object to be compared

Returns: Boolean

isAfter (date) : Boolean

Compares the Date object with a passed Date object. If the date is after the passed date object, it returns true. Otherwise, returns false.

Argument	Type	Required	Description
date	Date	Yes	A Date object to be compared

Returns: Boolean

equals (date) : Boolean

Compares the Date object with a passed Date object. If the dates and times are equal, it returns true. Otherwise, returns false.

Argument	Type	Required	Description
date	Date	Yes	A Date object to be compared

Returns: Boolean

equalsIgnoreTime (date) : Boolean

Compares the Date object with a passed Date object. If the dates values are equal (year, month, date) - regardless of the time values of each- then it returns true. Otherwise, returns false.

Argument	Type	Required	Description
date	Date	Yes	A Date object to be compared

Returns: Boolean

format (stringFormat) : String

Converts the date into a String representation using the format specified. The format string should use the Format Strings above and any other characters.

Argument	Type	Required	Description
stringFormat	String	Yes	The string format to convert the date to

Returns: String

getDayName () : String

Returns the name of the day of the week for the Date, using the Date.dayNames array.

Returns: String

getDayAbbreviation () : String

Returns the abbreviation of the day of the week for the Date, using the Date.dayAbbreviations array.

Returns: String

getMonthName () : String

Returns the name of the month for the Date, using the Date.monthNames array.

Returns: String

getMonthAbbreviation () : String

Returns the abbrevation of the month for the Date, using the Date.monthAbbreviations array.

Returns: String

clearTime () : Date

Sets the hours, minutes, seconds, and milliseconds values of the date object all to 0 and returns the object.

Returns: Date

add (stringInterval, number) : Date

Adds a certain amount of time to a date object. The interval of time to be added and the number of intervals must both be passed.

Argument	Type	Required	Description
stringInterval	String	Yes	The time increment of the number to be added to the date. The interval must be one of: Value Description y Years M Months d Days w Weekdays (Mon-Fri) h Hours m Minutes s Seconds Note the difference between M and m!
number	Number	Yes	The number of time intervals to be added to the date

Returns: Date