Class 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:
    AbsoluteDate, FieldAbsoluteDate, Serialized Form
    • Field Detail

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

      • 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 constructors builds a split time corresponding to factortime

        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 constructors builds a split time corresponding to f1t1 + f2t2

        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 constructors builds a split time corresponding to f1t1 + f2t2 + f3t3

        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 constructors builds a split time corresponding to f1t1 + f2t2 + f3t3 + f4t4

        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 constructors builds a split time corresponding to f1t1 + f2t2 + f3t3 + f4t4 + f5t5

        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 Detail

      • isZero

        public boolean isZero()
        check if the time is zero.
        Returns:
        true if the time is zero
      • 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
      • 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.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object