Package: java.util

## Class Date

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `Date` | `clearTime()` Clears the time portion of this Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.
    `Date` | `copyWith(Map updates)` Support creating a new Date having similar properties to an existing Date (which remains unaltered) but with some fields updated according to a Map of changes.
    `void` | `downto(Date to, Closure closure)` Iterates from this date down to the given date, inclusive, decrementing by one day each time.
    `String` | `format(String format)` Create a String representation of this date according to the given format pattern.
    `String` | `format(String format, TimeZone tz)` Create a String representation of this date according to the given format pattern and timezone.
    `int` | `getAt(int field)` Support the subscript operator for a Date.
    `String` | `getDateString()` Return a string representation of the 'day' portion of this date according to the locale-specific DateFormat#SHORT default format.
    `String` | `getDateTimeString()` Return a string representation of the date and time time portion of this Date instance, according to the locale-specific format used by DateFormat.
    `String` | `getTimeString()` Return a string representation of the time portion of this date according to the locale-specific DateFormat#MEDIUM default format.
    `Date` | `minus(int days)` Subtract a number of days from this date and returns the new date.
    `int` | `minus(Date then)` Subtract another Date from this one and return the number of days of the difference.
    `Date` | `next()` Increment a Date by one day.
    `static Date` | `parse(String format, String input)` Parse a String into a Date instance using the given pattern.
    `static Date` | `parse(String format, String input, TimeZone zone)` Parse a String into a Date instance using the given pattern and TimeZone.
    `static Date` | `parseToStringDate(String dateToString)` Parse a String matching the pattern EEE MMM dd HH:mm:ss zzz yyyy containing US-locale-constants only (e.g.
    `Date` | `plus(int days)` Add a number of days to this date and returns the new date.
    `Date` | `previous()` Decrement a Date by one day.
    `void` | `putAt(int field, int value)` Support the subscript operator for mutating a Date.
    `void` | `set(Map updates)` Support mutating a Date with a Map.
    `Calendar` | `toCalendar()` Convert a Date to a Calendar.
    `Timestamp` | `toTimestamp()` Return a java.sql.Timestamp given a java.util.Date.
    `Date` | `updated(Map updates)` Legacy alias for copyWith.
    `void` | `upto(Date to, Closure closure)` Iterates from this date up to the given date, inclusive, incrementing by one day each time.

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

    `addShutdownHook`, `any`, `any`, `asBoolean`, `asType`, `collect`, `collect`, `collect`, `contains`, `count`, `dump`, `each`, `eachWithIndex`, `equals`, `every`, `every`, `find`, `find`, `findAll`, `findAll`, `findIndexOf`, `findIndexOf`, `findIndexValues`, `findIndexValues`, `findLastIndexOf`, `findLastIndexOf`, `findResult`, `findResult`, `flatten`, `getAt`, `getMetaClass`, `getMetaPropertyValues`, `getProperties`, `grep`, `grep`, `groupBy`, `groupBy`, `hasProperty`, `identity`, `inject`, `inject`, `inspect`, `invokeMethod`, `is`, `isCase`, `iterator`, `join`, `metaClass`, `print`, `print`, `printf`, `printf`, `println`, `println`, `println`, `putAt`, `respondsTo`, `respondsTo`, `setMetaClass`, `size`, `split`, `sprintf`, `sprintf`, `sum`, `sum`, `sum`, `sum`, `toArrayString`, `toSpreadMap`, `toString`, `use`, `use`, `use`, `with`, `withTraits`

  - #### Methods inherited from interface java.lang.Comparable

    `numberAwareCompareTo`

- - ### Methods Detail

    - #### public Date clearTime()

      Clears the time portion of this Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.

      Returns:
        the Date but with the time portion cleared
      Since:
        1.6.7

    - #### public Date copyWith(Map updates)

      Support creating a new Date having similar properties to an existing Date (which remains unaltered) but with some fields updated according to a Map of changes.

      Example usage:

          import static java.util.Calendar.YEAR
          def today = new Date()
          def nextYear = today[YEAR] + 1
          def oneYearFromNow = today.copyWith(year: nextYear)
          println today
          println oneYearFromNow

      Parameters:
        `updates` - A Map of Calendar keys and values
      Returns:
        The newly created Date
      Since:
        2.2.0
      See Also:
        Calendar#set(int, int)
        Date#set(java.util.Map)
        Calendar#copyWith(java.util.Map)

    - #### public void downto(Date to, Closure closure)

      Iterates from this date down to the given date, inclusive, decrementing by one day each time.

      Parameters:
        `to` - another Date to go down to
        `closure` - the closure to call
      Since:
        2.2

    - #### public String format(String format)

      Create a String representation of this date according to the given format pattern.

      For example, if the system timezone is GMT, `new Date(0).format('MM/dd/yy')` would return the string `"01/01/70"`. See documentation for SimpleDateFormat for format pattern use.

      Note that a new DateFormat instance is created for every invocation of this method (for thread safety).

      Parameters:
        `format` - the format pattern to use according to SimpleDateFormat
      Returns:
        a string representation of this date.
      Since:
        1.5.7
      See Also:
        SimpleDateFormat

    - #### public String format(String format, TimeZone tz)

      Create a String representation of this date according to the given format pattern and timezone.

      For example: `def d = new Date(0) def tz = TimeZone.getTimeZone('GMT') println d.format('dd/MMM/yyyy', tz)` would return the string `"01/Jan/1970"`. See documentation for SimpleDateFormat for format pattern use.

      Note that a new DateFormat instance is created for every invocation of this method (for thread safety).

      Parameters:
        `format` - the format pattern to use according to SimpleDateFormat
        `tz` - the TimeZone to use
      Returns:
        a string representation of this date.
      Since:
        1.8.3
      See Also:
        SimpleDateFormat

    - #### public int getAt(int field)

      Support the subscript operator for a Date.

      Parameters:
        `field` - a Calendar field, e.g. MONTH
      Returns:
        the value for the given field, e.g. FEBRUARY
      Since:
        1.5.5
      See Also:
        Calendar

    - #### public String getDateString()

      Return a string representation of the 'day' portion of this date according to the locale-specific DateFormat#SHORT default format. For an "en_UK" system locale, this would be `dd/MM/yy`.

      Note that a new DateFormat instance is created for every invocation of this method (for thread safety).

      Returns:
        a string representation of this date
      Since:
        1.5.7
      See Also:
        DateFormat#getDateInstance(int)
        DateFormat#SHORT

    - #### public String getDateTimeString()

      Return a string representation of the date and time time portion of this Date instance, according to the locale-specific format used by DateFormat. This method uses the DateFormat#SHORT preset for the day portion and DateFormat#MEDIUM for the time portion of the output string.

      Note that a new DateFormat instance is created for every invocation of this method (for thread safety).

      Returns:
        a string representation of this date and time
      Since:
        1.5.7
      See Also:
        DateFormat#getDateTimeInstance(int, int)

    - #### public String getTimeString()

      Return a string representation of the time portion of this date according to the locale-specific DateFormat#MEDIUM default format. For an "en_UK" system locale, this would be `HH:MM:ss`.

      Note that a new DateFormat instance is created for every invocation of this method (for thread safety).

      Returns:
        a string representing the time portion of this date
      Since:
        1.5.7
      See Also:
        DateFormat#getTimeInstance(int)
        DateFormat#MEDIUM

    - #### public Date minus(int days)

      Subtract a number of days from this date and returns the new date.

      Parameters:
        `days` - the number of days to subtract
      Returns:
        the new date
      Since:
        1.0

    - #### public int minus(Date then)

      Subtract another Date from this one and return the number of days of the difference.

      Date self = Date then + (Date self - Date then)

      IOW, if self is before then the result is a negative value.

      Parameters:
        `then` - another Date
      Returns:
        number of days
      Since:
        1.6.0

    - #### public Date next()

      Increment a Date by one day.

      Returns:
        the next days date
      Since:
        1.0

    - #### public static Date parse(String format, String input)

      Parse a String into a Date instance using the given pattern. This convenience method acts as a wrapper for SimpleDateFormat.

      Note that a new SimpleDateFormat instance is created for every invocation of this method (for thread safety).

      Parameters:
        `format` - pattern used to parse the input string.
        `input` - String to be parsed to create the date instance
      Returns:
        a new Date instance representing the parsed input string
      Since:
        1.5.7
      See Also:
        SimpleDateFormat#parse(java.lang.String)

    - #### public static Date parse(String format, String input, TimeZone zone)

      Parse a String into a Date instance using the given pattern and TimeZone. This convenience method acts as a wrapper for SimpleDateFormat.

      Note that a new SimpleDateFormat instance is created for every invocation of this method (for thread safety).

      Parameters:
        `format` - pattern used to parse the input string.
        `input` - String to be parsed to create the date instance
        `zone` - TimeZone to use when parsing
      Returns:
        a new Date instance representing the parsed input string
      Since:
        2.4.1
      See Also:
        SimpleDateFormat#parse(java.lang.String)

    - #### public static Date parseToStringDate(String dateToString)

      Parse a String matching the pattern EEE MMM dd HH:mm:ss zzz yyyy containing US-locale-constants only (e.g. Sat for Saturdays). Such a string is generated by the toString method of Date

      Note that a new SimpleDateFormat instance is created for every invocation of this method (for thread safety).

      Parameters:
        `dateToString` - String to be parsed to create the date instance. Must match the pattern EEE MMM dd HH:mm:ss zzz yyyy with US-locale symbols
      Returns:
        a new Date instance representing the parsed input string

    - #### public Date plus(int days)

      Add a number of days to this date and returns the new date.

      Parameters:
        `days` - the number of days to increase
      Returns:
        the new date
      Since:
        1.0

    - #### public Date previous()

      Decrement a Date by one day.

      Returns:
        the previous days date
      Since:
        1.0

    - #### public void putAt(int field, int value)

      Support the subscript operator for mutating a Date.

      Parameters:
        `field` - A Calendar field, e.g. MONTH
        `value` - The value for the given field, e.g. FEBRUARY
      Since:
        1.7.3
      See Also:
        Calendar#putAt(int, int)
        Calendar#set(int, int)

    - #### public void set(Map updates)

      Support mutating a Date with a Map.

      The map values are the normal values provided as the second parameter to `java.util.Calendar#set(int, int)`. The keys can either be the normal fields values provided as the first parameter to that method or one of the following Strings:

      Calendar index values
      year | Calendar.YEAR
      month | Calendar.MONTH
      date | Calendar.DATE
      dayOfMonth | Calendar.DATE
      hourOfDay | Calendar.HOUR_OF_DAY
      minute | Calendar.MINUTE
      second | Calendar.SECOND

      Example usage:

          import static java.util.Calendar.YEAR
          def date = new Date()
          def nextYear = date[YEAR] + 1
          date.set(year: nextYear)
          println date

      Parameters:
        `updates` - A Map of Calendar keys and values
      Since:
        1.7.3
      See Also:
        Calendar#set(int, int)
        Calendar#set(java.util.Map)

    - #### public Calendar toCalendar()

      Convert a Date to a Calendar.

      Returns:
        a Calendar corresponding to the given Date
      Since:
        1.7.6

    - #### public Timestamp toTimestamp()

      Return a java.sql.Timestamp given a java.util.Date.

      Returns:
        the date wrapped as a Timestamp
      Since:
        1.6.6

    - #### public Date updated(Map updates)

      Legacy alias for copyWith. Will be deprecated and removed in future versions of Groovy.

      Parameters:
      Since:
        1.7.3
      See Also:
        Date#copyWith(java.util.Map)

    - #### public void upto(Date to, Closure closure)

      Iterates from this date up to the given date, inclusive, incrementing by one day each time.

      Parameters:
        `to` - another Date to go up to
        `closure` - the closure to call
      Since:
        2.2