Package org.orekit.time

Class TimeOffset

java.lang.Object
org.orekit.time.TimeOffset
All Implemented Interfaces:
Serializable, Comparable<TimeOffset>
Direct Known Subclasses:
AbsoluteDate
public class TimeOffset extends Object implements Comparable<TimeOffset>, Serializable
This class represents a time range split into seconds and attoseconds.

Instances of this class may either be interpreted as offsets from a reference date, or they may be interpreted as durations. Negative values represent dates earlier than the reference date in the first interpretation, and negative durations in the second interpretation.

The whole number of seconds is stored as signed primitive long, so the range of dates that can be represented is ±292 billion years. The fractional part within the second is stored as non-negative primitive long with fixed precision at a resolution of one attosecond (10⁻¹⁸s). The choice of attoseconds allows to represent exactly all important offsets (between TT and TAI, or between UTC and TAI during the linear eras), as well as all times converted from standard Java Instant, Date or TimeUnit classes. It also allows simple computation as adding or subtracting a few values in attoseconds that are less than one second does not overflow (a primitive long could hold any values between ±9.22s in attoseconds so simple additions and subtractions followed by handling a carry to bring the value back between 0 and 10¹⁸ is straightforward). There are also special encodings (internally using negative longs in the fractional part) to represent NaN, POSITIVE_INFINITY and NEGATIVE_INFINITY.

