org.apache.commons.lang.time

Class DateUtils

public class DateUtils extends Object

A suite of utilities surrounding the use of the java.util.Calendar and java.util.Date object.

Since: 2.0

Version: $Id: DateUtils.java 437554 2006-08-28 06:21:41Z bayard $

Author: Serge Knystautas Stephen Colebourne Janek Bogucki Gary Gregory Phil Steitz

Field Summary
static intMILLIS_IN_DAY
Number of milliseconds in a standard day.
static intMILLIS_IN_HOUR
Number of milliseconds in a standard hour.
static intMILLIS_IN_MINUTE
Number of milliseconds in a standard minute.
static intMILLIS_IN_SECOND
Number of milliseconds in a standard second.
static longMILLIS_PER_DAY
Number of milliseconds in a standard day.
static longMILLIS_PER_HOUR
Number of milliseconds in a standard hour.
static longMILLIS_PER_MINUTE
Number of milliseconds in a standard minute.
static longMILLIS_PER_SECOND
Number of milliseconds in a standard second.
static intRANGE_MONTH_MONDAY
A month range, the week starting on Monday.
static intRANGE_MONTH_SUNDAY
A month range, the week starting on Sunday.
static intRANGE_WEEK_CENTER
A week range, centered around the day focused.
static intRANGE_WEEK_MONDAY
A week range, starting on Monday.
static intRANGE_WEEK_RELATIVE
A week range, starting on the day focused.
static intRANGE_WEEK_SUNDAY
A week range, starting on Sunday.
static intSEMI_MONTH
This is half a month, so this represents whether a date is in the top or bottom half of the month.
static TimeZoneUTC_TIME_ZONE
The UTC time zone (often referred to as GMT).
Constructor Summary
DateUtils()

DateUtils instances should NOT be constructed in standard programming.

