Android APIs
public class

DateFormat

extends Object
java.lang.Object
   ↳ android.text.format.DateFormat

Class Overview

Utility class for producing strings with formatted date/time.

Most callers should avoid supplying their own format strings to this class' format methods and rely on the correctly localized ones supplied by the system. This class' factory methods return appropriately-localized DateFormat instances, suitable for both formatting and parsing dates. For the canonical documentation of format strings, see SimpleDateFormat.

In cases where the system does not provide a suitable pattern, this class offers the getBestDateTimePattern(Locale, String) method.

The format methods in this class implement a subset of Unicode UTS #35 patterns. The subset currently supported by this class includes the following format characters: acdEHhLKkLMmsyz. Up to API level 17, only adEhkMmszy were supported. Note that this class incorrectly implements k as if it were H for backwards compatibility.

See SimpleDateFormat for more documentation about patterns, or if you need a more complete or correct implementation. Note that the non-format methods in this class are implemented by SimpleDateFormat.

Summary

Constants
char AM_PM This constant was deprecated in API level 18. Use a literal 'a' instead.
char CAPITAL_AM_PM This constant was deprecated in API level 18. Use a literal 'a' instead; 'A' was always equivalent to 'a'.
char DATE This constant was deprecated in API level 18. Use a literal 'd' instead.
char DAY This constant was deprecated in API level 18. Use a literal 'E' instead.
char HOUR This constant was deprecated in API level 18. Use a literal 'h' instead.
char HOUR_OF_DAY This constant was deprecated in API level 18. Use a literal 'H' (for compatibility with SimpleDateFormat and Unicode) or 'k' (for compatibility with Android releases up to and including Jelly Bean MR-1) instead. Note that the two are incompatible.
char MINUTE This constant was deprecated in API level 18. Use a literal 'm' instead.
char MONTH This constant was deprecated in API level 18. Use a literal 'M' instead.
char QUOTE This constant was deprecated in API level 18. Use a literal ' instead.
char SECONDS This constant was deprecated in API level 18. Use a literal 's' instead.
char STANDALONE_MONTH This constant was deprecated in API level 18. Use a literal 'L' instead.
char TIME_ZONE This constant was deprecated in API level 18. Use a literal 'z' instead.
char YEAR This constant was deprecated in API level 18. Use a literal 'y' instead.
Public Constructors
DateFormat()
Public Methods
static CharSequence format(CharSequence inFormat, Calendar inDate)
Given a format string and a Calendar object, returns a CharSequence containing the requested date.
static CharSequence format(CharSequence inFormat, Date inDate)
Given a format string and a Date object, returns a CharSequence containing the requested date.
static CharSequence format(CharSequence inFormat, long inTimeInMillis)
Given a format string and a time in milliseconds since Jan 1, 1970 GMT, returns a CharSequence containing the requested date.
static String getBestDateTimePattern(Locale locale, String skeleton)
Returns the best possible localized form of the given skeleton for the given locale.
static DateFormat getDateFormat(Context context)
Returns a DateFormat object that can format the date in short form (such as 12/31/1999) according to the current locale and the user's date-order preference.
static char[] getDateFormatOrder(Context context)
Gets the current date format stored as a char array.
static DateFormat getLongDateFormat(Context context)
Returns a DateFormat object that can format the date in long form (such as Monday, January 3, 2000) for the current locale.
static DateFormat getMediumDateFormat(Context context)
Returns a DateFormat object that can format the date in medium form (such as Jan 3, 2000) for the current locale.
static DateFormat getTimeFormat(Context context)
Returns a DateFormat object that can format the time according to the current locale and the user's 12-/24-hour clock preference.
static boolean is24HourFormat(Context context)
Returns true if user preference is set to 24-hour format.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final char AM_PM

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'a' instead.

Constant Value: 97 (0x00000061)

public static final char CAPITAL_AM_PM

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'a' instead; 'A' was always equivalent to 'a'.

Constant Value: 65 (0x00000041)

public static final char DATE

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'd' instead.

Constant Value: 100 (0x00000064)

public static final char DAY

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'E' instead.

Constant Value: 69 (0x00000045)

public static final char HOUR

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'h' instead.

Constant Value: 104 (0x00000068)

public static final char HOUR_OF_DAY

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'H' (for compatibility with SimpleDateFormat and Unicode) or 'k' (for compatibility with Android releases up to and including Jelly Bean MR-1) instead. Note that the two are incompatible.

Constant Value: 107 (0x0000006b)

