public abstract class

DateFormat

extends Format
java.lang.Object
   ↳ java.text.Format
     ↳ java.text.DateFormat
Known Direct Subclasses

Class Overview

An abstract class for date/time formatting subclasses which formats and parses dates or time in a language-independent manner. The date/time formatting subclass, such as SimpleDateFormat, allows for formatting (i.e., date -> text), parsing (text -> date), and normalization. The date is represented as a Date object or as the milliseconds since January 1, 1970, 00:00:00 GMT.

DateFormat provides many class methods for obtaining default date/time formatters based on the default or a given locale and a number of formatting styles. The formatting styles include FULL, LONG, MEDIUM, and SHORT. More details and examples for using these styles are provided in the method descriptions.

DateFormat helps you to format and parse dates for any locale. Your code can be completely independent of the locale conventions for months, days of the week, or even the calendar format: lunar vs. solar.

To format a date for the current Locale, use one of the static factory methods: 

 myString = DateFormat.getDateInstance().format(myDate);

If you are formatting multiple dates, it is more efficient to get the format and use it multiple times so that the system doesn't have to fetch the information about the local language and country conventions multiple times. 

 DateFormat df = DateFormat.getDateInstance();
 for (int i = 0; i < a.length; ++i) {
     output.println(df.format(myDate[i]) + "; ");
 }

To format a number for a different locale, specify it in the call to getDateInstance: 

 DateFormat df = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);

DateFormat can also be used to parse strings: 

 myDate = df.parse(myString);

Use getDateInstance to get the normal date format for a country. Other static factory methods are available: Use getTimeInstance to get the time format for a country. Use getDateTimeInstance to get the date and time format. You can pass in different options to these factory methods to control the length of the result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the locale, but generally:

  • SHORT is completely numeric, such as 12.13.52 or 3:30pm
  • MEDIUM is longer, such as Jan 12, 1952
  • LONG is longer, such as January 12, 1952 or 3:30:32pm
  • FULL is pretty completely specified, such as Tuesday, April 12, 1952 AD or 3:30:42pm PST.

If needed, the time zone can be set on the format. For even greater control over the formatting or parsing, try casting the DateFormat you get from the factory methods to a SimpleDateFormat. This will work for the majority of countries; just remember to put it in a try block in case you encounter an unusual one.

There are versions of the parse and format methods which use ParsePosition and FieldPosition to allow you to

  • progressively parse through pieces of a string;
  • align any particular field.

Synchronization

Date formats are not synchronized. It is recommended to create separate format instances for each thread. If multiple threads access a format concurrently, it must be synchronized externally.

See Also

Summary

Nested Classes
class DateFormat.Field The instances of this inner class are used as attribute keys and values in AttributedCharacterIterator that the formatToCharacterIterator(Object) method returns. 
Constants
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.
Fields
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.
Protected Constructors
DateFormat()
Constructs a new instance of DateFormat.
Public Methods
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.
[Expand]
Inherited Methods
From class java.text.Format
From class java.lang.Object

Constants

public static final int AM_PM_FIELD

Since: API Level 1

FieldPosition selector for 'a' field alignment, corresponds to the AM_PM field.

Constant Value: 14 (0x0000000e)

public static final int DATE_FIELD

Since: API Level 1

The FieldPosition selector for 'd' field alignment, corresponds to the DATE field.

Constant Value: 3 (0x00000003)

public static final int DAY_OF_WEEK_FIELD

Since: API Level 1

FieldPosition selector for 'E' field alignment, corresponds to the DAY_OF_WEEK field.

Constant Value: 9 (0x00000009)

public static final int DAY_OF_WEEK_IN_MONTH_FIELD

Since: API Level 1

FieldPosition selector for 'F' field alignment, corresponds to the DAY_OF_WEEK_IN_MONTH field.

Constant Value: 11 (0x0000000b)

public static final int DAY_OF_YEAR_FIELD

Since: API Level 1

FieldPosition selector for 'D' field alignment, corresponds to the DAY_OF_YEAR field.

Constant Value: 10 (0x0000000a)

public static final int DEFAULT

Since: API Level 1

The format style constant defining the default format style. The default is MEDIUM.

Constant Value: 2 (0x00000002)

public static final int ERA_FIELD

Since: API Level 1

