Package: java.util

## [Java] Class Date

- java.util.Date

-     public class Date
      extends Object

  GDK enhancements for Date.

  displayName:
    Date
  receiverFqcn:
    java.util.Date

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `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.
    `` | `public Date` | `copyWith(Map<Object, Integer> 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.
    `` | `public void` | `downto(Date to, Closure closure)` Iterates from this date down to the given date, inclusive, decrementing by one day each time.
    `` | `public String` | `format(String format)`
    `` | `public String` | `format(String format, TimeZone tz)`
    `` | `public int` | `getAt(int field)` Support the subscript operator for a Date.
    `` | `public List<Integer>` | `getAt(Collection fields)` Support the subscript operator for a Date with a collection of indices.
    `` | `public String` | `getDateString()`
    `` | `public String` | `getDateTimeString()`
    `` | `public String` | `getTimeString()`
    `` | `public ZoneId` | `getZoneId()` Returns the Time Zone of the Date as a ZoneId.
    `` | `public ZoneOffset` | `getZoneOffset()` Returns the Time Zone offset of the Date as a ZoneOffset, which will typically be system's default offset.
    `` | `public Date` | `minus(int days)` Subtract a number of days from this date and returns the new date.
    `` | `public int` | `minus(Date then)` Subtract another Date from this one and return the number of days of the difference.
    `` | `public Date` | `next()` Increment a Date by one day.
    `` | `public Date` | `plus(int days)` Add a number of days to this date and returns the new date.
    `` | `public Date` | `previous()` Decrement a Date by one day.
    `` | `public void` | `putAt(int field, int value)` Support the subscript operator for mutating a Date.
    `` | `public void` | `set(Map<Object, Integer> updates)` Support mutating a Date with a Map.
    `` | `public Calendar` | `toCalendar()` Convert a Date to a Calendar.
    `` | `public DayOfWeek` | `toDayOfWeek()` Converts the Date to a corresponding DayOfWeek.
    `` | `public LocalDate` | `toLocalDate()` Converts the Date to a corresponding LocalDate.
    `` | `public LocalDateTime` | `toLocalDateTime()` Converts the Date to a corresponding LocalDateTime.
    `` | `public LocalTime` | `toLocalTime()` Converts the Date to a corresponding LocalTime.
    `` | `public Month` | `toMonth()` Converts the Date to a corresponding Month.
    `` | `public MonthDay` | `toMonthDay()` Converts the Date to a corresponding MonthDay.
    `` | `public OffsetDateTime` | `toOffsetDateTime()` Converts the Date to a corresponding OffsetDateTime.
    `` | `public OffsetTime` | `toOffsetTime()` Converts the Date to a corresponding OffsetTime.
    `` | `public Timestamp` | `toTimestamp()` Return a java.sql.Timestamp given a java.util.Date.
    `` | `public Year` | `toYear()` Converts the Date to a corresponding Year.
    `` | `public YearMonth` | `toYearMonth()` Converts the Date to a corresponding YearMonth.
    `` | `public ZonedDateTime` | `toZonedDateTime()` Converts the Date to a corresponding ZonedDateTime.
    `` | `public Date` | `updated(Map<Object, Integer> updates)` Legacy alias for copyWith.
    `` | `public void` | `upto(Date to, Closure closure)` Iterates from this date up to the given date, inclusive, incrementing by one day each time.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `addShutdownHook, any, any, asBoolean, asType, clamp, clamp, collect, collect, collect, dump, each, eachMatch, eachMatch, eachWithIndex, every, every, find, find, findAll, findAll, findIndexOf, findIndexOf, findIndexValues, findIndexValues, findLastIndexOf, findLastIndexOf, findResult, findResult, findResult, findResult, getAt, getMetaClass, getMetaPropertyValues, getProperties, grep, grep, hasProperty, identity, inject, inject, inject, inject, inspect, invokeMethod, is, isCase, isNotCase, iterator, metaClass, print, print, printf, printf, println, println, println, putAt, respondsTo, respondsTo, setMetaClass, sleep, sleep, split, sprintf, sprintf, stream, takeIf, tap, toString, use, use, use, with, with, withCloseable, withCloseable, withMethodClosure, withStream, withStream, withTraits`

- - ### Method 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<Object, Integer> 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
      See Also:
        Calendar.set
        set(java.util.Date, java.util.Map)
        copyWith(java.util.Calendar, java.util.Map)
      Since:
        2.2.0

    - #### 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.
      See Also:
        SimpleDateFormat
      Since:
        1.5.7

    - #### 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.
      See Also:
        SimpleDateFormat
      Since:
        1.8.3

    - #### 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
      See Also:
        Calendar
      Since:
        1.5.5

    - #### public List<Integer> getAt(Collection fields)

      Support the subscript operator for a Date with a collection of indices.

      Parameters:
        `fields` - a collection of Calendar fields, e.g. [YEAR, MONTH]
      Returns:
        the value for the given field, e.g. [2022, FEBRUARY]
      See Also:
        Calendar
      Since:
        4.0.5

    - #### 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
      See Also:
        DateFormat.getDateInstance
        DateFormat.SHORT
      Since:
        1.5.7

    - #### public String getDateTimeString()

      Return a string representation of the date and 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
      See Also:
        DateFormat.getDateTimeInstance
      Since:
        1.5.7

    - #### 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
      See Also:
        DateFormat.getTimeInstance
        DateFormat.MEDIUM
      Since:
        1.5.7

    - #### 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
      See Also:
        putAt(java.util.Calendar, int, int)
        Calendar.set
      Since:
        1.7.3

    - #### public void set(Map<Object, Integer> 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
      See Also:
        Calendar.set
        set(java.util.Calendar, java.util.Map)
      Since:
        1.7.3

    - #### 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<Object, Integer> updates)

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

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

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