Package org.orekit.time

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:

  • Field Details

    • 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 Details

    • 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 23
      minute - minute number from 0 to 59
      second - 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 23
      minute - minute number from 0 to 59
      second - 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 23
      minute - minute number from 0 to 59
      second - 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 23
      minute - minute number from 0 to 59
      second - 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 than 60.0 then getSecond() and getSplitSecond() will be less than 60.0, otherwise they will be less than 61.0. This constructor may produce an invalid value of getSecond() and getSplitSecond() during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute use TimeComponents(TimeOffset, TimeOffset, int).

      This constructor is always in UTC (i.e. will return 0).

      Parameters:
      secondInDay - second number from 0.0 to Constants.JULIAN_DAY + 1 (excluded)
      Throws:
      OrekitIllegalArgumentException - if seconds number is out of range
      See Also:

    • 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 to Constants.JULIAN_DAY + 1 (excluded). The two parameters are used for increased accuracy.

      If the sum is less than 60.0 then getSecond() will be less than 60.0, otherwise it will be less than 61.0. This constructor may produce an invalid value of getSecond() during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute use TimeComponents(TimeOffset, TimeOffset, int).

      This constructor is always in UTC (i.e. getMinutesFromUTC() will return 0).

      Parameters:
      secondInDayA - first part of the second number
      secondInDayB - last part of the second number
      Throws:
      OrekitIllegalArgumentException - if seconds number is out of range
      See Also:

    • TimeComponents

      public TimeComponents(TimeOffset splitSecondInDay)
      Build a time from the second number within the day.

      If the secondInDay is less than 60.0 then getSecond() will be less than 60.0, otherwise it will be less than 61.0. This constructor may produce an invalid value of getSecond() during a negative leap second, through there has never been one. For more control over the number of seconds in the final minute use TimeComponents(TimeOffset, TimeOffset, int).

      This constructor is always in UTC (i.e. will return 0).

      Parameters:
      splitSecondInDay - second number from 0.0 to Constants.JULIAN_DAY + 1 (excluded)
      Since:
      13.0
      See Also:

    • 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 part secondInDay 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 from secondInDay + leap is greater than or equal to 60 + leap then the second of minute will be set to FastMath.nextDown(60 + leap). This prevents rounding to an invalid seconds of minute number when the input values have greater precision than a double.

      This constructor is always in UTC (i.e. will return 0).

      If secondsInDay or leap 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, otherwise 0.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, normally 60.
      Throws:
      OrekitIllegalArgumentException - if the inequalities above do not hold.
      Since:
      10.2

  • Method Details

    • 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 the offset from UTC.
      Returns:
      second number from 0.0 to Constants.JULIAN_DAY
      Since:
      7.2
      See Also:

    • getSplitSecondsInLocalDay

      public TimeOffset getSplitSecondsInLocalDay()
      Get the second number within the local day, without applying the offset from UTC.
      Returns:
      second number from 0.0 to Constants.JULIAN_DAY
      Since:
      13.0
      See Also:

    • getSecondsInUTCDay

      public double getSecondsInUTCDay()
      Get the second number within the UTC day, applying the offset from UTC.
      Returns:
      second number from -getMinutesFromUTC() to Constants.JULIAN_DAY + getMinutesFromUTC()
      Since:
      7.2
      See Also:

    • getSplitSecondsInUTCDay

      public TimeOffset getSplitSecondsInUTCDay()
      Get the second number within the UTC day, applying the offset from UTC.
      Returns:
      second number from -getMinutesFromUTC() to Constants.JULIAN_DAY + getMinutesFromUTC()
      Since:
      13.0
      See Also:

    • 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 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:
      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 to minuteDuration when rounded to fractionDigits 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

      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:

    • toString

      public String toString()
      Get a string representation of the time including the offset from UTC.
      Overrides:
      toString in class Object
      Returns:
      string representation of the time in an ISO 8601 like format including the UTC offset.
      See Also:

    • compareTo

      public int compareTo(TimeComponents other)
      Specified by:
      compareTo in interface Comparable<TimeComponents>

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object