SimpleDateFormat

Class Overview

Formats and parses 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 Unicode UTS #35 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. In cases where the system does not provide a suitable pattern, see getBestDateTimePattern(Locale, String) which lets you specify the elements you'd like in a pattern and get back a pattern suitable for any given 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, as shown in the table. For fields of kind "number", the count is the minimum number of digits; shorter values are zero-padded to the given width and longer values overflow it.

Symbol	Meaning	Kind	Example
D	day in year	(Number)	189
E	day of week	(Text)	E/EE/EEE:Tue, EEEE:Tuesday, EEEEE:T
F	day of week in month	(Number)	2 (2nd Wed in July)
G	era designator	(Text)	AD
H	hour in day (0-23)	(Number)	0
K	hour in am/pm (0-11)	(Number)	0
L	stand-alone month	(Text)	L:1 LL:01 LLL:Jan LLLL:January LLLLL:J
M	month in year	(Text)	M:1 MM:01 MMM:Jan MMMM:January MMMMM:J
S	fractional seconds	(Number)	978
W	week in month	(Number)	2
Z	time zone (RFC 822)	(Time Zone)	Z/ZZ/ZZZ:-0800 ZZZZ:GMT-08:00 ZZZZZ:-08:00
a	am/pm marker	(Text)	PM
c	stand-alone day of week	(Text)	c/cc/ccc:Tue, cccc:Tuesday, ccccc:T
d	day in month	(Number)	10
h	hour in am/pm (1-12)	(Number)	12
k	hour in day (1-24)	(Number)	24
m	minute in hour	(Number)	30
s	second in minute	(Number)	55
w	week in year	(Number)	27
y	year	(Number)	yy:10 y/yyy/yyyy:2010
z	time zone	(Time Zone)	z/zz/zzz:PST zzzz:Pacific Standard Time
'	escape for text	(Delimiter)	'Date=':Date=
''	single quote	(Literal)	'o''clock':o'clock

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

The two pattern characters L and c are ICU-compatible extensions, not available in the RI or in Android before Android 2.3 (Gingerbread, API level 9). These extensions are necessary for correct localization in languages such as Russian that make a grammatical distinction between, say, the word "June" in the sentence "June" and in the sentence "June 10th"; the former is the stand-alone form, the latter the regular form (because the usual case is to format a complete date). The relationship between E and c is equivalent, but for weekday names.

Five-count patterns (such as "MMMMM") used for the shortest non-numeric representation of a field were introduced in Android 4.3 (Jelly Bean MR2, API level 18).

When two numeric fields are directly adjacent 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.out.println(df.format(new Date(0)));
 }
 

Produces this output when run on an en_US device in the America/Los_Angeles time zone:

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

And will produce similarly appropriate localized human-readable output on any user's system.

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.out.format("%30s %s\n", format, sdf.format(new Date(0)));
   sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
   System.out.format("%30s %s\n", format, sdf.format(new Date(0)));
 }
 

Which produces this output when run in the America/Los_Angeles 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). It is often best to avoid formatting completely when writing dates/times in machine-readable form. Simply sending the "Unix time" as a long or as the string corresponding to the long is cheaper and unambiguous, and can be formatted any way the recipient deems appropriate.

Synchronization

SimpleDateFormat is not thread-safe. Users should create a separate instance for each thread.

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.

Public Constructors
	SimpleDateFormat() Constructs a new SimpleDateFormat for formatting and parsing dates and times in the SHORT style for the user's default locale.
	SimpleDateFormat(String pattern) Constructs a new SimpleDateFormat using the specified non-localized pattern and the DateFormatSymbols and Calendar for the user's default locale.
	SimpleDateFormat(String template, DateFormatSymbols value) Constructs a new SimpleDateFormat using the specified non-localized pattern and DateFormatSymbols and the Calendar for the user's default locale.
	SimpleDateFormat(String template, Locale locale) Constructs a new SimpleDateFormat using the specified non-localized pattern and the DateFormatSymbols and Calendar for the specified locale.

Public Methods
void	applyLocalizedPattern(String template) Changes the pattern of this simple date format to the specified pattern which uses localized pattern characters.
void	applyPattern(String template) Changes the pattern of this simple date format to the specified pattern which uses non-localized pattern characters.
Object	clone() Returns a new SimpleDateFormat with the same pattern and properties as this simple date format.
boolean	equals(Object object) Compares the specified object with this simple date format and indicates if they are equal.
StringBuffer	format(Date date, StringBuffer buffer, FieldPosition fieldPos) Formats the specified date as a string using the pattern of this date format and appends the string to the specified string buffer.
AttributedCharacterIterator	formatToCharacterIterator(Object object) Formats the specified object using the rules of this simple date format and returns an AttributedCharacterIterator with the formatted date and attributes.
Date	get2DigitYearStart() Returns the date which is the start of the one hundred year period for two-digit year values.
DateFormatSymbols	getDateFormatSymbols() Returns the DateFormatSymbols used by this simple date format.
int	hashCode() Returns an integer hash code for this object.
Date	parse(String string, ParsePosition position) Parses a date from the specified string starting at the index specified by position.
void	set2DigitYearStart(Date date) Sets the date which is the start of the one hundred year period for two-digit year values.
void	setDateFormatSymbols(DateFormatSymbols value) Sets the DateFormatSymbols used by this simple date format.
String	toLocalizedPattern() Returns the pattern of this simple date format using localized pattern characters.
String	toPattern() Returns the pattern of this simple date format using non-localized pattern characters.

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