CDate (josef 3.2.5 API)

java.lang.Object
- org.josef.util.CDate

```
@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
public final class CDate
extends Object
```
Date utility class.
This class provides some basic date functionality and supports a hybrid calendar, just like GregorianCalendar. Dates on or after 1582/10/15 are supposed to be Gregorian and dates up to and including 1582/10/4 are supposed to be Julian.
Note:
- All months are 1 based instead of 0 based as in Sun's classes!
- Since months are often expressed as integers, most methods accept integer months.
- Note: This class was neither created to replace the GregorianCalendar nor the Date class.
Version:

1.1 $Revision: 5855 $

Author:

Kees Schotanus

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`CENTURY` A century is not a leap year in the Gregorian Calendar.
`static int`	`DAYS_IN_A_YEAR` Number of days in a (non leap) year.
`static int`	`FOUR_CENTURIES` Every fourth century is a leap year in the Gregorian Calendar.
`static int`	`FOUR_YEARS` Every fourth year is a leap year.
`static int`	`MAXIMUM_AGE_OF_A_PERSON` The maximum age a person could possibly reach.
`static int`	`MAXIMUM_YEAR` The last year for which this CDate will give valid results.
`static int`	`MINIMUM_YEAR` The first year for which this CDate will give valid results.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static Date`	`addDays(Calendar calendar, int numberOfDays)` Adds the supplied numberOfDays to the supplied calendar.
`static Date`	`addDays(Date date, int numberOfDays)` Adds the supplied numberOfDays to the supplied date.
`static GregorianCalendar`	`asGregorianCalendar(Date date)` Gets a GregorianCalendar from the supplied date.
`static void`	`clearTimeInfo(Calendar calendar)` Clears time information from the supplied calendar.
`static void`	`clearTimeInfo(Date date)` Clears time information from the supplied date.
`static GregorianCalendar`	`computeEasterSunday(int year)` For the supplied (Gregorian) year, this method calculates the date of Easter Sunday.
`static int`	`getCurrentYear()` Gets the current year.
`static int`	`getDayOfYear(int year, int month, int day)` Computes the ordinal day number within a year, for the supplied Gregorian date (in the form of a year, month and day).
`static int`	`getDifferenceInDays(Calendar startCalendar, Calendar endCalendar)` Computes the difference in days between the supplied calendars.
`static int`	`getDifferenceInDays(Date startDate, Date endDate)` Computes the difference in days between the supplied dates.
`static int`	`getDifferenceInMonths(Calendar startCalendar, Calendar endCalendar)` Computes the difference in whole months between the supplied calendars.
`static int`	`getDifferenceInMonths(Date startDate, Date endDate)` Computes the difference in whole months between the supplied dates.
`static int`	`getDifferenceInYears(Calendar startCalendar, Calendar endCalendar)` Computes the difference in whole years between the supplied calendars.
`static int`	`getDifferenceInYears(Date startDate, Date endDate)` Computes the difference in whole years between the supplied dates.
`static int`	`getDurationInYears(Calendar startCalendar, Calendar endCalendar)` Computes the duration in whole years between the supplied calendars.
`static int`	`getDurationInYears(Date startDate, Date endDate)` Computes the duration in whole years between the supplied dates.
`static int`	`getMaximumDayOfMonth(int year, int month)` Calculates the maximum ordinal day number for the supplied month.
`static int`	`getMaximumDayOfYear(int year)` Gets the maximum number of days in the supplied year.
`static int`	`getMinumumYearOfBirth()` Gets the minimum year in which a living person may be born.
`static Date`	`getTime()` Gets the current system time.
`static Date`	`getToday()` Gets the current date, without time information.
`static boolean`	`isLeapYear(int year)` Determines whether the supplied year is a leap year or not.
`static void`	`validate(int year, int month, int day)` Validates that the supplied date is an existing day.
`static void`	`validateMonth(int month)` Validates the supplied month.
`static void`	`validateYear(int year)` Validates the supplied year.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - MINIMUM_YEAR
```
public static final int MINIMUM_YEAR
```
    The first year for which this CDate will give valid results.
    Note: This is a year in the Julian Calendar but it is represented as a proleptic Gregorian date.
    
    See Also:
    
    Constant Field Values
  - MAXIMUM_YEAR
```
public static final int MAXIMUM_YEAR
```
    The last year for which this CDate will give valid results.
    Note: This is a year in the Gregorian Calendar.
    
    See Also:
    
    Constant Field Values
  - DAYS_IN_A_YEAR
```
public static final int DAYS_IN_A_YEAR
```
    Number of days in a (non leap) year.
    
    See Also:
    
    Constant Field Values
  - MAXIMUM_AGE_OF_A_PERSON
```
public static final int MAXIMUM_AGE_OF_A_PERSON
```
    The maximum age a person could possibly reach.
    
    See Also:
    
    Constant Field Values
  - FOUR_YEARS
```
public static final int FOUR_YEARS
```
    Every fourth year is a leap year.
    
    See Also:
    
    Constant Field Values
  - CENTURY
```
public static final int CENTURY
```
    A century is not a leap year in the Gregorian Calendar.
    
    See Also:
    
    Constant Field Values
  - FOUR_CENTURIES
```
public static final int FOUR_CENTURIES
```
    Every fourth century is a leap year in the Gregorian Calendar.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - validate
```
public static void validate(int year,
                            int month,
                            int day)