Method Summary
static Dateadd(Date date, int calendarField, int amount)
Adds to a date returning a new object.
static DateaddDays(Date date, int amount)
Adds a number of days to a date returning a new object.
static DateaddHours(Date date, int amount)
Adds 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 DateaddMonths(Date date, int amount)
Adds 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 DateaddWeeks(Date date, int amount)
Adds a number of weeks to a date returning a new object.
static DateaddYears(Date date, int amount)
Adds a number of years to a date returning a new object.
static booleanisSameDay(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.

static booleanisSameDay(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.

static booleanisSameInstant(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.

static booleanisSameInstant(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.

static booleanisSameLocalTime(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.

static Iteratoriterator(Date focus, int rangeStyle)

This 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.

static Iteratoriterator(Calendar focus, int rangeStyle)

This 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.

static Iteratoriterator(Object focus, int rangeStyle)

This 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.

static DateparseDate(String str, String[] parsePatterns)

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

The parse will try each parse pattern in turn.

static Dateround(Date date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000.

static Calendarround(Calendar date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000.

static Dateround(Object date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if this was passed with HOUR, it would return 28 Mar 2002 14:00:00.000.

static Datetruncate(Date date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000.

static Calendartruncate(Calendar date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000.

static Datetruncate(Object date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime of 28 Mar 2002 13:45:01.231, if you passed with HOUR, it would return 28 Mar 2002 13:00:00.000.

Field Detail

MILLIS_IN_DAY

public static final int MILLIS_IN_DAY

Deprecated: Use MILLIS_PER_DAY. This will be removed in Commons Lang 3.0.

Number of milliseconds in a standard day.

MILLIS_IN_HOUR

public static final int MILLIS_IN_HOUR

Deprecated: Use MILLIS_PER_HOUR. This will be removed in Commons Lang 3.0.

Number of milliseconds in a standard hour.

MILLIS_IN_MINUTE

public static final int MILLIS_IN_MINUTE

Deprecated: Use MILLIS_PER_MINUTE. This will be removed in Commons Lang 3.0.

Number of milliseconds in a standard minute.

MILLIS_IN_SECOND

public static final int MILLIS_IN_SECOND

Deprecated: Use MILLIS_PER_SECOND. This will be removed in Commons Lang 3.0.

Number of milliseconds in a standard second.

MILLIS_PER_DAY

public static final long MILLIS_PER_DAY
Number of milliseconds in a standard day.

Since: 2.1

MILLIS_PER_HOUR

public static final long MILLIS_PER_HOUR
Number of milliseconds in a standard hour.

Since: 2.1

MILLIS_PER_MINUTE

public static final long MILLIS_PER_MINUTE
Number of milliseconds in a standard minute.

Since: 2.1

MILLIS_PER_SECOND

public static final long MILLIS_PER_SECOND
Number of milliseconds in a standard second.

Since: 2.1

RANGE_MONTH_MONDAY

public static final int RANGE_MONTH_MONDAY
A month range, the week starting on Monday.

RANGE_MONTH_SUNDAY

public static final int RANGE_MONTH_SUNDAY
A month range, the week starting on Sunday.

RANGE_WEEK_CENTER

public static final int RANGE_WEEK_CENTER
A week range, centered around the day focused.

RANGE_WEEK_MONDAY

public static final int RANGE_WEEK_MONDAY
A week range, starting on Monday.

RANGE_WEEK_RELATIVE

public static final int RANGE_WEEK_RELATIVE
A week range, starting on the day focused.

RANGE_WEEK_SUNDAY

public static final int RANGE_WEEK_SUNDAY
A week range, starting on Sunday.

SEMI_MONTH

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.

UTC_TIME_ZONE

public static final TimeZone UTC_TIME_ZONE
The UTC time zone (often referred to as GMT).

Constructor Detail

DateUtils

public DateUtils()

DateUtils instances should NOT be constructed in standard programming. Instead, the class should be used as DateUtils.parse(str);.

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

Method Detail

add

public static Date add(Date date, int calendarField, int amount)
Adds to a date returning a new object. The original date object is unchanged.

Parameters: date the date, not null calendarField the calendar field to add to amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException if the date is null

addDays

public static Date addDays(Date date, int amount)
Adds a number of days to a date returning a new object. The original date object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException 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 object is unchanged.

Parameters: date the date, not null amount the amount to add, may be negative

Returns: the new date object with the amount added

Throws: IllegalArgumentException if the date is null

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: IllegalArgumentException if either date is null

Since: 2.1

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: IllegalArgumentException if either calendar 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: IllegalArgumentException 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: IllegalArgumentException 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: IllegalArgumentException if either date is null

Since: 2.1

iterator

public static Iterator iterator(Date focus, int rangeStyle)

This 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, which always returns Calendar instances

Throws: IllegalArgumentException if the date is null IllegalArgumentException if the rangeStyle is invalid

iterator

public static Iterator iterator(Calendar focus, int rangeStyle)

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

Throws: IllegalArgumentException if the date is null IllegalArgumentException if the rangeStyle is invalid

iterator

public static Iterator iterator(Object focus, int rangeStyle)

This 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: focus the date to work with, either Date or Calendar rangeStyle the style constant to use. Must be one of the range styles listed for the DateUtils method.

Returns: the date iterator

Throws: IllegalArgumentException if the date is null ClassCastException if the object type is not a Date or Calendar

parseDate

public static Date parseDate(String str, String[] parsePatterns)

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 sucessful if it parses the whole of the input string. If no parse patterns match, a ParseException is thrown.

Parameters: str the date to parse, not null parsePatterns the date format patterns to use, see SimpleDateFormat, not null

Returns: the parsed date

Throws: IllegalArgumentException if the date string or pattern array is null ParseException if none of the date patterns were suitable

round

public static Date round(Date date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 timezone 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:

Parameters: date the date to work with field the field from Calendar or SEMI_MONTH

Returns: the rounded date

Throws: IllegalArgumentException if the date is null ArithmeticException if the year is over 280 million

round

public static Calendar round(Calendar date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 timezone 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:

Parameters: date the date to work with field the field from Calendar or SEMI_MONTH

Returns: the rounded date (a different object)

Throws: IllegalArgumentException if the date is null ArithmeticException if the year is over 280 million

round

public static Date round(Object date, int field)

Round this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 timezone 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:

Parameters: date the date to work with, either Date or Calendar field the field from Calendar or SEMI_MONTH

Returns: the rounded date

Throws: IllegalArgumentException if the date is null ClassCastException if the object type is not a Date or Calendar ArithmeticException if the year is over 280 million

truncate

public static Date truncate(Date date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 field the field from Calendar or SEMI_MONTH

Returns: the rounded date

Throws: IllegalArgumentException if the date is null ArithmeticException if the year is over 280 million

truncate

public static Calendar truncate(Calendar date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 field the field from Calendar or SEMI_MONTH

Returns: the rounded date (a different object)

Throws: IllegalArgumentException if the date is null ArithmeticException if the year is over 280 million

truncate

public static Date truncate(Object date, int field)

Truncate this date, leaving the field specified as the most significant field.

For example, if you had the datetime 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 field the field from Calendar or SEMI_MONTH

Returns: the rounded date

Throws: IllegalArgumentException if the date is null ClassCastException if the object type is not a Date or Calendar ArithmeticException if the year is over 280 million

Copyright © 2001-2005 - Apache Software Foundation