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

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

`cloneSimilarCollection, cloneSimilarMap, closeQuietly, closeWithWarning, 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(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 Calendar toCalendar(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(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(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(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(Calendar self,
           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:

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 Calendar updated(Calendar self,
                   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.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(Date self,
           Map<Object,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 Date updated(Date self,
               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 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 Date next(Date self)

Increment a Date by one day.

Parameters:
  `self` - a Date
Returns:
  the next days date
Since:
  1.0

#### next

    public static Date next(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 Date previous(Date self)

Decrement a Date by one day.

Parameters:
  `self` - a Date
Returns:
  the previous days date
Since:
  1.0

#### previous

    public static Date previous(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 Date plus(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 Date plus(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

#### minus

    public static Date minus(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 Date minus(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 int minus(Calendar self,
            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(Date self,
            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 String format(Date self,
                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`

#### getDateString

    public static String getDateString(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 String getTimeString(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 String getDateTimeString(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 void clearTime(Date self)

Clears the time portion of this Date instance; Util where it makes sense to compare month/day/year only portions of a Date

Parameters:
  `self` - a Date
Since:
  1.6.7

#### clearTime

    public static void clearTime(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
Since:
  1.6.7

#### clearTime

    public static void clearTime(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
Since:
  1.6.7

#### format

    public static String format(Calendar self,
                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)`