Skip to content

Most visited

Recently visited

navigation
Added in API level 1

DateFormat

public abstract class DateFormat
extends Format

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


Formats or parses dates and times.

This class provides factories for obtaining instances configured for a specific locale. The most common subclass is SimpleDateFormat.

Sample Code

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 AM
 
And 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.

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.

Inherited methods

From class java.text.Format
From class java.lang.Object

Constants

AM_PM_FIELD

Added in API level 1
int AM_PM_FIELD

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

Constant Value: 14 (0x0000000e)

DATE_FIELD

Added in API level 1
int DATE_FIELD

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

Constant Value: 3 (0x00000003)

DAY_OF_WEEK_FIELD

Added in API level 1
int DAY_OF_WEEK_FIELD

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

Constant Value: 9 (0x00000009)

DAY_OF_WEEK_IN_MONTH_FIELD

Added in API level 1
int DAY_OF_WEEK_IN_MONTH_FIELD

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

Constant Value: 11 (0x0000000b)

DAY_OF_YEAR_FIELD

Added in API level 1
int DAY_OF_YEAR_FIELD

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

Constant Value: 10 (0x0000000a)

DEFAULT

Added in API level 1
int DEFAULT

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

Constant Value: 2 (0x00000002)

ERA_FIELD

Added in API level 1
int ERA_FIELD

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

Constant Value: 0 (0x00000000)

FULL

Added in API level 1
int FULL

The format style constant defining the full style.

Constant Value: 0 (0x00000000)

HOUR0_FIELD

Added in API level 1
int HOUR0_FIELD

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

Constant Value: 16 (0x00000010)

HOUR1_FIELD

Added in API level 1
int HOUR1_FIELD

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

Constant Value: 15 (0x0000000f)

HOUR_OF_DAY0_FIELD

Added in API level 1
int HOUR_OF_DAY0_FIELD

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)

HOUR_OF_DAY1_FIELD

Added in API level 1
int HOUR_OF_DAY1_FIELD

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)

LONG

Added in API level 1
int LONG

The format style constant defining the long style.

Constant Value: 1 (0x00000001)

MEDIUM

Added in API level 1
int MEDIUM

The format style constant defining the medium style.

Constant Value: 2 (0x00000002)

MILLISECOND_FIELD

Added in API level 1
int MILLISECOND_FIELD

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

Constant Value: 8 (0x00000008)

MINUTE_FIELD

Added in API level 1
int MINUTE_FIELD

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

Constant Value: 6 (0x00000006)

MONTH_FIELD

Added in API level 1
int MONTH_FIELD

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

Constant Value: 2 (0x00000002)

SECOND_FIELD

Added in API level 1
int SECOND_FIELD

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

Constant Value: 7 (0x00000007)

SHORT

Added in API level 1
int SHORT

The format style constant defining the short style.

Constant Value: 3 (0x00000003)

TIMEZONE_FIELD

Added in API level 1
int TIMEZONE_FIELD

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

Constant Value: 17 (0x00000011)

WEEK_OF_MONTH_FIELD

Added in API level 1
int WEEK_OF_MONTH_FIELD

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

Constant Value: 13 (0x0000000d)

WEEK_OF_YEAR_FIELD

Added in API level 1
int WEEK_OF_YEAR_FIELD

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

Constant Value: 12 (0x0000000c)

YEAR_FIELD

Added in API level 1
int YEAR_FIELD

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

Constant Value: 1 (0x00000001)

Fields

calendar

Added in API level 1
Calendar calendar

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

numberFormat

Added in API level 1
NumberFormat numberFormat

The number format used to format a number.

Protected constructors

DateFormat

Added in API level 1
DateFormat ()

Constructs a new instance of DateFormat.

Public methods

clone

Added in API level 1
Object clone ()

Returns a new instance of DateFormat with the same properties.

Returns
Object a shallow copy of this format.

equals

Added in API level 1
boolean equals (Object object)

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

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

See also:

format

Added in API level 1
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.

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 Date: the date to format.
buffer StringBuffer: the target string buffer to append the formatted date/time to.
field FieldPosition: on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
Returns
StringBuffer the string buffer.

format

Added in API level 1
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.

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 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 StringBuffer: the target string buffer to append the formatted date/time to.
field FieldPosition: on input: an optional alignment field; on output: the offsets of the alignment field in the formatted text.
Returns
StringBuffer the string buffer.
Throws
IllegalArgumentException if object is neither a Date nor a Number instance.

format

Added in API level 1
String format (Date date)

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

Parameters
date Date: the date to format.
Returns
String the formatted string.

getAvailableLocales

Added in API level 1
Locale[] getAvailableLocales ()

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

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

Returns
Locale[]

getCalendar

Added in API level 1
Calendar getCalendar ()

Returns the calendar used by this DateFormat.

Returns
Calendar the calendar used by this date format.

getDateInstance

Added in API level 1
DateFormat getDateInstance (int style)

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 int: one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
DateFormat the DateFormat instance for style and the default locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

getDateInstance

Added in API level 1
DateFormat getDateInstance (int style, 
                Locale locale)

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

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

getDateInstance

Added in API level 1
DateFormat getDateInstance ()

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

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

getDateTimeInstance

Added in API level 1
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.

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

getDateTimeInstance

Added in API level 1
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. See "Be wary of the default locale".

Parameters
dateStyle int: one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
timeStyle int: one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
DateFormat 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.

getDateTimeInstance

Added in API level 1
DateFormat getDateTimeInstance ()

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

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

getInstance

Added in API level 1
DateFormat getInstance ()

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

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

getNumberFormat

Added in API level 1
NumberFormat getNumberFormat ()

Returns the NumberFormat used by this DateFormat.

Returns
NumberFormat the NumberFormat used by this date format.

getTimeInstance

Added in API level 1
DateFormat getTimeInstance (int style)

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 int: one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.
Returns
DateFormat the DateFormat instance for style and the default locale.
Throws
IllegalArgumentException if style is not one of SHORT, MEDIUM, LONG, FULL, or DEFAULT.

getTimeInstance

Added in API level 1
DateFormat getTimeInstance ()

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

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

getTimeInstance

Added in API level 1
DateFormat getTimeInstance (int style, 
                Locale locale)

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

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

getTimeZone

Added in API level 1
TimeZone getTimeZone ()

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

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

hashCode

Added in API level 1
int hashCode ()

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
int this object's hash code.

isLenient

Added in API level 1
boolean isLenient ()

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

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

parse

Added in API level 1
Date parse (String string)

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

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

parse

Added in API level 1
Date parse (String string, 
                ParsePosition position)

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 String: the string to parse.
position ParsePosition: 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
Date the date resulting from the parse, or null if there is an error.

parseObject

Added in API level 1
Object parseObject (String string, 
                ParsePosition position)

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 String: the string to parse.
position ParsePosition: 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
Object the date resulting from the parsing, or null if there is an error.

setCalendar

Added in API level 1
void setCalendar (Calendar cal)

Sets the calendar used by this date format.

Parameters
cal Calendar: the new calendar.

setLenient

Added in API level 1
void setLenient (boolean value)

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 boolean: true to set the calendar to be lenient, false otherwise.

setNumberFormat

Added in API level 1
void setNumberFormat (NumberFormat format)

Sets the NumberFormat used by this date format.

Parameters
format NumberFormat: the new number format.

setTimeZone

Added in API level 1
void setTimeZone (TimeZone timezone)

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

Parameters
timezone TimeZone: the new time zone.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.