Class DateUtils
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 SummaryFieldsModifier and TypeFieldDescriptionstatic final longNumber of milliseconds in a standard day.static final longNumber of milliseconds in a standard hour.static final longNumber of milliseconds in a standard minute.static final longNumber of milliseconds in a standard second.static final intA month range, the week starting on Monday.static final intA month range, the week starting on Sunday.static final intA week range, centered around the day focused.static final intA week range, starting on Monday.static final intA week range, starting on the day focused.static final intA week range, starting on Sunday.static final intThis is half a month, so this represents whether a date is in the top or bottom half of the month.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionstatic DateAdds a number of days to a date returning a new object.static DateAdds a number of hours to a date returning a new object.static DateaddMilliseconds(Date date, int amount) Adds a number of milliseconds to a date returning a new object.static DateaddMinutes(Date date, int amount) Adds a number of minutes to a date returning a new object.static DateAdds a number of months to a date returning a new object.static DateaddSeconds(Date date, int amount) Adds a number of seconds to a date returning a new object.static DateAdds a number of weeks to a date returning a new object.static DateAdds a number of years to a date returning a new object.static DateGets a date ceiling, leaving the field specified as the most significant field.static CalendarGets a date ceiling, leaving the field specified as the most significant field.static DateGets a date ceiling, leaving the field specified as the most significant field.static longgetFragmentInDays(Calendar calendar, int fragment) Returns the number of days within the fragment.static longgetFragmentInDays(Date date, int fragment) Returns the number of days within the fragment.static longgetFragmentInHours(Calendar calendar, int fragment) Returns the number of hours within the fragment.static longgetFragmentInHours(Date date, int fragment) Returns the number of hours within the fragment.static longgetFragmentInMilliseconds(Calendar calendar, int fragment) Returns the number of milliseconds within the fragment.static longgetFragmentInMilliseconds(Date date, int fragment) Returns the number of milliseconds within the fragment.static longgetFragmentInMinutes(Calendar calendar, int fragment) Returns the number of minutes within the fragment.static longgetFragmentInMinutes(Date date, int fragment) Returns the number of minutes within the fragment.static longgetFragmentInSeconds(Calendar calendar, int fragment) Returns the number of seconds within the fragment.static longgetFragmentInSeconds(Date date, int fragment) Returns the number of seconds within the fragment.static booleanChecks if two calendar objects are on the same day ignoring time.static booleanChecks if two date objects are on the same day ignoring time.static booleanisSameInstant(Calendar cal1, Calendar cal2) Checks if two calendar objects represent the same instant in time.static booleanisSameInstant(Date date1, Date date2) Checks if two date objects represent the same instant in time.static booleanisSameLocalTime(Calendar cal1, Calendar cal2) Checks if two calendar objects represent the same local time.static Iterator<?>Constructs anIteratorover each day in a date range defined by a focus date and range style.Constructs anIteratorover each day in a date range defined by a focus date and range style.Constructs anIteratorover each day in a date range defined by a focus date and range style.static DateParses a string representing a date by trying a variety of different parsers.static DateParses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.static DateparseDateStrictly(String str, String... parsePatterns) Parses a string representing a date by trying a variety of different parsers.static DateparseDateStrictly(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 DateRounds a date, leaving the field specified as the most significant field.static CalendarRounds a date, leaving the field specified as the most significant field.static DateRounds a date, leaving the field specified as the most significant field.static DateSets the day of month field to a date returning a new object.static DateSets the hours field to a date returning a new object.static DatesetMilliseconds(Date date, int amount) Sets the milliseconds field to a date returning a new object.static DatesetMinutes(Date date, int amount) Sets the minute field to a date returning a new object.static DateSets the months field to a date returning a new object.static DatesetSeconds(Date date, int amount) Sets the seconds field to a date returning a new object.static DateSets the years field to a date returning a new object.static CalendartoCalendar(Date date) static CalendartoCalendar(Date date, TimeZone tz) static DateTruncates a date, leaving the field specified as the most significant field.static CalendarTruncates a date, leaving the field specified as the most significant field.static DateTruncates a date, leaving the field specified as the most significant field.static inttruncatedCompareTo(Calendar cal1, Calendar cal2, int field) Determines how two calendars compare up to no more than the specified most significant field.static inttruncatedCompareTo(Date date1, Date date2, int field) Determines how two dates compare up to no more than the specified most significant field.static booleantruncatedEquals(Calendar cal1, Calendar cal2, int field) Determines if two calendars are equal up to no more than the specified most significant field.static booleantruncatedEquals(Date date1, Date date2, int field) Determines if two dates are equal up to no more than the specified most significant field.
- 
Field Details- 
MILLIS_PER_SECONDNumber of milliseconds in a standard second.- Since:
- 2.1
- See Also:
 
- 
MILLIS_PER_MINUTENumber of milliseconds in a standard minute.- Since:
- 2.1
- See Also:
 
- 
MILLIS_PER_HOURNumber of milliseconds in a standard hour.- Since:
- 2.1
- See Also:
 
- 
MILLIS_PER_DAYNumber of milliseconds in a standard day.- Since:
- 2.1
- See Also:
 
- 
SEMI_MONTHThis is half a month, so this represents whether a date is in the top or bottom half of the month.- See Also:
 
- 
RANGE_WEEK_SUNDAYA week range, starting on Sunday.- See Also:
 
- 
RANGE_WEEK_MONDAYA week range, starting on Monday.- See Also:
 
- 
RANGE_WEEK_RELATIVEA week range, starting on the day focused.- See Also:
 
- 
RANGE_WEEK_CENTERA week range, centered around the day focused.- See Also:
 
- 
RANGE_MONTH_SUNDAYA month range, the week starting on Sunday.- See Also:
 
- 
RANGE_MONTH_MONDAYA month range, the week starting on Monday.- See Also:
 
 
- 
- 
Constructor Details- 
DateUtilsDeprecated.TODO Make private in 4.0.DateUtilsinstances should NOT be constructed in standard programming. Instead, the static methods on the class should be used, such asDateUtils.parseDate(str);.This constructor is public to permit tools that require a JavaBean instance to operate. 
 
- 
- 
Method Details- 
addDaysAdds a number of days to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addHoursAdds a number of hours to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addMillisecondsAdds a number of milliseconds to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addMinutesAdds a number of minutes to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addMonthsAdds a number of months to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addSecondsAdds a number of seconds to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addWeeksAdds a number of weeks to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
addYearsAdds a number of years to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to add, may be negative
- Returns:
- the new Datewith the amount added
- Throws:
- NullPointerException- if the date is null
 
- 
ceilingGets 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- Calendaror- 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
 
- 
ceilingGets 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- Calendaror- 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
 
- 
ceilingGets 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- Dateor- Calendar, not null
- field- the field from- Calendaror- SEMI_MONTH
- Returns:
- the different ceil date, not null
- Throws:
- NullPointerException- if the date is- null
- ClassCastException- if the object type is not a- Dateor- Calendar
- ArithmeticException- if the year is over 280 million
- Since:
- 2.5
 
- 
getFragmentInDaysReturns 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- Calendarfield part of calendar to calculate
- Returns:
- number of days within the fragment of date
- Throws:
- NullPointerException- if the date is- nullor fragment is not supported
- Since:
- 2.4
 
- 
getFragmentInDaysReturns 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- Calendarfield 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
 
- 
getFragmentInHoursReturns 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- Calendarfield part of calendar to calculate
- Returns:
- number of hours within the fragment of date
- Throws:
- NullPointerException- if the date is- nullor fragment is not supported
- Since:
- 2.4
 
- 
getFragmentInHoursReturns 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- Calendarfield 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
 
- 
getFragmentInMillisecondsReturns 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- Calendarfield part of calendar to calculate
- Returns:
- number of milliseconds within the fragment of date
- Throws:
- NullPointerException- if the date is- nullor fragment is not supported
- Since:
- 2.4
 
- 
getFragmentInMillisecondsReturns 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- Calendarfield 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
 
- 
getFragmentInMinutesReturns 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- Calendarfield part of calendar to calculate
- Returns:
- number of minutes within the fragment of date
- Throws:
- NullPointerException- if the date is- nullor fragment is not supported
- Since:
- 2.4
 
- 
getFragmentInMinutesReturns 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- Calendarfield 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
 
- 
getFragmentInSecondsReturns 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- Calendarfield part of calendar to calculate
- Returns:
- number of seconds within the fragment of date
- Throws:
- NullPointerException- if the date is- nullor fragment is not supported
- Since:
- 2.4
 
- 
getFragmentInSecondsReturns 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- Calendarfield 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
 
- 
isSameDayChecks 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
 
- 
isSameDayChecks 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
 
- 
isSameInstantChecks 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
 
- 
isSameInstantChecks 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
 
- 
isSameLocalTimeChecks 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
 
- 
iteratorConstructs anIteratorover 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_SUNDAYwill return anIteratorthat 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
 
- 
iteratorConstructs anIteratorover 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_SUNDAYwill return anIteratorthat 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
 
- 
iteratorConstructs anIteratorover 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_SUNDAYwill return anIteratorthat 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- Dateor- 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- Dateor- Calendar
 
- 
parseDatepublic 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
 
- 
parseDateParses 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)
 
- 
parseDateStrictlypublic 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
 
- 
parseDateStrictlyParses 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
 
- 
roundRounds 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- Calendaror- SEMI_MONTH
- Returns:
- the different rounded date, not null
- Throws:
- NullPointerException- if the date is- null
- ArithmeticException- if the year is over 280 million
 
- 
roundRounds 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- Calendaror- SEMI_MONTH
- Returns:
- the different rounded date, not null
- Throws:
- NullPointerException- if the date is null
- ArithmeticException- if the year is over 280 million
 
- 
roundRounds 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- Dateor- Calendar, not null
- field- the field from- Calendaror- SEMI_MONTH
- Returns:
- the different rounded date, not null
- Throws:
- NullPointerException- if the date is- null
- ClassCastException- if the object type is not a- Dateor- Calendar
- ArithmeticException- if the year is over 280 million
 
- 
setDaysSets the day of month field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 1 <= amount <= 31
- Since:
- 2.4
 
- 
setHoursSets the hours field to a date returning a new object. Hours range from 0-23. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 0 <= amount <= 23
- Since:
- 2.4
 
- 
setMillisecondsSets the milliseconds field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 0 <= amount <= 999
- Since:
- 2.4
 
- 
setMinutesSets the minute field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 0 <= amount <= 59
- Since:
- 2.4
 
