Package org.apache.commons.lang3.time

Class DateUtils

java.lang.Object
org.apache.commons.lang3.time.DateUtils
public class DateUtils extends Object
A suite of utilities surrounding the use of the Calendar and Date object.

DateUtils contains a lot of common methods considering manipulations of Dates or Calendars. Some methods require some extra explanation. The truncate, ceiling and round methods could be considered the Math.floor(), Math.ceil() or Math.round versions for dates This way date-fields will be ignored in bottom-up order. As a complement to these methods we've introduced some fragment-methods. With these methods the Date-fields will be ignored in top-down order. Since a date without a year is not a valid date, you have to decide in what kind of date-field you want your result, for instance milliseconds or days.

Several methods are provided for adding to Date objects, of the form addXXX(Date date, int amount). It is important to note these methods use a Calendar internally (with default time zone and locale) and may be affected by changes to daylight saving time (DST).

Since:
2.0

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    MILLIS_PER_DAY
    Number of milliseconds in a standard day.
    static final long
    MILLIS_PER_HOUR
    Number of milliseconds in a standard hour.
    static final long
    MILLIS_PER_MINUTE
    Number of milliseconds in a standard minute.
    static final long
    MILLIS_PER_SECOND
    Number of milliseconds in a standard second.
    static final int
    RANGE_MONTH_MONDAY
    A month range, the week starting on Monday.
    static final int
    RANGE_MONTH_SUNDAY
    A month range, the week starting on Sunday.
    static final int
    RANGE_WEEK_CENTER
    A week range, centered around the day focused.
    static final int
    RANGE_WEEK_MONDAY
    A week range, starting on Monday.
    static final int
    RANGE_WEEK_RELATIVE
    A week range, starting on the day focused.
    static final int
    RANGE_WEEK_SUNDAY
    A week range, starting on Sunday.
    static final int
    SEMI_MONTH
    This is half a month, so this represents whether a date is in the top or bottom half of the month.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DateUtils()
    Deprecated.
    TODO Make private in 4.0.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Date
    addDays(Date date, int amount)
    Adds a number of days to a date returning a new object.
    static Date
    addHours(Date date, int amount)
    Adds a number of hours to a date returning a new object.
    static Date
    addMilliseconds(Date date, int amount)
    Adds a number of milliseconds to a date returning a new object.
    static Date
    addMinutes(Date date, int amount)
    Adds a number of minutes to a date returning a new object.
    static Date
    addMonths(Date date, int amount)
    Adds a number of months to a date returning a new object.
    static Date
    addSeconds(Date date, int amount)
    Adds a number of seconds to a date returning a new object.
    static Date
    addWeeks(Date date, int amount)
    Adds a number of weeks to a date returning a new object.
    static Date
    addYears(Date date, int amount)
    Adds a number of years to a date returning a new object.
    static Date
    ceiling(Object date, int field)
    Gets a date ceiling, leaving the field specified as the most significant field.
    static Calendar
    ceiling(Calendar calendar, int field)
    Gets a date ceiling, leaving the field specified as the most significant field.
    static Date
    ceiling(Date date, int field)
    Gets a date ceiling, leaving the field specified as the most significant field.
    static long
    getFragmentInDays(Calendar calendar, int fragment)
    Returns the number of days within the fragment.
    static long
    getFragmentInDays(Date date, int fragment)
    Returns the number of days within the fragment.
    static long
    getFragmentInHours(Calendar calendar, int fragment)
    Returns the number of hours within the fragment.
    static long
    getFragmentInHours(Date date, int fragment)
    Returns the number of hours within the fragment.
    static long
    getFragmentInMilliseconds(Calendar calendar, int fragment)
    Returns the number of milliseconds within the fragment.
    static long
    getFragmentInMilliseconds(Date date, int fragment)
    Returns the number of milliseconds within the fragment.
    static long
    getFragmentInMinutes(Calendar calendar, int fragment)
    Returns the number of minutes within the fragment.
    static long
    getFragmentInMinutes(Date date, int fragment)
    Returns the number of minutes within the fragment.
    static long
    getFragmentInSeconds(Calendar calendar, int fragment)
    Returns the number of seconds within the fragment.
    static long
    getFragmentInSeconds(Date date, int fragment)
    Returns the number of seconds within the fragment.
    static boolean
    isSameDay(Calendar cal1, Calendar cal2)
    Checks if two calendar objects are on the same day ignoring time.
    static boolean
    isSameDay(Date date1, Date date2)
    Checks if two date objects are on the same day ignoring time.
    static boolean
    isSameInstant(Calendar cal1, Calendar cal2)
    Checks if two calendar objects represent the same instant in time.
    static boolean
    isSameInstant(Date date1, Date date2)
    Checks if two date objects represent the same instant in time.
    static boolean
    isSameLocalTime(Calendar cal1, Calendar cal2)
    Checks if two calendar objects represent the same local time.
    static Iterator<?>
    iterator(Object calendar, int rangeStyle)
    Constructs an Iterator over each day in a date range defined by a focus date and range style.
    static Iterator<Calendar>
    iterator(Calendar calendar, int rangeStyle)
    Constructs an Iterator over each day in a date range defined by a focus date and range style.
    static Iterator<Calendar>
    iterator(Date focus, int rangeStyle)
    Constructs an Iterator over each day in a date range defined by a focus date and range style.
    static Date
    parseDate(String str, String... parsePatterns)
    Parses a string representing a date by trying a variety of different parsers.
    static Date
    parseDate(String str, Locale locale, String... parsePatterns)
    Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.
    static Date
    parseDateStrictly(String str, String... parsePatterns)
    Parses a string representing a date by trying a variety of different parsers.
    static Date
    parseDateStrictly(String str, Locale locale, String... parsePatterns)
    Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.
    static Date
    round(Object date, int field)
    Rounds a date, leaving the field specified as the most significant field.
    static Calendar
    round(Calendar calendar, int field)
    Rounds a date, leaving the field specified as the most significant field.
    static Date
    round(Date date, int field)
    Rounds a date, leaving the field specified as the most significant field.
    static Date
    setDays(Date date, int amount)
    Sets the day of month field to a date returning a new object.
    static Date
    setHours(Date date, int amount)
    Sets the hours field to a date returning a new object.
    static Date
    setMilliseconds(Date date, int amount)
    Sets the milliseconds field to a date returning a new object.
    static Date
    setMinutes(Date date, int amount)
    Sets the minute field to a date returning a new object.
    static Date
    setMonths(Date date, int amount)
    Sets the months field to a date returning a new object.
    static Date
    setSeconds(Date date, int amount)
    Sets the seconds field to a date returning a new object.
    static Date
    setYears(Date date, int amount)
    Sets the years field to a date returning a new object.
    static Calendar
    toCalendar(Date date)
    Converts a Date into a Calendar.
    static Calendar
    toCalendar(Date date, TimeZone tz)
    Converts a Date of a given TimeZone into a Calendar
    static Date
    truncate(Object date, int field)
    Truncates a date, leaving the field specified as the most significant field.
    static Calendar
    truncate(Calendar date, int field)
    Truncates a date, leaving the field specified as the most significant field.
    static Date
    truncate(Date date, int field)
    Truncates a date, leaving the field specified as the most significant field.
    static int
    truncatedCompareTo(Calendar cal1, Calendar cal2, int field)
    Determines how two calendars compare up to no more than the specified most significant field.
    static int
    truncatedCompareTo(Date date1, Date date2, int field)
    Determines how two dates compare up to no more than the specified most significant field.
    static boolean
    truncatedEquals(Calendar cal1, Calendar cal2, int field)
    Determines if two calendars are equal up to no more than the specified most significant field.
    static boolean
    truncatedEquals(Date date1, Date date2, int field)
    Determines if two dates are equal up to no more than the specified most significant field.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • DateUtils

      @Deprecated public DateUtils()
      Deprecated.
      TODO Make private in 4.0.
      DateUtils instances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such as DateUtils.parseDate(str);.

      This constructor is public to permit tools that require a JavaBean instance to operate.

  • Method Details

    • addDays

      public static Date addDays(Date date, int amount)
      Adds a number of days to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addHours

      public static Date addHours(Date date, int amount)
      Adds a number of hours to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addMilliseconds

      public static Date addMilliseconds(Date date, int amount)
      Adds a number of milliseconds to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addMinutes

      public static Date addMinutes(Date date, int amount)
      Adds a number of minutes to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addMonths

      public static Date addMonths(Date date, int amount)
      Adds a number of months to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addSeconds

      public static Date addSeconds(Date date, int amount)
      Adds a number of seconds to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addWeeks

      public static Date addWeeks(Date date, int amount)
      Adds a number of weeks to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • addYears

      public static Date addYears(Date date, int amount)
      Adds a number of years to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to add, may be negative
      Returns:
      the new Date with the amount added
      Throws:
      NullPointerException - if the date is null

    • ceiling

      public static Calendar ceiling(Calendar calendar, int field)
      Gets a date ceiling, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 Apr 2002 0:00:00.000.

      Parameters:
      calendar - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different ceil date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million
      Since:
      2.5

    • ceiling

      public static Date ceiling(Date date, int field)
      Gets a date ceiling, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 Apr 2002 0:00:00.000.

      Parameters:
      date - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different ceil date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million
      Since:
      2.5

    • ceiling

      public static Date ceiling(Object date, int field)
      Gets a date ceiling, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 Apr 2002 0:00:00.000.

      Parameters:
      date - the date to work with, either Date or Calendar, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different ceil date, not null
      Throws:
      NullPointerException - if the date is null
      ClassCastException - if the object type is not a Date or Calendar
      ArithmeticException - if the year is over 280 million
      Since:
      2.5

    • getFragmentInDays

      public static long getFragmentInDays(Calendar calendar, int fragment)
      Returns the number of days within the fragment. All datefields greater than the fragment will be ignored.

      Asking the days of any date will only return the number of days of the current month (resulting in a number between 1 and 31). This method will retrieve the number of days for any fragment. For example, if you want to calculate the number of days past this year, your fragment is Calendar.YEAR. The result will be all days of the past month(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a DAY field will return 0.

      • January 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_MONTH))
      • February 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_MONTH))
      • January 28, 2008 with Calendar.YEAR as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_YEAR))
      • February 28, 2008 with Calendar.YEAR as fragment will return 59 (equivalent to calendar.get(Calendar.DAY_OF_YEAR))
      • January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in days)
      Parameters:
      calendar - the calendar to work with, not null
      fragment - the Calendar field part of calendar to calculate
      Returns:
      number of days within the fragment of date
      Throws:
      NullPointerException - if the date is null or fragment is not supported
      Since:
      2.4

    • getFragmentInDays

      public static long getFragmentInDays(Date date, int fragment)
      Returns the number of days within the fragment. All date fields greater than the fragment will be ignored.

      Asking the days of any date will only return the number of days of the current month (resulting in a number between 1 and 31). This method will retrieve the number of days for any fragment. For example, if you want to calculate the number of days past this year, your fragment is Calendar.YEAR. The result will be all days of the past month(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a DAY field will return 0.

      • January 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to deprecated date.getDay())
      • February 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to deprecated date.getDay())
      • January 28, 2008 with Calendar.YEAR as fragment will return 28
      • February 28, 2008 with Calendar.YEAR as fragment will return 59
      • January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in days)
      Parameters:
      date - the date to work with, not null
      fragment - the Calendar field part of date to calculate
      Returns:
      number of days within the fragment of date
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the fragment is not supported
      Since:
      2.4

    • getFragmentInHours

      public static long getFragmentInHours(Calendar calendar, int fragment)
      Returns the number of hours within the fragment. All date fields greater than the fragment will be ignored.

      Asking the hours of any date will only return the number of hours of the current day (resulting in a number between 0 and 23). This method will retrieve the number of hours for any fragment. For example, if you want to calculate the number of hours past this month, your fragment is Calendar.MONTH. The result will be all hours of the past day(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a HOUR field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to calendar.get(Calendar.HOUR_OF_DAY))
      • January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to calendar.get(Calendar.HOUR_OF_DAY))
      • January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7
      • January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in hours)
      Parameters:
      calendar - the calendar to work with, not null
      fragment - the Calendar field part of calendar to calculate
      Returns:
      number of hours within the fragment of date
      Throws:
      NullPointerException - if the date is null or fragment is not supported
      Since:
      2.4

    • getFragmentInHours

      public static long getFragmentInHours(Date date, int fragment)
      Returns the number of hours within the fragment. All date fields greater than the fragment will be ignored.

      Asking the hours of any date will only return the number of hours of the current day (resulting in a number between 0 and 23). This method will retrieve the number of hours for any fragment. For example, if you want to calculate the number of hours past this month, your fragment is Calendar.MONTH. The result will be all hours of the past day(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a HOUR field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to deprecated date.getHours())
      • January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to deprecated date.getHours())
      • January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7
      • January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in hours)
      Parameters:
      date - the date to work with, not null
      fragment - the Calendar field part of date to calculate
      Returns:
      number of hours within the fragment of date
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the fragment is not supported
      Since:
      2.4

    • getFragmentInMilliseconds

      public static long getFragmentInMilliseconds(Calendar calendar, int fragment)
      Returns the number of milliseconds within the fragment. All date fields greater than the fragment will be ignored.

      Asking the milliseconds of any date will only return the number of milliseconds of the current second (resulting in a number between 0 and 999). This method will retrieve the number of milliseconds for any fragment. For example, if you want to calculate the number of seconds past today, your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will be all seconds of the past hour(s), minutes(s) and second(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a MILLISECOND field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538 (equivalent to calendar.get(Calendar.MILLISECOND))
      • January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538 (equivalent to calendar.get(Calendar.MILLISECOND))
      • January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538 (10*1000 + 538)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in milliseconds)
      Parameters:
      calendar - the calendar to work with, not null
      fragment - the Calendar field part of calendar to calculate
      Returns:
      number of milliseconds within the fragment of date
      Throws:
      NullPointerException - if the date is null or fragment is not supported
      Since:
      2.4

    • getFragmentInMilliseconds

      public static long getFragmentInMilliseconds(Date date, int fragment)
      Returns the number of milliseconds within the fragment. All date fields greater than the fragment will be ignored.

      Asking the milliseconds of any date will only return the number of milliseconds of the current second (resulting in a number between 0 and 999). This method will retrieve the number of milliseconds for any fragment. For example, if you want to calculate the number of milliseconds past today, your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will be all milliseconds of the past hour(s), minutes(s) and second(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a SECOND field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
      • January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
      • January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538 (10*1000 + 538)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in milliseconds)
      Parameters:
      date - the date to work with, not null
      fragment - the Calendar field part of date to calculate
      Returns:
      number of milliseconds within the fragment of date
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the fragment is not supported
      Since:
      2.4

    • getFragmentInMinutes

      public static long getFragmentInMinutes(Calendar calendar, int fragment)
      Returns the number of minutes within the fragment. All date fields greater than the fragment will be ignored.

      Asking the minutes of any date will only return the number of minutes of the current hour (resulting in a number between 0 and 59). This method will retrieve the number of minutes for any fragment. For example, if you want to calculate the number of minutes past this month, your fragment is Calendar.MONTH. The result will be all minutes of the past day(s) and hour(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a MINUTE field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to calendar.get(Calendar.MINUTES))
      • January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to calendar.get(Calendar.MINUTES))
      • January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15
      • January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in minutes)
      Parameters:
      calendar - the calendar to work with, not null
      fragment - the Calendar field part of calendar to calculate
      Returns:
      number of minutes within the fragment of date
      Throws:
      NullPointerException - if the date is null or fragment is not supported
      Since:
      2.4

    • getFragmentInMinutes

      public static long getFragmentInMinutes(Date date, int fragment)
      Returns the number of minutes within the fragment. All date fields greater than the fragment will be ignored.

      Asking the minutes of any date will only return the number of minutes of the current hour (resulting in a number between 0 and 59). This method will retrieve the number of minutes for any fragment. For example, if you want to calculate the number of minutes past this month, your fragment is Calendar.MONTH. The result will be all minutes of the past day(s) and hour(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a MINUTE field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to deprecated date.getMinutes())
      • January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to deprecated date.getMinutes())
      • January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15
      • January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in minutes)
      Parameters:
      date - the date to work with, not null
      fragment - the Calendar field part of date to calculate
      Returns:
      number of minutes within the fragment of date
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the fragment is not supported
      Since:
      2.4

    • getFragmentInSeconds

      public static long getFragmentInSeconds(Calendar calendar, int fragment)
      Returns the number of seconds within the fragment. All date fields greater than the fragment will be ignored.

      Asking the seconds of any date will only return the number of seconds of the current minute (resulting in a number between 0 and 59). This method will retrieve the number of seconds for any fragment. For example, if you want to calculate the number of seconds past today, your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will be all seconds of the past hour(s) and minutes(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a SECOND field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to calendar.get(Calendar.SECOND))
      • January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to calendar.get(Calendar.SECOND))
      • January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110 (7*3600 + 15*60 + 10)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in seconds)
      Parameters:
      calendar - the calendar to work with, not null
      fragment - the Calendar field part of calendar to calculate
      Returns:
      number of seconds within the fragment of date
      Throws:
      NullPointerException - if the date is null or fragment is not supported
      Since:
      2.4

    • getFragmentInSeconds

      public static long getFragmentInSeconds(Date date, int fragment)
      Returns the number of seconds within the fragment. All date fields greater than the fragment will be ignored.

      Asking the seconds of any date will only return the number of seconds of the current minute (resulting in a number between 0 and 59). This method will retrieve the number of seconds for any fragment. For example, if you want to calculate the number of seconds past today, your fragment is Calendar.DATE or Calendar.DAY_OF_YEAR. The result will be all seconds of the past hour(s) and minutes(s).

      Valid fragments are: Calendar.YEAR, Calendar.MONTH, both Calendar.DAY_OF_YEAR and Calendar.DATE, Calendar.HOUR_OF_DAY, Calendar.MINUTE, Calendar.SECOND and Calendar.MILLISECOND A fragment less than or equal to a SECOND field will return 0.

      • January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to deprecated date.getSeconds())
      • January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to deprecated date.getSeconds())
      • January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110 (7*3600 + 15*60 + 10)
      • January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in seconds)
      Parameters:
      date - the date to work with, not null
      fragment - the Calendar field part of date to calculate
      Returns:
      number of seconds within the fragment of date
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the fragment is not supported
      Since:
      2.4

    • isSameDay

      public static boolean isSameDay(Calendar cal1, Calendar cal2)
      Checks if two calendar objects are on the same day ignoring time.

      28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false.

      Parameters:
      cal1 - the first calendar, not altered, not null
      cal2 - the second calendar, not altered, not null
      Returns:
      true if they represent the same day
      Throws:
      NullPointerException - if either calendar is null
      Since:
      2.1

    • isSameDay

      public static boolean isSameDay(Date date1, Date date2)
      Checks if two date objects are on the same day ignoring time.

      28 Mar 2002 13:45 and 28 Mar 2002 06:01 would return true. 28 Mar 2002 13:45 and 12 Mar 2002 13:45 would return false.

      Parameters:
      date1 - the first date, not altered, not null
      date2 - the second date, not altered, not null
      Returns:
      true if they represent the same day
      Throws:
      NullPointerException - if either date is null
      Since:
      2.1

    • isSameInstant

      public static boolean isSameInstant(Calendar cal1, Calendar cal2)
      Checks if two calendar objects represent the same instant in time.

      This method compares the long millisecond time of the two objects.

      Parameters:
      cal1 - the first calendar, not altered, not null
      cal2 - the second calendar, not altered, not null
      Returns:
      true if they represent the same millisecond instant
      Throws:
      NullPointerException - if either date is null
      Since:
      2.1

    • isSameInstant

      public static boolean isSameInstant(Date date1, Date date2)
      Checks if two date objects represent the same instant in time.

      This method compares the long millisecond time of the two objects.

      Parameters:
      date1 - the first date, not altered, not null
      date2 - the second date, not altered, not null
      Returns:
      true if they represent the same millisecond instant
      Throws:
      NullPointerException - if either date is null
      Since:
      2.1

    • isSameLocalTime

      public static boolean isSameLocalTime(Calendar cal1, Calendar cal2)
      Checks if two calendar objects represent the same local time.

      This method compares the values of the fields of the two objects. In addition, both calendars must be the same of the same type.

      Parameters:
      cal1 - the first calendar, not altered, not null
      cal2 - the second calendar, not altered, not null
      Returns:
      true if they represent the same millisecond instant
      Throws:
      NullPointerException - if either date is null
      Since:
      2.1

    • iterator

      public static Iterator<Calendar> iterator(Calendar calendar, int rangeStyle)
      Constructs an Iterator over each day in a date range defined by a focus date and range style.

      For instance, passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return an Iterator that starts with Sunday, June 30, 2002 and ends with Saturday, August 3, 2002, returning a Calendar instance for each intermediate day.

      This method provides an iterator that returns Calendar objects. The days are progressed using Calendar.add(int, int).

      Parameters:
      calendar - the date to work with, not null
      rangeStyle - the style constant to use. Must be one of RANGE_MONTH_SUNDAY, RANGE_MONTH_MONDAY, RANGE_WEEK_SUNDAY, RANGE_WEEK_MONDAY, RANGE_WEEK_RELATIVE, RANGE_WEEK_CENTER
      Returns:
      the date iterator, not null
      Throws:
      NullPointerException - if calendar is null
      IllegalArgumentException - if the rangeStyle is invalid

    • iterator

      public static Iterator<Calendar> iterator(Date focus, int rangeStyle)
      Constructs an Iterator over each day in a date range defined by a focus date and range style.

      For instance, passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return an Iterator that starts with Sunday, June 30, 2002 and ends with Saturday, August 3, 2002, returning a Calendar instance for each intermediate day.

      This method provides an iterator that returns Calendar objects. The days are progressed using Calendar.add(int, int).

      Parameters:
      focus - the date to work with, not null
      rangeStyle - the style constant to use. Must be one of RANGE_MONTH_SUNDAY, RANGE_MONTH_MONDAY, RANGE_WEEK_SUNDAY, RANGE_WEEK_MONDAY, RANGE_WEEK_RELATIVE, RANGE_WEEK_CENTER
      Returns:
      the date iterator, not null, not null
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if the rangeStyle is invalid

    • iterator

      public static Iterator<?> iterator(Object calendar, int rangeStyle)
      Constructs an Iterator over each day in a date range defined by a focus date and range style.

      For instance, passing Thursday, July 4, 2002 and a RANGE_MONTH_SUNDAY will return an Iterator that starts with Sunday, June 30, 2002 and ends with Saturday, August 3, 2002, returning a Calendar instance for each intermediate day.

      Parameters:
      calendar - the date to work with, either Date or Calendar, not null
      rangeStyle - the style constant to use. Must be one of the range styles listed for the iterator(Calendar, int) method.
      Returns:
      the date iterator, not null
      Throws:
      NullPointerException - if the date is null
      ClassCastException - if the object type is not a Date or Calendar

    • parseDate

      public static Date parseDate(String str, Locale locale, String... parsePatterns) throws ParseException
      Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.

      The parse will try each parse pattern in turn. A parse is only deemed successful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

      The parser will be lenient toward the parsed date.
      Parameters:
      str - the date to parse, not null
      locale - the locale whose date format symbols should be used. If null, the system locale is used (as per parseDate(String, String...)).
      parsePatterns - the date format patterns to use, see SimpleDateFormat, not null
      Returns:
      the parsed date
      Throws:
      NullPointerException - if the date string or pattern array is null
      ParseException - if none of the date patterns were suitable (or there were none)
      Since:
      3.2

    • parseDate

      public static Date parseDate(String str, String... parsePatterns) throws ParseException
      Parses a string representing a date by trying a variety of different parsers.

      The parse will try each parse pattern in turn. A parse is only deemed successful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

      The parser will be lenient toward the parsed date.
      Parameters:
      str - the date to parse, not null
      parsePatterns - the date format patterns to use, see SimpleDateFormat, not null
      Returns:
      the parsed date
      Throws:
      NullPointerException - if the date string or pattern array is null
      ParseException - if none of the date patterns were suitable (or there were none)

    • parseDateStrictly

      public static Date parseDateStrictly(String str, Locale locale, String... parsePatterns) throws ParseException
      Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.

      The parse will try each parse pattern in turn. A parse is only deemed successful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

      The parser parses strictly - it does not allow for dates such as "February 942, 1996".
      Parameters:
      str - the date to parse, not null
      locale - the locale whose date format symbols should be used. If null, the system locale is used (as per parseDateStrictly(String, String...)).
      parsePatterns - the date format patterns to use, see SimpleDateFormat, not null
      Returns:
      the parsed date
      Throws:
      NullPointerException - if the date string or pattern array is null
      ParseException - if none of the date patterns were suitable
      Since:
      3.2

    • parseDateStrictly

      public static Date parseDateStrictly(String str, String... parsePatterns) throws ParseException
      Parses a string representing a date by trying a variety of different parsers.

      The parse will try each parse pattern in turn. A parse is only deemed successful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

      The parser parses strictly - it does not allow for dates such as "February 942, 1996".
      Parameters:
      str - the date to parse, not null
      parsePatterns - the date format patterns to use, see SimpleDateFormat, not null
      Returns:
      the parsed date
      Throws:
      NullPointerException - if the date string or pattern array is null
      ParseException - if none of the date patterns were suitable
      Since:
      2.5

    • round

      public static Calendar round(Calendar calendar, int field)
      Rounds a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 April 2002 0:00:00.000.

      For a date in a time zone that handles the change to daylight saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. Suppose daylight saving time begins at 02:00 on March 30. Rounding a date that crosses this time would produce the following values:

      • March 30, 2003 01:10 rounds to March 30, 2003 01:00
      • March 30, 2003 01:40 rounds to March 30, 2003 03:00
      • March 30, 2003 02:10 rounds to March 30, 2003 03:00
      • March 30, 2003 02:40 rounds to March 30, 2003 04:00
      Parameters:
      calendar - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different rounded date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million

    • round

      public static Date round(Date date, int field)
      Rounds a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 April 2002 0:00:00.000.

      For a date in a time zone that handles the change to daylight saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. Suppose daylight saving time begins at 02:00 on March 30. Rounding a date that crosses this time would produce the following values:

      • March 30, 2003 01:10 rounds to March 30, 2003 01:00
      • March 30, 2003 01:40 rounds to March 30, 2003 03:00
      • March 30, 2003 02:10 rounds to March 30, 2003 03:00
      • March 30, 2003 02:40 rounds to March 30, 2003 04:00
      Parameters:
      date - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different rounded date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million

    • round

      public static Date round(Object date, int field)
      Rounds a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000. If this was passed with MONTH, it would return 1 April 2002 0:00:00.000.

      For a date in a time zone that handles the change to daylight saving time, rounding to Calendar.HOUR_OF_DAY will behave as follows. Suppose daylight saving time begins at 02:00 on March 30. Rounding a date that crosses this time would produce the following values:

      • March 30, 2003 01:10 rounds to March 30, 2003 01:00
      • March 30, 2003 01:40 rounds to March 30, 2003 03:00
      • March 30, 2003 02:10 rounds to March 30, 2003 03:00
      • March 30, 2003 02:40 rounds to March 30, 2003 04:00
      Parameters:
      date - the date to work with, either Date or Calendar, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different rounded date, not null
      Throws:
      NullPointerException - if the date is null
      ClassCastException - if the object type is not a Date or Calendar
      ArithmeticException - if the year is over 280 million

    • setDays

      public static Date setDays(Date date, int amount)
      Sets the day of month field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 1 <= amount <= 31
      Since:
      2.4

    • setHours

      public static Date setHours(Date date, int amount)
      Sets the hours field to a date returning a new object. Hours range from 0-23. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 0 <= amount <= 23
      Since:
      2.4

    • setMilliseconds

      public static Date setMilliseconds(Date date, int amount)
      Sets the milliseconds field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 0 <= amount <= 999
      Since:
      2.4

    • setMinutes

      public static Date setMinutes(Date date, int amount)
      Sets the minute field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 0 <= amount <= 59
      Since:
      2.4

    • setMonths

      public static Date setMonths(Date date, int amount)
      Sets the months field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 0 <= amount <= 11
      Since:
      2.4

    • setSeconds

      public static Date setSeconds(Date date, int amount)
      Sets the seconds field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      IllegalArgumentException - if amount is not in the range 0 <= amount <= 59
      Since:
      2.4

    • setYears

      public static Date setYears(Date date, int amount)
      Sets the years field to a date returning a new object. The original Date is unchanged.
      Parameters:
      date - the date, not null
      amount - the amount to set
      Returns:
      a new Date set with the specified value
      Throws:
      NullPointerException - if the date is null
      Since:
      2.4

    • toCalendar

      public static Calendar toCalendar(Date date)
      Converts a Date into a Calendar.
      Parameters:
      date - the date to convert to a Calendar
      Returns:
      the created Calendar
      Throws:
      NullPointerException - if null is passed in
      Since:
      3.0

    • toCalendar

      public static Calendar toCalendar(Date date, TimeZone tz)
      Converts a Date of a given TimeZone into a Calendar
      Parameters:
      date - the date to convert to a Calendar
      tz - the time zone of the date
      Returns:
      the created Calendar
      Throws:
      NullPointerException - if date or tz is null

    • truncate

      public static Calendar truncate(Calendar date, int field)
      Truncates a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000. If this was passed with MONTH, it would return 1 Mar 2002 0:00:00.000.

      Parameters:
      date - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different truncated date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million

    • truncate

      public static Date truncate(Date date, int field)
      Truncates a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000. If this was passed with MONTH, it would return 1 Mar 2002 0:00:00.000.

      Parameters:
      date - the date to work with, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different truncated date, not null
      Throws:
      NullPointerException - if the date is null
      ArithmeticException - if the year is over 280 million

    • truncate

      public static Date truncate(Object date, int field)
      Truncates a date, leaving the field specified as the most significant field.

      For example, if you had the date-time of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000. If this was passed with MONTH, it would return 1 Mar 2002 0:00:00.000.

      Parameters:
      date - the date to work with, either Date or Calendar, not null
      field - the field from Calendar or SEMI_MONTH
      Returns:
      the different truncated date, not null
      Throws:
      NullPointerException - if the date is null
      ClassCastException - if the object type is not a Date or Calendar
      ArithmeticException - if the year is over 280 million

    • truncatedCompareTo

      public static int truncatedCompareTo(Calendar cal1, Calendar cal2, int field)
      Determines how two calendars compare up to no more than the specified most significant field.
      Parameters:
      cal1 - the first calendar, not null
      cal2 - the second calendar, not null
      field - the field from Calendar
      Returns:
      a negative integer, zero, or a positive integer as the first calendar is less than, equal to, or greater than the second.
      Throws:
      NullPointerException - if any argument is null
      Since:
      3.0
      See Also:

    • truncatedCompareTo

      public static int truncatedCompareTo(Date date1, Date date2, int field)
      Determines how two dates compare up to no more than the specified most significant field.
      Parameters:
      date1 - the first date, not null
      date2 - the second date, not null
      field - the field from Calendar
      Returns:
      a negative integer, zero, or a positive integer as the first date is less than, equal to, or greater than the second.
      Throws:
      NullPointerException - if any argument is null
      Since:
      3.0
      See Also:

    • truncatedEquals

      public static boolean truncatedEquals(Calendar cal1, Calendar cal2, int field)
      Determines if two calendars are equal up to no more than the specified most significant field.
      Parameters:
      cal1 - the first calendar, not null
      cal2 - the second calendar, not null
      field - the field from Calendar
      Returns:
      true if equal; otherwise false
      Throws:
      NullPointerException - if any argument is null
      Since:
      3.0
      See Also:

    • truncatedEquals

      public static boolean truncatedEquals(Date date1, Date date2, int field)
      Determines if two dates are equal up to no more than the specified most significant field.
      Parameters:
      date1 - the first date, not null
      date2 - the second date, not null
      field - the field from Calendar
      Returns:
      true if equal; otherwise false
      Throws:
      NullPointerException - if any argument is null
      Since:
      3.0
      See Also: