| Formats and parses dates and times using locale-sensitive patterns.
Patterns
| Symbol |
Meaning |
Presentation |
Example |
G |
era designator |
Text |
AD |
y |
year |
Number |
1996 |
M |
month in year |
Text or Number |
July (or) 07 |
d |
day in month |
Number |
10 |
h |
hour in am/pm (1-12) |
Number |
12 |
H |
hour in day (0-23) |
Number |
0 |
m |
minute in hour |
Number |
30 |
s |
second in minute |
Number |
55 |
S |
fractional second |
Number |
978 |
E |
day of week |
Text |
Tuesday |
a |
am/pm marker |
Text |
PM |
k |
hour in day (1-24) |
Number |
24 |
K |
hour in am/pm (0-11) |
Number |
0 |
z |
time zone |
Text |
Pacific Standard Time |
Z |
time zone (RFC 822) |
Number |
-0800 |
v |
time zone (generic) |
Text |
Pacific Time |
' |
escape for text |
Delimiter |
'Date=' |
'' |
single quote |
Literal |
'o''clock' |
The number of pattern letters influences the format, as follows:
- Text
- if 4 or more, then use the full form; if less than 4, use short or
abbreviated form if it exists (e.g.,
"EEEE" produces
"Monday", "EEE" produces "Mon")
- Number
- the minimum number of digits. Shorter numbers are zero-padded to this
amount (e.g. if
"m" produces "6",
"mm" produces "06"). Year is handled
specially; that is, if the count of 'y' is 2, the Year will be truncated to 2
digits. (e.g., if "yyyy" produces "1997",
"yy" produces "97".) Unlike other fields,
fractional seconds are padded on the right with zero.
- Text or Number
- 3 or more, use text, otherwise use number. (e.g.
"M"
produces "1", "MM" produces "01",
"MMM" produces "Jan", and "MMMM"
produces "January".
Any characters in the pattern that are not in the ranges of ['a'..'z']
and ['A'..'Z'] will be treated as quoted
text. For instance, characters like ':', '.', ' '
(space), '#' and '@' will appear in the
resulting time text even they are not embraced within single quotes.
Parsing Dates and Times
This implementation could parse partial date/time. Current date will be
used to fill in the unavailable date part. 00:00:00 will be used to
fill in the time part.
As with formatting (described above), the count of pattern letters determine
the parsing behavior.
- Text
- 4 or more pattern letters--use full form, less than 4--use short or
abbreviated form if one exists. In parsing, we will always try long format,
then short.
- Number
- the minimum number of digits.
- Text or Number
- 3 or more characters means use text, otherwise use number
Although the current pattern specification doesn't not specify behavior for
all letters, it may in the future. It is strongly discouraged to used
unspecified letters as literal text without being surrounded by quotes.
Examples
| Pattern |
Formatted Text |
"yyyy.MM.dd G 'at' HH:mm:ss vvvv" |
1996.07.10 AD at 15:08:56 Pacific Time |
"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, vvv" |
0:00 PM, PT |
"yyyyy.MMMMM.dd GGG hh:mm aaa" |
01996.July.10 AD 12:08 PM |
Additional Parsing Considerations
When parsing a date string using the abbreviated year pattern ("yy"),
the parser must interpret the abbreviated year relative to some century. It
does this by adjusting dates to be within 80 years before and 20 years after
the time the parser instance is created. For example, using a pattern of
"MM/dd/yy" and a DateTimeFormat object 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
java.lang.Character.isDigit(char) , will be
parsed into the default century. If the year pattern does not have exactly
two 'y' characters, the year is interpreted literally, regardless of the
number of digits. For example, 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.
In the current implementation, timezone parsing only supports
GMT:hhmm, GMT:+hhmm, and
GMT:-hhmm.
|
