A date pattern is a string of characters, where specific strings of characters are replaced with date and time data from a calendar when formatting or used to generate data for a calendar when parsing. The following are the characters used in patterns to show the appropriate formats for a given locale. The following are examples:
|Pattern||Result (in a particular locale)|
|yyyy.MM.dd G 'at' HH:mm:ss zzz||1996.07.10 AD at 15:08:56 PDT|
|EEE, MMM d, ''yy||Wed, July 10, '96|
|h:mm a||12:08 PM|
|hh 'o''clock' a, zzzz||12 o'clock PM, Pacific Daylight Time|
|K:mm a, z||0:00 PM, PST|
|yyyyy.MMMM.dd GGG hh:mm aaa||01996.July.10 AD 12:08 PM|
Characters may be used multiple times. For example, if y is used for the year, 'yy' might produce '99', whereas 'yyyy' produces '1999'. For most numerical fields, the number of characters specifies the field width. For example, if h is the hour, 'h' might produce '5', but 'hh' produces '05'. For some characters, the count specifies whether an abbreviated or full form should be used, but may have other choices, as given below.
Note: the counter-intuitive use of 5 letters for the narrow form of weekdays and months is forced by backwards compatibility.
|Era - Replaced with the Era string for the current date.|
|Year (of "Week of Year"), used in ISO year-week calendar. May differ from calendar year.|
|Extended year. This is a single number designating the year of this calendar system, encompassing all supra-year fields. For example, for the Julian calendar system, year numbers are positive, with an era of BCE or CE. An extended year value for the Julian calendar system assigns positive values to CE years and negative values to BCE years, with 1 BCE being year 0.|
|Month - Use one or two for the numerical month, three for the abbreviation, or four for the full name, or 5 for the narrow name.|
|Week of Year.|
|Week of Month|
|Date - Day of the month|
|Day of year|
|Day of Week in Month. The example is for the 2nd Wed in July|
|Modified Julian day. This is different from the conventional Julian day number in two regards. First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; that is, it depends on the local time zone. It can be thought of as a single number that encompasses all the date-related fields.|
|Day of week - Use three for the short day, or four for the full name, or 5 for the narrow name. Sunday is always day 1|
|Local day of week. Same as E except numeric value will depend on the local starting day of the week. For this example, Monday is the first day of the week.|
|AM or PM|
|Minute. Use one or two for zero padding.|
|Second. Use one or two for zero padding.|
|Fractional Second - rounds to the count of letters. (example is for 12.34567)|
|Milliseconds in day. This field behaves exactly like a composite of all time-related fields, not including the zone fields. As such, it also reflects discontinuities of those fields on DST transition days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This reflects the fact that is must be combined with the offset field to obtain a unique local time value.|
|Timezone. Use 1 for short wall (generic) time, 2 for long wall time, 3 for the short timezone (i.e. PST) or 4 for the full name (Pacific Standard Time). If there's no name for the zone, fallbacks may be used, depending on available data.|
Pacific Daylight Time
|Use 1 for GMT format, 2 for RFC 822|
All non-letter character represent themselves in a pattern, except for the single quote. It is used to 'escape' letters. Two single quotes in a row, whether inside or outside a quoted sequence, represent a 'real' single quote.
These are characters that can be used when displaying a date pattern to an end user. This can occur, for example, when a spreadsheet allows users to specify date patterns. Whatever is in the string is substituted one-for-one with the characters "GyMdkHmsSEDFwWahKzYe", with the above meanings. Thus, for example, if "J" is to be used instead of "Y" to mean Year, then the string would be: "GyMdkHmsSEDFwWahKzJe".
[TBD: fix list. Consider changing to be more structured.]
AM / PM
Even for countries where the customary date format only has a 24 hour format, both the am and pm localized strings must be present and must be distinct from one another. Note that as long as the 24 hour format is used, these strings will normally never be used, but for testing and unusual circumstances they must be present.
There are only two values for an era in a Gregorian calendar, "BC" and "AD". These values can be translated into other languages, like "a.C." and and "d.C." for Spanish, but there are no other eras in the Gregorian calendar. Other calendars have a different numbers of eras. Care should be taken when translating the era names for a specific calendar.
Week of Year
Values calculated for the Week of Year field range from 1 to 53. Week 1 for a year is the first week that contains at least the specified minimum number of days from that year. Weeks between week 1 of one year and week 1 of the following year are numbered sequentially from 2 to 52 or 53 (if needed). For example, January 1, 1998 was a Thursday. If the first day of the week is MONDAY and the minimum days in a week is 4 (these are the values reflecting ISO 8601 and many national standards), then week 1 of 1998 starts on December 29, 1997, and ends on January 4, 1998. However, if the first day of the week is SUNDAY, then week 1 of 1998 starts on January 4, 1998, and ends on January 10, 1998. The first three days of 1998 are then part of week 53 of 1997.
Values are similarly calculated for the Week of Month.
A number indicating which day of the week is considered the 'first' day, for calendar purposes. Because the ordering of days may vary between calendar, keywords are used for this value, such as sun, mon,... These values will be replaced by the localized name when they are actually used.
minDays (Minimal Days in First Week)
Minimal days required in the first week of a month or year. For example, if the first week is defined as one that contains at least one day, this value will be 1. If it must contain a full seven days before it counts as the first week, then the value would be 7.
Indicates the day and time that the weekend starts or ends. As with firstDay, keywords are used instead of numbers.