Groovy Documentation

## org.codehaus.groovy.runtime
[Java] 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.

Method Summary
`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` | `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.lang.String` | `format(java.util.Date self, java.lang.String format)`
`static java.lang.String` | `format(java.util.Date self, java.lang.String format, java.util.TimeZone tz)`
`static java.lang.String` | `format(java.util.Calendar self, java.lang.String pattern)`
`static int` | `getAt(java.util.Date self, int field)` Support the subscript operator for a Date.
`static int` | `getAt(java.util.Calendar self, int field)` Support the subscript operator for a Calendar.
`static java.lang.String` | `getDateString(java.util.Date self)`
`static java.lang.String` | `getDateTimeString(java.util.Date self)`
`static java.lang.String` | `getTimeString(java.util.Date self)`
`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 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` | `next(java.util.Date self)` Increment a Date by one day.
`static java.util.Calendar` | `next(java.util.Calendar self)` Increment a Calendar 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 updates)` Support mutating a Calendar with a Map.
`static void` | `set(java.util.Date self, java.util.Map 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 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 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 DefaultGroovyMethodsSupport
cloneSimilarCollection, cloneSimilarMap, closeQuietly, closeWithWarning, createSimilarArray, createSimilarCollection, createSimilarCollection, createSimilarList, createSimilarMap, createSimilarOrDefaultCollection, createSimilarSet, normaliseIndex, sameType, subListBorders, subListBorders

Methods inherited from class java.lang.Object
java.lang.Object#wait(long), java.lang.Object#wait(long, int), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()

Method Detail

### 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.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 java.text.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 java.text.SimpleDateFormat
  Returns:
    a string representation of this date.
  See Also:
    java.text.SimpleDateFormat
  Since:
    1.5.7

### 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 java.text.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 java.text.SimpleDateFormat
    `tz` - the TimeZone to use
  Returns:
    a string representation of this date.
  See Also:
    java.text.SimpleDateFormat
  Since:
    1.8.3

### format

    public static java.lang.String format(java.util.Calendar self, java.lang.String pattern)

  Shortcut for java.text.SimpleDateFormat to output a String representation of this calendar instance. This method respects the Calendar's assigned java.util.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 java.util.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 java.text.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.
  See Also:
    java.text.DateFormat#setTimeZone(java.util.TimeZone)
    java.text.SimpleDateFormat#format(java.util.Date)
    format(java.util.Date, String)
  Since:
    1.6.0

### 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
  See Also:
    java.util.Calendar
  Since:
    1.5.5

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

### 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 java.text.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
  See Also:
    java.text.DateFormat#getDateInstance(int)
    java.text.DateFormat#SHORT
  Since:
    1.5.7

### 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 java.text.DateFormat. This method uses the java.text.DateFormat#SHORT preset for the day portion and java.text.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
  See Also:
    java.text.DateFormat#getDateTimeInstance(int, int)
  Since:
    1.5.7

### 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 java.text.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
  See Also:
    java.text.DateFormat#getTimeInstance(int)
    java.text.DateFormat#MEDIUM
  Since:
    1.5.7

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

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

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

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

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

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

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

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

### set

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

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

### set

    public static void set(java.util.Date self, java.util.Map 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
  See Also:
    java.util.Calendar#set(int, int)
    set(java.util.Calendar, java.util.Map)
  Since:
    1.7.3

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

### updated

    public static java.util.Calendar updated(java.util.Calendar self, java.util.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.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
  See Also:
    java.util.Calendar#set(int, int)
    java.util.Calendar#set(int, int, int, int, int, int)
    set(java.util.Calendar, java.util.Map)
  Since:
    1.7.3

### updated

    public static java.util.Date updated(java.util.Date self, java.util.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 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
  See Also:
    java.util.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)
  Since:
    1.7.3

Groovy Documentation