```
    Validates that the supplied date is an existing day.
    
    Parameters:
    
    year - Year number where: MINIMUM_YEAR <= year <= MAXIMUM_YEAR, with the exception of 0 since after 1 BC comes 1 AD.
    A date before the Gregorian cutover is supposed to be Julian, a date on or after the Gregorian cutover is supposed to be Gregorian.
    
    month - Ordinal month number where: 1 <= month <= 12.
    
    day - Ordinal day number where: 1 <= day <= max day for month.
    
    Throws:
    
    IllegalArgumentException - When one of the input parameters is out of range.
  - validateYear
```
public static void validateYear(int year)
```
    Validates the supplied year.
    A valid year is in the range: MINIMUM_YEAR <= year <= MAXIMUM_YEAR with the exception of 0 since after 1 BC comes 1 AD.
    
    Parameters:
    
    year - The year to validate.
    
    Throws:
    
    IllegalArgumentException - When the supplied year is 0 or not in range.
  - validateMonth
```
public static void validateMonth(int month)
```
    Validates the supplied month.
    A valid month is in the range: 1 <= month <= 12.
    
    Parameters:
    
    month - The month to validate.
    
    Throws:
    
    IllegalArgumentException - When the supplied month is not in range.
  - getDayOfYear
```
public static int getDayOfYear(int year,
                               int month,
                               int day)
```
    Computes the ordinal day number within a year, for the supplied Gregorian date (in the form of a year, month and day).
    
    Parameters:
    
    year - Gregorian year.
    -4712 <= year <= 9999. To be safe it is best to use a date after the year 1582.
    
    month - Ordinal month number. 1 <= month <= 12
    
    day - Ordinal day number. 1 <= day <= maximumDayForSuppliedMonth
    
    Returns:
    
    Ordinal day number in the range 1 <= day number <= 366.
    
    Throws:
    
    IllegalArgumentException - When one of the input parameters is out of range.
  - getMaximumDayOfMonth
```
public static int getMaximumDayOfMonth(int year,
                                       int month)
```
    Calculates the maximum ordinal day number for the supplied month.
    
    Parameters:
    
    year - The year.
    The year is necessary to calculate the maximum day for February. See: isLeapYear(int). A year before the Gregorian cutover is supposed to be a year from the Julian Calendar.
    
    month - Ordinal month number where: 1 <= month <= 12.
    
    Returns:
    
    Maximum day for the supplied month.
    
    Throws:
    
    IllegalArgumentException - When the supplied month is out of range.
  - getMaximumDayOfYear
```
public static int getMaximumDayOfYear(int year)
```
    Gets the maximum number of days in the supplied year.
    
    Parameters:
    
    year - The year to get the maximum number of days of.
    
    Returns:
    
    The maximum number of days in the supplied year.
    
    Throws:
    
    IllegalArgumentException - When the supplied year is out of range.
  - isLeapYear
```
public static boolean isLeapYear(int year)
```
    Determines whether the supplied year is a leap year or not. A year before the year of the Gregorian cutover is a leap year when it is divisible by 4. A year on or after the Gregorian cutover is a leap year when it is divisible 4 but not by 100 or when it is divisible by 400.
    
    Parameters:
    
    year - Year to check.
    
    Returns:
    
    True when the supplied year is a leap year, false otherwise.
  - getDifferenceInDays
```
public static int getDifferenceInDays(Date startDate,
                                      Date endDate)
