Android APIs
public class

SimpleDateFormat

extends DateFormat
java.lang.Object
   ↳ java.text.Format
     ↳ java.text.DateFormat
       ↳ java.text.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

Note that 'S' represents fractional seconds and not millisecond values. They will be padded on the left or on the right or both depending on the number of 'S' in the pattern. For example, the number of fractional seconds in a Date where Date.getTime() == 1000006 are 0.006 or (6 / 1000). This leads to the following formatting:

  • "S" => "0"
  • "SSS" => "006"
  • "SSSSSS" => "006000"

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
[Expand]
Inherited Fields
From class java.text.DateFormat
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
From class java.text.Format
From class java.lang.Object

Public Constructors

public SimpleDateFormat ()

Added in API level 1

Constructs a new SimpleDateFormat for formatting and parsing dates and times in the SHORT style for the user's default locale. See "Be wary of the default locale".

public SimpleDateFormat (String pattern)

Added in API level 1

Constructs a new SimpleDateFormat using the specified non-localized pattern and the DateFormatSymbols and Calendar for the user's default locale. See "Be wary of the default locale".

Parameters
pattern the pattern.
Throws
NullPointerException if the pattern is null.
IllegalArgumentException if pattern is not considered to be usable by this formatter.

public SimpleDateFormat (String template, DateFormatSymbols value)

Added in API level 1

Constructs a new SimpleDateFormat using the specified non-localized pattern and DateFormatSymbols and the Calendar for the user's default locale. See "Be wary of the default locale".

Parameters
template the pattern.
value the DateFormatSymbols.
Throws
NullPointerException if the pattern is null.
IllegalArgumentException if the pattern is invalid.

public SimpleDateFormat (String template, Locale locale)

Added in API level 1

Constructs a new SimpleDateFormat using the specified non-localized pattern and the DateFormatSymbols and Calendar for the specified locale.

Parameters
template the pattern.
locale the locale.
Throws
NullPointerException if the pattern is null.
IllegalArgumentException if the pattern is invalid.

Public Methods

public void applyLocalizedPattern (String template)

Added in API level 1

Changes the pattern of this simple date format to the specified pattern which uses localized pattern characters.

Parameters
template the localized pattern.

public void applyPattern (String template)

Added in API level 1

Changes the pattern of this simple date format to the specified pattern which uses non-localized pattern characters.

Parameters
template the non-localized pattern.
Throws
NullPointerException if the pattern is null.
IllegalArgumentException if the pattern is invalid.

public Object clone ()

Added in API level 1

Returns a new SimpleDateFormat with the same pattern and properties as this simple date format.

Returns
  • a shallow copy of this format.

public boolean equals (Object object)

Added in API level 1

Compares the specified object with this simple date format and indicates if they are equal. In order to be equal, object must be an instance of SimpleDateFormat and have the same DateFormat properties, pattern, DateFormatSymbols and creation year.

Parameters
object the object to compare with this object.
Returns
  • true if the specified object is equal to this simple date format; false otherwise.
See Also

public StringBuffer format (Date date, StringBuffer buffer, FieldPosition fieldPos)

Added in API level 1

Formats the specified date as a string using the pattern of this date format and appends the string to the specified string buffer.

If the field member of field contains a value specifying a format field, then its beginIndex and endIndex members will be updated with the position of the first occurrence of this field in the formatted text.

Parameters
date the date to format.
buffer the target string buffer to append the formatted date/time to.
fieldPos on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
Returns
  • the string buffer.
Throws
IllegalArgumentException if there are invalid characters in the pattern.

public AttributedCharacterIterator formatToCharacterIterator (Object object)

Added in API level 1

Formats the specified object using the rules of this simple date format and returns an AttributedCharacterIterator with the formatted date and attributes.

Parameters
object the object to format.
Returns
  • an AttributedCharacterIterator with the formatted date and attributes.
Throws
NullPointerException if the object is null.
IllegalArgumentException if the object cannot be formatted by this simple date format.

public Date get2DigitYearStart ()

Added in API level 1

Returns the date which is the start of the one hundred year period for two-digit year values. See set2DigitYearStart(Date) for details.

public DateFormatSymbols getDateFormatSymbols ()

Added in API level 1

Returns the DateFormatSymbols used by this simple date format.

Returns
  • the DateFormatSymbols object.

public int hashCode ()

Added in API level 1

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Note that hash values must not change over time unless information used in equals comparisons also changes.

See Writing a correct hashCode method if you intend implementing your own hashCode method.

Returns
  • this object's hash code.

public Date parse (String string, ParsePosition position)

Added in API level 1

Parses a date from the specified string starting at the index specified by position. If the string is successfully parsed then the index of the ParsePosition is updated to the index following the parsed text. On error, the index is unchanged and the error index of ParsePosition is set to the index where the error occurred.

Parameters
string the string to parse using the pattern of this simple date format.
position input/output parameter, specifies the start index in string from where to start parsing. If parsing is successful, it is updated with the index following the parsed text; on error, the index is unchanged and the error index is set to the index where the error occurred.
Returns
  • the date resulting from the parse, or null if there is an error.
Throws
IllegalArgumentException if there are invalid characters in the pattern.

public void set2DigitYearStart (Date date)

Added in API level 1

Sets the date which is the start of the one hundred year period for two-digit year values.

When parsing a date string using the abbreviated year pattern yy, SimpleDateFormat 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 SimpleDateFormat instance was created. For example, using a pattern of MM/dd/yy, an instance created on Jan 1, 1997 would interpret the string "01/11/12" as Jan 11, 2012 but interpret the string "05/04/64" 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. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that isn't all digits (for example, "-1"), is interpreted literally. So using the same pattern, both "01/02/3" and "01/02/003" are parsed as Jan 2, 3 AD. Similarly, "01/02/-3" is parsed as Jan 2, 4 BC.

If the year pattern does not have exactly two 'y' characters, the year is interpreted literally, regardless of the number of digits. So using the pattern MM/dd/yyyy, "01/11/12" is parsed as Jan 11, 12 A.D.

public void setDateFormatSymbols (DateFormatSymbols value)

Added in API level 1

Sets the DateFormatSymbols used by this simple date format.

Parameters
value the new DateFormatSymbols object.

public String toLocalizedPattern ()

Added in API level 1

Returns the pattern of this simple date format using localized pattern characters.

Returns
  • the localized pattern.

public String toPattern ()

Added in API level 1

Returns the pattern of this simple date format using non-localized pattern characters.

Returns
  • the non-localized pattern.