Calendar (Groovy JDK enhancements)

Package: java.util

## Class Calendar

- - ### Methods Summary

    Methods
    Return type | Name and parameters
    --- | ---
    `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.
    `Calendar` | `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(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.
    `String` | `format(String pattern)` Shortcut for SimpleDateFormat to output a String representation of this calendar instance.
    `int` | `getAt(int field)` Support the subscript operator for a Calendar.
    `int` | `minus(Calendar then)` Subtract another date from this one and return the number of days of the difference.
    `Calendar` | `next()` Increment a Calendar by one day.
    `Calendar` | `previous()` Decrement a Calendar by one day.
    `void` | `putAt(int field, int value)` Support the subscript operator for mutating a Calendar.
    `void` | `set(Map updates)` Support mutating a Calendar with a Map.
    `Calendar` | `updated(Map updates)` Legacy alias for copyWith.
    `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.

  - #### 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`, `tap`, `toArrayString`, `toSpreadMap`, `toString`, `use`, `use`, `use`, `with`, `with`, `withTraits`

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

    `numberAwareCompareTo`

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

    - #### 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(int, java.util.Locale) 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.
      Since:
        1.6.0
      See Also:
        DateFormat#setTimeZone(java.util.TimeZone)
        SimpleDateFormat#format(java.util.Date)
        Date#format(String)

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

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

    - #### public void set(Map 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
      Since:
        1.7.3
      See Also:
        Calendar#set(int, int)
        Calendar#set(int, int, int, int, int, int)

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

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

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

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