public static final char MINUTE

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'm' instead.

Constant Value: 109 (0x0000006d)

public static final char MONTH

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'M' instead.

Constant Value: 77 (0x0000004d)

public static final char QUOTE

Added in API level 3

This constant was deprecated in API level 18.
Use a literal ' instead.

Constant Value: 39 (0x00000027)

public static final char SECONDS

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 's' instead.

Constant Value: 115 (0x00000073)

public static final char STANDALONE_MONTH

Added in API level 17

This constant was deprecated in API level 18.
Use a literal 'L' instead.

Constant Value: 76 (0x0000004c)

public static final char TIME_ZONE

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'z' instead.

Constant Value: 122 (0x0000007a)

public static final char YEAR

Added in API level 3

This constant was deprecated in API level 18.
Use a literal 'y' instead.

Constant Value: 121 (0x00000079)

Public Constructors

public DateFormat ()

Added in API level 3

Public Methods

public static CharSequence format (CharSequence inFormat, Calendar inDate)

Added in API level 3

Given a format string and a Calendar object, returns a CharSequence containing the requested date.

Parameters
inFormat the format string, as described in DateFormat
inDate the date to format
Returns

public static CharSequence format (CharSequence inFormat, Date inDate)

Added in API level 3

Given a format string and a Date object, returns a CharSequence containing the requested date.

Parameters
inFormat the format string, as described in DateFormat
inDate the date to format
Returns

public static CharSequence format (CharSequence inFormat, long inTimeInMillis)

Added in API level 3

Given a format string and a time in milliseconds since Jan 1, 1970 GMT, returns a CharSequence containing the requested date.

Parameters
inFormat the format string, as described in DateFormat
inTimeInMillis in milliseconds since Jan 1, 1970 GMT
Returns

public static String getBestDateTimePattern (Locale locale, String skeleton)

Added in API level 18

Returns the best possible localized form of the given skeleton for the given locale. A skeleton is similar to, and uses the same format characters as, a Unicode UTS #35 pattern.

One difference is that order is irrelevant. For example, "MMMMd" will return "MMMM d" in the en_US locale, but "d. MMMM" in the de_CH locale.

Note also in that second example that the necessary punctuation for German was added. For the same input in es_ES, we'd have even more extra text: "d 'de' MMMM".

This method will automatically correct for grammatical necessity. Given the same "MMMMd" input, this method will return "d LLLL" in the fa_IR locale, where stand-alone months are necessary. Lengths are preserved where meaningful, so "Md" would give a different result to "MMMd", say, except in a locale such as ja_JP where there is only one length of month.

This method will only return patterns that are in CLDR, and is useful whenever you know what elements you want in your format string but don't want to make your code specific to any one locale.

Parameters
locale the locale into which the skeleton should be localized
skeleton a skeleton as described above
Returns

public static DateFormat getDateFormat (Context context)

Added in API level 3

Returns a DateFormat object that can format the date in short form (such as 12/31/1999) according to the current locale and the user's date-order preference.

Parameters
context the application context
Returns
  • the DateFormat object that properly formats the date.

public static char[] getDateFormatOrder (Context context)

Added in API level 3

Gets the current date format stored as a char array. The array will contain 3 elements (DATE, MONTH, and YEAR) in the order specified by the user's format preference. Note that this order is only appropriate for all-numeric dates; spelled-out (MEDIUM and LONG) dates will generally contain other punctuation, spaces, or words, not just the day, month, and year, and not necessarily in the same order returned here.

public static DateFormat getLongDateFormat (Context context)

Added in API level 3

Returns a DateFormat object that can format the date in long form (such as Monday, January 3, 2000) for the current locale.

Parameters
context the application context
Returns
  • the DateFormat object that formats the date in long form.

public static DateFormat getMediumDateFormat (Context context)

Added in API level 3

Returns a DateFormat object that can format the date in medium form (such as Jan 3, 2000) for the current locale.

Parameters
context the application context
Returns
  • the DateFormat object that formats the date in long form.

public static DateFormat getTimeFormat (Context context)

Added in API level 3

Returns a DateFormat object that can format the time according to the current locale and the user's 12-/24-hour clock preference.

Parameters
context the application context
Returns
  • the DateFormat object that properly formats the time.

public static boolean is24HourFormat (Context context)

Added in API level 3

Returns true if user preference is set to 24-hour format.

Parameters
context the context to use for the content resolver
Returns
  • true if 24 hour time format is selected, false otherwise.