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 and Description
    --- | ---
    `static FastDateFormat` | `ISO_8601_EXTENDED_DATE_FORMAT` ISO 8601 formatter for date without time zone.
    `static FastDateFormat` | `ISO_8601_EXTENDED_DATETIME_FORMAT` ISO 8601 formatter for date-time without time zone.
    `static FastDateFormat` | `ISO_8601_EXTENDED_DATETIME_TIME_ZONE_FORMAT` ISO 8601 formatter for date-time with time zone.
    `static FastDateFormat` | `ISO_8601_EXTENDED_TIME_FORMAT` ISO 8601 formatter for time without time zone.
    `static FastDateFormat` | `ISO_8601_EXTENDED_TIME_TIME_ZONE_FORMAT` ISO 8601 formatter for time with time zone.
    `static FastDateFormat` | `ISO_DATE_FORMAT` Deprecated. - as of 4.0, ISO_DATE_FORMAT will be replaced by ISO_8601_EXTENDED_DATE_FORMAT.
    `static FastDateFormat` | `ISO_DATE_TIME_ZONE_FORMAT` Deprecated. - as of 4.0, ISO_DATE_TIME_ZONE_FORMAT will be removed.
    `static FastDateFormat` | `ISO_DATETIME_FORMAT` Deprecated. - as of 4.0, ISO_DATETIME_FORMAT will be replaced by ISO_8601_EXTENDED_DATETIME_FORMAT.
    `static 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 FastDateFormat` | `ISO_TIME_FORMAT` Deprecated. - as of 4.0, ISO_TIME_FORMAT will be removed.
    `static 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 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 FastDateFormat` | `ISO_TIME_TIME_ZONE_FORMAT` Deprecated. - as of 4.0, ISO_TIME_TIME_ZONE_FORMAT will be removed.
    `static FastDateFormat` | `SMTP_DATETIME_FORMAT` SMTP (and probably other) date headers.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateFormatUtils()` DateFormatUtils instances should NOT be constructed in standard programming.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `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` | `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.
    `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.

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### DateFormatUtils

          public DateFormatUtils()

      DateFormatUtils instances should NOT be constructed in standard programming.

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

  - ### Method Detail

    - #### 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

Copyright © 2001–2023 The Apache Software Foundation. All rights reserved.