The full date, as serialized by JavaScript's built-in Date object.

NOTES

The full year, represented using four digits, where leading zeros will be added as needed for dates before the year 1000.

The year, represented using only two digits (i.e. only year of century).

When parsing a date string where the year is represented using the {YY} token, the year is assumed to be in the 20th century (i.e. the value 99 represents the year 1999). When formatting a date string where the year is represented using the {YY} token, century information will be lost. Therefore, this token can only be safely used in a date format that will be applied to dates in the 20th century.

The month number, represented always using two digits (i.e. leading 0 if necessary), where January is represented by the value 01, and where December is represented by the value 12.

The month number, represented using only as many digits as necessary (i.e. no leading 0), where January is represented by the value 1, and where December is represented by the value 12.

The full name of the month, as registered in the Uize.Date.monthNames static property of the Uize.Date module.

Unless overriding the value of the Uize.Date.monthNames static property, the month names will be the English names January, February, March, April, May, June, July, August, September, October, November, and December.

The short name of the month, as registered in the Uize.Date.shortMonthNames static property of the Uize.Date module.

Unless overriding the value of the Uize.Date.shortMonthNames static property, the short month names will be derived from the English month names, as Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.

The day number, represented always using two digits (i.e. leading 0 if necessary), where the first day of any month is represented by the value 01, and where the last day of the month January is represented by the value 31.

The day number, represented using only as many digits as necessary (i.e. no leading 0), where the first day of any month is represented by the value 1, and where the last day of the month January is represented by the value 31.

An English language suffix that can be appended after the value for the {dayNo} token in order to produce friendlier and more human readable date strings.

The suffixes 'st', 'nd', 'rd', and 'th' are registered in the Uize.Date.dayNoSuffixes static property of the Uize.Date module. The {dayNoSuffix} token can be combined with the {dayNo} token, as in {dayNo}{dayNoSuffix}, to produce formatted results like 1st, 2nd, 3rd, etc.

The rules for determining the suffix for a particular day number are as follows...

DAY NUMBER(S)  |  DAY NUMBER SUFFIX
---------------+-------------------
1              |  st
2              |  nd
3              |  rd
4-20           |  th
21             |  st
22             |  nd
23             |  rd
24-30          |  th
31             |  st

Because multiple days in a month can have the same day number suffix, the value of the {dayNoSuffix} token is ambiguous and is not considered meaningful when parsing date strings formatted using this token - it is simply ignored.

The full name of the day, as registered in the Uize.Date.dayNames static property of the Uize.Date module.

Unless overriding the value of the Uize.Date.dayNames static property, the day names will be the English names Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday. Because multiple days in a month can occur on the same day of the week and have the same day name, the value of the {dayName} token is ambiguous and is not considered meaningful when parsing date strings formatted using this token - it is simply ignored.

The short name of the day, as registered in the Uize.Date.shortDayNames static property of the Uize.Date module.

Unless overriding the value of the Uize.Date.shortDayNames static property, the short day names will be derived from the English day names, as Mon, Tue, Wed, Thu, Fri, Sat, and Sun. Because multiple days in a month can occur on the same day of the week and have the same short day name, the value of the {shortDayName} token is ambiguous and is not considered meaningful when parsing date strings formatted using this token - it is simply ignored.

The hour in military time (24-hour clock), represented always using two digits (i.e. leading 0 if necessary), where 12am (midnight) is represented by the value 00, where 12pm (midday) is represented by the value 12, and where 11pm is represented by the value 23.

The hour of the day in 12-hour notation, represented using only as many digits as necessary (i.e. no leading 0), where 12am (midnight) and 12pm (midday) are both represented by the value 12, and where 1am and 1pm are both represented by the value 1.

Because the {h12} token does not convey whether the time is in the first or second half of the day, this token should be used in conjunction with the companion {ampm} token.

The hour of the day in 12-hour notation, represented always using two digits (i.e. leading 0 if necessary), where 12am (midnight) and 12pm (midday) are both represented by the value 12, and where 1am and 1pm are both represented by the value 01.

Because the {hh12} token does not convey whether the time is in the first or second half of the day, this token should be used in conjunction with the companion {ampm} token.

The minutes of the hour, represented always using two digits (i.e. leading 0 if necessary), where the first minute of the hour is represented by the value 00, and where the last minute of the hour is represented by the value 59.

The minutes of the hour, represented using only as many digits as necessary (i.e. no leading 0), where the first minute of the hour is represented by the value 0, and where the last minute of the hour is represented by the value 59.

The seconds of the minute, represented always using two digits (i.e. leading 0 if necessary), where the first second of the minute is represented by the value 00, and where the last second of the minute is represented by the value 59.

The seconds of the minute, represented using only as many digits as necessary (i.e. no leading 0), where the first second of the minute is represented by the value 0, and where the last second of the minute is represented by the value 59.

The milliseconds of the second, represented always using three digits (i.e. leading zeros as necessary), where the first millisecond of the second is represented by the value 000, and where the last millisecond of the second is represented by the value 59.

