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