Package org.orekit.time

Class DateTimeComponents

java.lang.Object

org.orekit.time.DateTimeComponents

All Implemented Interfaces:

Serializable, Comparable<DateTimeComponents>

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

Holder for date and time components.

This class is a simple holder with no processing methods.

Instance of this class are guaranteed to be immutable.

Author:

Luc Maisonobe

See Also:

AbsoluteDate, DateComponents, TimeComponents, Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static DateTimeComponents	JULIAN_EPOCH	The Julian Epoch.

Constructor Summary

Constructors

Constructor	Description
DateTimeComponents(int year, int month, int day)	Build an instance from raw level components.
DateTimeComponents(int year, int month, int day, int hour, int minute, double second)	Build an instance from raw level components.
DateTimeComponents(int year, Month month, int day)	Build an instance from raw level components.
DateTimeComponents(int year, Month month, int day, int hour, int minute, double second)	Build an instance from raw level components.
DateTimeComponents(DateComponents date, TimeComponents time)	Build a new instance from its components.
DateTimeComponents(DateTimeComponents reference, double offset)	Build an instance from a seconds offset with respect to another one.
DateTimeComponents(DateTimeComponents reference, long offset, TimeUnit timeUnit)	Build an instance from a seconds offset with respect to another one.

Method Summary

Modifier and Type	Method	Description
int	compareTo(DateTimeComponents other)
boolean	equals(Object other)
DateComponents	getDate()	Get the date component.
TimeComponents	getTime()	Get the time component.
int	hashCode()
double	offsetFrom(DateTimeComponents dateTime)	Compute the seconds offset between two instances.
long	offsetFrom(DateTimeComponents dateTime, TimeUnit timeUnit)	Compute the seconds offset between two instances.
static DateTimeComponents	parseDateTime(String string)	Parse a string in ISO-8601 format to build a date/time.
DateTimeComponents	roundIfNeeded(int minuteDuration, int fractionDigits)	Round this date-time to the given precision if needed to prevent rounding up to an invalid seconds number.
String	toString()	Return a string representation of this pair.
String	toString(int minuteDuration)	Return a string representation of this date-time, rounded to millisecond precision.
String	toString(int minuteDuration, int fractionDigits)	Return a string representation of this date-time, rounded to the given precision.
String	toStringRfc3339()	Represent the given date and time as a string according to the format in RFC 3339.
String	toStringWithoutUtcOffset()	Get a string representation of the date-time without the offset from UTC.
String	toStringWithoutUtcOffset(int minuteDuration, int fractionDigits)	Return a string representation of this date-time, rounded to the given precision.

Methods inherited from class java.lang.Object

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

Field Detail

JULIAN_EPOCH

public static final DateTimeComponents JULIAN_EPOCH

The Julian Epoch.

See Also:

TimeScales.getJulianEpoch()

Constructor Detail

DateTimeComponents

public DateTimeComponents(DateComponents date,
                          TimeComponents time)

Build a new instance from its components.

Parameters:

date - date component

time - time component

DateTimeComponents

public DateTimeComponents(int year,
                          int month,
                          int day,
                          int hour,
                          int minute,
                          double second)
                   throws IllegalArgumentException

Build an instance from raw level components.

Parameters:

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

month - month number from 1 to 12

day - day number from 1 to 31

hour - hour number from 0 to 23

minute - minute number from 0 to 59

second - second number from 0.0 to 60.0 (excluded)

Throws:

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

DateTimeComponents

public DateTimeComponents(int year,
                          Month month,
                          int day,
                          int hour,
                          int minute,
                          double second)
                   throws IllegalArgumentException

Build an instance from raw level components.

Parameters:

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

month - month enumerate

day - day number from 1 to 31

hour - hour number from 0 to 23

minute - minute number from 0 to 59

second - second number from 0.0 to 60.0 (excluded)

Throws:

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

DateTimeComponents

public DateTimeComponents(int year,
                          int month,
                          int day)
                   throws IllegalArgumentException

Build an instance from raw level components.

The hour is set to 00:00:00.000.

Parameters:

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

month - month number from 1 to 12

day - 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 ...)

DateTimeComponents

public DateTimeComponents(int year,
                          Month month,
                          int day)
                   throws IllegalArgumentException

Build an instance from raw level components.

The hour is set to 00:00:00.000.

Parameters:

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

month - month enumerate

day - 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 ...)

DateTimeComponents

public DateTimeComponents(DateTimeComponents reference,
                          double offset)

Build an instance from a seconds offset with respect to another one.

Parameters:

reference - reference date/time

offset - offset from the reference in seconds

See Also:

offsetFrom(DateTimeComponents)

DateTimeComponents

public DateTimeComponents(DateTimeComponents reference,
                          long offset,
                          TimeUnit timeUnit)

Build an instance from a seconds offset with respect to another one.

Parameters:

reference - reference date/time

offset - offset from the reference

timeUnit - the TimeUnit for the offset

Since:

12.1

See Also:

offsetFrom(DateTimeComponents, TimeUnit)

Method Detail

parseDateTime

public static DateTimeComponents parseDateTime(String string)

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