The milliseconds of the second, represented using only as many digits as necessary (i.e. no leading zeros), where the first millisecond of the second is represented by the value 0, and where the last millisecond of the second is represented by the value 999.

An indicator of which half of the day the hour is in, where the first half of the day (morning) is represented by the value am, and where the second half of the day (afternoon and evening) is represented by the value pm.

When using either of the {h12} or {hh12} tokens to indicate hour of day in a date format string, it is important to also use the {ampm} token in order to disambiguate between the two halves of the day.

When formatting a date string using a specified date format, each date component token in the date format string is replaced by the corresponding date component token value for the date being formatted.

Any date format static text separating the tokens is left undisturbed and makes its way into the formatted date string. As you can tell from the above example, all the tokens have been replaced with the appropriate values for our example date, the historically significant September 11th, 2001. The static text - such as the comma, spaces, and the "of" - have been left in. The end result is an elegantly formatted date.

When parsing a date string to produce a date object, the date format must be specified in order for the parser to know how to parse the string.

The parser takes the specified date format string and translates it into a sophisticated regular expression that is used to match against the date string being parsed and then "capture" the values for the various date component tokens in the date format string. If the regular expression cannot be matched against a date string being parsed, then that date string is not formatted according to the specified date format, and the parser will produce the value undefined.

A date format string may contain static text arround the one or more date component tokens.

Static text can be used to introduce separator characters between year, month, and day, for example. Static text can also be used to create more elegant and more human readable date strings. For instance, in the date format string '{dayName}, {dayNo}{dayNoSuffix} of {monthName}, {YYYY}', the commas, spaces, and the "of" static text all contribute to friendlier date strings, such as the date string "Tuesday, 11th of September, 2001".

The formatting and parsing methods of the Uize.Date.Formatter module don't care which of the date component tokens are used or how they are used.

Insufficient tokens could be used to fully convey the date. Or, the same token could be used multiple times, either to produce silly results or to express a date in multiple ways in the same formatted result. The wrong tokens could be used in the wrong places to produce incorrect representations of a date. Bottom line: specifying a silly date format string will produce a silly result.

EXAMPLE

alert (
  Uize.Date.Formatter.format (
    new Date ('Sat Sep 8 2007 18:03:05'),
    '{ss}:{mm}:{h12}{ampm} on {YYYY}{dayNoSuffix} {monthName} {dayNo}',
  )
);

In the above example, the date 'Sat Sep 8 2007 18:03:05' is being formatted using the date format string '{ss}:{mm}:{h12}{ampm} on {YYYY}{dayNoSuffix} {monthName} {dayNo}', and the resulting date string is then displayed in an alert dialog. The alert dialog will show the value '05:03:6pm on 2007th September 8'. Any human reading this date string will be completely confused. It's not a date that makes any sense. That said, if this date string was parsed using the Uize.Date.Formatter.parse method and using the same format that was used to produce it, then the correct original date would be produced.

All values for date component tokens can implicitly have whitespace / padding around them.

Consider the following example...

EXAMPLE

Uize.Date.Formatter.parse ('2001 / 09 / 11','{YYYY}/{MM}/{DD}');

In the above example, the date string is being parsed using the date format '{YYYY}/{MM}/{DD}'. Now, even though there are no spaces around the slashes in the format, the values for the {YYYY}, {MM}, and {DD} tokens in the date string being parsed can implicitly have an arbitrary amount of surrounding whitespace padding. Therefore, the date string '2001 / 09 / 11', even though it does have whitespace padding around the slashes, can be parsed successfully. It's not that the slashes can have padding around them, but that any date component token value may have padding around it.

Whitespace within date format static text is implicitly treated as flexible, so that some whitespace between non-whitespace characters within the static text will be matched against some whitespace within the corresponding static text of a date string being parsed.

Consider the following example...

EXAMPLE

Uize.Date.Formatter.parse (
  'HISTORICALLY   IMPORTANT   DATE: 2001-09-11',
  'HISTORICALLY IMPORTANT DATE: {YYYY}-{MM}-{DD}'
);

In the above example, the date September 11th, 2001 will be successfully parsed from the date string, even though the static text in the date string contains more whitespace separating the words than the corresponding "HISTORICALLY IMPORTANT DATE" static text in the date format string.

Whitespace within date format static text in a date format string must exist within the corresponding static text in a date string being parsed in order for it to be parsed successfully.

Consider the following example...

EXAMPLE

Uize.Date.Formatter.parse (
  'HistoricallyImportantDate: 2001-09-11',
  'Historically Important Date: {YYYY}-{MM}-{DD}'
);

In the above example, the Uize.Date.Formatter.parse method will return the value undefined because it will not be able to successfully parse the date string. This is because the whitespace separating the words in the static text of the date format string must exist within the corresponding static text of the date being parsed. The exact amount of whitespace is not important, as long as the words / non-whitespace substrings are separated by whitespace in the same spots in both the date format string and the date string being parsed.