org.codehaus.groovy.runtime

## Class DateGroovyMethods

- java.lang.Object
- - org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport
  - - org.codehaus.groovy.runtime.DateGroovyMethods

-     public class DateGroovyMethods
      extends DefaultGroovyMethodsSupport

  This class defines new groovy methods which appear on normal JDK Date and Calendar classes inside the Groovy environment.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport

      `DefaultGroovyMethodsSupport.RangeInfo`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DateGroovyMethods()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.util.Calendar` | `clearTime(java.util.Calendar self)` Clears the time portion of this Calendar instance; useful utility where it makes sense to compare month/day/year only portions of a Calendar.
    `static java.util.Date` | `clearTime(java.util.Date self)` Clears the time portion of this Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.
    `static java.sql.Date` | `clearTime(java.sql.Date self)` Clears the time portion of this java.sql.Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.
    `static java.lang.String` | `format(java.util.Calendar self, java.lang.String pattern)` Shortcut for `SimpleDateFormat` to output a String representation of this calendar instance.
    `static java.lang.String` | `format(java.util.Date self, java.lang.String format)` Create a String representation of this date according to the given format pattern.
    `static java.lang.String` | `format(java.util.Date self, java.lang.String format, java.util.TimeZone tz)` Create a String representation of this date according to the given format pattern and timezone.
    `static int` | `getAt(java.util.Calendar self, int field)` Support the subscript operator for a Calendar.
    `static int` | `getAt(java.util.Date self, int field)` Support the subscript operator for a Date.
    `static java.lang.String` | `getDateString(java.util.Date self)` Return a string representation of the 'day' portion of this date according to the locale-specific `DateFormat.SHORT` default format.
    `static java.lang.String` | `getDateTimeString(java.util.Date self)` Return a string representation of the date and time time portion of this Date instance, according to the locale-specific format used by `DateFormat`.
    `static java.lang.String` | `getTimeString(java.util.Date self)` Return a string representation of the time portion of this date according to the locale-specific `DateFormat.MEDIUM` default format.
    `static int` | `minus(java.util.Calendar self, java.util.Calendar then)` Subtract another date from this one and return the number of days of the difference.
    `static int` | `minus(java.util.Date self, java.util.Date then)` Subtract another Date from this one and return the number of days of the difference.
    `static java.util.Date` | `minus(java.util.Date self, int days)` Subtract a number of days from this date and returns the new date.
    `static java.sql.Date` | `minus(java.sql.Date self, int days)` Subtract a number of days from this date and returns the new date.
    `static java.sql.Timestamp` | `minus(java.sql.Timestamp self, int days)` Subtract a number of days from this Timestamp and returns the new Timestamp object.
    `static java.util.Calendar` | `next(java.util.Calendar self)` Increment a Calendar by one day.
    `static java.util.Date` | `next(java.util.Date self)` Increment a Date by one day.
    `static java.sql.Date` | `next(java.sql.Date self)` Increment a java.sql.Date by one day.
    `static java.util.Date` | `plus(java.util.Date self, int days)` Add a number of days to this date and returns the new date.
    `static java.sql.Date` | `plus(java.sql.Date self, int days)` Add a number of days to this date and returns the new date.
    `static java.sql.Timestamp` | `plus(java.sql.Timestamp self, int days)` Add number of days to this Timestamp and returns the new Timestamp object.
    `static java.util.Calendar` | `previous(java.util.Calendar self)` Decrement a Calendar by one day.
    `static java.util.Date` | `previous(java.util.Date self)` Decrement a Date by one day.
    `static java.sql.Date` | `previous(java.sql.Date self)` Decrement a java.sql.Date by one day.
    `static void` | `putAt(java.util.Calendar self, int field, int value)` Support the subscript operator for mutating a Calendar.
    `static void` | `putAt(java.util.Date self, int field, int value)` Support the subscript operator for mutating a Date.
    `static void` | `set(java.util.Calendar self, java.util.Map<java.lang.Object,java.lang.Integer> updates)` Support mutating a Calendar with a Map.
    `static void` | `set(java.util.Date self, java.util.Map<java.lang.Object,java.lang.Integer> updates)` Support mutating a Date with a Map.
    `static java.util.Calendar` | `toCalendar(java.util.Date self)` Convert a Date to a Calendar.
    `static java.util.Calendar` | `updated(java.util.Calendar self, java.util.Map<java.lang.Object,java.lang.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.
    `static java.util.Date` | `updated(java.util.Date self, java.util.Map<java.lang.Object,java.lang.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.

    - ### Methods inherited from class org.codehaus.groovy.runtime.DefaultGroovyMethodsSupport

      `cloneSimilarCollection, cloneSimilarMap, closeQuietly, closeWithWarning, createSimilarArray, createSimilarCollection, createSimilarCollection, createSimilarList, createSimilarMap, createSimilarOrDefaultCollection, createSimilarSet, normaliseIndex, sameType, subListBorders, subListBorders`

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DateGroovyMethods

          public DateGroovyMethods()

  - ### Method Detail

    - #### getAt

          public static int getAt(java.util.Date self,
                  int field)

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

    - #### toCalendar

          public static java.util.Calendar toCalendar(java.util.Date self)

      Convert a Date to a Calendar.
      Parameters:
        `self` - a Date
      Returns:
        a Calendar corresponding to the given Date
      Since:
        1.7.6

    - #### getAt

          public static int getAt(java.util.Calendar self,
                  int field)

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

    - #### putAt

          public static void putAt(java.util.Calendar self,
                   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:
        `self` - A Calendar
        `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)`

    - #### putAt

          public static void putAt(java.util.Date self,
                   int field,
                   int value)

      Support the subscript operator for mutating a Date.
      Parameters:
        `self` - A Date
        `field` - A Calendar field, e.g. MONTH
        `value` - The value for the given field, e.g. FEBRUARY
      Since:
        1.7.3
      See Also:
        `putAt(java.util.Calendar, int, int)`, `Calendar.set(int, int)`

    - #### set

          public static void set(java.util.Calendar self,
                 java.util.Map<java.lang.Object,java.lang.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:

      year | Calendar.YEAR
      month | Calendar.MONTH
      date | 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:
        `self` - A Calendar
        `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)`

    - #### updated

          public static java.util.Calendar updated(java.util.Calendar self,
                                   java.util.Map<java.lang.Object,java.lang.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.updated(year: nextYear)
           println now.time
           println oneYearFromNow.time

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

    - #### set

          public static void set(java.util.Date self,
                 java.util.Map<java.lang.Object,java.lang.Integer> updates)

      Support mutating a Date with a Map.

      Example usage:

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

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

    - #### updated

          public static java.util.Date updated(java.util.Date self,
                               java.util.Map<java.lang.Object,java.lang.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.updated(year: nextYear)
           println today
           println oneYearFromNow

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

    - #### next

          public static java.util.Date next(java.util.Date self)

      Increment a Date by one day.
      Parameters:
        `self` - a Date
      Returns:
        the next days date
      Since:
        1.0

    - #### next

          public static java.util.Calendar next(java.util.Calendar self)

      Increment a Calendar by one day.
      Parameters:
        `self` - a Calendar
      Returns:
        a new Calendar set to the next day
      Since:
        1.8.7

    - #### previous

          public static java.util.Calendar previous(java.util.Calendar self)

      Decrement a Calendar by one day.
      Parameters:
        `self` - a Calendar
      Returns:
        a new Calendar set to the previous day
      Since:
        1.8.7

    - #### next

          public static java.sql.Date next(java.sql.Date self)

      Increment a java.sql.Date by one day.
      Parameters:
        `self` - a java.sql.Date
      Returns:
        the next days date
      Since:
        1.0

    - #### previous

          public static java.util.Date previous(java.util.Date self)

      Decrement a Date by one day.
      Parameters:
        `self` - a Date
      Returns:
        the previous days date
      Since:
        1.0

    - #### previous

          public static java.sql.Date previous(java.sql.Date self)

      Decrement a java.sql.Date by one day.
      Parameters:
        `self` - a java.sql.Date
      Returns:
        the previous days date
      Since:
        1.0

    - #### plus

          public static java.util.Date plus(java.util.Date self,
                            int days)

      Add a number of days to this date and returns the new date.
      Parameters:
        `self` - a Date
        `days` - the number of days to increase
      Returns:
        the new date
      Since:
        1.0

    - #### plus

          public static java.sql.Date plus(java.sql.Date self,
                           int days)

      Add a number of days to this date and returns the new date.
      Parameters:
        `self` - a java.sql.Date
        `days` - the number of days to increase
      Returns:
        the new date
      Since:
        1.0

    - #### plus

          public static java.sql.Timestamp plus(java.sql.Timestamp self,
                                int days)

      Add number of days to this Timestamp and returns the new Timestamp object.
      Parameters:
        `self` - a Timestamp
        `days` - the number of days to increase
      Returns:
        the new Timestamp

    - #### minus

          public static java.util.Date minus(java.util.Date self,
                             int days)

      Subtract a number of days from this date and returns the new date.
      Parameters:
        `self` - a Date
        `days` - the number of days to subtract
      Returns:
        the new date
      Since:
        1.0

    - #### minus

          public static java.sql.Date minus(java.sql.Date self,
                            int days)

      Subtract a number of days from this date and returns the new date.
      Parameters:
        `self` - a java.sql.Date
        `days` - the number of days to subtract
      Returns:
        the new date
      Since:
        1.0

    - #### minus

          public static java.sql.Timestamp minus(java.sql.Timestamp self,
                                 int days)

      Subtract a number of days from this Timestamp and returns the new Timestamp object.
      Parameters:
        `self` - a Timestamp
        `days` - the number of days to subtract
      Returns:
        the new Timestamp

    - #### minus

          public static int minus(java.util.Calendar self,
                  java.util.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:
        `self` - a Calendar
        `then` - another Calendar
      Returns:
        number of days
      Since:
        1.6.0

    - #### minus

          public static int minus(java.util.Date self,
                  java.util.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:
        `self` - a Date
        `then` - another Date
      Returns:
        number of days
      Since:
        1.6.0

    - #### format

          public static java.lang.String format(java.util.Date self,
                                java.lang.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:
        `self` - a Date
        `format` - the format pattern to use according to `SimpleDateFormat`
      Returns:
        a string representation of this date.
      Since:
        1.5.7
      See Also:
        `SimpleDateFormat`

    - #### format

          public static java.lang.String format(java.util.Date self,
                                java.lang.String format,
                                java.util.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:
        `self` - a Date
        `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`

    - #### getDateString

          public static java.lang.String getDateString(java.util.Date self)

      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).

      Parameters:
        `self` - a Date
      Returns:
        a string representation of this date
      Since:
        1.5.7
      See Also:
        `DateFormat.getDateInstance(int)`, `DateFormat.SHORT`

    - #### getTimeString

          public static java.lang.String getTimeString(java.util.Date self)

      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).

      Parameters:
        `self` - a Date
      Returns:
        a string representing the time portion of this date
      Since:
        1.5.7
      See Also:
        `DateFormat.getTimeInstance(int)`, `DateFormat.MEDIUM`

    - #### getDateTimeString

          public static java.lang.String getDateTimeString(java.util.Date self)

      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).

      Parameters:
        `self` - a Date
      Returns:
        a string representation of this date and time
      Since:
        1.5.7
      See Also:
        `DateFormat.getDateTimeInstance(int, int)`

    - #### clearTime

          public static java.util.Date clearTime(java.util.Date self)

      Clears the time portion of this Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.
      Parameters:
        `self` - a Date
      Returns:
        the Date but with the time portion cleared
      Since:
        1.6.7

    - #### clearTime

          public static java.sql.Date clearTime(java.sql.Date self)

      Clears the time portion of this java.sql.Date instance; useful utility where it makes sense to compare month/day/year only portions of a Date.
      Parameters:
        `self` - a java.sql.Date
      Returns:
        the java.sql.Date but with the time portion cleared
      Since:
        1.6.7

    - #### clearTime

          public static java.util.Calendar clearTime(java.util.Calendar self)

      Clears the time portion of this Calendar instance; useful utility where it makes sense to compare month/day/year only portions of a Calendar.
      Parameters:
        `self` - a Calendar
      Returns:
        the Calendar but with the time portion cleared
      Since:
        1.6.7

    - #### format

          public static java.lang.String format(java.util.Calendar self,
                                java.lang.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:
        `self` - this calendar
        `pattern` - format pattern
      Returns:
        String representation of this calendar with the given format.
      Since:
        1.6.0
      See Also:
        `DateFormat.setTimeZone(java.util.TimeZone)`, `DateFormat.format(java.util.Date)`, `format(java.util.Date, String)`