Class DateUtilExtensions


  • public class DateUtilExtensions
    extends Object
    This class defines new groovy methods which appear on normal JDK Date and Calendar classes inside the Groovy environment.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static Date 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 Calendar 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 Date clearTime​(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 Calendar copyWith​(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 copyWith​(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.
      static void downto​(Calendar self, 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​(Date self, Date to, Closure closure)
      Iterates from this date down to the given date, inclusive, decrementing by one day each time.
      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 String format​(Date self, String format, TimeZone tz)
      Create a String representation of this date according to the given format pattern and timezone.
      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 Date minus​(Date self, int days)
      Subtract a number of days from this date and returns the new date.
      static Timestamp minus​(Timestamp self, int days)
      Subtract a number of days from this Timestamp and returns the new Timestamp object.
      static int minus​(Calendar self, Calendar 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 int minus​(Date self, Date then)
      Subtract another Date from this one and return the number of days of the difference.
      static Date next​(Date self)
      Increment a java.sql.Date by one day.
      static Calendar next​(Calendar self)
      Increment a Calendar by one day.
      static Date next​(Date self)
      Increment a 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 Timestamp plus​(Timestamp self, int days)
      Add number of days to this Timestamp and returns the new Timestamp object.
      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 java.sql.Date by one day.
      static Calendar previous​(Calendar self)
      Decrement a Calendar by one day.
      static Date previous​(Date self)
      Decrement a 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)
      Legacy alias for copyWith.
      static Date updated​(Date self, Map<Object,​Integer> updates)
      Legacy alias for copyWith.
      static void upto​(Calendar self, 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​(Date self, Date to, Closure closure)
      Iterates from this date up to the given date, inclusive, incrementing by one day each time.
    • Constructor Detail

      • DateUtilExtensions

        public DateUtilExtensions()
    • 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:

        Calendar index values
        yearCalendar.YEAR
        monthCalendar.MONTH
        dateCalendar.DATE
        dayOfMonthCalendar.DATE
        hourOfDayCalendar.HOUR_OF_DAY
        minuteCalendar.MINUTE
        secondCalendar.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)
      • copyWith

        public static Calendar copyWith​(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.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​(Date self,
                               Map<Object,​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
        yearCalendar.YEAR
        monthCalendar.MONTH
        dateCalendar.DATE
        dayOfMonthCalendar.DATE
        hourOfDayCalendar.HOUR_OF_DAY
        minuteCalendar.MINUTE
        secondCalendar.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)
      • copyWith

        public static Date copyWith​(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.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 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 Calendar next​(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 Calendar previous​(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 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
      • plus

        public static Timestamp plus​(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 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 Timestamp minus​(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​(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
      • format

        public static String format​(Date self,
                                    String format,
                                    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 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 Date clearTime​(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 Date 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
        Returns:
        the java.sql.Date but with the time portion cleared
        Since:
        1.6.7
      • clearTime

        public static Calendar 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
        Returns:
        the Calendar but with the time portion cleared
        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)
      • upto

        public static void upto​(Date self,
                                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​(Calendar self,
                                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​(Date self,
                                  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​(Calendar self,
                                  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