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.

### Constructor Summary

Constructors
Constructor and Description
`DateGroovyMethods()`

### Method Summary

All Methods Static Methods Concrete 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.util.Calendar` `copyWith(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` `copyWith(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.
`static void` `downto(java.util.Calendar self, java.util.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.
`static void` `downto(java.util.Date self, java.util.Date to, Closure closure)` Iterates from this date down to the given date, inclusive, decrementing by one day each time.
`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)` Legacy alias for copyWith.
`static java.util.Date` `updated(java.util.Date self, java.util.Map<java.lang.Object,java.lang.Integer> updates)` Legacy alias for copyWith.
`static void` `upto(java.util.Calendar self, java.util.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.
`static void` `upto(java.util.Date self, java.util.Date to, Closure closure)` Iterates from this date up to the given date, inclusive, incrementing by one day each time.

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

`cloneSimilarCollection, cloneSimilarMap, closeQuietly, closeWithWarning, createSimilarArray, createSimilarCollection, 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:

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

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

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

#### copyWith

    public static java.util.Calendar copyWith(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.copyWith(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:
  2.2.0
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.

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

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

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

#### copyWith

    public static java.util.Date copyWith(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.copyWith(year: nextYear)
     println today
     println oneYearFromNow

Parameters:
  `self` - A Date
  `updates` - A Map of Calendar keys and values
Returns:
  The newly created Date
Since:
  2.2.0
See Also:
  `Calendar.set(int, int)`, `set(java.util.Date, java.util.Map)`, `copyWith(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)`

#### upto

    public static void upto(java.util.Date self,
                            java.util.Date to,
                            Closure closure)

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

Parameters:
  `self` - a Date
  `to` - another Date to go up to
  `closure` - the closure to call
Since:
  2.2

#### upto

    public static void upto(java.util.Calendar self,
                            java.util.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:
  `self` - a Calendar
  `to` - another Calendar to go up to
  `closure` - the closure to call
Since:
  2.2

#### downto

    public static void downto(java.util.Date self,
                              java.util.Date to,
                              Closure closure)

Iterates from this date down to the given date, inclusive, decrementing by one day each time.

Parameters:
  `self` - a Date
  `to` - another Date to go down to
  `closure` - the closure to call
Since:
  2.2

#### downto

    public static void downto(java.util.Calendar self,
                              java.util.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:
  `self` - a Calendar
  `to` - another Calendar to go down to
  `closure` - the closure to call
Since:
  2.2