The supported formats are all date formats supported by DateComponents.parseDate(String) and all time formats supported by TimeComponents.parseTime(String) separated by the standard time separator 'T', or date components only (in which case a 00:00:00 hour is implied). Typical examples are 2000-01-01T12:00:00Z or 1976W186T210000.

Parameters:

string - string to parse

Returns:

a parsed date/time

Throws:

IllegalArgumentException - if string cannot be parsed

offsetFrom

public double offsetFrom(DateTimeComponents dateTime)

Compute the seconds offset between two instances.

Parameters:

dateTime - dateTime to subtract from the instance

Returns:

offset in seconds between the two instants (positive if the instance is posterior to the argument)

See Also:

DateTimeComponents(DateTimeComponents, double)

offsetFrom

public long offsetFrom(DateTimeComponents dateTime,
                       TimeUnit timeUnit)

Compute the seconds offset between two instances.

Parameters:

dateTime - dateTime to subtract from the instance

timeUnit - the desired TimeUnit

Returns:

offset in the given timeunit between the two instants (positive if the instance is posterior to the argument), rounded to the nearest integer TimeUnit

Since:

12.1

See Also:

DateTimeComponents(DateTimeComponents, long, TimeUnit)

getDate

public DateComponents getDate()

Get the date component.

Returns:

date component

getTime

public TimeComponents getTime()

Get the time component.

Returns:

time component

compareTo

public int compareTo(DateTimeComponents other)

Specified by:

compareTo in interface Comparable<DateTimeComponents>

equals

public boolean equals(Object other)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Return a string representation of this pair.

The format used is ISO8601 including the UTC offset.

Overrides:

toString in class Object

Returns:

string representation of this pair

toStringWithoutUtcOffset

public String toStringWithoutUtcOffset()

Get a string representation of the date-time without the offset from UTC. The format used is ISO6801, except without the offset from UTC.

Returns:

a string representation of the date-time.

See Also:

toStringWithoutUtcOffset(int, int), toString(int, int), toStringRfc3339()

toString

public String toString(int minuteDuration)

Return a string representation of this date-time, rounded to millisecond precision.

The format used is ISO8601 including the UTC offset.

Parameters:

minuteDuration - 60, 61, or 62 seconds depending on the date being close to a leap second introduction and the magnitude of the leap second.

Returns:

string representation of this date, time, and UTC offset

See Also:

toString(int, int)

toString

public String toString(int minuteDuration,
                       int fractionDigits)

Return a string representation of this date-time, rounded to the given precision.

The format used is ISO8601 including the UTC offset.

Parameters:

minuteDuration - 59, 60, 61, or 62 seconds depending on the date being close to a leap second introduction and the magnitude of the leap second.

fractionDigits - the number of digits to include after the decimal point in the string representation of the seconds. The date and time is first rounded as necessary. fractionDigits must be greater than or equal to 0.

Returns:

string representation of this date, time, and UTC offset

Since:

11.0

See Also:

toStringRfc3339(), toStringWithoutUtcOffset(), toStringWithoutUtcOffset(int, int)

toStringWithoutUtcOffset

public String toStringWithoutUtcOffset(int minuteDuration,
                                       int fractionDigits)

Return a string representation of this date-time, rounded to the given precision.

The format used is ISO8601 without the UTC offset.

Parameters:

minuteDuration - 59, 60, 61, or 62 seconds depending on the date being close to a leap second introduction and the magnitude of the leap second.

fractionDigits - the number of digits to include after the decimal point in the string representation of the seconds. The date and time is first rounded as necessary. fractionDigits must be greater than or equal to 0.

Returns:

string representation of this date, time, and UTC offset

Since:

11.1

See Also:

toStringRfc3339(), toStringWithoutUtcOffset(), toString(int, int)

roundIfNeeded

public DateTimeComponents roundIfNeeded(int minuteDuration,
                                        int fractionDigits)

Round this date-time to the given precision if needed to prevent rounding up to an invalid seconds number. This is useful, for example, when writing custom date-time formatting methods so one does not, e.g., end up with "60.0" seconds during a normal minute when the value of seconds is 59.999. This method will instead round up the minute, hour, day, month, and year as needed.

Parameters:

minuteDuration - 59, 60, 61, or 62 seconds depending on the date being close to a leap second introduction and the magnitude of the leap second.

fractionDigits - the number of decimal digits after the decimal point in the seconds number that will be printed. This date-time is rounded to fractionDigits after the decimal point if necessary to prevent rounding up to minuteDuration. fractionDigits must be greater than or equal to 0.

Returns:

a date-time within 0.5 * 10**-fractionDigits seconds of this, and with a seconds number that will not round up to minuteDuration when rounded to fractionDigits after the decimal point.

Since:

11.3

toStringRfc3339

public String toStringRfc3339()

Represent the given date and time as a string according to the format in RFC 3339. RFC3339 is a restricted subset of ISO 8601 with a well defined grammar. This method includes enough precision to represent the point in time without rounding up to the next minute.

RFC3339 is unable to represent BC years, years of 10000 or more, time zone offsets of 100 hours or more, or NaN. In these cases the value returned from this method will not be valid RFC3339 format.

Returns:

RFC 3339 format string.

See Also:

RFC 3339, AbsoluteDate.toStringRfc3339(TimeScale), toString(int, int), toStringWithoutUtcOffset()