Since:
13.0
Author:
Luc Maisonobe
See Also:

  • Field Details

    • ZERO

      public static final TimeOffset ZERO
      Split time representing 0.

    • ATTOSECOND

      public static final TimeOffset ATTOSECOND
      Split time representing 1 attosecond.

    • FEMTOSECOND

      public static final TimeOffset FEMTOSECOND
      Split time representing 1 femtosecond.

    • PICOSECOND

      public static final TimeOffset PICOSECOND
      Split time representing 1 picosecond.

    • NANOSECOND

      public static final TimeOffset NANOSECOND
      Split time representing 1 nanosecond.

    • MICROSECOND

      public static final TimeOffset MICROSECOND
      Split time representing 1 microsecond.

    • MILLISECOND

      public static final TimeOffset MILLISECOND
      Split time representing 1 millisecond.

    • SECOND

      public static final TimeOffset SECOND
      Split time representing 1 second.

    • MINUTE

      public static final TimeOffset MINUTE
      Split time representing 1 minute.

    • HOUR

      public static final TimeOffset HOUR
      Split time representing 1 hour.

    • DAY

      public static final TimeOffset DAY
      Split time representing 1 day.

    • DAY_WITH_POSITIVE_LEAP

      public static final TimeOffset DAY_WITH_POSITIVE_LEAP
      Split time representing 1 day that includes an additional leap second.

    • NaN

      public static final TimeOffset NaN
      Split time representing a NaN.

    • NEGATIVE_INFINITY

      public static final TimeOffset NEGATIVE_INFINITY
      Split time representing negative infinity.

    • POSITIVE_INFINITY

      public static final TimeOffset POSITIVE_INFINITY
      Split time representing positive infinity.

  • Constructor Details

    • TimeOffset

      public TimeOffset(TimeOffset... times)
      Build a time by adding several times.
      Parameters:
      times - times to add

    • TimeOffset

      public TimeOffset(long seconds, long attoSeconds)
      Build a time from its components.

      The components will be normalized so that getAttoSeconds() returns a value between 0L and {1000000000000000000L}

      Parameters:
      seconds - seconds part
      attoSeconds - attoseconds part

    • TimeOffset

      public TimeOffset(double time)
      Build a time from a value in seconds.
      Parameters:
      time - time

    • TimeOffset

      public TimeOffset(long factor, TimeOffset time)
      Multiplicative constructor.

      This constructor builds a split time corresponding to factor ⨉ time

      Parameters:
      factor - multiplicative factor (negative values allowed here, contrary to multiply(long))
      time - base time

    • TimeOffset

      public TimeOffset(long f1, TimeOffset t1, long f2, TimeOffset t2)
      Linear combination constructor.

      This constructor builds a split time corresponding to f1 ⨉ t1 + f2 ⨉ t2

      Parameters:
      f1 - first multiplicative factor (negative values allowed here, contrary to multiply(long))
      t1 - first base time
      f2 - second multiplicative factor (negative values allowed here, contrary to multiply(long))
      t2 - second base time

    • TimeOffset

      public TimeOffset(long f1, TimeOffset t1, long f2, TimeOffset t2, long f3, TimeOffset t3)
      Linear combination constructor.

      This constructor builds a split time corresponding to f1 ⨉ t1 + f2 ⨉ t2 + f3 ⨉ t3

      Parameters:
      f1 - first multiplicative factor (negative values allowed here, contrary to multiply(long))
      t1 - first base time
      f2 - second multiplicative factor (negative values allowed here, contrary to multiply(long))
      t2 - second base time
      f3 - third multiplicative factor (negative values allowed here, contrary to multiply(long))
      t3 - third base time

    • TimeOffset

      public TimeOffset(long f1, TimeOffset t1, long f2, TimeOffset t2, long f3, TimeOffset t3, long f4, TimeOffset t4)
      Linear combination constructor.

      This constructor builds a split time corresponding to f1 ⨉ t1 + f2 ⨉ t2 + f3 ⨉ t3 + f4 ⨉ t4

      Parameters:
      f1 - first multiplicative factor (negative values allowed here, contrary to multiply(long))
      t1 - first base time
      f2 - second multiplicative factor (negative values allowed here, contrary to multiply(long))
      t2 - second base time
      f3 - third multiplicative factor (negative values allowed here, contrary to multiply(long))
      t3 - third base time
      f4 - fourth multiplicative factor (negative values allowed here, contrary to multiply(long))
      t4 - fourth base time

    • TimeOffset

      public TimeOffset(long f1, TimeOffset t1, long f2, TimeOffset t2, long f3, TimeOffset t3, long f4, TimeOffset t4, long f5, TimeOffset t5)
      Linear combination constructor.

      This constructor builds a split time corresponding to f1 ⨉ t1 + f2 ⨉ t2 + f3 ⨉ t3 + f4 ⨉ t4 + f5 ⨉ t5

      Parameters:
      f1 - first multiplicative factor (negative values allowed here, contrary to multiply(long))
      t1 - first base time
      f2 - second multiplicative factor (negative values allowed here, contrary to multiply(long))
      t2 - second base time
      f3 - third multiplicative factor (negative values allowed here, contrary to multiply(long))
      t3 - third base time
      f4 - fourth multiplicative factor (negative values allowed here, contrary to multiply(long))
      t4 - fourth base time
      f5 - fifth multiplicative factor (negative values allowed here, contrary to multiply(long))
      t5 - fifth base time

    • TimeOffset

      public TimeOffset(long time, TimeUnit unit)
      Build a time from a value defined in some time unit.
      Parameters:
      time - time
      unit - time unit in which time is expressed

  • Method Details

    • isZero

      public boolean isZero()
      check if the time is zero.
      Returns:
      true if the time is zero

    • isFinite

      public boolean isFinite()
      Check if time is finite (i.e. neither NaN nor infinite).
      Returns:
      true if time is finite
      See Also:

    • isNaN

      public boolean isNaN()
      Check if time is NaN.
      Returns:
      true if time is NaN
      See Also:

    • isInfinite

      public boolean isInfinite()
      Check if time is infinity.
      Returns:
      true if time is infinity
      See Also:

    • isPositiveInfinity

      public boolean isPositiveInfinity()
      Check if time is positive infinity.
      Returns:
      true if time is positive infinity
      See Also:

    • isNegativeInfinity

      public boolean isNegativeInfinity()
      Check if time is negative infinity.
      Returns:
      true if time is negative infinity
      See Also:

    • add

      public TimeOffset add(TimeOffset t)
      Build a time by adding two times.
      Parameters:
      t - time to add
      Returns:
      this+t

    • subtract

      public TimeOffset subtract(TimeOffset t)
      Build a time by subtracting one time from the instance.
      Parameters:
      t - time to subtract
      Returns:
      this-t

    • multiply

      public TimeOffset multiply(long p)
      Multiply the instance by a positive or zero constant.
      Parameters:
      p - multiplication factor (must be positive)
      Returns:
      this ⨉ p

    • divide

      public TimeOffset divide(int q)
      Divide the instance by a positive constant.
      Parameters:
      q - division factor (must be strictly positive)
      Returns:
      this ÷ q

    • negate

      public TimeOffset negate()
      Negate the instance.
      Returns:
      new instance corresponding to opposite time

    • getRoundedTime

      public long getRoundedTime(TimeUnit unit)
      Get the time in some unit.
      Parameters:
      unit - time unit
      Returns:
      time in this unit, rounded to the closest long, returns arbitrarily Long.MAX_VALUE for NaN times

    • getRoundedOffset

      public TimeOffset getRoundedOffset(int fractionDigits)
      Round to specified accuracy.

      For simplicity of implementation, the tiebreaking rule applied here is to round half towards positive infinity. This implies that rounding to 3 fraction digits an offset of exactly 2.0025s implies adding 0.0005s so the rounded value becomes 2.003s, whereas rounding to 3 fraction digits an offset of exactly -2.0025s also implies adding 0.0005s so the rounded value becomes -2.002s.

      Parameters:
      fractionDigits - the number of decimal digits after the decimal point in the seconds number
      Returns:
      rounded time offset
      Since:
      13.0.3

    • getSeconds

      public long getSeconds()
      Get the normalized seconds part of the time.
      Returns:
      normalized seconds part of the time (may be negative)

    • getAttoSeconds

      public long getAttoSeconds()
      Get the normalized attoseconds part of the time.

      The normalized attoseconds is always between 0L and 1000000000000000000L for finite ranges. Note that it may reach 1000000000000000000L if for example the time is less than 1 attosecond before a whole second. It is negative for NaN or infinite times.

      Returns:
      normalized attoseconds part of the time

    • toDouble

      public double toDouble()
      Get the time collapsed into a single double.

      Beware that lots of accuracy is lost when combining getSeconds() and getAttoSeconds() into a single double.

      Returns:
      time as a single double

    • parse

      public static TimeOffset parse(String s)
      Parse a string to produce an accurate split time.

      This method is more accurate than parsing the string as a double and then calling TimeOffset(double) because it reads the before separator and after separator parts in decimal, hence avoiding problems like for example 0.1 not being an exact IEEE754 number.

      Parameters:
      s - string to parse
      Returns:
      parsed split time

    • compareTo

      public int compareTo(TimeOffset other)
      Compare the instance with another one.

      Not that in order to be consistent with Double#compareTo(Double), NaN is considered equal to itself and greater than positive infinity.

      Specified by:
      compareTo in interface Comparable<TimeOffset>
      Parameters:
      other - other time to compare the instance to
      Returns:
      a negative integer, zero, or a positive integer if applying this time to reference date would result in a date being before, simultaneous, or after the date obtained by applying the other time to the same reference date.

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object