public abstract class DateFormat extends Format
This class provides factories for obtaining instances configured for a specific locale.
The most common subclass is SimpleDateFormat.
This code:
DateFormat[] formats = new DateFormat[] {
DateFormat.getDateInstance(),
DateFormat.getDateTimeInstance(),
DateFormat.getTimeInstance(),
};
for (DateFormat df : formats) {
System.out.println(df.format(new Date(0)));
df.setTimeZone(TimeZone.getTimeZone("UTC"));
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 Jan 1, 1970 Dec 31, 1969 4:00:00 PM Jan 1, 1970 12:00:00 AM 4:00:00 PM 12:00:00 AMAnd will produce similarly appropriate localized human-readable output on any user's system. Notice how the same point in time when formatted can appear to be a different time when rendered for a different time zone. This is one reason why formatting should be left until the data will only be presented to a human. Machines should interchange "Unix time" integers.
| Modifier and Type | Class and Description |
|---|---|
static class |
DateFormat.Field
The instances of this inner class are used as attribute keys and values
in
AttributedCharacterIterator that the
SimpleDateFormat.formatToCharacterIterator(Object) method returns. |
| Modifier and Type | Field and Description |
|---|---|
static int |
AM_PM_FIELD
FieldPosition selector for 'a' field alignment, corresponds to the
Calendar.AM_PM field. |
protected Calendar |
calendar
The calendar that this
DateFormat uses to format a number
representing a date. |
static int |
DATE_FIELD
The
FieldPosition selector for 'd' field alignment, corresponds
to the Calendar.DATE field. |
static int |
DAY_OF_WEEK_FIELD
FieldPosition selector for 'E' field alignment, corresponds to the
Calendar.DAY_OF_WEEK field. |
static int |
DAY_OF_WEEK_IN_MONTH_FIELD
FieldPosition selector for 'F' field alignment, corresponds to the
Calendar.DAY_OF_WEEK_IN_MONTH field. |
static int |
DAY_OF_YEAR_FIELD
FieldPosition selector for 'D' field alignment, corresponds to the
Calendar.DAY_OF_YEAR field. |
static int |
DEFAULT
The format style constant defining the default format style.
|
static int |
ERA_FIELD
The
FieldPosition selector for 'G' field alignment, corresponds
to the Calendar.ERA field. |
static int |
FULL
The format style constant defining the full style.
|
static int |
HOUR_OF_DAY0_FIELD
The
FieldPosition selector for 'H' field alignment, corresponds
to the Calendar.HOUR_OF_DAY field. |
static int |
HOUR_OF_DAY1_FIELD
The
FieldPosition selector for 'k' field alignment, corresponds
to the Calendar.HOUR_OF_DAY field. |
static int |
HOUR0_FIELD
The
FieldPosition selector for 'K' field alignment, corresponding to the
Calendar.HOUR field. |
static int |
HOUR1_FIELD
FieldPosition selector for 'h' field alignment, corresponding to the
Calendar.HOUR field. |
static Boolean |
is24Hour
A tri-state boolean.
|
static int |
LONG
The format style constant defining the long style.
|
static int |
MEDIUM
The format style constant defining the medium style.
|
static int |
MILLISECOND_FIELD
FieldPosition selector for 'S' field alignment, corresponds to the
Calendar.MILLISECOND field. |
static int |
MINUTE_FIELD
FieldPosition selector for 'm' field alignment, corresponds to the
Calendar.MINUTE field. |
static int |
MONTH_FIELD
The
FieldPosition selector for 'M' field alignment, corresponds
to the Calendar.MONTH field. |
protected NumberFormat |
numberFormat
The number format used to format a number.
|
static int |
SECOND_FIELD
FieldPosition selector for 's' field alignment, corresponds to the
Calendar.SECOND field. |
static int |
SHORT
The format style constant defining the short style.
|
static int |
TIMEZONE_FIELD
The
FieldPosition selector for 'z' field alignment, corresponds
to the Calendar.ZONE_OFFSET and Calendar.DST_OFFSET
fields. |
static int |
WEEK_OF_MONTH_FIELD
FieldPosition selector for 'W' field alignment, corresponds to the
Calendar.WEEK_OF_MONTH field. |
static int |
WEEK_OF_YEAR_FIELD
FieldPosition selector for 'w' field alignment, corresponds to the
Calendar.WEEK_OF_YEAR field. |
static int |
YEAR_FIELD
The
FieldPosition selector for 'y' field alignment, corresponds
to the Calendar.YEAR field. |
| Modifier | Constructor and Description |
|---|---|
protected |
DateFormat()
Constructs a new instance of
DateFormat. |
| Modifier and Type | Method and Description |
|---|---|
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.
|
String |
format(Date date)
Formats the specified date using the rules of this date format.
|
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.
|
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.
|
static Locale[] |
getAvailableLocales()
Returns an array of locales for which custom
DateFormat instances
are available. |
Calendar |
getCalendar()
Returns the calendar used by this
DateFormat. |
static DateFormat |
getDateInstance()
Returns a
DateFormat instance for formatting and parsing dates in
the DEFAULT style for the default locale. |
static DateFormat |
getDateInstance(int style)
Returns a
DateFormat instance for formatting and parsing dates in
the specified style for the user's default locale. |
static DateFormat |
getDateInstance(int style,
Locale locale)
Returns a
DateFormat instance for formatting and parsing dates in
the specified style for the specified locale. |
static DateFormat |
getDateTimeInstance()
Returns a
DateFormat instance for formatting and parsing dates
and time values in the DEFAULT style for the default locale. |
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. |
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. |
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. |
static DateFormat |
getTimeInstance()
Returns a
DateFormat instance for formatting and parsing time
values in the DEFAULT style for the default locale. |
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. |
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. |
static void |
set24HourTimePref(boolean is24Hour) |
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.
|
format, formatToCharacterIterator, parseObjectpublic static Boolean is24Hour
protected Calendar calendar
DateFormat uses to format a number
representing a date.protected NumberFormat numberFormat
public static final int DEFAULT
public static final int FULL
public static final int LONG
public static final int MEDIUM
public static final int SHORT
public static final int ERA_FIELD
FieldPosition selector for 'G' field alignment, corresponds
to the Calendar.ERA field.public static final int YEAR_FIELD
FieldPosition selector for 'y' field alignment, corresponds
to the Calendar.YEAR field.public static final int MONTH_FIELD
FieldPosition selector for 'M' field alignment, corresponds
to the Calendar.MONTH field.public static final int DATE_FIELD
FieldPosition selector for 'd' field alignment, corresponds
to the Calendar.DATE field.public static final int HOUR_OF_DAY1_FIELD
FieldPosition selector for 'k' field alignment, corresponds
to the Calendar.HOUR_OF_DAY field. HOUR_OF_DAY1_FIELD is
used for the one-based 24-hour clock. For example, 23:59 + 01:00 results
in 24:59.public static final int HOUR_OF_DAY0_FIELD
FieldPosition selector for 'H' field alignment, corresponds
to the Calendar.HOUR_OF_DAY field. HOUR_OF_DAY0_FIELD is
used for the zero-based 24-hour clock. For example, 23:59 + 01:00 results
in 00:59.public static final int MINUTE_FIELD
Calendar.MINUTE field.public static final int SECOND_FIELD
Calendar.SECOND field.public static final int MILLISECOND_FIELD
Calendar.MILLISECOND field.public static final int DAY_OF_WEEK_FIELD
Calendar.DAY_OF_WEEK field.public static final int DAY_OF_YEAR_FIELD
Calendar.DAY_OF_YEAR field.public static final int DAY_OF_WEEK_IN_MONTH_FIELD
Calendar.DAY_OF_WEEK_IN_MONTH field.public static final int WEEK_OF_YEAR_FIELD
Calendar.WEEK_OF_YEAR field.public static final int WEEK_OF_MONTH_FIELD
Calendar.WEEK_OF_MONTH field.public static final int AM_PM_FIELD
Calendar.AM_PM field.public static final int HOUR1_FIELD
Calendar.HOUR field.public static final int HOUR0_FIELD
FieldPosition selector for 'K' field alignment, corresponding to the
Calendar.HOUR field.public static final int TIMEZONE_FIELD
FieldPosition selector for 'z' field alignment, corresponds
to the Calendar.ZONE_OFFSET and Calendar.DST_OFFSET
fields.public Object clone()
DateFormat with the same properties.public boolean equals(Object object)
equals in class Objectobject - the object to compare with this date format.true if object is a DateFormat object and
it has the same properties as this date format; false
otherwise.hashCode()public final StringBuffer format(Object object, StringBuffer buffer, FieldPosition field)
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.
format in class Formatobject - the source object to format, must be a Date or a
Number. If object is a number then a date is
constructed using the longValue() of the number.buffer - the target string buffer to append the formatted date/time to.field - on input: an optional alignment field; on output: the offsets
of the alignment field in the formatted text.IllegalArgumentException - if object is neither a Date nor a
Number instance.public final String format(Date date)
date - the date to format.public abstract StringBuffer format(Date date, StringBuffer buffer, FieldPosition field)
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.
date - the date to format.buffer - the target string buffer to append the formatted date/time to.field - on input: an optional alignment field; on output: the offsets
of the alignment field in the formatted text.public static Locale[] getAvailableLocales()
DateFormat instances
are available.
Note that Android does not support user-supplied locale service providers.
public Calendar getCalendar()
DateFormat.public static final DateFormat getDateInstance()
DateFormat instance for formatting and parsing dates in
the DEFAULT style for the default locale.DateFormat instance for the default style and locale.public static final DateFormat getDateInstance(int style)
DateFormat instance for formatting and parsing dates in
the specified style for the user's default locale.
See "Be wary of the default locale".style - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.DateFormat instance for style and the default
locale.IllegalArgumentException - if style is not one of SHORT, MEDIUM, LONG, FULL, or
DEFAULT.public static final DateFormat getDateInstance(int style, Locale locale)
DateFormat instance for formatting and parsing dates in
the specified style for the specified locale.style - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.locale - the locale.DateFormat instance for style and
locale.IllegalArgumentException - if style is not one of SHORT, MEDIUM, LONG, FULL, or
DEFAULT.public static final DateFormat getDateTimeInstance()
DateFormat instance for formatting and parsing dates
and time values in the DEFAULT style for the default locale.DateFormat instance for the default style and locale.public static final DateFormat getDateTimeInstance(int dateStyle, int timeStyle)
DateFormat instance for formatting and parsing of both
dates and time values in the manner appropriate for the user's default locale.
See "Be wary of the default locale".dateStyle - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.timeStyle - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.DateFormat instance for dateStyle,
timeStyle and the default locale.IllegalArgumentException - if dateStyle or timeStyle is not one of
SHORT, MEDIUM, LONG, FULL, or DEFAULT.public static final DateFormat getDateTimeInstance(int dateStyle, int timeStyle, Locale locale)
DateFormat instance for formatting and parsing dates
and time values in the specified styles for the specified locale.dateStyle - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.timeStyle - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.locale - the locale.DateFormat instance for dateStyle,
timeStyle and locale.IllegalArgumentException - if dateStyle or timeStyle is not one of
SHORT, MEDIUM, LONG, FULL, or DEFAULT.public static final DateFormat getInstance()
DateFormat instance for formatting and parsing dates
and times in the SHORT style for the default locale.DateFormat instance for the SHORT style and default
locale.public static final void set24HourTimePref(boolean is24Hour)
public NumberFormat getNumberFormat()
NumberFormat used by this DateFormat.NumberFormat used by this date format.public static final DateFormat getTimeInstance()
DateFormat instance for formatting and parsing time
values in the DEFAULT style for the default locale.DateFormat instance for the default style and locale.public static final DateFormat getTimeInstance(int style)
DateFormat instance for formatting and parsing time
values in the specified style for the user's default locale.
See "Be wary of the default locale".style - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.DateFormat instance for style and the default
locale.IllegalArgumentException - if style is not one of SHORT, MEDIUM, LONG, FULL, or
DEFAULT.public static final DateFormat getTimeInstance(int style, Locale locale)
DateFormat instance for formatting and parsing time
values in the specified style for the specified locale.style - one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.locale - the locale.DateFormat instance for style and
locale.IllegalArgumentException - if style is not one of SHORT, MEDIUM, LONG, FULL, or
DEFAULT.public TimeZone getTimeZone()
public int hashCode()
ObjectObject.equals(java.lang.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.
hashCode in class ObjectObject.equals(java.lang.Object)public boolean isLenient()
true if the calendar is lenient; false otherwise.public Date parse(String string) throws ParseException
string - the string to parse.Date resulting from the parsing.ParseException - if an error occurs during parsing.public abstract Date parse(String string, ParsePosition position)
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.
By default, parsing is lenient: If the input is not in the form used by
this object's format method but can still be parsed as a date, then the
parse succeeds. Clients may insist on strict adherence to the format by
calling setLenient(false).
string - the string to parse.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.null if there is an
error.public Object parseObject(String string, ParsePosition position)
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.
By default, parsing is lenient: If the input is not in the form used by
this object's format method but can still be parsed as a date, then the
parse succeeds. Clients may insist on strict adherence to the format by
calling setLenient(false).
parseObject in class Formatstring - the string to parse.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.null if there is
an error.public void setCalendar(Calendar cal)
cal - the new calendar.public void setLenient(boolean value)
value - true to set the calendar to be lenient, false
otherwise.public void setNumberFormat(NumberFormat format)
NumberFormat used by this date format.format - the new number format.public void setTimeZone(TimeZone timezone)
timezone - the new time zone.