DateFormatUtils (Apache Commons Lang 3.17.0 API)
Description: declaration: package: org.apache.commons.lang3.time, class: DateFormatUtils

Package org.apache.commons.lang3.time

# Class DateFormatUtils

java.lang.Object
org.apache.commons.lang3.time.DateFormatUtils

public class DateFormatUtils extends Object
Date and time formatting utilities and constants.

Formatting is performed using the thread-safe `FastDateFormat` class.

Note that the JDK has a bug wherein calling Calendar.get(int) will override any previously called Calendar.clear() calls. See LANG-755.

Note that when using capital YYYY instead of lowercase yyyy, the formatter will assume current year as week year is not supported. See `GregorianCalendar` Week Year section for an explanation on the difference between calendar and week years.

Since:
  2.0

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final FastDateFormat`
  `ISO_8601_EXTENDED_DATE_FORMAT`
  ISO 8601 formatter for date without time zone.
  `static final FastDateFormat`
  `ISO_8601_EXTENDED_DATETIME_FORMAT`
  ISO 8601 formatter for date-time without time zone.
  `static final FastDateFormat`
  `ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT`
  ISO 8601 formatter for date-time with time zone.
  `static final FastDateFormat`
  `ISO_8601_EXTENDED_TIME_FORMAT`
  ISO 8601 formatter for time without time zone.
  `static final FastDateFormat`
  `ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT`
  ISO 8601 formatter for time with time zone.
  `static final FastDateFormat`
  `ISO_DATE_FORMAT`
  Deprecated.
  - as of 4.0, ISO_DATE_FORMAT will be replaced by ISO_8601_EXTENDED_DATE_FORMAT.
  `static final FastDateFormat`
  `ISO_DATE_TIME_ZONE_FORMAT`
  Deprecated.
  - as of 4.0, ISO_DATE_TIME_ZONE_FORMAT will be removed.
  `static final FastDateFormat`
  `ISO_DATETIME_FORMAT`
  Deprecated.
  - as of 4.0, ISO_DATETIME_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_FORMAT.
  `static final FastDateFormat`
  `ISO_DATETIME_TIME_ZONE_FORMAT`
  Deprecated.
  - as of 4.0, ISO_DATETIME_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT.
  `static final FastDateFormat`
  `ISO_TIME_FORMAT`
  Deprecated.
  - as of 4.0, ISO_TIME_FORMAT will be removed.
  `static final FastDateFormat`
  `ISO_TIME_NO_T_FORMAT`
  Deprecated.
  - as of 4.0, ISO_TIME_NO_T_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_FORMAT.
  `static final FastDateFormat`
  `ISO_TIME_NO_T_TIME_ZONE_FORMAT`
  Deprecated.
  - as of 4.0, ISO_TIME_NO_T_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT.
  `static final FastDateFormat`
  `ISO_TIME_TIME_ZONE_FORMAT`
  Deprecated.
  - as of 4.0, ISO_TIME_TIME_ZONE_FORMAT will be removed.
  `static final FastDateFormat`
  `SMTP_DATETIME_FORMAT`
  SMTP (and probably other) date headers.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DateFormatUtils()`
  Deprecated.
  TODO Make private in 4.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `format(long millis, String pattern)`
  Formats a date/time into a specific pattern.
  `static String`
  `format(long millis, String pattern, Locale locale)`
  Formats a date/time into a specific pattern in a locale.
  `static String`
  `format(long millis, String pattern, TimeZone timeZone)`
  Formats a date/time into a specific pattern in a time zone.
  `static String`
  `format(long millis, String pattern, TimeZone timeZone, Locale locale)`
  Formats a date/time into a specific pattern in a time zone and locale.
  `static String`
  `format(Calendar calendar, String pattern)`
  Formats a calendar into a specific pattern.
  `static String`
  `format(Calendar calendar, String pattern, Locale locale)`
  Formats a calendar into a specific pattern in a locale.
  `static String`
  `format(Calendar calendar, String pattern, TimeZone timeZone)`
  Formats a calendar into a specific pattern in a time zone.
  `static String`
  `format(Calendar calendar, String pattern, TimeZone timeZone, Locale locale)`
  Formats a calendar into a specific pattern in a time zone and locale.
  `static String`
  `format(Date date, String pattern)`
  Formats a date/time into a specific pattern.
  `static String`
  `format(Date date, String pattern, Locale locale)`
  Formats a date/time into a specific pattern in a locale.
  `static String`
  `format(Date date, String pattern, TimeZone timeZone)`
  Formats a date/time into a specific pattern in a time zone.
  `static String`
  `format(Date date, String pattern, TimeZone timeZone, Locale locale)`
  Formats a date/time into a specific pattern in a time zone and locale.
  `static String`
  `formatUTC(long millis, String pattern)`
  Formats a date/time into a specific pattern using the UTC time zone.
  `static String`
  `formatUTC(long millis, String pattern, Locale locale)`
  Formats a date/time into a specific pattern using the UTC time zone.
  `static String`
  `formatUTC(Date date, String pattern)`
  Formats a date/time into a specific pattern using the UTC time zone.
  `static String`
  `formatUTC(Date date, String pattern, Locale locale)`
  Formats a date/time into a specific pattern using the UTC time zone.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ISO_8601_EXTENDED_DATETIME_FORMAT

    public static final FastDateFormat ISO_8601_EXTENDED_DATETIME_FORMAT
    ISO 8601 formatter for date-time without time zone.

    The format used is `yyyy-MM-dd'T'HH:mm:ss`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

    Since:
      3.5

  - ### ISO_DATETIME_FORMAT

    @Deprecated public static final FastDateFormat ISO_DATETIME_FORMAT
    Deprecated.
    - as of 4.0, ISO_DATETIME_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_FORMAT.

  - ### ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT

    public static final FastDateFormat ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT
    ISO 8601 formatter for date-time with time zone.

    The format used is `yyyy-MM-dd'T'HH:mm:ssZZ`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

    Since:
      3.5

  - ### ISO_DATETIME_TIME_ZONE_FORMAT

    @Deprecated public static final FastDateFormat ISO_DATETIME_TIME_ZONE_FORMAT
    Deprecated.
    - as of 4.0, ISO_DATETIME_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT.

  - ### ISO_8601_EXTENDED_DATE_FORMAT

    public static final FastDateFormat ISO_8601_EXTENDED_DATE_FORMAT
    ISO 8601 formatter for date without time zone.

    The format used is `yyyy-MM-dd`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

    Since:
      3.5

  - ### ISO_DATE_FORMAT

    @Deprecated public static final FastDateFormat ISO_DATE_FORMAT
    Deprecated.
    - as of 4.0, ISO_DATE_FORMAT will be replaced by ISO_8601_EXTENDED_DATE_FORMAT.

  - ### ISO_DATE_TIME_ZONE_FORMAT

    @Deprecated public static final FastDateFormat ISO_DATE_TIME_ZONE_FORMAT
    Deprecated.
    - as of 4.0, ISO_DATE_TIME_ZONE_FORMAT will be removed.
    ISO 8601-like formatter for date with time zone.

    The format used is `yyyy-MM-ddZZ`. This pattern does not comply with the formal ISO 8601 specification as the standard does not allow a time zone without a time. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

  - ### ISO_TIME_FORMAT

    @Deprecated public static final FastDateFormat ISO_TIME_FORMAT
    Deprecated.
    - as of 4.0, ISO_TIME_FORMAT will be removed.
    Non-compliant formatter for time without time zone (ISO 8601 does not prefix 'T' for standalone time value).

    The format used is `'T'HH:mm:ss`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

  - ### ISO_TIME_TIME_ZONE_FORMAT

    @Deprecated public static final FastDateFormat ISO_TIME_TIME_ZONE_FORMAT
    Deprecated.
    - as of 4.0, ISO_TIME_TIME_ZONE_FORMAT will be removed.
    Non-compliant formatter for time with time zone (ISO 8601 does not prefix 'T' for standalone time value).

    The format used is `'T'HH:mm:ssZZ`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

  - ### ISO_8601_EXTENDED_TIME_FORMAT

    public static final FastDateFormat ISO_8601_EXTENDED_TIME_FORMAT
    ISO 8601 formatter for time without time zone.

    The format used is `HH:mm:ss`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

    Since:
      3.5

  - ### ISO_TIME_NO_T_FORMAT

    @Deprecated public static final FastDateFormat ISO_TIME_NO_T_FORMAT
    Deprecated.
    - as of 4.0, ISO_TIME_NO_T_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_FORMAT.

  - ### ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT

    public static final FastDateFormat ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT
    ISO 8601 formatter for time with time zone.

    The format used is `HH:mm:ssZZ`. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

    Since:
      3.5

  - ### ISO_TIME_NO_T_TIME_ZONE_FORMAT

    @Deprecated public static final FastDateFormat ISO_TIME_NO_T_TIME_ZONE_FORMAT
    Deprecated.
    - as of 4.0, ISO_TIME_NO_T_TIME_ZONE_FORMAT will be replaced by ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT.

  - ### SMTP_DATETIME_FORMAT

    public static final FastDateFormat SMTP_DATETIME_FORMAT
    SMTP (and probably other) date headers.

    The format used is `EEE, dd MMM yyyy HH:mm:ss Z` in US locale. This format uses the default TimeZone in effect at the time of loading DateFormatUtils class.

