public class DateFormat extends Object
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(java.util.Locale, java.lang.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
.
Modifier and Type | Field and Description |
---|---|
static char |
AM_PM
Deprecated.
Use a literal
'a' instead. |
static char |
CAPITAL_AM_PM
Deprecated.
Use a literal
'a' instead; 'A' was always equivalent to 'a'. |
static char |
DATE
Deprecated.
Use a literal
'd' instead. |
static char |
DAY
Deprecated.
Use a literal
'E' instead. |
static char |
HOUR
Deprecated.
Use a literal
'h' instead. |
static char |
HOUR_OF_DAY
Deprecated.
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. |
static char |
MINUTE
Deprecated.
Use a literal
'm' instead. |
static char |
MONTH
Deprecated.
Use a literal
'M' instead. |
static char |
QUOTE
Deprecated.
Use a literal
' instead. |
static char |
SECONDS
Deprecated.
Use a literal
's' instead. |
static char |
STANDALONE_MONTH
Deprecated.
Use a literal
'L' instead. |
static char |
TIME_ZONE
Deprecated.
Use a literal
'z' instead. |
static char |
YEAR
Deprecated.
Use a literal
'y' instead. |
Constructor and Description |
---|
DateFormat() |
Modifier and Type | Method and Description |
---|---|
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 according to the current locale. |
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 String |
getTimeFormatString(Context context)
Returns a String pattern that can be used to format the time according
to the current locale and the user's 12-/24-hour clock preference.
|
static String |
getTimeFormatString(Context context,
int userHandle)
Returns a String pattern that can be used to format the time according
to the current locale and the user's 12-/24-hour clock preference.
|
static boolean |
hasDesignator(CharSequence inFormat,
char designator)
Test if a format string contains the given designator.
|
static boolean |
hasSeconds(CharSequence inFormat)
Indicates whether the specified format string contains seconds.
|
static boolean |
is24HourFormat(Context context)
Returns true if user preference is set to 24-hour format.
|
static boolean |
is24HourFormat(Context context,
int userHandle)
Returns true if user preference with the given user handle is set to 24-hour format.
|
@Deprecated public static final char QUOTE
'
instead.@Deprecated public static final char AM_PM
'a'
instead.@Deprecated public static final char CAPITAL_AM_PM
'a'
instead; 'A' was always equivalent to 'a'.@Deprecated public static final char DATE
'd'
instead.@Deprecated public static final char DAY
'E'
instead.@Deprecated public static final char HOUR
'h'
instead.@Deprecated public static final char HOUR_OF_DAY
'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.@Deprecated public static final char MINUTE
'm'
instead.@Deprecated public static final char MONTH
'M'
instead.@Deprecated public static final char STANDALONE_MONTH
'L'
instead.@Deprecated public static final char SECONDS
's'
instead.@Deprecated public static final char TIME_ZONE
'z'
instead.@Deprecated public static final char YEAR
'y'
instead.public static boolean is24HourFormat(Context context)
context
- the context to use for the content resolverpublic static boolean is24HourFormat(Context context, int userHandle)
context
- the context to use for the content resolveruserHandle
- the user handle of the user to query.public static String getBestDateTimePattern(Locale locale, String skeleton)
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.
locale
- the locale into which the skeleton should be localizedskeleton
- a skeleton as described aboveSimpleDateFormat
.public static DateFormat getTimeFormat(Context context)
DateFormat
object that can format the time according
to the current locale and the user's 12-/24-hour clock preference.context
- the application contextDateFormat
object that properly formats the time.public static String getTimeFormatString(Context context)
context
- the application contextpublic static String getTimeFormatString(Context context, int userHandle)
context
- the application contextuserHandle
- the user handle of the user to query the format forpublic static DateFormat getDateFormat(Context context)
DateFormat
object that can format the date
in short form according to the current locale.context
- the application contextDateFormat
object that properly formats the date.public static DateFormat getLongDateFormat(Context context)
DateFormat
object that can format the date
in long form (such as Monday, January 3, 2000
) for the current locale.context
- the application contextDateFormat
object that formats the date in long form.public static DateFormat getMediumDateFormat(Context context)
DateFormat
object that can format the date
in medium form (such as Jan 3, 2000
) for the current locale.context
- the application contextDateFormat
object that formats the date in long form.public static char[] getDateFormatOrder(Context context)
'd'
), month ('M'
), and year ('y'
))
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 CharSequence format(CharSequence inFormat, long inTimeInMillis)
inFormat
- the format string, as described in DateFormat
inTimeInMillis
- in milliseconds since Jan 1, 1970 GMTCharSequence
containing the requested textpublic static CharSequence format(CharSequence inFormat, Date inDate)
Date
object, returns a CharSequence containing
the requested date.inFormat
- the format string, as described in DateFormat
inDate
- the date to formatCharSequence
containing the requested textpublic static boolean hasSeconds(CharSequence inFormat)
inFormat
- the format string, as described in DateFormat
SECONDS
, false otherwisepublic static boolean hasDesignator(CharSequence inFormat, char designator)
false
if the input format is null
.public static CharSequence format(CharSequence inFormat, Calendar inDate)
Calendar
object, returns a CharSequence
containing the requested date.inFormat
- the format string, as described in DateFormat
inDate
- the date to formatCharSequence
containing the requested text