Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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(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:

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.

[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, ZZZ | -0700 | -0700
ZZZZ | GMT-07:00 | GMT-07:00
v, vv, vvv, vvvv | America/Los_Angeles | Etc/GMT+7

### Parsing Dates and Times

This implementation can parse partial date/time. Current date will be used to fill in an unspecified date part. 00:00:00 will be used to fill in an unspecified time.

As with formatting (described above), the count of pattern letters determines 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 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.

### Examples

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`

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

### Example

>     public class DateTimeFormatExample implements EntryPoint {

>       public void onModuleLoad() {
>         Date today = new Date();

>         // prints Tue Dec 18 12:01:26 GMT-500 2007 in the default locale.
>         GWT.log(today.toString(), null);

>         // prints 12/18/07 in the default locale
>         GWT.log(DateTimeFormat.getShortDateFormat().format(today), null);

>         // prints December 18, 2007 in the default locale
>         GWT.log(DateTimeFormat.getLongDateFormat().format(today), null);

>         // prints 12:01 PM in the default locale
>         GWT.log(DateTimeFormat.getShortTimeFormat().format(today), null);

>         // prints 12:01:26 PM GMT-05:00 in the default locale
>         GWT.log(DateTimeFormat.getLongTimeFormat().format(today), null);

>         // prints Dec 18, 2007 12:01:26 PM in the default locale
>         GWT.log(DateTimeFormat.getMediumDateTimeFormat().format(today), null);

>         // A custom date format
>         DateTimeFormat fmt = DateTimeFormat.getFormat("EEEE, MMMM dd, yyyy");
>         // prints Monday, December 17, 2007 in the default locale
>         GWT.log(fmt.format(today), null);
>       }
>     }

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.
`java.lang.String` | `format(java.util.Date date, TimeZone timeZone)` Format a date object using specified time zone.
`static DateTimeFormat` | `getFormat(java.lang.String pattern)` Returns a DateTimeFormat object using the specified pattern.
`static DateTimeFormat` | `getFullDateFormat()` Retrieve the DateTimeFormat object for full date format.
`static DateTimeFormat` | `getFullDateTimeFormat()` Retrieve the DateTimeFormat object for full date and time format.
`static DateTimeFormat` | `getFullTimeFormat()` Retrieve the DateTimeFormat object for full time format.
`static DateTimeFormat` | `getLongDateFormat()` Retrieve the DateTimeFormat object for long date format.
`static DateTimeFormat` | `getLongDateTimeFormat()` Retrieve the DateTimeFormat object for long date and time format.
`static DateTimeFormat` | `getLongTimeFormat()` Retrieve the DateTimeFormat object for long time format.
`static DateTimeFormat` | `getMediumDateFormat()` Retrieve the DateTimeFormat object for medium date format.
`static DateTimeFormat` | `getMediumDateTimeFormat()` Retrieve the DateTimeFormat object for medium date and time format.
`static DateTimeFormat` | `getMediumTimeFormat()` Retrieve the DateTimeFormat object for medium time format.
`java.lang.String` | `getPattern()` Retrieve the pattern used in this DateTimeFormat object.
`static DateTimeFormat` | `getShortDateFormat()` Retrieve the DateTimeFormat object for short date format.
`static DateTimeFormat` | `getShortDateTimeFormat()` Retrieve the DateTimeFormat object for short date and time format.
`static DateTimeFormat` | `getShortTimeFormat()` Retrieve the DateTimeFormat object for short time format.
`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 modifies a `Date` object to reflect the date that is parsed from an input string.
`java.util.Date` | `parseStrict(java.lang.String text)` Parses text to produce a `Date` value.
`int` | `parseStrict(java.lang.String text, int start, java.util.Date date)` This method modifies a `Date` object to reflect the date that is parsed from an input string.

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

  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()

  Retrieve the DateTimeFormat object for full date format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getFullDateTimeFormat

    public static DateTimeFormat getFullDateTimeFormat()

  Retrieve the DateTimeFormat object for full date and time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getFullTimeFormat

    public static DateTimeFormat getFullTimeFormat()

  Retrieve the DateTimeFormat object for full time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getLongDateFormat

    public static DateTimeFormat getLongDateFormat()

  Retrieve the DateTimeFormat object for long date format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getLongDateTimeFormat

    public static DateTimeFormat getLongDateTimeFormat()

  Retrieve the DateTimeFormat object for long date and time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getLongTimeFormat

    public static DateTimeFormat getLongTimeFormat()

  Retrieve the DateTimeFormat object for long time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getMediumDateFormat

    public static DateTimeFormat getMediumDateFormat()

  Retrieve the DateTimeFormat object for medium date format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getMediumDateTimeFormat

    public static DateTimeFormat getMediumDateTimeFormat()

  Retrieve the DateTimeFormat object for medium date and time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getMediumTimeFormat

    public static DateTimeFormat getMediumTimeFormat()

  Retrieve the DateTimeFormat object for medium time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getShortDateFormat

    public static DateTimeFormat getShortDateFormat()

  Retrieve the DateTimeFormat object for short date format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getShortDateTimeFormat

    public static DateTimeFormat getShortDateTimeFormat()

  Retrieve the DateTimeFormat object for short date and time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### getShortTimeFormat

    public static DateTimeFormat getShortTimeFormat()

  Retrieve the DateTimeFormat object for short time format. The pattern for this format is predefined for each locale.

  Returns:
    A DateTimeFormat object.

### format

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

  Format a date object.

  Parameters:
    `date` - the date object being formatted
  Returns:
    string representation for this date in desired format

### format

    public java.lang.String format(java.util.Date date,
                                   TimeZone timeZone)

  Format a date object using specified time zone.

  Parameters:
    `date` - the date object being formatted
    `timeZone` - a TimeZone object that holds time zone information
  Returns:
    string representation for this date in the format defined by this object

### getPattern

    public java.lang.String getPattern()

  Retrieve the pattern used in this DateTimeFormat object.

  Returns:
    pattern string

### parse

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

  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.

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

  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

### parseStrict

    public java.util.Date parseStrict(java.lang.String text)
                               throws java.lang.IllegalArgumentException

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

  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

### parseStrict

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

  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.

  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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD