Top Description Inners Fields Constructors Methods
org.apache.commons.lang3.time

public Class DateUtils

extends Object
Class Inheritance
Imports
java.text.ParseException, .ParsePosition, java.time.LocalDateTime, .OffsetDateTime, .ZoneId, .ZonedDateTime, java.util.Calendar, .Date, .Iterator, .Locale, .NoSuchElementException, .Objects, .TimeZone, java.util.concurrent.TimeUnit, org.apache.commons.lang3.LocaleUtils
A suite of utilities surrounding the use of the java.util.Calendar and java.util.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

Nested and Inner Type Summary

Modifier and TypeClass and Description
pack-priv static class
DateUtils.DateIterator

Date iterator.

private static enum
DateUtils.ModifyType

Calendar modification types.

Field Summary

Modifier and TypeField and Description
private static final int[][]
fields

public static final long
MILLIS_PER_DAY

Number of milliseconds in a standard day.

public static final long
MILLIS_PER_HOUR

Number of milliseconds in a standard hour.

public static final long
MILLIS_PER_MINUTE

Number of milliseconds in a standard minute.

public static final long
MILLIS_PER_SECOND

Number of milliseconds in a standard second.

public static final int
RANGE_MONTH_MONDAY

A month range, the week starting on Monday.

public static final int
RANGE_MONTH_SUNDAY

A month range, the week starting on Sunday.

public static final int
RANGE_WEEK_CENTER

A week range, centered around the day focused.

public static final int
RANGE_WEEK_MONDAY

A week range, starting on Monday.

public static final int
RANGE_WEEK_RELATIVE

A week range, starting on the day focused.

public static final int
RANGE_WEEK_SUNDAY

A week range, starting on Sunday.

public 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

AccessConstructor and Description
public
DateUtils()
Deprecated TODO Make private in 4.0.

DateUtils instances should NOT be constructed in standard programming.

Method Summary

Modifier and TypeMethod and Description
private static Date

Returns:

the new Date with the amount added.
add(final Date
the date, not null.
date, final int
the calendar field to add to.
calendarField, final int
the amount to add, may be negative.
amount)

Adds to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addDays(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of days to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addHours(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of hours to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addMilliseconds(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of milliseconds to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addMinutes(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of minutes to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addMonths(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of months to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addSeconds(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of seconds to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addWeeks(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of weeks to a date returning a new object.

public static Date

Returns:

the new Date with the amount added.
addYears(final Date
the date, not null.
date, final int
the amount to add, may be negative.
amount)

Adds a number of years to a date returning a new object.

public static Calendar

Returns:

the different ceil date, not null.
ceiling(final Calendar
the date to work with, not null.
calendar, final int
the field from Calendar or SEMI_MONTH.
field)

Gets a date ceiling, leaving the field specified as the most significant field.

public static Date

Returns:

the different ceil date, not null.
ceiling(final Date
the date to work with, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Gets a date ceiling, leaving the field specified as the most significant field.

public static Date

Returns:

the different ceil date, not null.
ceiling(final Object
the date to work with, either Date or Calendar, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Gets a date ceiling, leaving the field specified as the most significant field.

private static long

Returns:

number of units within the fragment of the calendar.
getFragment(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment, final TimeUnit
the time unit.
unit)

Gets a Calendar fragment for any unit.

private static long

Returns:

number of units within the fragment of the date.
getFragment(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment, final TimeUnit
the time unit.
unit)

Gets a Date fragment for any unit.

public static long

Returns:

number of days within the fragment of date.
getFragmentInDays(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment)

Gets the number of days within the fragment.

public static long

Returns:

number of days within the fragment of date.
getFragmentInDays(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment)

Gets the number of days within the fragment.

public static long

Returns:

number of hours within the fragment of date.
getFragmentInHours(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment)

Gets the number of hours within the fragment.

public static long

Returns:

number of hours within the fragment of date.
getFragmentInHours(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment)

Gets the number of hours within the fragment.

public static long

Returns:

number of milliseconds within the fragment of date.
getFragmentInMilliseconds(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment)

Gets the number of milliseconds within the fragment.

public static long

Returns:

number of milliseconds within the fragment of date.
getFragmentInMilliseconds(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment)

Gets the number of milliseconds within the fragment.

public static long

Returns:

number of minutes within the fragment of date.
getFragmentInMinutes(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment)

Gets the number of minutes within the fragment.

public static long

Returns:

number of minutes within the fragment of date.
getFragmentInMinutes(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment)

Gets the number of minutes within the fragment.

public static long

Returns:

number of seconds within the fragment of date.
getFragmentInSeconds(final Calendar
the calendar to work with, not null.
calendar, final int
the Calendar field part of calendar to calculate.
fragment)

Gets the number of seconds within the fragment.

public static long

Returns:

number of seconds within the fragment of date.
getFragmentInSeconds(final Date
the date to work with, not null.
date, final int
the Calendar field part of date to calculate.
fragment)

Gets the number of seconds within the fragment.

public static boolean

Returns:

true if they represent the same day.
isSameDay(final Calendar
the first calendar, not altered, not null.
cal1, final Calendar
the second calendar, not altered, not null.
cal2)

Tests whether two calendar objects are on the same day ignoring time.

public static boolean

Returns:

true if they represent the same day.
isSameDay(final Date
the first date, not altered, not null.
date1, final Date
the second date, not altered, not null.
date2)

Tests whether two date objects are on the same day ignoring time.

public static boolean

Returns:

true if they represent the same millisecond instant.
isSameInstant(final Calendar
the first calendar, not altered, not null.
cal1, final Calendar
the second calendar, not altered, not null.
cal2)

Tests whether two calendar objects represent the same instant in time.

public static boolean

Returns:

true if they represent the same millisecond instant.
isSameInstant(final Date
the first date, not altered, not null.
date1, final Date
the second date, not altered, not null.
date2)

Tests whether two date objects represent the same instant in time.

public static boolean

Returns:

true if they represent the same millisecond instant.
isSameLocalTime(final Calendar
the first calendar, not altered, not null.
cal1, final Calendar
the second calendar, not altered, not null.
cal2)

Tests whether two calendar objects represent the same local time.

public static Iterator<Calendar>

Returns:

the date iterator, not null.
iterator(final Calendar
the date to work with, not null.
calendar, final int
the style constant to use. Must be one of DateUtils#RANGE_MONTH_SUNDAY, DateUtils#RANGE_MONTH_MONDAY, DateUtils#RANGE_WEEK_SUNDAY, DateUtils#RANGE_WEEK_MONDAY, DateUtils#RANGE_WEEK_RELATIVE, DateUtils#RANGE_WEEK_CENTER.
rangeStyle)

Constructs an Iterator over each day in a date range defined by a focus date and range style.

public static Iterator<Calendar>

Returns:

the date iterator, not null, not null.
iterator(final Date
the date to work with, not null.
focus, final int
the style constant to use. Must be one of DateUtils#RANGE_MONTH_SUNDAY, DateUtils#RANGE_MONTH_MONDAY, DateUtils#RANGE_WEEK_SUNDAY, DateUtils#RANGE_WEEK_MONDAY, DateUtils#RANGE_WEEK_RELATIVE, DateUtils#RANGE_WEEK_CENTER.
rangeStyle)

Constructs an Iterator over each day in a date range defined by a focus date and range style.

public static Iterator<?>

Returns:

the date iterator, not null.
iterator(final Object
the date to work with, either Date or Calendar, not null.
calendar, final int
the style constant to use. Must be one of the range styles listed for the iterator(Calendar, int) method.
rangeStyle)

Constructs an Iterator over each day in a date range defined by a focus date and range style.

private static Calendar

Returns:

the given calendar.
modify(final Calendar
the calendar, not null.
val, final int
the field constant.
field, final DateUtils.ModifyType
type to truncate, round or ceiling.
modType)

Internal calculation method.

public static Date

Returns:

the parsed date.
parseDate(final String
the date to parse, not null.
str, final Locale
the locale whose date format symbols should be used. If null, the system locale is used (as per parseDate(String, String...)).
locale, final String...
the date format patterns to use, see SimpleDateFormat, not null.
parsePatterns)

Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.

public static Date

Returns:

the parsed date.
parseDate(final String
the date to parse, not null.
str, final String...
the date format patterns to use, see SimpleDateFormat, not null.
parsePatterns)

Parses a string representing a date by trying a variety of different parsers.

public static Date

Returns:

the parsed date.
parseDateStrictly(final String
the date to parse, not null.
str, final Locale
the locale whose date format symbols should be used. If null, the system locale is used (as per parseDateStrictly(String, String...)).
locale, final String...
the date format patterns to use, see SimpleDateFormat, not null.
parsePatterns)

Parses a string representing a date by trying a variety of different parsers, using the default date format symbols for the given locale.

public static Date

Returns:

the parsed date.
parseDateStrictly(final String
the date to parse, not null.
str, final String...
the date format patterns to use, see SimpleDateFormat, not null.
parsePatterns)

Parses a string representing a date by trying a variety of different parsers.

private static Date

Returns:

the parsed date.
parseDateWithLeniency(final String
the date to parse, not null.
dateStr, final Locale
the locale to use when interpreting the pattern, can be null in which case the default system locale is used.
locale, final String[]
the date format patterns to use, see SimpleDateFormat, not null.
parsePatterns, final boolean
Specify whether or not date/time parsing is to be lenient.
lenient)

Parses a string representing a date by trying a variety of different parsers.

public static Calendar

Returns:

the different rounded date, not null.
round(final Calendar
the date to work with, not null.
calendar, final int
the field from Calendar or SEMI_MONTH.
field)

Rounds a date, leaving the field specified as the most significant field.

public static Date

Returns:

the different rounded date, not null.
round(final Date
the date to work with, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Rounds a date, leaving the field specified as the most significant field.

public static Date

Returns:

the different rounded date, not null.
round(final Object
the date to work with, either Date or Calendar, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Rounds a date, leaving the field specified as the most significant field.

private static Date

Returns:

a new Date set with the specified value.
set(final Date
the date, not null.
date, final int
the Calendar field to set the amount to.
calendarField, final int
the amount to set.
amount)

Sets the specified field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setDays(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the day of month field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setHours(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the hours field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setMilliseconds(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the milliseconds field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setMinutes(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the minute field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setMonths(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the months field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setSeconds(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the seconds field to a date returning a new object.

public static Date

Returns:

a new Date set with the specified value.
setYears(final Date
the date, not null.
date, final int
the amount to set.
amount)

Sets the years field to a date returning a new object.

public static Calendar

Returns:

the created Calendar.
toCalendar(final Date
the date to convert to a Calendar.
date)

Converts a Date into a Calendar.

public static Calendar

Returns:

the created Calendar.
toCalendar(final Date
the date to convert to a Calendar.
date, final TimeZone
the time zone of the date.
tz)

Converts a Date of a given TimeZone into a Calendar.

public static LocalDateTime

Returns:

a new LocalDateTime.
toLocalDateTime(final Date
the Date to convert, not null.
date)

Converts a Date to a LocalDateTime.

public static LocalDateTime

Returns:

a new LocalDateTime.
toLocalDateTime(final Date
the Date to convert to a LocalDateTime, not null.
date, final TimeZone
the time zone, null maps to to the default time zone.
timeZone)

Converts a Date to a LocalDateTime.

public static OffsetDateTime

Returns:

a new OffsetDateTime.
toOffsetDateTime(final Date
the Date to convert, not null.
date)

Converts a Date to a OffsetDateTime.

public static OffsetDateTime

Returns:

a new OffsetDateTime.
toOffsetDateTime(final Date
the Date to convert to a OffsetDateTime, not null.
date, final TimeZone
the time zone, null maps to to the default time zone.
timeZone)

Converts a Date to a OffsetDateTime.

public static ZonedDateTime

Returns:

a new ZonedDateTime.
toZonedDateTime(final Date
the Date to convert, not null.
date)

Converts a Date to a ZonedDateTime.

public static ZonedDateTime

Returns:

a new ZonedDateTime.
toZonedDateTime(final Date
the Date to convert to a ZonedDateTime, not null.
date, final TimeZone
the time zone, null maps to to the default time zone.
timeZone)

Converts a Date to a ZonedDateTime.

private static ZoneId
toZoneId(final TimeZone timeZone)

public static Calendar

Returns:

the different truncated date, not null.
truncate(final Calendar
the date to work with, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Truncates a date, leaving the field specified as the most significant field.

public static Date

Returns:

the different truncated date, not null.
truncate(final Date
the date to work with, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Truncates a date, leaving the field specified as the most significant field.

public static Date

Returns:

the different truncated date, not null.
truncate(final Object
the date to work with, either Date or Calendar, not null.
date, final int
the field from Calendar or SEMI_MONTH.
field)

Truncates a date, leaving the field specified as the most significant field.

public static int

Returns:

a negative integer, zero, or a positive integer as the first calendar is less than, equal to, or greater than the second.
truncatedCompareTo(final Calendar
the first calendar, not null.
cal1, final Calendar
the second calendar, not null.
cal2, final int
the field from Calendar.
field)

Determines how two calendars compare up to no more than the specified most significant field.

public static int

Returns:

a negative integer, zero, or a positive integer as the first date is less than, equal to, or greater than the second.
truncatedCompareTo(final Date
the first date, not null.
date1, final Date
the second date, not null.
date2, final int
the field from Calendar.
field)

Determines how two dates compare up to no more than the specified most significant field.

public static boolean

Returns:

true if equal; otherwise false.
truncatedEquals(final Calendar
the first calendar, not null.
cal1, final Calendar
the second calendar, not null.
cal2, final int
the field from Calendar.
field)

Determines if two calendars are equal up to no more than the specified most significant field.

public static boolean

Returns:

true if equal; otherwise false.
truncatedEquals(final Date
the first date, not null.
date1, final Date
the second date, not null.
date2, final int
the field from Calendar.
field)

Determines if two dates are equal up to no more than the specified most significant field.

private static void
validateDateNotNull(final Date
Date to validate.
date)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait