Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | 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 Object

A suite of utilities surrounding the use of the `Calendar` and `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 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 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 Date` | `add(Date date, int calendarField, int amount)` Adds to a date returning a new object.
`static Date` | `addDays(Date date, int amount)` Adds a number of days to a date returning a new object.
`static Date` | `addHours(Date date, int amount)` Adds a number of hours to a date returning a new object.
`static Date` | `addMilliseconds(Date date, int amount)` Adds a number of milliseconds to a date returning a new object.
`static Date` | `addMinutes(Date date, int amount)` Adds a number of minutes to a date returning a new object.
`static Date` | `addMonths(Date date, int amount)` Adds a number of months to a date returning a new object.
`static Date` | `addSeconds(Date date, int amount)` Adds a number of seconds to a date returning a new object.
`static Date` | `addWeeks(Date date, int amount)` Adds a number of weeks to a date returning a new object.
`static Date` | `addYears(Date date, int amount)` Adds a number of years to a date returning a new object.
`static boolean` | `isSameDay(Calendar cal1, Calendar cal2)` Checks if two calendar objects are on the same day ignoring time.
`static boolean` | `isSameDay(Date date1, Date date2)` Checks if two date objects are on the same day ignoring time.
`static boolean` | `isSameInstant(Calendar cal1, Calendar cal2)` Checks if two calendar objects represent the same instant in time.
`static boolean` | `isSameInstant(Date date1, Date date2)` Checks if two date objects represent the same instant in time.
`static boolean` | `isSameLocalTime(Calendar cal1, Calendar cal2)` Checks if two calendar objects represent the same local time.
`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.
`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.
`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.
`static Date` | `parseDate(String str, String[] parsePatterns)` Parses a string representing a date by trying a variety of different parsers.
`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_PER_SECOND

    public static final long MILLIS_PER_SECOND

  Number of milliseconds in a standard second.
  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_HOUR

    public static final long MILLIS_PER_HOUR

  Number of milliseconds in a standard hour.
  Since:
    2.1

### MILLIS_PER_DAY

    public static final long MILLIS_PER_DAY

  Number of milliseconds in a standard day.
  Since:
    2.1

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

### RANGE_WEEK_SUNDAY

    public static final int RANGE_WEEK_SUNDAY

  A week range, starting on Sunday.

### 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_CENTER

    public static final int RANGE_WEEK_CENTER

  A week range, centered around the day focused.

### RANGE_MONTH_SUNDAY

    public static final int RANGE_MONTH_SUNDAY

  A month range, the week starting on Sunday.

### RANGE_MONTH_MONDAY

    public static final int RANGE_MONTH_MONDAY

  A month range, the week starting on Monday.

### 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_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_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_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.

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

### parseDate

    public static Date parseDate(String str,
                                 String[] parsePatterns)
                          throws 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:
    `IllegalArgumentException` - if the date string or pattern array is null
    `ParseException` - if none of the date patterns were suitable

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

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

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

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

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

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

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

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

### 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:

  - 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:
    `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:

  - 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:
    `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:

  - 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:
    `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

### 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 `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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2005 - Apache Software Foundation