Package: java.util

## [Java] Class Calendar

- java.util.Calendar

-     public class Calendar
      extends Object

  GDK enhancements for Calendar.

  displayName:
    Calendar
  receiverFqcn:
    java.util.Calendar

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Calendar` | `clearTime()` Clears the time portion of this Calendar instance; useful utility where it makes sense to compare month/day/year only portions of a Calendar.
    `` | `public Calendar` | `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(Calendar to, Closure closure)` Iterates from the date represented by this calendar up to the date represented by the given calendar, inclusive, incrementing by one day each time.
    `` | `public String` | `format(String pattern)`
    `` | `public int` | `getAt(int field)` Support the subscript operator for a Calendar.
    `` | `public List<Integer>` | `getAt(Collection fields)` Support the subscript operator for a Calendar with a collection of indices.
    `` | `public ZoneId` | `getZoneId()` Returns the Time Zone of the Calendar as a java.time.ZoneId.
    `` | `public ZoneOffset` | `getZoneOffset()` Returns the Time Zone offset of the Calendar as a ZoneOffset.
    `` | `public int` | `minus(Calendar then)` Subtract another date from this one and return the number of days of the difference.
    `` | `public Calendar` | `next()` Increment a Calendar by one day.
    `` | `public Calendar` | `previous()` Decrement a Calendar by one day.
    `` | `public void` | `putAt(int field, int value)` Support the subscript operator for mutating a Calendar.
    `` | `public void` | `set(Map<Object, Integer> updates)` Support mutating a Calendar with a Map.
    `` | `public DayOfWeek` | `toDayOfWeek()` Converts the Calendar to a corresponding DayOfWeek.
    `` | `public Instant` | `toInstant()` Convenience method for converting a Calendar to a corresponding Instant.
    `` | `public LocalDateTime` | `toLocalDateTime()` Converts the Calendar to a corresponding LocalDateTime.
    `` | `public LocalTime` | `toLocalTime()` Converts the Calendar to a corresponding LocalTime.
    `` | `public Month` | `toMonth()` Converts the Calendar to a corresponding Month.
    `` | `public MonthDay` | `toMonthDay()` Converts the Calendar to a corresponding MonthDay.
    `` | `public OffsetDateTime` | `toOffsetDateTime()` Converts the Calendar to a corresponding OffsetDateTime.
    `` | `public OffsetTime` | `toOffsetTime()` Converts the Calendar to a corresponding OffsetTime.
    `` | `public Year` | `toYear()` Converts the Calendar to a corresponding Year.
    `` | `public YearMonth` | `toYearMonth()` Converts the Calendar to a corresponding YearMonth.
    `` | `public ZonedDateTime` | `toZonedDateTime()`
    `` | `public Calendar` | `updated(Map<Object, Integer> updates)` Legacy alias for copyWith.
    `` | `public void` | `upto(Calendar to, Closure closure)` Iterates from the date represented by this calendar up to the date represented by the given calendar, 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 Calendar clearTime()

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

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

    - #### public Calendar 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 now = Calendar.instance
           def nextYear = now[YEAR] + 1
           def oneYearFromNow = now.copyWith(year: nextYear)
           println now.time
           println oneYearFromNow.time

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

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

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

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

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

      Shortcut for SimpleDateFormat to output a String representation of this calendar instance. This method respects the Calendar's assigned TimeZone, whereas calling `cal.time.format('HH:mm:ss')` would use the system timezone.

      Note that Calendar equivalents of `date.getDateString()` and variants do not exist because those methods are Locale-dependent. Although a Calendar may be assigned a Locale, that information is lost and therefore cannot be used to control the default date/time formats provided by these methods. Instead, the system Locale would always be used. The alternative is to simply call DateFormat.getDateInstance and pass the same Locale that was used for the Calendar.

      Parameters:
        `pattern` - format pattern
      Returns:
        String representation of this calendar with the given format.
      See Also:
        DateFormat.setTimeZone
        SimpleDateFormat.format
        format(java.util.Date, String)
      Since:
        1.6.0

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

      Support the subscript operator for a Calendar.

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

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

      Support the subscript operator for a Calendar 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 ZoneId getZoneId()

      Returns the Time Zone of the Calendar as a java.time.ZoneId.

      Returns:
        a ZoneId
      Since:
        2.5.0

    - #### public ZoneOffset getZoneOffset()

      Returns the Time Zone offset of the Calendar as a ZoneOffset.

      Returns:
        a ZoneOffset
      Since:
        2.5.0

    - #### public int minus(Calendar 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 Calendar
      Returns:
        number of days
      Since:
        1.6.0

    - #### public Calendar next()

      Increment a Calendar by one day.

      Returns:
        a new Calendar set to the next day
      Since:
        1.8.7

    - #### public Calendar previous()

      Decrement a Calendar by one day.

      Returns:
        a new Calendar set to the previous day
      Since:
        1.8.7

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

      Support the subscript operator for mutating a Calendar. Example usage:

           import static java.util.Calendar.*
           def cal = Calendar.instance
           cal[DAY_OF_WEEK] = MONDAY
           cal[MONTH] = MARCH
           println cal.time // A Monday in March

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

    - #### public void set(Map<Object, Integer> updates)

      Support mutating a Calendar 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.*
           def cal = Calendar.instance
           def m = [:]
           m[YEAR] = 2010
           m[MONTH] = DECEMBER
           m[DATE] = 25
           cal.set(m)
           println cal.time // Christmas 2010

           cal.set(year:2011, month:DECEMBER, date:25)
           println cal.time // Christmas 2010

      Parameters:
        `updates` - A Map of Calendar keys and values
      See Also:
        Calendar.set
        Calendar.set
      Since:
        1.7.3

    - #### public DayOfWeek toDayOfWeek()

      Converts the Calendar to a corresponding DayOfWeek. If the Calendar has a different time zone than the system default, the DayOfWeek will be adjusted into the default time zone.

      Returns:
        a DayOfWeek
      Since:
        2.5.0

    - #### public Instant toInstant()

      Convenience method for converting a Calendar to a corresponding Instant.

      Returns:
        an Instant
      Since:
        2.5.0

    - #### public LocalDateTime toLocalDateTime()

      Converts the Calendar to a corresponding LocalDateTime. If the Calendar has a different time zone than the system default, the LocalDateTime will be adjusted into the default time zone.

      Returns:
        a LocalDateTime
      Since:
        2.5.0

    - #### public LocalTime toLocalTime()

      Converts the Calendar to a corresponding LocalTime. If the Calendar has a different time zone than the system default, the LocalTime will be adjusted into the default time zone.

      Returns:
        a LocalTime
      Since:
        2.5.0

    - #### public Month toMonth()

      Converts the Calendar to a corresponding Month. If the Calendar has a different time zone than the system default, the Month will be adjusted into the default time zone.

      Returns:
        a Month
      Since:
        2.5.0

    - #### public MonthDay toMonthDay()

      Converts the Calendar to a corresponding MonthDay. If the Calendar has a different time zone than the system default, the MonthDay will be adjusted into the default time zone.

      Returns:
        a MonthDay
      Since:
        2.5.0

    - #### public OffsetDateTime toOffsetDateTime()

      Converts the Calendar to a corresponding OffsetDateTime.

      Returns:
        an OffsetDateTime
      Since:
        2.5.0

    - #### public OffsetTime toOffsetTime()

      Converts the Calendar to a corresponding OffsetTime.

      Returns:
        an OffsetTime
      Since:
        2.5.0

    - #### public Year toYear()

      Converts the Calendar to a corresponding Year. If the Calendar has a different time zone than the system default, the Year will be adjusted into the default time zone.

      Returns:
        a Year
      Since:
        2.5.0

    - #### public YearMonth toYearMonth()

      Converts the Calendar to a corresponding YearMonth. If the Calendar has a different time zone than the system default, the YearMonth will be adjusted into the default time zone.

      Returns:
        a YearMonth
      Since:
        2.5.0

    - #### public ZonedDateTime toZonedDateTime()

      Converts the Calendar to a corresponding ZonedDateTime.

      Note that GregorianCalendar has a GregorianCalendar.toZonedDateTime method, which is commonly the specific type of Calendar in use.

      Returns:
        a ZonedDateTime
      Since:
        2.5.0

    - #### public Calendar updated(Map<Object, Integer> updates)

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

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

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

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

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