```
    Computes the difference in days between the supplied dates.
    Note: This method ignores the time stamp of the supplied dates. For example: the difference between 1 March 2002 23:55:00 and 2 March 2002 00:05:00 is 1 day although the difference in time is only 10 minutes.
    
    Parameters:
    
    startDate - Start date.
    
    endDate - End date.
    
    Returns:
    
    The total number of days between the supplied startDate and endDate.
    The result will be negative when the supplied startDate is after the supplied endDate.
    
    Throws:
    
    NullPointerException - When either the supplied startDate or endDate is null.
  - getDifferenceInDays
```
public static int getDifferenceInDays(Calendar startCalendar,
                                      Calendar endCalendar)
```
    Computes the difference in days between the supplied calendars.
    Note: This method ignores the time stamp of the supplied calendars. For example: the difference between 1 March 2002 23:55:00 and 2 March 2002 00:05:00 is 1 day although the difference in time is only 10 minutes.
    
    Parameters:
    
    startCalendar - Start date.
    
    endCalendar - End date.
    
    Returns:
    
    The total number of days between the supplied startCalendar and endCalendar.
    The result will be negative when the supplied startCalendar is after the supplied endCalendar.
    
    Throws:
    
    NullPointerException - When either the supplied startCalendar or endCalendar is null.
  - getDifferenceInMonths
```
public static int getDifferenceInMonths(Date startDate,
                                        Date endDate)
```
    Computes the difference in whole months between the supplied dates.
    Note: the difference in months is determined by the month number and the year. Therefore, the difference in months between March 31st 2002 and April 1st 2003 is 13 months (1 year * 12 + 1 month).
    
    Parameters:
    
    startDate - Start date.
    
    endDate - End date.
    
    Returns:
    
    The total number of whole months between the supplied startDate and endDate.
    The result may be negative when the supplied startCalendar is after the supplied endCalendar.
    
    Throws:
    
    NullPointerException - When either the supplied startDate or endDate is null.
  - getDifferenceInMonths
```
public static int getDifferenceInMonths(Calendar startCalendar,
                                        Calendar endCalendar)
```
    Computes the difference in whole months between the supplied calendars.
    Note: the difference in months is determined by the month number and the year. Therefore, the difference in months between March 31st 2002 and April 1st 2003 is 13 months (1 year * 12 + 1 month).
    
    Parameters:
    
    startCalendar - The start date.
    
    endCalendar - The end date.
    
    Returns:
    
    The total number of months between the supplied startCalendar and endCalendar.
    The result may be negative when the supplied startCalendar is after the supplied endCalendar.
    
    Throws:
    
    NullPointerException - When either the supplied startCalendar or endCalendar is null.
  - getDifferenceInYears
```
public static int getDifferenceInYears(Date startDate,
                                       Date endDate)
```
    Computes the difference in whole years between the supplied dates.
    
    Parameters:
    
    startDate - Start date.
    
    endDate - End date.
    
    Returns:
    
    The total number of whole years between the supplied startDate and endDate.
    The result will be negative when the supplied startDate is after the supplied endDate.
    
    Throws:
    
    NullPointerException - When either the supplied startDate or endDate is null.
  - getDifferenceInYears
```
public static int getDifferenceInYears(Calendar startCalendar,
                                       Calendar endCalendar)
```
    Computes the difference in whole years between the supplied calendars.
    
    Parameters:
    
    startCalendar - Start date.
    
    endCalendar - End date.
    
    Returns:
    
    The total number of whole years between the supplied startCalendar and endCalendar.
    The result will be negative when the supplied startCalendar is after the supplied endCalendar.
    
    Throws:
    
    NullPointerException - When either the supplied startCalendar or endCalendar is null.
  - getDurationInYears
```
public static int getDurationInYears(Date startDate,
                                     Date endDate)
```
    Computes the duration in whole years between the supplied dates.
    
    Parameters:
    
    startDate - Start date.
    
    endDate - End date.
    
    Returns:
    
    The duration in whole years between the supplied dates.
    The result will be negative when the supplied startDate is after the supplied endDate.
    
    Throws:
    
    NullPointerException - When either the supplied startDate or endDate is null.
  - getDurationInYears
```
public static int getDurationInYears(Calendar startCalendar,
                                     Calendar endCalendar)
```
    Computes the duration in whole years between the supplied calendars.
    
    Parameters:
    
    startCalendar - Start date.
    
    endCalendar - End date.
    
    Returns:
    
    The duration in whole years between the supplied calendars.
    The result will be negative when the supplied startCalendar is after the supplied endCalendar.
    
    Throws:
    
    NullPointerException - When either the supplied startCalendar or endCalendar is null.
  - addDays
```
public static Date addDays(Date date,
                           int numberOfDays)
