SimpleDateFormat

Class Overview

A concrete class for formatting and parsing dates in a locale-sensitive manner. Formatting turns a Date into a String, and parsing turns a String into a Date.

Time Pattern Syntax

You can supply a pattern describing what strings are produced/accepted, but almost all callers should use getDateInstance(), getDateTimeInstance(), or getTimeInstance() to get a ready-made instance suitable for the user's locale.

The main reason you'd create an instance this class directly is because you need to format/parse a specific machine-readable format, in which case you almost certainly want to explicitly ask for US to ensure that you get ASCII digits (rather than, say, Arabic digits). (See "Be wary of the default locale".) The most useful non-localized pattern is "yyyy-MM-dd HH:mm:ss.SSSZ", which corresponds to the ISO 8601 international standard date format.

To specify the time format, use a time pattern string. In this string, any character from 'A' to 'Z' or 'a' to 'z' is treated specially. All other characters are passed through verbatim. The interpretation of each of the ASCII letters is given in the table below. ASCII letters not appearing in the table are reserved for future use, and it is an error to attempt to use them.

The number of consecutive copies (the "count") of a pattern character further influences the format.

• Text if the count is 4 or more, use the full form; otherwise use a short or abbreviated form if one exists. So zzzz might give Pacific Standard Time whereas z might give PST. Note that the count does not specify the exact width of the field.
• Number the count is the minimum number of digits. Shorter values are zero-padded to this width, longer values overflow this width.

  Years are handled specially: yy truncates to the last 2 digits, but any other number of consecutive ys does not truncate. So where yyyy or y might give 2010, yy would give 10.

  Fractional seconds are also handled specially: they're zero-padded on the right.

• Text/Number: if the count is 3 or more, use text; otherwise use a number. So MM might give 07 while MMM gives July.

The two pattern characters L and c are ICU-compatible extensions, not available in the RI. These are necessary for correct localization in languages such as Russian that distinguish between, say, "June" and "June 2010".

When numeric fields are adjacent directly, with no intervening delimiter characters, they constitute a run of adjacent 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.

See set2DigitYearStart(Date) for more about handling two-digit years.

Sample Code

If you're formatting for human use, you should use an instance returned from DateFormat as described above. This code:

 DateFormat[] formats = new DateFormat[] {
   DateFormat.getDateInstance(),
   DateFormat.getDateTimeInstance(),
   DateFormat.getTimeInstance(),
 };
 for (DateFormat df : formats) {
   System.err.println(df.format(new Date(0)));
 }
 

Produces this output when run on an en_US device in the PDT time zone:

 Dec 31, 1969
 Dec 31, 1969 4:00:00 PM
 4:00:00 PM
 

If you're formatting for machine use, consider this code:

 String[] formats = new String[] {
   "yyyy-MM-dd",
   "yyyy-MM-dd HH:mm",
   "yyyy-MM-dd HH:mmZ",
   "yyyy-MM-dd HH:mm:ss.SSSZ",
   "yyyy-MM-dd'T'HH:mm:ss.SSSZ",
 };
 for (String format : formats) {
   SimpleDateFormat sdf = new SimpleDateFormat(format, Locale.US);
   System.err.format("%30s %s\n", format, sdf.format(new Date(0)));
   sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
   System.err.format("%30s %s\n", format, sdf.format(new Date(0)));
 }
 

Which produces this output when run in the PDT time zone:

                     yyyy-MM-dd 1969-12-31
                     yyyy-MM-dd 1970-01-01
               yyyy-MM-dd HH:mm 1969-12-31 16:00
               yyyy-MM-dd HH:mm 1970-01-01 00:00
              yyyy-MM-dd HH:mmZ 1969-12-31 16:00-0800
              yyyy-MM-dd HH:mmZ 1970-01-01 00:00+0000
       yyyy-MM-dd HH:mm:ss.SSSZ 1969-12-31 16:00:00.000-0800
       yyyy-MM-dd HH:mm:ss.SSSZ 1970-01-01 00:00:00.000+0000
     yyyy-MM-dd'T'HH:mm:ss.SSSZ 1969-12-31T16:00:00.000-0800
     yyyy-MM-dd'T'HH:mm:ss.SSSZ 1970-01-01T00:00:00.000+0000
 

As this example shows, each SimpleDateFormat instance has a TimeZone. This is because it's called upon to format instances of Date, which represents an absolute time in UTC. That is, Date does not carry time zone information. By default, SimpleDateFormat will use the system's default time zone. This is appropriate for human-readable output (for which, see the previous sample instead), but generally inappropriate for machine-readable output, where ambiguity is a problem. Note that in this example, the output that included a time but no time zone cannot be parsed back into the original Date. For this reason it is almost always necessary and desirable to include the timezone in the output. It may also be desirable to set the formatter's time zone to UTC (to ease comparison, or to make logs more readable, for example).

Synchronization

Summary

[Expand] Inherited Constants

