Package java.text

Class DateFormat

java.lang.Object
java.text.Format
java.text.DateFormat
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
SimpleDateFormat
public abstract class DateFormat
extends Format
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.
See Also:
Serialized Form

  • Field Details

    • calendar

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

    • numberFormat

      protected NumberFormat numberFormat
      The number format used to format a number.

    • DEFAULT

      public static final int DEFAULT
      The format style constant defining the default format style. The default is MEDIUM.
      See Also:
      Constant Field Values

    • FULL

      public static final int FULL
      The format style constant defining the full style.
      See Also:
      Constant Field Values

    • LONG

      public static final int LONG
      The format style constant defining the long style.
      See Also:
      Constant Field Values

    • MEDIUM

      public static final int MEDIUM
      The format style constant defining the medium style.
      See Also:
      Constant Field Values

    • SHORT

      public static final int SHORT
      The format style constant defining the short style.
      See Also:
      Constant Field Values

    • ERA_FIELD

      public static final int ERA_FIELD
      The FieldPosition selector for 'G' field alignment, corresponds to the Calendar.ERA field.
      See Also:
      Constant Field Values

    • YEAR_FIELD

      public static final int YEAR_FIELD
      The FieldPosition selector for 'y' field alignment, corresponds to the Calendar.YEAR field.
      See Also:
      Constant Field Values

    • MONTH_FIELD

      public static final int MONTH_FIELD
      The FieldPosition selector for 'M' field alignment, corresponds to the Calendar.MONTH field.
      See Also:
      Constant Field Values

    • DATE_FIELD

      public static final int DATE_FIELD
      The FieldPosition selector for 'd' field alignment, corresponds to the Calendar.DATE field.
      See Also:
      Constant Field Values

    • HOUR_OF_DAY1_FIELD

      public static final int HOUR_OF_DAY1_FIELD
      The 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.
      See Also:
      Constant Field Values

    • HOUR_OF_DAY0_FIELD

      public static final int HOUR_OF_DAY0_FIELD
      The 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.
      See Also:
      Constant Field Values

    • MINUTE_FIELD

      public static final int MINUTE_FIELD
      FieldPosition selector for 'm' field alignment, corresponds to the Calendar.MINUTE field.
      See Also:
      Constant Field Values

    • SECOND_FIELD

      public static final int SECOND_FIELD
      FieldPosition selector for 's' field alignment, corresponds to the Calendar.SECOND field.
      See Also:
      Constant Field Values

    • MILLISECOND_FIELD

      public static final int MILLISECOND_FIELD
      FieldPosition selector for 'S' field alignment, corresponds to the Calendar.MILLISECOND field.
      See Also:
      Constant Field Values

    • DAY_OF_WEEK_FIELD

      public static final int DAY_OF_WEEK_FIELD
      FieldPosition selector for 'E' field alignment, corresponds to the Calendar.DAY_OF_WEEK field.
      See Also:
      Constant Field Values

    • DAY_OF_YEAR_FIELD

      public static final int DAY_OF_YEAR_FIELD
      FieldPosition selector for 'D' field alignment, corresponds to the Calendar.DAY_OF_YEAR field.
      See Also:
      Constant Field Values

    • DAY_OF_WEEK_IN_MONTH_FIELD

      public static final int DAY_OF_WEEK_IN_MONTH_FIELD
      FieldPosition selector for 'F' field alignment, corresponds to the Calendar.DAY_OF_WEEK_IN_MONTH field.
      See Also:
      Constant Field Values

    • WEEK_OF_YEAR_FIELD

      public static final int WEEK_OF_YEAR_FIELD
      FieldPosition selector for 'w' field alignment, corresponds to the Calendar.WEEK_OF_YEAR field.
      See Also:
      Constant Field Values

    • WEEK_OF_MONTH_FIELD

      public static final int WEEK_OF_MONTH_FIELD
      FieldPosition selector for 'W' field alignment, corresponds to the Calendar.WEEK_OF_MONTH field.
      See Also:
      Constant Field Values

    • AM_PM_FIELD

      public static final int AM_PM_FIELD
      FieldPosition selector for 'a' field alignment, corresponds to the Calendar.AM_PM field.
      See Also:
      Constant Field Values

    • HOUR1_FIELD

      public static final int HOUR1_FIELD
      FieldPosition selector for 'h' field alignment, corresponding to the Calendar.HOUR field.
      See Also:
      Constant Field Values

    • HOUR0_FIELD

      public static final int HOUR0_FIELD
      The FieldPosition selector for 'K' field alignment, corresponding to the Calendar.HOUR field.
      See Also:
      Constant Field Values

    • TIMEZONE_FIELD

      public static final int TIMEZONE_FIELD
      The FieldPosition selector for 'z' field alignment, corresponds to the Calendar.ZONE_OFFSET and Calendar.DST_OFFSET fields.
      See Also:
      Constant Field Values

  • Constructor Details

    • DateFormat

      protected DateFormat()
      Constructs a new instance of DateFormat.

  • Method Details

    • clone

      public Object clone()
      Returns a new instance of DateFormat with the same properties.
      Overrides:
      clone in class Format
      Returns:
      a shallow copy of this format.
      See Also:
      Cloneable

    • equals

      public boolean equals​(Object object)
      Compares this date format with the specified object and indicates if they are equal.
      Overrides:
      equals in class Object
      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:
      hashCode()

    • format

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

      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.

      Specified by:
      format in class Format
      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.

    • format

      public final String format​(Date date)
      Formats the specified date using the rules of this date format.
      Parameters:
      date - the date to format.
      Returns:
      the formatted string.

    • format

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

      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.

    • getAvailableLocales

      public static 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.

    • getCalendar

      public Calendar getCalendar()
      Returns the calendar used by this DateFormat.
      Returns:
      the calendar used by this date format.

    • getDateInstance

      public static final DateFormat getDateInstance()
      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.

    • getDateInstance

      public static final 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 - 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.

    • getDateInstance

      public static final 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 - 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.

    • getDateTimeInstance

      public static final DateFormat getDateTimeInstance()
      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.

    • getDateTimeInstance

      public static final 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 - 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.

    • getDateTimeInstance

      public static final 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 - 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.

    • getInstance

      public static final DateFormat getInstance()
      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.

    • getNumberFormat

      public NumberFormat getNumberFormat()
      Returns the NumberFormat used by this DateFormat.
      Returns:
      the NumberFormat used by this date format.

    • getTimeInstance

      public static final DateFormat getTimeInstance()
      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.

    • getTimeInstance

      public static final 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 - 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.

    • getTimeInstance

      public static final 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 - 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.

    • getTimeZone

      public TimeZone getTimeZone()
      Returns the time zone of this date format's calendar.
      Returns:
      the time zone of the calendar used by this date format.

    • hashCode

      public int hashCode()
      Description copied from class: Object
      Returns an integer hash code for this object. By contract, any two objects for which Object.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.

      Overrides:
      hashCode in class Object
      Returns:
      this object's hash code.
      See Also:
      Object.equals(java.lang.Object)

    • isLenient

      public boolean isLenient()
      Indicates whether the calendar used by this date format is lenient.
      Returns:
      true if the calendar is lenient; false otherwise.

    • parse

      public Date parse​(String string) throws ParseException
      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.

    • parse

      public abstract 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 - 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.

    • parseObject

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

      Specified by:
      parseObject in class Format
      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.

    • setCalendar

      public void setCalendar​(Calendar cal)
      Sets the calendar used by this date format.
      Parameters:
      cal - the new calendar.

    • setLenient

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

    • setNumberFormat

      public void setNumberFormat​(NumberFormat format)
      Sets the NumberFormat used by this date format.
      Parameters:
      format - the new number format.

    • setTimeZone

      public void setTimeZone​(TimeZone timezone)
      Sets the time zone of the calendar used by this date format.
      Parameters:
      timezone - the new time zone.