- 
setMonthsSets the months field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 0 <= amount <= 11
- Since:
- 2.4
 
- 
setSecondsSets the seconds field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- IllegalArgumentException- if- amountis not in the range- 0 <= amount <= 59
- Since:
- 2.4
 
- 
setYearsSets the years field to a date returning a new object. The originalDateis unchanged.- Parameters:
- date- the date, not null
- amount- the amount to set
- Returns:
- a new Dateset with the specified value
- Throws:
- NullPointerException- if the date is null
- Since:
- 2.4
 
- 
toCalendar- Parameters:
- date- the date to convert to a Calendar
- Returns:
- the created Calendar
- Throws:
- NullPointerException- if null is passed in
- Since:
- 3.0
 
- 
toCalendar- Parameters:
- date- the date to convert to a Calendar
- tz- the time zone of the- date
- Returns:
- the created Calendar
- Throws:
- NullPointerException- if- dateor- tzis null
 
- 
truncateTruncates 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- Calendaror- SEMI_MONTH
- Returns:
- the different truncated date, not null
- Throws:
- NullPointerException- if the date is- null
- ArithmeticException- if the year is over 280 million
 
- 
truncateTruncates 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- Calendaror- SEMI_MONTH
- Returns:
- the different truncated date, not null
- Throws:
- NullPointerException- if the date is- null
- ArithmeticException- if the year is over 280 million
 
- 
truncateTruncates 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- Dateor- Calendar, not null
- field- the field from- Calendaror- SEMI_MONTH
- Returns:
- the different truncated date, not null
- Throws:
- NullPointerException- if the date is- null
- ClassCastException- if the object type is not a- Dateor- Calendar
- ArithmeticException- if the year is over 280 million
 
- 
truncatedCompareToDetermines 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:
 
- 
truncatedCompareToDetermines 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:
 
- 
truncatedEqualsDetermines 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:
- trueif equal; otherwise- false
- Throws:
- NullPointerException- if any argument is- null
- Since:
- 3.0
- See Also:
 
- 
truncatedEqualsDetermines 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:
- trueif equal; otherwise- false
- Throws:
- NullPointerException- if any argument is- null
- Since:
- 3.0
- See Also:
 
 
-