From class java.text.DateFormat int AM_PM_FIELD FieldPosition selector for 'a' field alignment, corresponds to the AM_PM field. int DATE_FIELD The FieldPosition selector for 'd' field alignment, corresponds to the DATE field. int DAY_OF_WEEK_FIELD FieldPosition selector for 'E' field alignment, corresponds to the DAY_OF_WEEK field. int DAY_OF_WEEK_IN_MONTH_FIELD FieldPosition selector for 'F' field alignment, corresponds to the DAY_OF_WEEK_IN_MONTH field. int DAY_OF_YEAR_FIELD FieldPosition selector for 'D' field alignment, corresponds to the DAY_OF_YEAR field. int DEFAULT The format style constant defining the default format style. int ERA_FIELD The FieldPosition selector for 'G' field alignment, corresponds to the ERA field. int FULL The format style constant defining the full style. int HOUR0_FIELD The FieldPosition selector for 'K' field alignment, corresponding to the HOUR field. int HOUR1_FIELD FieldPosition selector for 'h' field alignment, corresponding to the HOUR field. int HOUR_OF_DAY0_FIELD The FieldPosition selector for 'H' field alignment, corresponds to the HOUR_OF_DAY field. int HOUR_OF_DAY1_FIELD The FieldPosition selector for 'k' field alignment, corresponds to the HOUR_OF_DAY field. int LONG The format style constant defining the long style. int MEDIUM The format style constant defining the medium style. int MILLISECOND_FIELD FieldPosition selector for 'S' field alignment, corresponds to the MILLISECOND field. int MINUTE_FIELD FieldPosition selector for 'm' field alignment, corresponds to the MINUTE field. int MONTH_FIELD The FieldPosition selector for 'M' field alignment, corresponds to the MONTH field. int SECOND_FIELD FieldPosition selector for 's' field alignment, corresponds to the SECOND field. int SHORT The format style constant defining the short style. int TIMEZONE_FIELD The FieldPosition selector for 'z' field alignment, corresponds to the ZONE_OFFSET and DST_OFFSET fields. int WEEK_OF_MONTH_FIELD FieldPosition selector for 'W' field alignment, corresponds to the WEEK_OF_MONTH field. int WEEK_OF_YEAR_FIELD FieldPosition selector for 'w' field alignment, corresponds to the WEEK_OF_YEAR field. int YEAR_FIELD The FieldPosition selector for 'y' field alignment, corresponds to the YEAR field.

[Expand] Inherited Fields
From class java.text.DateFormat protected Calendar calendar The calendar that this DateFormat uses to format a number representing a date. protected NumberFormat numberFormat The number format used to format a number.

[Expand] Inherited Methods
From class java.text.DateFormat Object clone() Returns a new instance of DateFormat with the same properties. boolean equals( Object object) Compares this date format with the specified object and indicates if they are equal. abstract StringBuffer format( Date date, StringBuffer buffer, FieldPosition field) Formats the specified date as a string using the pattern of this date format and appends the string to the specified string buffer. final StringBuffer format( Object object, StringBuffer buffer, FieldPosition field) Formats the specified object as a string using the pattern of this date format and appends the string to the specified string buffer. final String format( Date date) Formats the specified date using the rules of this date format. static Locale[] getAvailableLocales() Returns an array of locales for which custom DateFormat instances are available. Calendar getCalendar() Returns the calendar used by this DateFormat. final static DateFormat getDateInstance(int style) Returns a DateFormat instance for formatting and parsing dates in the specified style for the user's default locale. final static DateFormat getDateInstance(int style, Locale locale) Returns a DateFormat instance for formatting and parsing dates in the specified style for the specified locale. final static DateFormat getDateInstance() Returns a DateFormat instance for formatting and parsing dates in the DEFAULT style for the default locale. final static DateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale locale) Returns a DateFormat instance for formatting and parsing dates and time values in the specified styles for the specified locale. final static DateFormat getDateTimeInstance(int dateStyle, int timeStyle) Returns a DateFormat instance for formatting and parsing of both dates and time values in the manner appropriate for the user's default locale. final static DateFormat getDateTimeInstance() Returns a DateFormat instance for formatting and parsing dates and time values in the DEFAULT style for the default locale. final static DateFormat getInstance() Returns a DateFormat instance for formatting and parsing dates and times in the SHORT style for the default locale. NumberFormat getNumberFormat() Returns the NumberFormat used by this DateFormat. final static DateFormat getTimeInstance(int style) Returns a DateFormat instance for formatting and parsing time values in the specified style for the user's default locale. final static DateFormat getTimeInstance() Returns a DateFormat instance for formatting and parsing time values in the DEFAULT style for the default locale. final static DateFormat getTimeInstance(int style, Locale locale) Returns a DateFormat instance for formatting and parsing time values in the specified style for the specified locale. TimeZone getTimeZone() Returns the time zone of this date format's calendar. int hashCode() Returns an integer hash code for this object. boolean isLenient() Indicates whether the calendar used by this date format is lenient. Date parse( String string) Parses a date from the specified string using the rules of this date format. abstract Date parse( String string, ParsePosition position) Parses a date from the specified string starting at the index specified by position. Object parseObject( String string, ParsePosition position) Parses a date from the specified string starting at the index specified by position. void setCalendar( Calendar cal) Sets the calendar used by this date format. void setLenient(boolean value) Specifies whether or not date/time parsing shall be lenient. void setNumberFormat( NumberFormat format) Sets the NumberFormat used by this date format. void setTimeZone( TimeZone timezone) Sets the time zone of the calendar used by this date format.
From class java.text.Format Object clone() Returns a copy of this Format instance. final String format( Object object) Formats the specified object using the rules of this format. abstract StringBuffer format( Object object, StringBuffer buffer, FieldPosition field) Appends the specified object to the specified string buffer using the rules of this format. AttributedCharacterIterator formatToCharacterIterator( Object object) Formats the specified object using the rules of this format and returns an AttributedCharacterIterator with the formatted string and no attributes. Object parseObject( String string) Parses the specified string using the rules of this format. abstract Object parseObject( String string, ParsePosition position) Parses the specified string starting at the index specified by position.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals( Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.