DateUtils (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.util, class: DateUtils

Package org.apache.tools.ant.util

# Class DateUtils

java.lang.Object
org.apache.tools.ant.util.DateUtils

public final class DateUtils extends Object
Helper methods to deal with date/time formatting with a specific defined format (ISO8601) or a correct pluralization of elapsed time in minutes and seconds.

Since:
  Ant 1.5

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final DateFormat`
  `DATE_HEADER_FORMAT`
  Deprecated.
  DateFormat is not thread safe, and we cannot guarantee that some other code is using the format in parallel.
  `static final ThreadLocal<DateFormat>`
  `EN_US_DATE_FORMAT_MIN`
  Provides a thread-local US-style date format.
  `static final ThreadLocal<DateFormat>`
  `EN_US_DATE_FORMAT_SEC`
  Provides a thread-local US-style date format.
  `static final String`
  `ISO8601_DATE_PATTERN`
  ISO8601-like pattern for date.
  `static final String`
  `ISO8601_DATETIME_PATTERN`
  ISO8601-like pattern for date-time.
  `static final String`
  `ISO8601_TIME_PATTERN`
  ISO8601-like pattern for time.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `format(long date, String pattern)`
  Format a date/time into a specific pattern.
  `static String`
  `format(Date date, String pattern)`
  Format a date/time into a specific pattern.
  `static String`
  `formatElapsedTime(long millis)`
  Format an elapsed time into a pluralization correct string.
  `static String`
  `getDateForHeader()`
  Returns the current Date in a format suitable for a SMTP date header.
  `static int`
  `getPhaseOfMoon(Calendar cal)`
  Calculate the phase of the moon for a given date.
  `static Date`
  `parseDateFromHeader(String datestr)`
  Parses the string in a format suitable for a SMTP date header.
  `static Date`
  `parseIso8601Date(String datestr)`
  Parse a string as a date using the ISO8601_DATE format which is `yyyy-MM-dd`
  `static Date`
  `parseIso8601DateTime(String datestr)`
  Parse a string as a datetime using the ISO8601_DATETIME format which is `yyyy-MM-dd'T'HH:mm:ss`
  `static Date`
  `parseIso8601DateTimeOrDate(String datestr)`
  Parse a string as a date using the either the ISO8601_DATETIME or ISO8601_DATE formats.
  `static Date`
  `parseLenientDateTime(String dateStr)`
  Parse a lenient ISO 8601, ms since epoch, or `<touch>`-style date.

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

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

- ## Field Details

  - ### ISO8601_DATETIME_PATTERN

    public static final String ISO8601_DATETIME_PATTERN
    ISO8601-like pattern for date-time. It does not support timezone. `yyyy-MM-ddTHH:mm:ss`
    See Also:
      - Constant Field Values

  - ### ISO8601_DATE_PATTERN

    public static final String ISO8601_DATE_PATTERN
    ISO8601-like pattern for date. `yyyy-MM-dd`
    See Also:
      - Constant Field Values

  - ### ISO8601_TIME_PATTERN

    public static final String ISO8601_TIME_PATTERN
    ISO8601-like pattern for time. `HH:mm:ss`
    See Also:
      - Constant Field Values

  - ### DATE_HEADER_FORMAT

    @Deprecated public static final DateFormat DATE_HEADER_FORMAT
    Deprecated.
    DateFormat is not thread safe, and we cannot guarantee that some other code is using the format in parallel. Deprecated since ant 1.8
    Format used for SMTP (and probably other) Date headers.

  - ### EN_US_DATE_FORMAT_MIN

    public static final ThreadLocal<DateFormat> EN_US_DATE_FORMAT_MIN
    Provides a thread-local US-style date format. Exactly as used by `<touch>`, to minute precision: `SimpleDateFormat("MM/dd/yyyy hh:mm a", Locale.US)`
    Since:
      Ant 1.10.2

  - ### EN_US_DATE_FORMAT_SEC

    public static final ThreadLocal<DateFormat> EN_US_DATE_FORMAT_SEC
    Provides a thread-local US-style date format. Exactly as used by `<touch>`, to second precision: `SimpleDateFormat("MM/dd/yyyy hh:mm:ss a", Locale.US)`
    Since:
      Ant 1.10.2

- ## Method Details

  - ### format

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

  - ### format

    public static String format(Date date, String pattern)
    Format a date/time into a specific pattern.
    Parameters:
      `date` - the date to format expressed in milliseconds.
      `pattern` - the pattern to use to format the date.
    Returns:
      the formatted date.

  - ### formatElapsedTime

    public static String formatElapsedTime(long millis)
    Format an elapsed time into a pluralization correct string. It is limited only to report elapsed time in minutes and seconds and has the following behavior.
    - minutes are not displayed when 0. (ie: "45 seconds")
    - seconds are always displayed in plural form (ie "0 seconds" or "10 seconds") except for 1 (ie "1 second")
    Parameters:
      `millis` - the elapsed time to report in milliseconds.
    Returns:
      the formatted text in minutes/seconds.

  - ### getPhaseOfMoon

    public static int getPhaseOfMoon(Calendar cal)
    Calculate the phase of the moon for a given date.

    Code heavily influenced by hacklib.c in Nethack

    The Algorithm:

         moon period = 29.53058 days ~= 30, year = 365.2422 days

         days moon phase advances on first day of year compared to preceding year
          = 365.2422 - 12 * 29.53058 ~= 11

         years in Metonic cycle (time until same phases fall on the same days of
          the month) = 18.6 ~= 19

         moon phase on first day of year (epact) ~= (11*(year%19) + 18) % 30
          (18 as initial condition for 1900)

         current phase in days = first day phase + days elapsed in year

         6 moons ~= 177 days
         177 ~= 8 reported phases * 22
         + 11 / 22 for rounding

    Parameters:
      `cal` - the calendar.
    Returns:
      The phase of the moon as a number between 0 and 7 with 0 meaning new moon and 4 meaning full moon.
    Since:
      1.2, Ant 1.5

  - ### getDateForHeader

    public static String getDateForHeader()
    Returns the current Date in a format suitable for a SMTP date header.
    Returns:
      the current date.
    Since:
      Ant 1.5.2

  - ### parseDateFromHeader

    public static Date parseDateFromHeader(String datestr) throws ParseException
    Parses the string in a format suitable for a SMTP date header.
    Parameters:
      `datestr` - string to be parsed
    Returns:
      a java.util.Date object as parsed by the format.
    Throws:
      `ParseException` - if the supplied string cannot be parsed by this pattern.
    Since:
      Ant 1.8.0

  - ### parseIso8601DateTime

    public static Date parseIso8601DateTime(String datestr) throws ParseException
    Parse a string as a datetime using the ISO8601_DATETIME format which is `yyyy-MM-dd'T'HH:mm:ss`
    Parameters:
      `datestr` - string to be parsed
    Returns:
      a java.util.Date object as parsed by the format.
    Throws:
      `ParseException` - if the supplied string cannot be parsed by this pattern.
    Since:
      Ant 1.6

  - ### parseIso8601Date

    public static Date parseIso8601Date(String datestr) throws ParseException
    Parse a string as a date using the ISO8601_DATE format which is `yyyy-MM-dd`
    Parameters:
      `datestr` - string to be parsed
    Returns:
      a java.util.Date object as parsed by the format.
    Throws:
      `ParseException` - if the supplied string cannot be parsed by this pattern.
    Since:
      Ant 1.6

  - ### parseIso8601DateTimeOrDate

    public static Date parseIso8601DateTimeOrDate(String datestr) throws ParseException
    Parse a string as a date using the either the ISO8601_DATETIME or ISO8601_DATE formats.
    Parameters:
      `datestr` - string to be parsed
    Returns:
      a java.util.Date object as parsed by the formats.
    Throws:
      `ParseException` - if the supplied string cannot be parsed by either of these patterns.
    Since:
      Ant 1.6

  - ### parseLenientDateTime

    public static Date parseLenientDateTime(String dateStr) throws ParseException
    Parse a lenient ISO 8601, ms since epoch, or `<touch>`-style date. That is:
    - Milliseconds since 1970-01-01 00:00
    - `YYYY-MM-DD{T| }HH:MM[:SS[.SSS]][ ][±ZZ[[:]ZZ]]`
    - `MM/DD/YYYY HH:MM[:SS] {AM|PM}`
    where {a|b} indicates that you must choose one of a or b, and [c] indicates that you may use or omit c. ±ZZZZ is the timezone offset, and may be literally "Z" to mean GMT.
    Parameters:
      `dateStr` - String
    Returns:
      Date
    Throws:
      `ParseException` - if date string does not match ISO 8601
    Since:
      Ant 1.10.2