DateUtils (Commons Lang 2.4 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.lang.time
Class DateUtils

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

public class DateUtils
extends java.lang.Object

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

DateUtils contains a lot of common methods considering manipulations of Dates or Calendars. Some methods require some extra explanation. The truncate 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.

Since:: 2.0
Version:: $Id: DateUtils.java 634096 2008-03-06 00:58:11Z niallp $
Author:: Serge Knystautas, Stephen Colebourne, Janek Bogucki, Gary Gregory, Phil Steitz, Robert Scholte

Field Summary
`static int`	`MILLIS_IN_DAY` Deprecated. Use MILLIS_PER_DAY. This will be removed in Commons Lang 3.0.
`static int`	`MILLIS_IN_HOUR` Deprecated. Use MILLIS_PER_HOUR. This will be removed in Commons Lang 3.0.
`static int`	`MILLIS_IN_MINUTE` Deprecated. Use MILLIS_PER_MINUTE. This will be removed in Commons Lang 3.0.
`static int`	`MILLIS_IN_SECOND` Deprecated. Use MILLIS_PER_SECOND. This will be removed in Commons Lang 3.0.
`static long`	`MILLIS_PER_DAY` Number of milliseconds in a standard day.
`static long`	`MILLIS_PER_HOUR` Number of milliseconds in a standard hour.
`static long`	`MILLIS_PER_MINUTE` Number of milliseconds in a standard minute.
`static long`	`MILLIS_PER_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 java.util.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 java.util.Date`	`add(java.util.Date date, int calendarField, int amount)` Deprecated. Will become privately scoped in 3.0
`static java.util.Date`	`addDays(java.util.Date date, int amount)` Adds a number of days to a date returning a new object.
`static java.util.Date`	`addHours(java.util.Date date, int amount)` Adds a number of hours to a date returning a new object.
`static java.util.Date`	`addMilliseconds(java.util.Date date, int amount)` Adds a number of milliseconds to a date returning a new object.
`static java.util.Date`	`addMinutes(java.util.Date date, int amount)` Adds a number of minutes to a date returning a new object.
`static java.util.Date`	`addMonths(java.util.Date date, int amount)` Adds a number of months to a date returning a new object.
`static java.util.Date`	`addSeconds(java.util.Date date, int amount)` Adds a number of seconds to a date returning a new object.
`static java.util.Date`	`addWeeks(java.util.Date date, int amount)` Adds a number of weeks to a date returning a new object.
`static java.util.Date`	`addYears(java.util.Date date, int amount)` Adds a number of years to a date returning a new object.
`static long`	`getFragmentInDays(java.util.Calendar calendar, int fragment)` Returns the number of days within the fragment.
`static long`	`getFragmentInDays(java.util.Date date, int fragment)` Returns the number of days within the fragment.
`static long`	`getFragmentInHours(java.util.Calendar calendar, int fragment)` Returns the number of hours within the fragment.
`static long`	`getFragmentInHours(java.util.Date date, int fragment)` Returns the number of hours within the fragment.
`static long`	`getFragmentInMilliseconds(java.util.Calendar calendar, int fragment)` Returns the number of milliseconds within the fragment.
`static long`	`getFragmentInMilliseconds(java.util.Date date, int fragment)` Returns the number of milliseconds within the fragment.
`static long`	`getFragmentInMinutes(java.util.Calendar calendar, int fragment)` Returns the number of minutes within the fragment.
`static long`	`getFragmentInMinutes(java.util.Date date, int fragment)` Returns the number of minutes within the fragment.
`static long`	`getFragmentInSeconds(java.util.Calendar calendar, int fragment)` Returns the number of seconds within the fragment.
`static long`	`getFragmentInSeconds(java.util.Date date, int fragment)` Returns the number of seconds within the fragment.
`static boolean`	`isSameDay(java.util.Calendar cal1, java.util.Calendar cal2)` Checks if two calendar objects are on the same day ignoring time.
`static boolean`	`isSameDay(java.util.Date date1, java.util.Date date2)` Checks if two date objects are on the same day ignoring time.
`static boolean`	`isSameInstant(java.util.Calendar cal1, java.util.Calendar cal2)` Checks if two calendar objects represent the same instant in time.
`static boolean`	`isSameInstant(java.util.Date date1, java.util.Date date2)` Checks if two date objects represent the same instant in time.
`static boolean`	`isSameLocalTime(java.util.Calendar cal1, java.util.Calendar cal2)` Checks if two calendar objects represent the same local time.
`static java.util.Iterator`	`iterator(java.util.Calendar focus, int rangeStyle)` This constructs an `Iterator` over each day in a date range defined by a focus date and range style.
`static java.util.Iterator`	`iterator(java.util.Date focus, int rangeStyle)` This constructs an `Iterator` over each day in a date range defined by a focus date and range style.
`static java.util.Iterator`	`iterator(java.lang.Object focus, int rangeStyle)` This constructs an `Iterator` over each day in a date range defined by a focus date and range style.
`static java.util.Date`	`parseDate(java.lang.String str, java.lang.String[] parsePatterns)` Parses a string representing a date by trying a variety of different parsers.
`static java.util.Calendar`	`round(java.util.Calendar date, int field)` Round this date, leaving the field specified as the most significant field.
`static java.util.Date`	`round(java.util.Date date, int field)` Round this date, leaving the field specified as the most significant field.
`static java.util.Date`	`round(java.lang.Object date, int field)` Round this date, leaving the field specified as the most significant field.
`static java.util.Date`	`setDays(java.util.Date date, int amount)` Sets the day of month field to a date returning a new object.
`static java.util.Date`	`setHours(java.util.Date date, int amount)` Sets the hours field to a date returning a new object.
`static java.util.Date`	`setMilliseconds(java.util.Date date, int amount)` Sets the miliseconds field to a date returning a new object.
`static java.util.Date`	`setMinutes(java.util.Date date, int amount)` Sets the minute field to a date returning a new object.
`static java.util.Date`	`setMonths(java.util.Date date, int amount)` Sets the months field to a date returning a new object.
`static java.util.Date`	`setSeconds(java.util.Date date, int amount)` Sets the seconds field to a date returning a new object.
`static java.util.Date`	`setYears(java.util.Date date, int amount)` Sets the years field to a date returning a new object.
`static java.util.Calendar`	`truncate(java.util.Calendar date, int field)` Truncate this date, leaving the field specified as the most significant field.
`static java.util.Date`	`truncate(java.util.Date date, int field)` Truncate this date, leaving the field specified as the most significant field.
`static java.util.Date`	`truncate(java.lang.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 java.util.TimeZone UTC_TIME_ZONE

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

MILLIS_PER_SECOND

public static final long MILLIS_PER_SECOND

Number of milliseconds in a standard second.

Since:: 2.1
See Also:: Constant Field Values

MILLIS_PER_MINUTE

public static final long MILLIS_PER_MINUTE

Number of milliseconds in a standard minute.

Since:: 2.1
See Also:: Constant Field Values

MILLIS_PER_HOUR

public static final long MILLIS_PER_HOUR

Number of milliseconds in a standard hour.

Since:: 2.1
See Also:: Constant Field Values

MILLIS_PER_DAY

public static final long MILLIS_PER_DAY

Number of milliseconds in a standard day.

Since:: 2.1
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

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.

See Also:: Constant Field Values

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.

See Also:: Constant Field Values

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.

See Also:: Constant Field Values

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.

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

isSameDay

public static boolean isSameDay(java.util.Date date1,
                                java.util.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:: java.lang.IllegalArgumentException - if either date is null
Since:: 2.1

isSameDay

public static boolean isSameDay(java.util.Calendar cal1,
                                java.util.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:: java.lang.IllegalArgumentException - if either calendar is null
Since:: 2.1

isSameInstant

public static boolean isSameInstant(java.util.Date date1,
                                    java.util.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:: java.lang.IllegalArgumentException - if either date is null
Since:: 2.1

isSameInstant

public static boolean isSameInstant(java.util.Calendar cal1,
                                    java.util.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:: java.lang.IllegalArgumentException - if either date is null
Since:: 2.1

isSameLocalTime

public static boolean isSameLocalTime(java.util.Calendar cal1,
                                      java.util.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:: java.lang.IllegalArgumentException - if either date is null
Since:: 2.1

parseDate

public static java.util.Date parseDate(java.lang.String str,
                                       java.lang.String[] parsePatterns)
                                throws java.text.ParseException

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

The parse will try each parse pattern in turn. A parse is only deemed 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:: java.lang.IllegalArgumentException - if the date string or pattern array is null; java.text.ParseException - if none of the date patterns were suitable

addYears

public static java.util.Date addYears(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addMonths

public static java.util.Date addMonths(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addWeeks

public static java.util.Date addWeeks(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addDays

public static java.util.Date addDays(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addHours

public static java.util.Date addHours(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addMinutes

public static java.util.Date addMinutes(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addSeconds

public static java.util.Date addSeconds(java.util.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:: java.lang.IllegalArgumentException - if the date is null

addMilliseconds

public static java.util.Date addMilliseconds(java.util.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:: java.lang.IllegalArgumentException - if the date is null

add

public static java.util.Date add(java.util.Date date,
                                 int calendarField,
                                 int amount)

Deprecated. Will become privately scoped in 3.0

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:: java.lang.IllegalArgumentException - if the date is null

setYears

public static java.util.Date setYears(java.util.Date date,
                                      int amount)

Sets the years field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setMonths

public static java.util.Date setMonths(java.util.Date date,
                                       int amount)

Sets the months field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setDays

public static java.util.Date setDays(java.util.Date date,
                                     int amount)

Sets the day of month field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setHours

public static java.util.Date setHours(java.util.Date date,
                                      int amount)

Sets the hours field to a date returning a new object. Hours range from 0-23. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setMinutes

public static java.util.Date setMinutes(java.util.Date date,
                                        int amount)

Sets the minute field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setSeconds

public static java.util.Date setSeconds(java.util.Date date,
                                        int amount)

Sets the seconds field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

setMilliseconds

public static java.util.Date setMilliseconds(java.util.Date date,
                                             int amount)

Sets the miliseconds field to a date returning a new object. The original date object is unchanged.

Parameters:: date - the date, not null; amount - the amount to set
Returns:: a new Date object set with the specified value
Throws:: java.lang.IllegalArgumentException - if the date is null
Since:: 2.4

round

public static java.util.Date round(java.util.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:

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; field - the field from Calendar or SEMI_MONTH
Returns:: the rounded date
Throws:: java.lang.IllegalArgumentException - if the date is null; java.lang.ArithmeticException - if the year is over 280 million

round

public static java.util.Calendar round(java.util.Calendar date,
                                       int field)

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

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; field - the field from Calendar or SEMI_MONTH
Returns:: the rounded date (a different object)
Throws:: java.lang.IllegalArgumentException - if the date is null; java.lang.ArithmeticException - if the year is over 280 million

round

public static java.util.Date round(java.lang.Object date,
                                   int field)

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

March 30, 2003 01:10 rounds to March 30, 2003 01:00
March 30, 2003 01:40 rounds to March 30, 2003 03:00
March 30, 2003 02:10 rounds to March 30, 2003 03:00
March 30, 2003 02:40 rounds to March 30, 2003 04:00

Parameters:: date - the date to work with, either Date or Calendar; field - the field from Calendar or SEMI_MONTH
Returns:: the rounded date
Throws:: java.lang.IllegalArgumentException - if the date is null; java.lang.ClassCastException - if the object type is not a Date or Calendar; java.lang.ArithmeticException - if the year is over 280 million

truncate

public static java.util.Date truncate(java.util.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:: java.lang.IllegalArgumentException - if the date is null; java.lang.ArithmeticException - if the year is over 280 million

truncate

public static java.util.Calendar truncate(java.util.Calendar date,
                                          int field)

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

Parameters:: date - the date to work with; field - the field from Calendar or SEMI_MONTH
Returns:: the rounded date (a different object)
Throws:: java.lang.IllegalArgumentException - if the date is null; java.lang.ArithmeticException - if the year is over 280 million

truncate

public static java.util.Date truncate(java.lang.Object date,
                                      int field)

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

Parameters:: date - the date to work with, either Date or Calendar; field - the field from Calendar or SEMI_MONTH
Returns:: the rounded date
Throws:: java.lang.IllegalArgumentException - if the date is null; java.lang.ClassCastException - if the object type is not a Date or Calendar; java.lang.ArithmeticException - if the year is over 280 million

iterator

public static java.util.Iterator iterator(java.util.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:: java.lang.IllegalArgumentException - if the date is null; java.lang.IllegalArgumentException - if the rangeStyle is invalid

iterator

public static java.util.Iterator iterator(java.util.Calendar focus,
                                          int rangeStyle)

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

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:: java.lang.IllegalArgumentException - if the date is null; java.lang.IllegalArgumentException - if the rangeStyle is invalid

iterator

public static java.util.Iterator iterator(java.lang.Object focus,
                                          int rangeStyle)

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

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:: java.lang.IllegalArgumentException - if the date is null; java.lang.ClassCastException - if the object type is not a Date or Calendar

getFragmentInMilliseconds

public static long getFragmentInMilliseconds(java.util.Date date,
                                             int fragment)

Returns the number of milliseconds within the fragment. All datefields greater than the fragment will be ignored.

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

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

January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538
January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538 (10*1000 + 538)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in milliseconds)

Parameters:: date - the date to work with, not null; fragment - the Calendar field part of date to calculate
Returns:: number of milliseconds within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInSeconds

public static long getFragmentInSeconds(java.util.Date date,
                                        int fragment)

Returns the number of seconds within the fragment. All datefields 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).

January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to deprecated date.getSeconds())
January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to deprecated date.getSeconds())
January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110 (7*3600 + 15*60 + 10)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in seconds)

Parameters:: date - the date to work with, not null; fragment - the Calendar field part of date to calculate
Returns:: number of seconds within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInMinutes

public static long getFragmentInMinutes(java.util.Date date,
                                        int fragment)

Returns the number of minutes within the fragment. All datefields 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).

January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to deprecated date.getMinutes())
January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to deprecated date.getMinutes())
January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15
January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in minutes)

Parameters:: date - the date to work with, not null; fragment - the Calendar field part of date to calculate
Returns:: number of minutes within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInHours

public static long getFragmentInHours(java.util.Date date,
                                      int fragment)

Returns the number of hours within the fragment. All datefields 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).

January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to deprecated date.getHours())
January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to deprecated date.getHours())
January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7
January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in hours)

Parameters:: date - the date to work with, not null; fragment - the Calendar field part of date to calculate
Returns:: number of hours within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInDays

public static long getFragmentInDays(java.util.Date date,
                                     int fragment)

Returns the number of days within the fragment. All datefields greater than the fragment will be ignored.

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

January 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to deprecated date.getDay())
February 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to deprecated date.getDay())
January 28, 2008 with Calendar.YEAR as fragment will return 28
February 28, 2008 with Calendar.YEAR as fragment will return 59
January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in days)

Parameters:: date - the date to work with, not null; fragment - the Calendar field part of date to calculate
Returns:: number of days within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInMilliseconds

public static long getFragmentInMilliseconds(java.util.Calendar calendar,
                                             int fragment)

Returns the number of milliseconds within the fragment. All datefields 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).

January 1, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538 (equivalent to calendar.get(Calendar.MILLISECOND))
January 6, 2008 7:15:10.538 with Calendar.SECOND as fragment will return 538 (equivalent to calendar.get(Calendar.MILLISECOND))
January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10538 (10*1000 + 538)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in milliseconds)

Parameters:: calendar - the calendar to work with, not null; fragment - the Calendar field part of calendar to calculate
Returns:: number of milliseconds within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInSeconds

public static long getFragmentInSeconds(java.util.Calendar calendar,
                                        int fragment)

Returns the number of seconds within the fragment. All datefields greater than the fragment will be ignored.

January 1, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to calendar.get(Calendar.SECOND))
January 6, 2008 7:15:10.538 with Calendar.MINUTE as fragment will return 10 (equivalent to calendar.get(Calendar.SECOND))
January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 26110 (7*3600 + 15*60 + 10)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in seconds)

Parameters:: calendar - the calendar to work with, not null; fragment - the Calendar field part of calendar to calculate
Returns:: number of seconds within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInMinutes

public static long getFragmentInMinutes(java.util.Calendar calendar,
                                        int fragment)

Returns the number of minutes within the fragment. All datefields greater than the fragment will be ignored.

January 1, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to calendar.get(Calendar.MINUTES))
January 6, 2008 7:15:10.538 with Calendar.HOUR_OF_DAY as fragment will return 15 (equivalent to calendar.get(Calendar.MINUTES))
January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 15
January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 435 (7*60 + 15)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in minutes)

Parameters:: calendar - the calendar to work with, not null; fragment - the Calendar field part of calendar to calculate
Returns:: number of minutes within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInHours

public static long getFragmentInHours(java.util.Calendar calendar,
                                      int fragment)

Returns the number of hours within the fragment. All datefields greater than the fragment will be ignored.

January 1, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to calendar.get(Calendar.HOUR_OF_DAY))
January 6, 2008 7:15:10.538 with Calendar.DAY_OF_YEAR as fragment will return 7 (equivalent to calendar.get(Calendar.HOUR_OF_DAY))
January 1, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 7
January 6, 2008 7:15:10.538 with Calendar.MONTH as fragment will return 127 (5*24 + 7)
January 16, 2008 7:15:10.538 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in hours)

Parameters:: calendar - the calendar to work with, not null; fragment - the Calendar field part of calendar to calculate
Returns:: number of hours within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

getFragmentInDays

public static long getFragmentInDays(java.util.Calendar calendar,
                                     int fragment)

Returns the number of days within the fragment. All datefields greater than the fragment will be ignored.

January 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_MONTH))
February 28, 2008 with Calendar.MONTH as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_MONTH))
January 28, 2008 with Calendar.YEAR as fragment will return 28 (equivalent to calendar.get(Calendar.DAY_OF_YEAR))
February 28, 2008 with Calendar.YEAR as fragment will return 59 (equivalent to calendar.get(Calendar.DAY_OF_YEAR))
January 28, 2008 with Calendar.MILLISECOND as fragment will return 0 (a millisecond cannot be split in days)

Parameters:: calendar - the calendar to work with, not null; fragment - the Calendar field part of calendar to calculate
Returns:: number of days within the fragment of date
Throws:: java.lang.IllegalArgumentException - if the date is null or fragment is not supported
Since:: 2.4

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.lang.time Class DateUtils

UTC_TIME_ZONE

MILLIS_PER_SECOND

MILLIS_PER_MINUTE

MILLIS_PER_HOUR

MILLIS_PER_DAY

SEMI_MONTH

RANGE_WEEK_SUNDAY

RANGE_WEEK_MONDAY

RANGE_WEEK_RELATIVE

RANGE_WEEK_CENTER

RANGE_MONTH_SUNDAY

RANGE_MONTH_MONDAY

MILLIS_IN_SECOND

MILLIS_IN_MINUTE

MILLIS_IN_HOUR

MILLIS_IN_DAY

DateUtils

isSameDay

isSameDay

isSameInstant

isSameInstant

isSameLocalTime

parseDate

addYears

addMonths

addWeeks

addDays

addHours

addMinutes

addSeconds

addMilliseconds

add

setYears

setMonths

setDays

setHours

setMinutes

setSeconds

setMilliseconds

round

round

round

truncate

truncate

truncate

iterator

iterator

iterator

getFragmentInMilliseconds

getFragmentInSeconds

getFragmentInMinutes

getFragmentInHours

getFragmentInDays

getFragmentInMilliseconds

getFragmentInSeconds

getFragmentInMinutes

getFragmentInHours

getFragmentInDays

org.apache.commons.lang.time
Class DateUtils