Format specification for the Time Format plug-in functions
The format and parse functions make use of the SimpleDateFormat class provided in the International Components for Unicode libraries. SimpleDateFormat is a class for formatting and parsing dates in a language-independent manner.
Pattern letters in format strings
The Time Format plug-in functions use the SimpleDateFormat class to transform between a string that contains a time and/or date and a normalized representation of that time and/or date. In this case, the normalized representation is the number of seconds since the epoch.
For the operation to succeed, it is important to define the format string so that it exactly represents the format of the time and/or date you provide as a string in the timeDate parameter to a parse function, or expect to be returned from a format function. You specify the format as a time pattern. In this pattern, all ASCII letters are reserved as pattern letters.
The number of pattern letters determines the format as follows:
For pattern letters that represent text
If you specify four or more letters, the
SimpleDataFormat class transforms the full form. For example,
EEEE formats/parses
Monday.
If you specify fewer than four letters, the
SimpleDataFormat class transforms the short or abbreviated form if it exists. For example,
E,
EE, and
EEE each formats/parses
Mon.
For pattern letters that represent numbers
Specify the minimum number of digits.
If necessary,
SimpleDateFormat prepends zeros to shorter numbers to equal the number of digits you specify. For example,
m formats/parses
6,
mm formats/parses
06.
Year is handled specially. If the count of
y is 2, the year is truncated to 2 digits. For example,
yyyy formats/parses
1997, while
yy formats/parses
97.
Unlike other fields, fractional seconds are padded on the right with zeros.
For pattern letters that can represent text or numbers
If you specify three or more letters, the
SimpleDataFormat class transforms text. For example,
MMM formats/parses
Jan, while
MMMM formats/parses
January.
If you specify one or two letters, the
SimpleDataFormat class transforms a number. For example,
M formats/parses
1, and
MM formats/parses for
01.
The following tables provides the meaning of each letter you can specify in a pattern. After the table, there are a number of combined examples.
Descriptions of pattern letters in format strings
Symbol | Meaning | Presentation | Example | Sample Result |
G | Era designator | Text | G G | AD BC |
y (lower- case) | Year | Number | yy yyyy | 96 1996 |
Y (upper- case) | Year for indicating which week of the year. Use with the w symbol. See Week in year later in this table. | Number | See example for Week in year. | |
u | Extended year | Number | uuuu | 5769 |
M | Month in year | Text or Number | M MM MMM MMMM | 9 09 Sep September |
d | Day in month | Number | d dd dd | 7 07 25 |
h | Hour in AM or PM (1—12) | Number | hh | 05 |
H | Hour in day (0—23) | Number | H HH HH | 0 05 14 |
m | Minute in hour | Number | m mm mm | 3 03 55 |
s | Second in minute | Number | s ss ss | 5 05 59 |
S | Fractional second | Number | S SS SSS | 2 20 200 |
E | Day of week | Text | E EE EEE EEEE | Fri Fri Fri Friday |
e | Day of week (1—7) This is locale dependent. Typically, Monday is 1. | Number | e | 4 |
D | Day in year | Number | D DD DDD DDD | 7 07 007 123 |
F | Day of particular week in month (1 — 7). Use with W (uppercase) for week in month. See Week in month later in this table. | Number | See example for Week in month. | |
w (lower- case) | Week in year. Use with uppercase Y. The week that contains January 1st is week 1. For example, if a week starts on Monday and ends on Sunday, and if January 1st is a Sunday, then week 1 contains December 26 - 31 plus January 1. | Number | The first example below uses uppercase Y. The second example shows the difference when you use lowercase y. "'Week' w YYYY" "'Week' w yyyy" | Suppose you are transforming December 31st, 2008, which is a Wednesday. “Week 1 2009” “Week 1 2008” |
W (upper- case) | Week in month. The week that contains the 1st of the month is week 1. For example, if a week starts on Monday and ends on Sunday, and if July 1 is a Friday (5), then week 1 of July contains June 27 - 30 and July 1 - 3. | Number | "'Day' F 'of Week' W" | "Day 2 of Week 3" |
a | AM/PM marker | Text | a a | AM PM |
k | Hour in day (1—24) | Number | k kk kk | 1 01 24 |
K | Hour in AM/PM (0—11) | Number | K KK KK | 0 07 11 |
z | Time zone | Text | z | Pacific Standard Time |
Z | Time zone (RFC 822) | Number | Z | -0800 |
v | Generic time zone | Text | v | Pacific Time |
V | Time zone abbreviation | Text | V | PT |
VVVV | Time zone location | Text | VVVV | United States (Los Angeles) |
g | Julian day | Number | g | 2451334 |
A | Milliseconds in day | Number | A | 69540000 |
' | Escape for text | Delimiter | "'Week' w YYYY" | "Week 1 2009" |
'' | Single quote | Literal | "KK 'o''clock'" | "11 o'clock" |
Any character in the format pattern that is not in the range of [‘a’..‘z’] or [‘A’..‘Z’] is treated as quoted text. For example, the following characters can be in a timeDate string without being enclosed in quotation marks:
: . , # @
A pattern that contains an invalid pattern letter results in a -1 return value.
The following table gives examples that assume the US locale:
Format pattern | Suitable timeDate string |
yyyy.MM.dd G 'at' HH:mm:ss z | 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.MMMMM.dd GGG hh:mm aaa | 1996.July.10 AD 12:08 PM |
When parsing a date string using the abbreviated year pattern (y or yy), SimpleDateFormat (and hence all parse functions) must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 79 years before and 19 years after the time the SimpleDateFormat instance is created. For example, using a pattern of MM/dd/yy and a SimpleDateFormat instance created on Jan 1, 1997, the string 01/11/12 would be interpreted as Jan 11, 2012 while the string 05/04/64 would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits, as defined by Unicode::isDigit(), will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that is not all digits (for example, -1), is interpreted literally. So 01/02/3 or 01/02/003 are parsed, using the same pattern, as Jan 2, 3 A.D. Likewise, 01/02/-3 is parsed as Jan 2, 4 B.C. Behavior is undefined if you specify a two-digit date that might be either twenty years in the future or eighty years in the past.
If the year pattern has more than two y characters, the year is interpreted literally, regardless of the number of digits. So using the pattern MM/dd/yyyy, 01/11/12 parses to Jan 11, 12 A.D.
When numeric fields abut one another directly, with no intervening delimiter characters, they constitute a run of abutting numeric fields. Such runs are parsed specially. For example, the format HHmmss parses the input text 123456 to 12:34:56, parses the input text 12345 to 1:23:45, and fails to parse 1234. In other words, the leftmost field of the run is flexible, while the others keep a fixed width. If the parse fails anywhere in the run, then the leftmost field is shortened by one character, and the entire run is parsed again. This is repeated until either the parse succeeds or the leftmost field is one character in length. If the parse still fails at that point, the parse of the run fails.
For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or GMT-hours:minutes.
The calendar defines what is the first day of the week, the first week of the year, whether hours are zero based or not (0 vs. 12 or 24), and the time zone. There is one common number format to handle all the numbers; the digit count is handled programmatically according to the pattern.
Midnight and noon
The format "HH:mm" parses "24:00" as midnight that ends the day. Given the formal "hh:mm a", both "00:00 am" and "12:00 am" parse as the midnight that begins the day. Note that "00:00 pm" and "12:00 pm" are both midday.