Class TimeComponents
- java.lang.Object
-
- org.orekit.time.TimeComponents
-
- All Implemented Interfaces:
Serializable
,Comparable<TimeComponents>
public class TimeComponents extends Object implements Serializable, Comparable<TimeComponents>
Class representing a time within the day broken up as hour, minute and second components.Instances of this class are guaranteed to be immutable.
- Author:
- Luc Maisonobe
- See Also:
DateComponents
,DateTimeComponents
, Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static TimeComponents
H00
Constant for commonly used hour 00:00:00.static TimeComponents
H12
Constant for commonly used hour 12:00:00.static TimeComponents
NaN
Constant for NaN time.
-
Constructor Summary
Constructors Constructor Description TimeComponents(double secondInDay)
Build a time from the second number within the day.TimeComponents(int secondInDayA, double secondInDayB)
Build a time from the second number within the day.TimeComponents(int hour, int minute, double second)
Build a time from its clock elements.TimeComponents(int hour, int minute, double second, int minutesFromUTC)
Build a time from its clock elements.TimeComponents(int hour, int minute, TimeOffset second)
Build a time from its clock elements.TimeComponents(int hour, int minute, TimeOffset second, int minutesFromUTC)
Build a time from its clock elements.TimeComponents(TimeOffset splitSecondInDay)
Build a time from the second number within the day.TimeComponents(TimeOffset secondInDay, TimeOffset leap, int minuteDuration)
Build a time from the second number within the day.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description int
compareTo(TimeComponents other)
boolean
equals(Object other)
String
formatUtcOffset()
Get the UTC offset as a string in ISO8601 format.int
getHour()
Get the hour number.int
getMinute()
Get the minute number.int
getMinutesFromUTC()
Get the offset between the specified date and UTC.double
getSecond()
Get the seconds number.double
getSecondsInLocalDay()
Get the second number within the local day, without applying theoffset from UTC
.double
getSecondsInUTCDay()
Get the second number within the UTC day, applying theoffset from UTC
.TimeOffset
getSplitSecond()
Get the seconds number.TimeOffset
getSplitSecondsInLocalDay()
Get the second number within the local day, without applying theoffset from UTC
.TimeOffset
getSplitSecondsInUTCDay()
Get the second number within the UTC day, applying theoffset from UTC
.int
hashCode()
static TimeComponents
parseTime(String string)
Parse a string in ISO-8601 format to build a time.String
toString()
Get a string representation of the time including the offset from UTC.String
toStringWithoutUtcOffset()
Get a string representation of the time without the offset from UTC.TimeComponents
wrapIfNeeded(int minuteDuration, int fractionDigits)
Round this time to the given precision if needed to prevent rounding up to an invalid seconds number.
-
-
-
Field Detail
-
H00
public static final TimeComponents H00
Constant for commonly used hour 00:00:00.
-
H12
public static final TimeComponents H12
Constant for commonly used hour 12:00:00.
-
NaN
public static final TimeComponents NaN
Constant for NaN time.- Since:
- 13.0
-
-
Constructor Detail
-
TimeComponents
public TimeComponents(int hour, int minute, double second) throws IllegalArgumentException
Build a time from its clock elements.Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed in this method, since they do occur during leap seconds introduction in the
UTC
time scale.- Parameters:
hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 61.0 (excluded)- Throws:
IllegalArgumentException
- if inconsistent arguments are given (parameters out of range)
-
TimeComponents
public TimeComponents(int hour, int minute, TimeOffset second) throws IllegalArgumentException
Build a time from its clock elements.Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed in this method, since they do occur during leap seconds introduction in the
UTC
time scale.- Parameters:
hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 61.0 (excluded)- Throws:
IllegalArgumentException
- if inconsistent arguments are given (parameters out of range)- Since:
- 13.0
-
TimeComponents
public TimeComponents(int hour, int minute, double second, int minutesFromUTC) throws IllegalArgumentException
Build a time from its clock elements.Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed in this method, since they do occur during leap seconds introduction in the
UTC
time scale.- Parameters:
hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 61.0 (excluded)minutesFromUTC
- offset between the specified date and UTC, as an integral number of minutes, as per ISO-8601 standard- Throws:
IllegalArgumentException
- if inconsistent arguments are given (parameters out of range)- Since:
- 7.2
-
TimeComponents
public TimeComponents(int hour, int minute, TimeOffset second, int minutesFromUTC) throws IllegalArgumentException
Build a time from its clock elements.Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed in this method, since they do occur during leap seconds introduction in the
UTC
time scale.- Parameters:
hour
- hour number from 0 to 23minute
- minute number from 0 to 59second
- second number from 0.0 to 62.0 (excluded, more than 61 s occurred on the 1961 leap second, which was between 1 and 2 seconds in duration)minutesFromUTC
- offset between the specified date and UTC, as an integral number of minutes, as per ISO-8601 standard- Throws:
IllegalArgumentException
- if inconsistent arguments are given (parameters out of range)- Since:
- 13.0
-
TimeComponents
public TimeComponents(double secondInDay) throws OrekitIllegalArgumentException
Build a time from the second number within the day.If the
secondInDay
is less than60.0
thengetSecond()
andgetSplitSecond()
will be less than60.0
, otherwise they will be less than61.0
. This constructor may produce an invalid value ofgetSecond()
andgetSplitSecond()
during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute useTimeComponents(TimeOffset, TimeOffset, int)
.This constructor is always in UTC (i.e.
will return 0
).- Parameters:
secondInDay
- second number from 0.0 toConstants.JULIAN_DAY
+ 1
(excluded)- Throws:
OrekitIllegalArgumentException
- if seconds number is out of range- See Also:
TimeComponents(TimeOffset, TimeOffset, int)
,TimeComponents(int, double)
-
TimeComponents
public TimeComponents(int secondInDayA, double secondInDayB) throws OrekitIllegalArgumentException
Build a time from the second number within the day.The second number is defined here as the sum
secondInDayA + secondInDayB
from 0.0 toConstants.JULIAN_DAY
+ 1
(excluded). The two parameters are used for increased accuracy.If the sum is less than
60.0
thengetSecond()
will be less than60.0
, otherwise it will be less than61.0
. This constructor may produce an invalid value ofgetSecond()
during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute useTimeComponents(TimeOffset, TimeOffset, int)
.This constructor is always in UTC (i.e.
getMinutesFromUTC()
will return 0).- Parameters:
secondInDayA
- first part of the second numbersecondInDayB
- last part of the second number- Throws:
OrekitIllegalArgumentException
- if seconds number is out of range- See Also:
TimeComponents(TimeOffset, TimeOffset, int)
-
TimeComponents
public TimeComponents(TimeOffset splitSecondInDay)
Build a time from the second number within the day.If the
secondInDay
is less than60.0
thengetSecond()
will be less than60.0
, otherwise it will be less than61.0
. This constructor may produce an invalid value ofgetSecond()
during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute useTimeComponents(TimeOffset, TimeOffset, int)
.This constructor is always in UTC (i.e.
will return 0
).- Parameters:
splitSecondInDay
- second number from 0.0 toConstants.JULIAN_DAY
+ 1
(excluded)- Since:
- 13.0
- See Also:
TimeComponents(TimeOffset, TimeOffset, int)
,TimeComponents(int, double)
-
TimeComponents
public TimeComponents(TimeOffset secondInDay, TimeOffset leap, int minuteDuration)
Build a time from the second number within the day.The seconds past midnight is the sum
secondInDay + leap
. Only the partsecondInDay
is used to compute the hours and minutes. The second parameter (leap
) is added directly to the second value (getSecond()
) to implement leap seconds. These two quantities must satisfy the following constraints. This first guarantees the hour and minute are valid, the second guarantees the second is valid.0 <= secondInDay < 86400
0 <= secondInDay % 60 + leap <= minuteDuration
0 <= leap <= minuteDuration - 60 if minuteDuration >= 60
0 >= leap >= minuteDuration - 60 if minuteDuration < 60
If the seconds of minute (
getSecond()
) computed fromsecondInDay + leap
is greater than or equal to60 + leap
then the second of minute will be set toFastMath.nextDown(60 + leap)
. This prevents rounding to an invalid seconds of minute number when the input values have greater precision than adouble
.This constructor is always in UTC (i.e.
will return 0
).If
secondsInDay
orleap
is NaN then the hour and minute will be set arbitrarily and the second of minute will be NaN.- Parameters:
secondInDay
- part of the second number.leap
- magnitude of the leap second if this point in time is during a leap second, otherwise0.0
. This value is not used to compute hours and minutes, but it is added to the computed second of minute.minuteDuration
- number of seconds in the current minute, normally60
.- Throws:
OrekitIllegalArgumentException
- if the inequalities above do not hold.- Since:
- 10.2
-
-
Method Detail
-
parseTime
public static TimeComponents parseTime(String string)
Parse a string in ISO-8601 format to build a time.The supported formats are:
- basic and extended format local time: hhmmss, hh:mm:ss (with optional decimals in seconds)
- optional UTC time: hhmmssZ, hh:mm:ssZ
- optional signed hours UTC offset: hhmmss+HH, hhmmss-HH, hh:mm:ss+HH, hh:mm:ss-HH
- optional signed basic hours and minutes UTC offset: hhmmss+HHMM, hhmmss-HHMM, hh:mm:ss+HHMM, hh:mm:ss-HHMM
- optional signed extended hours and minutes UTC offset: hhmmss+HH:MM, hhmmss-HH:MM, hh:mm:ss+HH:MM, hh:mm:ss-HH:MM
As shown by the list above, only the complete representations defined in section 4.2 of ISO-8601 standard are supported, neither expended representations nor representations with reduced accuracy are supported.
- Parameters:
string
- string to parse- Returns:
- a parsed time
- Throws:
IllegalArgumentException
- if string cannot be parsed
-
getHour
public int getHour()
Get the hour number.- Returns:
- hour number from 0 to 23
-
getMinute
public int getMinute()
Get the minute number.- Returns:
- minute minute number from 0 to 59
-
getSecond
public double getSecond()
Get the seconds number.- Returns:
- second second number from 0.0 to 61.0 (excluded). Note that 60 ≤ second < 61 only occurs during a leap second.
-
getSplitSecond
public TimeOffset getSplitSecond()
Get the seconds number.- Returns:
- second second number from 0.0 to 61.0 (excluded). Note that 60 ≤ second < 61 only occurs during a leap second.
-
getMinutesFromUTC
public int getMinutesFromUTC()
Get the offset between the specified date and UTC.The offset is always an integral number of minutes, as per ISO-8601 standard.
- Returns:
- offset in minutes between the specified date and UTC
- Since:
- 7.2
-
getSecondsInLocalDay
public double getSecondsInLocalDay()
Get the second number within the local day, without applying theoffset from UTC
.- Returns:
- second number from 0.0 to Constants.JULIAN_DAY
- Since:
- 7.2
- See Also:
getSplitSecondsInLocalDay()
,getSecondsInUTCDay()
-
getSplitSecondsInLocalDay
public TimeOffset getSplitSecondsInLocalDay()
Get the second number within the local day, without applying theoffset from UTC
.- Returns:
- second number from 0.0 to Constants.JULIAN_DAY
- Since:
- 13.0
- See Also:
getSecondsInLocalDay()
,getSplitSecondsInUTCDay()
-
getSecondsInUTCDay
public double getSecondsInUTCDay()
Get the second number within the UTC day, applying theoffset from UTC
.- Returns:
- second number from
-getMinutesFromUTC()
to Constants.JULIAN_DAY+ getMinutesFromUTC()
- Since:
- 7.2
- See Also:
getSplitSecondsInUTCDay()
,getSecondsInLocalDay()
-
getSplitSecondsInUTCDay
public TimeOffset getSplitSecondsInUTCDay()
Get the second number within the UTC day, applying theoffset from UTC
.- Returns:
- second number from
-getMinutesFromUTC()
to Constants.JULIAN_DAY+ getMinutesFromUTC()
- Since:
- 13.0
- See Also:
getSecondsInUTCDay()
,getSplitSecondsInLocalDay()
-
wrapIfNeeded
public TimeComponents wrapIfNeeded(int minuteDuration, int fractionDigits)
Round this 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 is59.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 tofractionDigits
after the decimal point if necessary to prevent rounding up tominuteDuration
.fractionDigits
must be greater than or equal to0
.- Returns:
- the instance itself if no rounding was needed, or a time within
0.5 * 10**-fractionDigits
seconds of this, and with a seconds number that will not round up tominuteDuration
when rounded tofractionDigits
after the decimal point - Since:
- 13.0
-
toStringWithoutUtcOffset
public String toStringWithoutUtcOffset()
Get a string representation of the time without the offset from UTC.- Returns:
- a string representation of the time in an ISO 8601 like format.
- See Also:
formatUtcOffset()
,toString()
-
formatUtcOffset
public String formatUtcOffset()
Get the UTC offset as a string in ISO8601 format. For example,+00:00
.- Returns:
- the UTC offset as a string.
- See Also:
toStringWithoutUtcOffset()
,toString()
-
toString
public String toString()
Get a string representation of the time including the offset from UTC.- Overrides:
toString
in classObject
- Returns:
- string representation of the time in an ISO 8601 like format including the UTC offset.
- See Also:
toStringWithoutUtcOffset()
,formatUtcOffset()
-
compareTo
public int compareTo(TimeComponents other)
- Specified by:
compareTo
in interfaceComparable<TimeComponents>
-
-