org.apache.commons.lang.time
Class DateUtils

java.lang.Object
  org.apache.commons.lang.time.DateUtils

public class DateUtils

extends Object

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

Since:

2.0

Version:

$Id: DateUtils.java,v 1.16 2003/08/18 21:52:39 ggregory Exp $

Author:

Serge Knystautas, Stephen Colebourne, Janek Bogucki, Gary Gregory

Field Summary

static int	MILLIS_IN_DAY Number of milliseconds in a standard day.
static int	MILLIS_IN_HOUR Number of milliseconds in a standard hour.
static int	MILLIS_IN_MINUTE Number of milliseconds in a standard minute.
static int	MILLIS_IN_SECOND Number of milliseconds in a standard second.
static int	RANGE_MONTH_MONDAY A month range, the week starting on Monday.
static int	RANGE_MONTH_SUNDAY A month range, the week starting on Sunday.
static int	RANGE_WEEK_CENTER A week range, centered around the day focused.
static int	RANGE_WEEK_MONDAY A week range, starting on Monday.
static int	RANGE_WEEK_RELATIVE A week range, starting on the day focused.
static int	RANGE_WEEK_SUNDAY A week range, starting on Sunday.
static int	SEMI_MONTH This is half a month, so this represents whether a date is in the top or bottom half of the month.
static TimeZone	UTC_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 Iterator	iterator(Calendar focus, int rangeStyle) This constructs an Iterator that will start and stop over a date range based on the focused date and the range style.
static Iterator	iterator(Date focus, int rangeStyle) This constructs an Iterator that will start and stop over a date range based on the focused date and the range style.
static Iterator	iterator(Object focus, int rangeStyle) This constructs an Iterator that will start and stop over a date range based on the focused date and the range style.
static Calendar	round(Calendar date, int field) Round this date, leaving the field specified as the most significant field.
static Date	round(Date date, int field) Round this date, leaving the field specified as the most significant field.
static Date	round(Object date, int field) Round this date, leaving the field specified as the most significant field.
static Calendar	truncate(Calendar date, int field) Truncate this date, leaving the field specified as the most significant field.
static Date	truncate(Date date, int field) Truncate this date, leaving the field specified as the most significant field.
static Date	truncate(Object date, int field) Truncate this date, leaving the field specified as the most significant field.

Methods inherited from class java.lang.Object

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

Field Detail

UTC_TIME_ZONE

public static final TimeZone UTC_TIME_ZONE

The UTC time zone (often referred to as GMT).

MILLIS_IN_SECOND

public static final int MILLIS_IN_SECOND

Number of milliseconds in a standard second.

See Also:

Constant Field Values

MILLIS_IN_MINUTE

public static final int MILLIS_IN_MINUTE

Number of milliseconds in a standard minute.

See Also:

Constant Field Values

MILLIS_IN_HOUR

public static final int MILLIS_IN_HOUR

Number of milliseconds in a standard hour.

See Also:

Constant Field Values

MILLIS_IN_DAY

public static final int MILLIS_IN_DAY

Number of milliseconds in a standard day.

See Also:

Constant Field Values

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.

See Also:

Constant Field Values

RANGE_WEEK_SUNDAY

public static final int RANGE_WEEK_SUNDAY

A week range, starting on Sunday.

See Also:

Constant Field Values

RANGE_WEEK_MONDAY

public static final int RANGE_WEEK_MONDAY

A week range, starting on Monday.

See Also:

Constant Field Values

RANGE_WEEK_RELATIVE

public static final int RANGE_WEEK_RELATIVE

A week range, starting on the day focused.

See Also:

Constant Field Values

RANGE_WEEK_CENTER

public static final int RANGE_WEEK_CENTER

A week range, centered around the day focused.

See Also:

Constant Field Values

RANGE_MONTH_SUNDAY

public static final int RANGE_MONTH_SUNDAY

A month range, the week starting on Sunday.

See Also:

Constant Field Values

RANGE_MONTH_MONDAY

public static final int RANGE_MONTH_MONDAY

A month range, the week starting on Monday.

See Also:

Constant Field Values

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

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.

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

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.

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

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.

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

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

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

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

iterator

public static Iterator iterator(Date focus,
                                int rangeStyle)

This constructs an Iterator that will start and stop over a date range based on the focused date and the 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.

Parameters:

focus - the date to work with

rangeStyle - the style constant to use. Must be one of the range styles listed for the iterator(Calendar, int) method.

Returns:

the date iterator

Throws:

IllegalArgumentException - if the date is null or if the rangeStyle is not

iterator

public static Iterator iterator(Calendar focus,
                                int rangeStyle)

This constructs an Iterator that will start and stop over a date range based on the focused date and the 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.

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

iterator

public static Iterator iterator(Object focus,
                                int rangeStyle)

This constructs an Iterator that will start and stop over a date range based on the focused date and the 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.

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 iterator(Calendar, int) method.

Returns:

the date iterator

Throws:

IllegalArgumentException - if the date is null

ClassCastException - if the object type is not a Date or Calendar