Logo
doctype [?]
[strict] [loose] [none]

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
Yearyyyy4 digits4 digits
Yearyy2 digits2 digits
Yeary2 or 4 digits4 digits
MonthMMMName or AbbreviationName
MonthNNNAbbreviationAbbreviation
MonthMM2 digits (01-12)2 digits (01-12)
MonthM1 or 2 digits (1-12)1-2 digits (1-12)
Day of Monthdd2 digits (01-31)2 digits (01-31)
Day of Monthd1 or 2 digits (1-31)1-2 digits (1-31)
Day of WeekEEFull name (Sunday-Saturday)Full name
Day of WeekEAbbreviation (Sun-Sat)Abbreviation
Hourhh2 digits (01-12)2 digits (01-12)
Hourh1 or 2 digits (1-12)1-2 digits (1-12)
HourHH2 digits (00-23)2 digits (00-23)
HourH1 or 2 digits (0-23)1-2 digits (0-23)
HourKK2 digits (00-11)2 digits (00-11)
HourK1 or 2 digits (0-11)1-2 digits (0-11)
Hourkk2 digits (01-24)2 digits (01-24)
Hourk1 or 2 digits (1-24)1-2 digits (1-24)
Minutemm2 digits (00-59)2 digits (00-59)
Minutem1 or 2 digits (0-59)1-2 digits (0-59)
Secondss2 digits (00-59)2 digits (00-59)
Seconds1 or 2 digits (0-59)1-2 digits (0-59)
AM/PMaAM/am/PM/pmAM/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.

ArgumentTypeRequiredDescription
stringDateStringYesA date string to be parsed. ex: "January 1, 2000"
stringFormatStringNoIf 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.

ArgumentTypeRequiredDescription
stringDateStringYesA date string to be parsed. ex: "January 1, 2000"
stringFormatStringNoIf 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.

ArgumentTypeRequiredDescription
dateDateYesA 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.

ArgumentTypeRequiredDescription
dateDateYesA 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.

ArgumentTypeRequiredDescription
dateDateYesA 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.

ArgumentTypeRequiredDescription
dateDateYesA 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.

ArgumentTypeRequiredDescription
stringFormatStringYesThe 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.

ArgumentTypeRequiredDescription
stringIntervalStringYesThe time increment of the number to be added to the date. The interval must be one of:
ValueDescription
yYears
MMonths
dDays
wWeekdays (Mon-Fri)
hHours
mMinutes
sSeconds
Note the difference between M and m!
numberNumberYesThe number of time intervals to be added to the date

Returns: Date