fr.cnes.sirius.patrius.time

Class DateComponents

java.lang.Object

fr.cnes.sirius.patrius.time.DateComponents

All Implemented Interfaces:

Serializable, Comparable<DateComponents>

public class DateComponents
extends Object
implements Serializable, Comparable<DateComponents>

Class representing a date broken up as year, month and day components.

This class uses the astronomical convention for calendars, which is also the convention used by java.util.Date: a year zero is present between years -1 and +1, and 10 days are missing in 1582. The calendar used around these special dates are:

• up to 0000-12-31 : proleptic julian calendar
• from 0001-01-01 to 1582-10-04: julian calendar
• from 1582-10-15: gregorian calendar

Instances of this class are guaranteed to be immutable.

Author:

Luc Maisonobe

See Also:

TimeComponents, DateTimeComponents, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static DateComponents	CCSDS_EPOCH Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01.
static DateComponents	FIFTIES_EPOCH Reference epoch for 1950 dates: 1950-01-01.
static DateComponents	GALILEO_EPOCH Reference epoch for Galileo System Time: 1999-08-22.
static DateComponents	GPS_EPOCH Reference epoch for GPS weeks: 1980-01-06.
static DateComponents	J2000_EPOCH J2000.0 Reference epoch: 2000-01-01.
static DateComponents	JAVA_EPOCH Java Reference epoch: 1970-01-01.
static DateComponents	JULIAN_EPOCH Reference epoch for julian dates: -4712-01-01.
static DateComponents	MODIFIED_JULIAN_EPOCH Reference epoch for modified julian dates: 1858-11-17.

Constructor Summary

Constructors

Constructor and Description
DateComponents(DateComponents epoch, int offset) Build a date from its offset with respect to a reference epoch.
DateComponents(int offset) Build a date from its offset with respect to a J2000_EPOCH.
DateComponents(int yearIn, int dayNumber) Build a date from a year and day number.
DateComponents(int yearIn, int monthIn, int dayIn) Build a date from its components.
DateComponents(int yearIn, Month monthIn, int dayIn) Build a date from its components.

Method Summary

Methods

Modifier and Type	Method and Description
int	compareTo(DateComponents other)
static DateComponents	createFromWeekComponents(int wYear, int week, int dayOfWeek) Build a date from week components.
boolean	equals(Object other)
int	getCalendarWeek() Get the calendar week number.
int	getDay() Get the day.
int	getDayOfWeek() Get the day of week.
int	getDayOfYear() Get the day number in year.
int	getJ2000Day() Get the day number with respect to J2000 epoch.
int	getMJD() Get the modified julian day.
int	getMonth() Get the month.
Month	getMonthEnum() Get the month as an enumerate.
int	getYear() Get the year number.
int	hashCode()
static DateComponents	parseDate(String string) Parse a string in ISO-8601 format to build a date.
String	toString() Get a string representation (ISO-8601) of the date.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

JULIAN_EPOCH

public static final DateComponents JULIAN_EPOCH

Reference epoch for julian dates: -4712-01-01.

Both java.util.Date and DateComponents classes follow the astronomical conventions and consider a year 0 between years -1 and +1, hence this reference date lies in year -4712 and not in year -4713 as can be seen in other documents or programs that obey a different convention (for example the convcal utility).

MODIFIED_JULIAN_EPOCH

public static final DateComponents MODIFIED_JULIAN_EPOCH

Reference epoch for modified julian dates: 1858-11-17.

FIFTIES_EPOCH

public static final DateComponents FIFTIES_EPOCH

Reference epoch for 1950 dates: 1950-01-01.

CCSDS_EPOCH

public static final DateComponents CCSDS_EPOCH

Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4): 1958-01-01.

GALILEO_EPOCH

public static final DateComponents GALILEO_EPOCH

Reference epoch for Galileo System Time: 1999-08-22.

GPS_EPOCH

public static final DateComponents GPS_EPOCH

Reference epoch for GPS weeks: 1980-01-06.

J2000_EPOCH

public static final DateComponents J2000_EPOCH

J2000.0 Reference epoch: 2000-01-01.

JAVA_EPOCH

public static final DateComponents JAVA_EPOCH

Java Reference epoch: 1970-01-01.

Constructor Detail

DateComponents

public DateComponents(int yearIn,
              int monthIn,
              int dayIn)

Build a date from its components.

Parameters:

yearIn - year number (may be 0 or negative for BC years)

monthIn - month number from 1 to 12

dayIn - day number from 1 to 31

Throws:

IllegalArgumentException - if inconsistent arguments are given (parameters out of range, february 29 for non-leap years, dates during the gregorian leap in 1582 ...)

DateComponents

public DateComponents(int yearIn,
              Month monthIn,
              int dayIn)

Build a date from its components.

Parameters:

yearIn - year number (may be 0 or negative for BC years)

