java.lang.Object | |
↳ | com.google.gwt.i18n.client.DateTimeFormat |
Formats and parses dates and times using locale-sensitive patterns.
Symbol | Meaning | Presentation | Example |
---|---|---|---|
G |
era designator | Text | AD |
y |
year | Number | 1996 |
L |
standalone month in year | Text or Number | July (or) 07 |
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 |
c |
standalone 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(see comment) |
Z |
time zone (RFC 822) | Text | -0800(See comment) |
v |
time zone id | Text | America/Los_Angeles(See comment) |
' |
escape for text | Delimiter | 'Date=' |
'' |
single quote | Literal | 'o''clock' |
The number of pattern letters influences the format, as follows:
"EEEE"
produces
"Monday"
, "EEE"
produces "Mon"
)"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."M"
produces "1"
, "MM"
produces "01"
,
"MMM"
produces "Jan"
, and "MMMM"
produces "January"
. Some pattern letters also treat a count
of 5 specially, meaning a single-letter abbreviation: L
,
M
, E
, and c
.
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.
[Time Zone Handling] Web browsers don't provide all the information we need for proper time zone formating -- so GWT has a copy of the required data, for your convenience. For simpler cases, one can also use a fallback implementation that only keeps track of the current timezone offset. These two approaches are called, respectively, Common TimeZones and Simple TimeZones, although both are implemented with the same TimeZone class. "TimeZone createTimeZone(String timezoneData)" returns a Common TimeZone object, and "TimeZone createTimeZone(int timeZoneOffsetInMinutes)" returns a Simple TimeZone object. The one provided by OS fall into to Simple TimeZone category. For formatting purpose, following table shows the behavior of GWT DateTimeFormat.
Pattern | Common TimeZone | Simple TimeZone |
---|---|---|
z, zz, zzz | PDT | UTC-7 |
zzzz | Pacific Daylight Time | UTC-7 |
Z, ZZ | -0700 | -0700 |
ZZZ | -07:00 | -07:00 |
ZZZZ | GMT-07:00 | GMT-07:00 |
v, vv, vvv, vvvv | America/Los_Angeles | Etc/GMT+7 |
The pattern does not need to specify every field. If the year, month, or day is missing from the pattern, the corresponding value will be taken from the current date. If the month is specified but the day is not, the day will be constrained to the last day within the specified month. If the hour, minute, or second is missing, the value defaults to zero.
As with formatting (described above), the count of pattern letters determines the parsing behavior.
Although the current pattern specification doesn't not specify behavior for all letters, it may in the future. It is strongly discouraged to use unspecified letters as literal text without quoting them.
[Note on TimeZone] The time zone support for parsing is limited. Only standard GMT and RFC format are supported. Time zone specification using time zone id (like America/Los_Angeles), time zone names (like PST, Pacific Standard Time) are not supported. Normally, it is too much a burden for a client application to load all the time zone symbols. And in almost all those cases, it is a better choice to do such parsing on server side through certain RPC mechanism. This decision is based on particular use cases we have studied; in principle, it could be changed in future versions.
Pattern | Formatted Text |
---|---|
"yyyy.MM.dd G 'at' HH:mm:ss vvvv" |
1996.07.10 AD at 15:08:56 America/Los_Angeles |
"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, vvvv" |
0:00 PM, America/Los_Angeles |
"yyyyy.MMMMM.dd GGG hh:mm aaa" |
01996.July.10 AD 12:08 PM |
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 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
.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
DateTimeFormat.PredefinedFormat | Predefined date/time formats -- see CustomDateTimeFormat if you
need some format that isn't supplied here. |
Protected Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Constructs a format object using the specified pattern and the date time
constants for the default locale.
| |||||||||||
This constructor is deprecated.
use
DateTimeFormat(String, DateTimeFormatInfo)
| |||||||||||
Constructs a format object using the specified pattern and user-supplied
date time constants.
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Format a date object using specified time zone.
| |||||||||||
Format a date object.
| |||||||||||
Returns a DateTimeFormat object using the specified pattern.
| |||||||||||
Get a DateTimeFormat instance for a predefined format.
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_FULL instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_TIME_FULL instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
TIME_FULL instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_LONG instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_TIME_LONG instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
TIME_LONG instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_MEDIUM instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_TIME_MEDIUM instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
TIME_MEDIUM instead
| |||||||||||
Retrieve the pattern used in this DateTimeFormat object.
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_SHORT instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
DATE_TIME_SHORT instead
| |||||||||||
This method is deprecated.
use
getFormat(PredefinedFormat) with
TIME_SHORT instead
| |||||||||||
This method modifies a
Date object to reflect the date that is
parsed from an input string. | |||||||||||
Parses text to produce a
Date value. | |||||||||||
Parses text to produce a
Date value. | |||||||||||
This method modifies a
Date object to reflect the date that is
parsed from an input string. |
Protected Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Internal factory method that provides caching.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Constructs a format object using the specified pattern and the date time constants for the default locale.
pattern | string pattern specification |
---|
This constructor is deprecated.
use DateTimeFormat(String, DateTimeFormatInfo)
Constructs a format object using the specified pattern and user-supplied date time constants.
pattern | string pattern specification |
---|---|
dateTimeConstants | locale specific symbol collection |
Constructs a format object using the specified pattern and user-supplied date time constants.
pattern | string pattern specification |
---|---|
dtfi | DateTimeFormatInfo instance to use |
Format a date object using specified time zone.
date | the date object being formatted |
---|---|
timeZone | a TimeZone object that holds time zone information |
Format a date object.
date | the date object being formatted |
---|
Returns a DateTimeFormat object using the specified pattern. If you need to
format or parse repeatedly using the same pattern, it is highly recommended
that you cache the returned DateTimeFormat
object and reuse it
rather than calling this method repeatedly.
Note that the pattern supplied is used as-is -- for example, if you
supply "MM/dd/yyyy" as the pattern, that is the order you will get the
fields, even in locales where the order is different. It is recommended to
use getFormat(PredefinedFormat)
instead -- if you use this method,
you are taking responsibility for localizing the patterns yourself.
pattern | string to specify how the date should be formatted |
---|
DateTimeFormat
object that can be used for format or
parse date/time values matching the specified patternIllegalArgumentException | if the specified pattern could not be parsed |
---|
Get a DateTimeFormat instance for a predefined format.
See CustomDateTimeFormat
if you need a localized format that is
not supported here.
predef | DateTimeFormat.PredefinedFormat describing desired format |
---|
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_FULL
instead
Retrieve the DateTimeFormat object for full date format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_TIME_FULL
instead
Retrieve the DateTimeFormat object for full date and time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
TIME_FULL
instead
Retrieve the DateTimeFormat object for full time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_LONG
instead
Retrieve the DateTimeFormat object for long date format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_TIME_LONG
instead
Retrieve the DateTimeFormat object for long date and time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
TIME_LONG
instead
Retrieve the DateTimeFormat object for long time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_MEDIUM
instead
Retrieve the DateTimeFormat object for medium date format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_TIME_MEDIUM
instead
Retrieve the DateTimeFormat object for medium date and time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
TIME_MEDIUM
instead
Retrieve the DateTimeFormat object for medium time format. The pattern for this format is predefined for each locale.
Retrieve the pattern used in this DateTimeFormat object.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_SHORT
instead
Retrieve the DateTimeFormat object for short date format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
DATE_TIME_SHORT
instead
Retrieve the DateTimeFormat object for short date and time format. The pattern for this format is predefined for each locale.
This method is deprecated.
use getFormat(PredefinedFormat)
with
TIME_SHORT
instead
Retrieve the DateTimeFormat object for short time format. The pattern for this format is predefined for each locale.
This method modifies a Date
object to reflect the date that is
parsed from an input string.
Dates are parsed leniently, so invalid dates will be wrapped around as
needed. For example, February 30 will wrap to March 2.
text | the string that need to be parsed |
---|---|
start | the character position in "text" where parsing should start |
date | the date object that will hold parsed value |
Parses text to produce a Date
value. An
IllegalArgumentException
is thrown if either the text is empty or
if the parse does not consume all characters of the text.
Dates are parsed leniently, so invalid dates will be wrapped around as
needed. For example, February 30 will wrap to March 2.
text | the string being parsed |
---|
IllegalArgumentException | if the entire text could not be converted into a number |
---|
Parses text to produce a Date
value. An
IllegalArgumentException
is thrown if either the text is empty or
if the parse does not consume all characters of the text.
Dates are parsed strictly, so invalid dates will result in an
IllegalArgumentException
.
text | the string being parsed |
---|
IllegalArgumentException | if the entire text could not be converted into a number |
---|
This method modifies a Date
object to reflect the date that is
parsed from an input string.
Dates are parsed strictly, so invalid dates will return 0. For example,
February 30 will return 0 because February only has 28 days.
text | the string that need to be parsed |
---|---|
start | the character position in "text" where parsing should start |
date | the date object that will hold parsed value |
Internal factory method that provides caching.