- ## Constructor Details

  - ### DateFormatUtils

    @Deprecated public DateFormatUtils()
    Deprecated.
    TODO Make private in 4.0.
    DateFormatUtils instances should NOT be constructed in standard programming.

    This constructor is public to permit tools that require a JavaBean instance to operate.

- ## Method Details

  - ### format

    public static String format(Calendar calendar, String pattern)
    Formats a calendar into a specific pattern. The TimeZone from the calendar will be used for formatting.
    Parameters:
      `calendar` - the calendar to format, not null
      `pattern` - the pattern to use to format the calendar, not null
    Returns:
      the formatted calendar
    Since:
      2.4
    See Also:
      - `FastDateFormat.format(Calendar)`

  - ### format

    public static String format(Calendar calendar, String pattern, Locale locale)
    Formats a calendar into a specific pattern in a locale. The TimeZone from the calendar will be used for formatting.
    Parameters:
      `calendar` - the calendar to format, not null
      `pattern` - the pattern to use to format the calendar, not null
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted calendar
    Since:
      2.4
    See Also:
      - `FastDateFormat.format(Calendar)`

  - ### format

    public static String format(Calendar calendar, String pattern, TimeZone timeZone)
    Formats a calendar into a specific pattern in a time zone.
    Parameters:
      `calendar` - the calendar to format, not null
      `pattern` - the pattern to use to format the calendar, not null
      `timeZone` - the time zone to use, may be `null`
    Returns:
      the formatted calendar
    Since:
      2.4
    See Also:
      - `FastDateFormat.format(Calendar)`

  - ### format

    public static String format(Calendar calendar, String pattern, TimeZone timeZone, Locale locale)
    Formats a calendar into a specific pattern in a time zone and locale.
    Parameters:
      `calendar` - the calendar to format, not null
      `pattern` - the pattern to use to format the calendar, not null
      `timeZone` - the time zone to use, may be `null`
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted calendar
    Since:
      2.4
    See Also:
      - `FastDateFormat.format(Calendar)`

  - ### format

    public static String format(Date date, String pattern)
    Formats a date/time into a specific pattern.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null
    Returns:
      the formatted date

  - ### format

    public static String format(Date date, String pattern, Locale locale)
    Formats a date/time into a specific pattern in a locale.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date

  - ### format

    public static String format(Date date, String pattern, TimeZone timeZone)
    Formats a date/time into a specific pattern in a time zone.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null
      `timeZone` - the time zone to use, may be `null`
    Returns:
      the formatted date

  - ### format

    public static String format(Date date, String pattern, TimeZone timeZone, Locale locale)
    Formats a date/time into a specific pattern in a time zone and locale.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null, not null
      `timeZone` - the time zone to use, may be `null`
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date

  - ### format

    public static String format(long millis, String pattern)
    Formats a date/time into a specific pattern.
    Parameters:
      `millis` - the date to format expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
    Returns:
      the formatted date

  - ### format

    public static String format(long millis, String pattern, Locale locale)
    Formats a date/time into a specific pattern in a locale.
    Parameters:
      `millis` - the date to format expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date

  - ### format

    public static String format(long millis, String pattern, TimeZone timeZone)
    Formats a date/time into a specific pattern in a time zone.
    Parameters:
      `millis` - the time expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
      `timeZone` - the time zone to use, may be `null`
    Returns:
      the formatted date

  - ### format

    public static String format(long millis, String pattern, TimeZone timeZone, Locale locale)
    Formats a date/time into a specific pattern in a time zone and locale.
    Parameters:
      `millis` - the date to format expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
      `timeZone` - the time zone to use, may be `null`
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date

  - ### formatUTC

    public static String formatUTC(Date date, String pattern)
    Formats a date/time into a specific pattern using the UTC time zone.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null
    Returns:
      the formatted date

  - ### formatUTC

    public static String formatUTC(Date date, String pattern, Locale locale)
    Formats a date/time into a specific pattern using the UTC time zone.
    Parameters:
      `date` - the date to format, not null
      `pattern` - the pattern to use to format the date, not null
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date

  - ### formatUTC

    public static String formatUTC(long millis, String pattern)
    Formats a date/time into a specific pattern using the UTC time zone.
    Parameters:
      `millis` - the date to format expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
    Returns:
      the formatted date

  - ### formatUTC

    public static String formatUTC(long millis, String pattern, Locale locale)
    Formats a date/time into a specific pattern using the UTC time zone.
    Parameters:
      `millis` - the date to format expressed in milliseconds
      `pattern` - the pattern to use to format the date, not null
      `locale` - the locale to use, may be `null`
    Returns:
      the formatted date