monthIn - month enumerate

dayIn - day number from 1 to 31

Throws:

IllegalArgumentException - if inconsistent arguments are given (parameters out of range, february 29 for non-leap years, dates during the gregorian leap in 1582 ...)

DateComponents

public DateComponents(int yearIn,
              int dayNumber)

Build a date from a year and day number.

Parameters:

yearIn - year number (may be 0 or negative for BC years)

dayNumber - day number in the year from 1 to 366

Throws:

IllegalArgumentException - if dayNumber is out of range with respect to year

DateComponents

public DateComponents(int offset)

Build a date from its offset with respect to a J2000_EPOCH.

Parameters:

offset - offset with respect to a J2000_EPOCH

See Also:

getJ2000Day()

DateComponents

public DateComponents(DateComponents epoch,
              int offset)

Build a date from its offset with respect to a reference epoch.

This constructor is mainly useful to build a date from a modified julian day (using MODIFIED_JULIAN_EPOCH) or a GPS week number (using GPS_EPOCH).

Parameters:

epoch - reference epoch

offset - offset with respect to a reference epoch

See Also:

DateComponents(int), getMJD()

Method Detail

createFromWeekComponents

public static DateComponents createFromWeekComponents(int wYear,
                                      int week,
                                      int dayOfWeek)

Build a date from week components.

The calendar week number is a number between 1 and 52 or 53 depending on the year. Week 1 is defined by ISO as the one that includes the first Thursday of a year. Week 1 may therefore start the previous year and week 52 or 53 may end in the next year. As an example calendar date 1995-01-01 corresponds to week date 1994-W52-7 (i.e. Sunday in the last week of 1994 is in fact the first day of year 1995). This date would beAnother example is calendar date 1996-12-31 which corresponds to week date 1997-W01-2 (i.e. Tuesday in the first week of 1997 is in fact the last day of year 1996).

Parameters:

wYear - year associated to week numbering

week - week number in year,from 1 to 52 or 53

dayOfWeek - day of week, from 1 (Monday) to 7 (Sunday)

Returns:

a builded date

Throws:

IllegalArgumentException - if inconsistent arguments are given (parameters out of range, week 53 on a 52 weeks year ...)

parseDate

public static DateComponents parseDate(String string)

Parse a string in ISO-8601 format to build a date.

The supported formats are:

• basic format calendar date: YYYYMMDD
• extended format calendar date: YYYY-MM-DD
• basic format ordinal date: YYYYDDD
• extended format ordinal date: YYYY-DDD
• basic format week date: YYYYWwwD
• extended format week date: YYYY-Www-D

As shown by the list above, only the complete representations defined in section 4.1 of ISO-8601 standard are supported, neither expended representations nor representations with reduced accuracy are supported.

Parsing a single integer as a julian day is not supported as it may be ambiguous with either the basic format calendar date or the basic format ordinal date depending on the number of digits.

Parameters:

string - string to parse

Returns:

a parsed date

Throws:

IllegalArgumentException - if string cannot be parsed

getYear

public int getYear()

Get the year number.

Returns:

year number (may be 0 or negative for BC years)

getMonth

public int getMonth()

Get the month.

Returns:

month number from 1 to 12

getMonthEnum

public Month getMonthEnum()

Get the month as an enumerate.

Returns:

month as an enumerate

getDay

public int getDay()

Get the day.

Returns:

day number from 1 to 31

getJ2000Day

public int getJ2000Day()

Get the day number with respect to J2000 epoch.

Returns:

day number with respect to J2000 epoch

getMJD

public int getMJD()

Get the modified julian day.

Returns:

modified julian day

getCalendarWeek

public int getCalendarWeek()

Get the calendar week number.

The calendar week number is a number between 1 and 52 or 53 depending on the year. Week 1 is defined by ISO as the one that includes the first Thursday of a year. Week 1 may therefore start the previous year and week 52 or 53 may end in the next year. As an example calendar date 1995-01-01 corresponds to week date 1994-W52-7 (i.e. Sunday in the last week of 1994 is in fact the first day of year 1995). Another example is calendar date 1996-12-31 which corresponds to week date 1997-W01-2 (i.e. Tuesday in the first week of 1997 is in fact the last day of year 1996).

Returns:

calendar week number

getDayOfWeek

public int getDayOfWeek()

Get the day of week.

Day of week is a number between 1 (Monday) and 7 (Sunday).

Returns:

day of week

getDayOfYear

public int getDayOfYear()

Get the day number in year.

Day number in year is between 1 (January 1st) and either 365 or 366 inclusive depending on year.

Returns:

day number in year

toString

public String toString()

Get a string representation (ISO-8601) of the date.

Overrides:

toString in class Object

Returns:

string representation of the date.

compareTo

public int compareTo(DateComponents other)

Specified by:

compareTo in interface Comparable<DateComponents>

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object