DateUtils (Apache Ant API)
Date: 2015-06-29

org.apache.tools.ant.util

## Class DateUtils

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

-     public final class DateUtils
      extends java.lang.Object

  Helper methods to deal with date/time formatting with a specific defined format (ISO8601) or a plurialization correct elapsed time in minutes and seconds.
  Since:
    Ant 1.5

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.text.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
    `static java.lang.String` | `ISO8601_DATE_PATTERN` ISO8601-like pattern for date.
    `static java.lang.String` | `ISO8601_DATETIME_PATTERN` ISO8601-like pattern for date-time.
    `static java.lang.String` | `ISO8601_TIME_PATTERN` ISO8601-like pattern for time.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `format(java.util.Date date, java.lang.String pattern)` Format a date/time into a specific pattern.
    `static java.lang.String` | `format(long date, java.lang.String pattern)` Format a date/time into a specific pattern.
    `static java.lang.String` | `formatElapsedTime(long millis)` Format an elapsed time into a plurialization correct string.
    `static java.lang.String` | `getDateForHeader()` Returns the current Date in a format suitable for a SMTP date header.
    `static int` | `getPhaseOfMoon(java.util.Calendar cal)` Calculate the phase of the moon for a given date.
    `static java.util.Date` | `parseDateFromHeader(java.lang.String datestr)` Parses the string in a format suitable for a SMTP date header.
    `static java.util.Date` | `parseIso8601Date(java.lang.String datestr)` Parse a string as a date using the ISO8601_DATE format which is `yyyy-MM-dd`
    `static java.util.Date` | `parseIso8601DateTime(java.lang.String datestr)` Parse a string as a datetime using the ISO8601_DATETIME format which is `yyyy-MM-dd'T'HH:mm:ss`
    `static java.util.Date` | `parseIso8601DateTimeOrDate(java.lang.String datestr)` Parse a string as a date using the either the ISO8601_DATETIME or ISO8601_DATE formats.

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

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

- - ### Field Detail

    - #### ISO8601_DATETIME_PATTERN

          public static final java.lang.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 java.lang.String ISO8601_DATE_PATTERN

      ISO8601-like pattern for date. `yyyy-MM-dd`
      See Also:
        Constant Field Values

    - #### ISO8601_TIME_PATTERN

          public static final java.lang.String ISO8601_TIME_PATTERN

      ISO8601-like pattern for time. `HH:mm:ss`
      See Also:
        Constant Field Values

    - #### DATE_HEADER_FORMAT

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

  - ### Method Detail

    - #### format

          public static java.lang.String format(long date,
                                java.lang.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 java.lang.String format(java.util.Date date,
                                java.lang.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 java.lang.String formatElapsedTime(long millis)

      Format an elapsed time into a plurialization 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(java.util.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 java.lang.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 java.util.Date parseDateFromHeader(java.lang.String datestr)
                                                    throws java.text.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:
        `java.text.ParseException` - if the supplied string cannot be parsed by this pattern.
      Since:
        Ant 1.8.0

    - #### parseIso8601DateTime

          public static java.util.Date parseIso8601DateTime(java.lang.String datestr)
                                                     throws java.text.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:
        `java.text.ParseException` - if the supplied string cannot be parsed by this pattern.
      Since:
        Ant 1.6

    - #### parseIso8601Date

          public static java.util.Date parseIso8601Date(java.lang.String datestr)
                                                 throws java.text.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:
        `java.text.ParseException` - if the supplied string cannot be parsed by this pattern.
      Since:
        Ant 1.6

    - #### parseIso8601DateTimeOrDate

          public static java.util.Date parseIso8601DateTimeOrDate(java.lang.String datestr)
                                                           throws java.text.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:
        `java.text.ParseException` - if the supplied string cannot be parsed by either of these patterns.
      Since:
        Ant 1.6