The FieldPosition selector for 'G' field alignment, corresponds to the ERA field.

Constant Value: 0 (0x00000000)

public static final int FULL

Since: API Level 1

The format style constant defining the full style.

Constant Value: 0 (0x00000000)

public static final int HOUR0_FIELD

Since: API Level 1

The FieldPosition selector for 'K' field alignment, corresponding to the HOUR field.

Constant Value: 16 (0x00000010)

public static final int HOUR1_FIELD

Since: API Level 1

FieldPosition selector for 'h' field alignment, corresponding to the HOUR field.

Constant Value: 15 (0x0000000f)

public static final int HOUR_OF_DAY0_FIELD

Since: API Level 1

The FieldPosition selector for 'H' field alignment, corresponds to the 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.

Constant Value: 5 (0x00000005)

public static final int HOUR_OF_DAY1_FIELD

Since: API Level 1

The FieldPosition selector for 'k' field alignment, corresponds to the 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.

Constant Value: 4 (0x00000004)

public static final int LONG

Since: API Level 1

The format style constant defining the long style.

Constant Value: 1 (0x00000001)

public static final int MEDIUM

Since: API Level 1

The format style constant defining the medium style.

Constant Value: 2 (0x00000002)

public static final int MILLISECOND_FIELD

Since: API Level 1

FieldPosition selector for 'S' field alignment, corresponds to the MILLISECOND field.

Constant Value: 8 (0x00000008)

public static final int MINUTE_FIELD

Since: API Level 1

FieldPosition selector for 'm' field alignment, corresponds to the MINUTE field.

Constant Value: 6 (0x00000006)

public static final int MONTH_FIELD

Since: API Level 1

The FieldPosition selector for 'M' field alignment, corresponds to the MONTH field.

Constant Value: 2 (0x00000002)

public static final int SECOND_FIELD

Since: API Level 1

FieldPosition selector for 's' field alignment, corresponds to the SECOND field.

Constant Value: 7 (0x00000007)

public static final int SHORT

Since: API Level 1

The format style constant defining the short style.

Constant Value: 3 (0x00000003)

public static final int TIMEZONE_FIELD

Since: API Level 1

The FieldPosition selector for 'z' field alignment, corresponds to the ZONE_OFFSET and DST_OFFSET fields.

Constant Value: 17 (0x00000011)

public static final int WEEK_OF_MONTH_FIELD

Since: API Level 1

FieldPosition selector for 'W' field alignment, corresponds to the WEEK_OF_MONTH field.

Constant Value: 13 (0x0000000d)

public static final int WEEK_OF_YEAR_FIELD

Since: API Level 1

FieldPosition selector for 'w' field alignment, corresponds to the WEEK_OF_YEAR field.

Constant Value: 12 (0x0000000c)

public static final int YEAR_FIELD

Since: API Level 1

The FieldPosition selector for 'y' field alignment, corresponds to the YEAR field.

Constant Value: 1 (0x00000001)

Fields

protected Calendar calendar

Since: API Level 1

The calendar that this DateFormat uses to format a number representing a date.

protected NumberFormat numberFormat

Since: API Level 1

The number format used to format a number.

Protected Constructors

protected DateFormat ()

Since: API Level 1

Constructs a new instance of DateFormat.

Public Methods

public Object clone ()

Since: API Level 1

Returns a new instance of DateFormat with the same properties.

Returns
  • a shallow copy of this DateFormat.
See Also

public boolean equals (Object object)

Since: API Level 1

Compares this date format with the specified object and indicates if they are equal.

Parameters
object the object to compare with this date format.
Returns
  • true if object is a DateFormat object and it has the same properties as this date format; false otherwise.
See Also

public abstract StringBuffer format (Date date, StringBuffer buffer, FieldPosition field)

Since: 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.
field on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
Returns
  • the string buffer.

public final StringBuffer format (Object object, StringBuffer buffer, FieldPosition field)

Since: API Level 1

Formats the specified object 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
object 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.
Returns
  • the string buffer.
Throws
IllegalArgumentException if object is neither a Date nor a Number instance.

public final String format (Date date)

Since: API Level 1

Formats the specified date using the rules of this date format.

Parameters
date the date to format.
Returns
  • the formatted string.

public static Locale[] getAvailableLocales ()

Since: API Level 1