```
    Adds the supplied numberOfDays to the supplied date.
    
    Parameters:
    
    date - The start date.
    
    numberOfDays - The number of days to add to the supplied date.
    In case this number is negative, the supplied numberOfDays will be subtracted from the supplied date.
    
    Returns:
    
    A new date that is numberOfDays after the supplied date.
    
    Throws:
    
    NullPointerException - When the supplied date is null.
  - addDays
```
public static Date addDays(Calendar calendar,
                           int numberOfDays)
```
    Adds the supplied numberOfDays to the supplied calendar.
    This method does not modify the supplied calendar!
    
    Parameters:
    
    calendar - The start date.
    
    numberOfDays - The number of days to add to the supplied calendar.
    In case this number is negative, the supplied numberOfDays will be subtracted from the supplied calendar.
    
    Returns:
    
    A new date that is numberOfDays after the supplied calendar.
    
    Throws:
    
    NullPointerException - When the supplied calendar is null.
  - computeEasterSunday
```
public static GregorianCalendar computeEasterSunday(int year)
```
    For the supplied (Gregorian) year, this method calculates the date of Easter Sunday.
    The algorithm used is given by Jean Meeus/Jones and Butcher. For more information see: Meeus/Jones/Butcher Gregorian algorithm
    Some Christian holidays can be computed using Easter Sunday as a start. Ascension Day (Hemelvaartsdag) for example is the 40th day of Easter. To, compute this day, simply add 39 days the Easter Sunday. For White Sunday or pentecost (Pinksteren) simply add 49 days to Easter Sunday.
    
    Parameters:
    
    year - The Gregorian year.
    
    Returns:
    
    The date of Easter Sunday for the supplied year.
    
    Throws:
    
    IllegalArgumentException - When the supplied year is before 1582.
  - clearTimeInfo
```
public static void clearTimeInfo(Calendar calendar)
```
    Clears time information from the supplied calendar.
    
    Parameters:
    
    calendar - The calendar for which the time info must be cleared.
    
    Throws:
    
    NullPointerException - When the supplied calendar is null.
  - clearTimeInfo
```
public static void clearTimeInfo(Date date)
```
    Clears time information from the supplied date.
    To avoid usage of deprecated methods, this method uses a three step process:
    1. Convert the supplied date to a GregorianCalendar
    2. Clear time info from the GregorianCalendar by calling clearTimeInfo(Calendar)
    3. Setting the time from the cleared GregorianCalendar on the supplied date.
    Parameters:
    
    date - The date for which the time info must be cleared.
    
    Throws:
    
    NullPointerException - When the supplied date is null.
  - getCurrentYear
```
public static int getCurrentYear()
```
    Gets the current year.
    This method uses the current time in the default locale and time zone.
    
    Returns:
    
    The current year.
  - getToday
```
public static Date getToday()
```
    Gets the current date, without time information.
    
    Returns:
    
    The current date, without time information.
  - getTime
```
public static Date getTime()
```
    Gets the current system time.
    
    Returns:
    
    The current system time.
  - getMinumumYearOfBirth
```
public static int getMinumumYearOfBirth()
```
    Gets the minimum year in which a living person may be born.
    This method assumes that no person can be older than MAXIMUM_AGE_OF_A_PERSON.
    
    Returns:
    
    The minimum year in which a living person may be born.
  - asGregorianCalendar
```
public static GregorianCalendar asGregorianCalendar(Date date)
```
    Gets a GregorianCalendar from the supplied date.
    
    Parameters:
    
    date - The date to convert to a GregorianCalendar.
    
    Returns:
    
    The GregorianCalendar from the supplied date.
    
    Throws:
    
    NullPointerException - When the supplied date is null.

Class CDate

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MINIMUM_YEAR

MAXIMUM_YEAR

DAYS_IN_A_YEAR

MAXIMUM_AGE_OF_A_PERSON

FOUR_YEARS

CENTURY

FOUR_CENTURIES

Method Detail

validate

validateYear

validateMonth

getDayOfYear

getMaximumDayOfMonth

getMaximumDayOfYear

isLeapYear

getDifferenceInDays

getDifferenceInDays

getDifferenceInMonths

getDifferenceInMonths

getDifferenceInYears

getDifferenceInYears

getDurationInYears

getDurationInYears

addDays

addDays

computeEasterSunday

clearTimeInfo

clearTimeInfo

getCurrentYear

getToday

getTime

getMinumumYearOfBirth

asGregorianCalendar