com.google.gwt.i18n.client
Class DateTimeFormat

java.lang.Object
  com.google.gwt.i18n.client.DateTimeFormat

public class DateTimeFormat
extends java.lang.Object

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 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.

Constructor Summary

protected	DateTimeFormat(java.lang.String pattern) Constructs a format object using the specified pattern and the date time constants for the default locale.
protected	DateTimeFormat(java.lang.String pattern, com.google.gwt.i18n.client.constants.DateTimeConstants dateTimeConstants) Constructs a format object using the specified pattern and user-supplied date time constants.

Method Summary

java.lang.String	format(java.util.Date date) Format a date object.
static DateTimeFormat	getFormat(java.lang.String pattern) Returns a format object using the specified pattern and the date time constants for the default locale.
static DateTimeFormat	getFullDateFormat()
static DateTimeFormat	getFullDateTimeFormat()
static DateTimeFormat	getFullTimeFormat()
static DateTimeFormat	getLongDateFormat()
static DateTimeFormat	getLongDateTimeFormat()
static DateTimeFormat	getLongTimeFormat()
static DateTimeFormat	getMediumDateFormat()
static DateTimeFormat	getMediumDateTimeFormat()
static DateTimeFormat	getMediumTimeFormat()
java.lang.String	getPattern()
static DateTimeFormat	getShortDateFormat()
static DateTimeFormat	getShortDateTimeFormat()
static DateTimeFormat	getShortTimeFormat()
java.util.Date	parse(java.lang.String text) Parses text to produce a Date value.
int	parse(java.lang.String text, int start, java.util.Date date) This method parses the input string, fill its value into a Date.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DateTimeFormat

protected DateTimeFormat(java.lang.String pattern)

Constructs a format object using the specified pattern and the date time constants for the default locale.

Parameters:

pattern - string pattern specification

DateTimeFormat

protected DateTimeFormat(java.lang.String pattern,
                         com.google.gwt.i18n.client.constants.DateTimeConstants dateTimeConstants)

Constructs a format object using the specified pattern and user-supplied date time constants.

Parameters:

pattern - string pattern specification

dateTimeConstants - locale specific symbol collection

Method Detail

getFormat

public static DateTimeFormat getFormat(java.lang.String pattern)

Returns a format object using the specified pattern and the date time constants for the default locale. 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.

Parameters:

pattern - string to specify how the date should be formatted

Returns:

a DateTimeFormat object that can be used for format or parse date/time values matching the specified pattern

Throws:

java.lang.IllegalArgumentException - if the specified pattern could not be parsed

getFullDateFormat

public static DateTimeFormat getFullDateFormat()

getFullDateTimeFormat

public static DateTimeFormat getFullDateTimeFormat()

getFullTimeFormat

public static DateTimeFormat getFullTimeFormat()

getLongDateFormat

public static DateTimeFormat getLongDateFormat()

getLongDateTimeFormat

public static DateTimeFormat getLongDateTimeFormat()

getLongTimeFormat

public static DateTimeFormat getLongTimeFormat()

getMediumDateFormat

public static DateTimeFormat getMediumDateFormat()

getMediumDateTimeFormat

public static DateTimeFormat getMediumDateTimeFormat()

getMediumTimeFormat

public static DateTimeFormat getMediumTimeFormat()

getShortDateFormat

public static DateTimeFormat getShortDateFormat()

getShortDateTimeFormat

public static DateTimeFormat getShortDateTimeFormat()

getShortTimeFormat

public static DateTimeFormat getShortTimeFormat()

format

public java.lang.String format(java.util.Date date)

Format a date object.

Parameters:

date - the date object being formatted

Returns:

formatted date representation

getPattern

public java.lang.String getPattern()

parse

public java.util.Date parse(java.lang.String text)

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.

Parameters:

text - the string being parsed

Returns:

a parsed date/time value

Throws:

java.lang.IllegalArgumentException - if the entire text could not be converted into a number

parse

public int parse(java.lang.String text,
                 int start,
                 java.util.Date date)

This method parses the input string, fill its value into a Date.

Parameters:

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

Returns:

0 if parsing failed, otherwise the number of characters advanced