Returns an array of locales for which custom DateFormat instances are available.

Note that Android does not support user-supplied locale service providers.

public Calendar getCalendar ()

Since: API Level 1

Returns the calendar used by this DateFormat.

Returns
  • the calendar used by this date format.

public static final DateFormat getDateInstance (int style)

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates in the specified style for the user's default locale. See "Be wary of the default locale".

Parameters
style one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
  • the DateFormat instance for style and the default locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public static final DateFormat getDateInstance (int style, Locale locale)

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates in the specified style for the specified locale.

Parameters
style one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
locale the locale.
Returns
  • the DateFormat instance for style and locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public static final DateFormat getDateInstance ()

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates in the DEFAULT style for the default locale.

Returns
  • the DateFormat instance for the default style and locale.

public static final DateFormat getDateTimeInstance (int dateStyle, int timeStyle, Locale locale)

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates and time values in the specified styles for the specified locale.

Parameters
dateStyle one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
timeStyle one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
locale the locale.
Returns
  • the DateFormat instance for dateStyle, timeStyle and locale.
Throws
IllegalArgumentException if dateStyle or timeStyle is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public static final DateFormat getDateTimeInstance (int dateStyle, int timeStyle)

Since: API Level 1

Returns a 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".

Parameters
dateStyle one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
timeStyle one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
  • the DateFormat instance for dateStyle, timeStyle and the default locale.
Throws
IllegalArgumentException if dateStyle or timeStyle is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public static final DateFormat getDateTimeInstance ()

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates and time values in the DEFAULT style for the default locale.

Returns
  • the DateFormat instance for the default style and locale.

public static final DateFormat getInstance ()

Since: API Level 1

Returns a DateFormat instance for formatting and parsing dates and times in the SHORT style for the default locale.

Returns
  • the DateFormat instance for the SHORT style and default locale.

public NumberFormat getNumberFormat ()

Since: API Level 1

Returns the NumberFormat used by this DateFormat.

Returns
  • the NumberFormat used by this date format.

public static final DateFormat getTimeInstance (int style)

Since: API Level 1

Returns a 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".

Parameters
style one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
  • the DateFormat instance for style and the default locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public static final DateFormat getTimeInstance ()

Since: API Level 1

Returns a DateFormat instance for formatting and parsing time values in the DEFAULT style for the default locale.

Returns
  • the DateFormat instance for the default style and locale.

public static final DateFormat getTimeInstance (int style, Locale locale)

Since: API Level 1

Returns a DateFormat instance for formatting and parsing time values in the specified style for the specified locale.

Parameters
style one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
locale the locale.
Returns
  • the DateFormat instance for style and locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

public TimeZone getTimeZone ()

Since: API Level 1

Returns the time zone of this date format's calendar.

Returns
  • the time zone of the calendar used by this date format.

public int hashCode ()

Since: 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 boolean isLenient ()

Since: API Level 1

Indicates whether the calendar used by this date format is lenient.

Returns
  • true if the calendar is lenient; false otherwise.

public Date parse (String string)

Since: API Level 1

Parses a date from the specified string using the rules of this date format.

Parameters
string the string to parse.
Returns
  • the Date resulting from the parsing.
Throws
ParseException if an error occurs during parsing.

public abstract Date parse (String string, ParsePosition position)

Since: 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.

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

Parameters
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.
Returns
  • the date resulting from the parse, or null if there is an error.

public Object parseObject (String string, ParsePosition position)

Since: 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.

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

Parameters
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.
Returns
  • the date resulting from the parsing, or null if there is an error.

public void setCalendar (Calendar cal)

Since: API Level 1

Sets the calendar used by this date format.

Parameters
cal the new calendar.

public void setLenient (boolean value)

Since: API Level 1

Specifies whether or not date/time parsing shall be lenient. With lenient parsing, the parser may use heuristics to interpret inputs that do not precisely match this object's format. With strict parsing, inputs must match this object's format.

Parameters
value true to set the calendar to be lenient, false otherwise.

public void setNumberFormat (NumberFormat format)

Since: API Level 1

Sets the NumberFormat used by this date format.

Parameters
format the new number format.

public void setTimeZone (TimeZone timezone)

Since: API Level 1

Sets the time zone of the calendar used by this date format.

Parameters
timezone the new time zone.