Date (Groovy JDK enhancements)

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.
    `ZoneId` | `getZoneId()` Returns the Time Zone of the Date as a ZoneId.
    `ZoneOffset` | `getZoneOffset()` Returns the Time Zone offset of the Date as a ZoneOffset, which will typically be system's default offset.
    `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.
    `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.
    `DayOfWeek` | `toDayOfWeek()` Converts the Date to a corresponding DayOfWeek.
    `LocalDate` | `toLocalDate()` Converts the Date to a corresponding LocalDate.
    `LocalDateTime` | `toLocalDateTime()` Converts the Date to a corresponding LocalDateTime.
    `LocalTime` | `toLocalTime()` Converts the Date to a corresponding LocalTime.
    `Month` | `toMonth()` Converts the Date to a corresponding Month.
    `MonthDay` | `toMonthDay()` Converts the Date to a corresponding MonthDay.
    `OffsetDateTime` | `toOffsetDateTime()` Converts the Date to a corresponding OffsetDateTime.
    `OffsetTime` | `toOffsetTime()` Converts the Date to a corresponding OffsetTime.
    `Timestamp` | `toTimestamp()` Return a java.sql.Timestamp given a java.util.Date.
    `Year` | `toYear()` Converts the Date to a corresponding Year.
    `YearMonth` | `toYearMonth()` Converts the Date to a corresponding YearMonth.
    `ZonedDateTime` | `toZonedDateTime()` Converts the Date to a corresponding ZonedDateTime.
    `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`, `average`, `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`, `stream`, `sum`, `sum`, `tap`, `toArrayString`, `toSpreadMap`, `toString`, `use`, `use`, `use`, `with`, `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 ZoneId getZoneId()

      Returns the Time Zone of the Date as a ZoneId. This will typically be the system's default ZoneId.

      Returns:
        a ZoneId
      Since:
        2.5.0

    - #### public ZoneOffset getZoneOffset()

      Returns the Time Zone offset of the Date as a ZoneOffset, which will typically be system's default offset.

      Returns:
        a ZoneOffset
      Since:
        2.5.0

    - #### 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 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 DayOfWeek toDayOfWeek()

      Converts the Date to a corresponding DayOfWeek.

      Returns:
        a DayOfWeek
      Since:
        2.5.0

    - #### public LocalDate toLocalDate()

      Converts the Date to a corresponding LocalDate.

      Returns:
        a LocalDate
      Since:
        2.5.0

    - #### public LocalDateTime toLocalDateTime()

      Converts the Date to a corresponding LocalDateTime.

      Returns:
        a LocalDateTime
      Since:
        2.5.0

    - #### public LocalTime toLocalTime()

      Converts the Date to a corresponding LocalTime.

      Returns:
        a LocalTime
      Since:
        2.5.0

    - #### public Month toMonth()

      Converts the Date to a corresponding Month.

      Returns:
        a Month
      Since:
        2.5.0

    - #### public MonthDay toMonthDay()

      Converts the Date to a corresponding MonthDay.

      Returns:
        a MonthDay
      Since:
        2.5.0

    - #### public OffsetDateTime toOffsetDateTime()

      Converts the Date to a corresponding OffsetDateTime.

      Returns:
        an OffsetDateTime
      Since:
        2.5.0

    - #### public OffsetTime toOffsetTime()

      Converts the Date to a corresponding OffsetTime.

      Returns:
        an OffsetTime
      Since:
        2.5.0

    - #### 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 Year toYear()

      Converts the Date to a corresponding Year.

      Returns:
        a Year
      Since:
        2.5.0

    - #### public YearMonth toYearMonth()

      Converts the Date to a corresponding YearMonth.

      Returns:
        a YearMonth
      Since:
        2.5.0

    - #### public ZonedDateTime toZonedDateTime()

      Converts the Date to a corresponding ZonedDateTime.

      Returns:
        a ZonedDateTime
      Since:
        2.5.0

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