TimeOffset.java

  1. /* Copyright 2022-2025 Luc Maisonobe
  2.  * Licensed to CS GROUP (CS) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * CS licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *   http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */
  17. package org.orekit.time;

  19. import org.hipparchus.exception.LocalizedCoreFormats;
  20. import org.hipparchus.util.FastMath;
  21. import org.orekit.errors.OrekitException;
  22. import org.orekit.errors.OrekitMessages;

  24. import java.io.Serializable;
  25. import java.util.concurrent.TimeUnit;

  27. /** This class represents a time range split into seconds and attoseconds.
  28.  * <p>
  29.  * Instances of this class may either be interpreted as offsets from a reference
  30.  * date, or they may be interpreted as durations. Negative values represent
  31.  * dates earlier than the reference date in the first interpretation, and
  32.  * negative durations in the second interpretation.
  33.  * </p>
  34.  * <p>
  35.  * The whole number of seconds is stored as signed primitive long, so the range
  36.  * of dates that can be represented is ±292 billion years. The fractional part
  37.  * within the second is stored as non-negative primitive long with fixed precision
  38.  * at a resolution of one attosecond (10⁻¹⁸s). The choice of attoseconds allows
  39.  * to represent exactly all important offsets (between TT and TAI, or between UTC
  40.  * and TAI during the linear eras), as well as all times converted from standard
  41.  * Java Instant, Date or TimeUnit classes. It also allows simple computation as
  42.  * adding or subtracting a few values in attoseconds that are less than one second
  43.  * does not overflow (a primitive long could hold any values between ±9.22s in
  44.  * attoseconds so simple additions and subtractions followed by handling a carry
  45.  * to bring the value back between 0 and 10¹⁸ is straightforward). There are also
  46.  * special encodings (internally using negative longs in the fractional part) to
  47.  * represent {@link #NaN}, {@link #POSITIVE_INFINITY} and {@link #NEGATIVE_INFINITY}.
  48.  * </p>
  49.  * @author Luc Maisonobe
  50.  * @see AbsoluteDate
  51.  * @see FieldAbsoluteDate
  52.  * @since 13.0
  53.  */
  54. public class TimeOffset
  55.     implements Comparable<TimeOffset>, Serializable {

  57.     /** Split time representing 0. */
  58.     public static final TimeOffset ZERO = new TimeOffset(0L, 0L);

  60.     /** Split time representing 1 attosecond. */
  61.     public static final TimeOffset ATTOSECOND = new TimeOffset(0L, 1L);

  63.     /** Split time representing 1 femtosecond. */
  64.     public static final TimeOffset FEMTOSECOND = new TimeOffset(0L, 1000L);

  66.     /** Split time representing 1 picosecond. */
  67.     public static final TimeOffset PICOSECOND = new TimeOffset(0L, 1000000L);

  69.     /** Split time representing 1 nanosecond. */
  70.     public static final TimeOffset NANOSECOND = new TimeOffset(0L, 1000000000L);

  72.     /** Split time representing 1 microsecond. */
  73.     public static final TimeOffset MICROSECOND = new TimeOffset(0L, 1000000000000L);

  75.     /** Split time representing 1 millisecond. */
  76.     public static final TimeOffset MILLISECOND = new TimeOffset(0L, 1000000000000000L);

  78.     /** Split time representing 1 second. */
  79.     public static final TimeOffset SECOND = new TimeOffset(1L, 0L);

  81.     /** Split time representing 1 minute. */
  82.     public static final TimeOffset MINUTE = new TimeOffset(60L, 0L);

  84.     /** Split time representing 1 hour. */
  85.     public static final TimeOffset HOUR = new TimeOffset(3600L, 0L);

  87.     /** Split time representing 1 day. */
  88.     public static final TimeOffset DAY = new TimeOffset(86400L, 0L);

  90.     /** Split time representing 1 day that includes an additional leap second. */
  91.     public static final TimeOffset DAY_WITH_POSITIVE_LEAP = new TimeOffset(86401L, 0L);

  93.     // CHECKSTYLE: stop ConstantName
  94.     /** Split time representing a NaN. */
  95.     public static final TimeOffset NaN = new TimeOffset(Double.NaN);
  96.     // CHECKSTYLE: resume ConstantName

  98.     /** Split time representing negative infinity. */
  99.     public static final TimeOffset NEGATIVE_INFINITY = new TimeOffset(Double.NEGATIVE_INFINITY);

  101.     /** Split time representing positive infinity. */
  102.     public static final TimeOffset POSITIVE_INFINITY = new TimeOffset(Double.POSITIVE_INFINITY);

  104.     /** Indicator for NaN time (bits pattern arbitrarily selected to avoid hashcode collisions). */
  105.     private static final long NAN_INDICATOR      = -0XFFL;

  107.     /** Indicator for positive infinite time (bits pattern arbitrarily selected to avoid hashcode collisions). */
  108.     private static final long POSITIVE_INFINITY_INDICATOR = -0XFF00L;

  110.     /** Indicator for negative infinite time (bits pattern arbitrarily selected to avoid hashcode collisions). */
  111.     private static final long NEGATIVE_INFINITY_INDICATOR = -0XFF0000L;

  113.     /** Milliseconds in one second. */
  114.     private static final long MILLIS_IN_SECOND = 1000L;

  116.     /** Microseconds in one second. */
  117.     private static final long MICROS_IN_SECOND = 1000000L;

  119.     /** Nanoseconds in one second. */
  120.     private static final long NANOS_IN_SECOND = 1000000000L;

  122.     /** Attoseconds in one second. */
  123.     private static final long ATTOS_IN_SECOND = 1000000000000000000L;

  125.     /** Attoseconds in one half-second. */
  126.     private static final long ATTOS_IN_HALF_SECOND = 500000000000000000L;

  128.     /** Factor to split long for multiplications.
  129.      * <p>
  130.      * It is important that SPLIT * SPLIT = ATTOS_IN_SECOND.
  131.      * </p>
  132.      */
  133.     private static final long SPLIT = 1000000000L;

  135.     /** Number of digits after separator for attoseconds. */
  136.     private static final int DIGITS_ATTOS = 18;

  138.     /** Multipliers for parsing partial strings. */
  139.     // CHECKSTYLE: stop Indentation check
  140.     private static final long[] MULTIPLIERS = new long[] {
  141.                          1L,
  142.                         10L,
  143.                        100L,
  144.                       1000L,
  145.                      10000L,
  146.                     100000L,
  147.                    1000000L,
  148.                   10000000L,
  149.                  100000000L,
  150.                 1000000000L,
  151.                10000000000L,
  152.               100000000000L,
  153.              1000000000000L,
  154.             10000000000000L,
  155.            100000000000000L,
  156.           1000000000000000L,
  157.          10000000000000000L,
  158.         100000000000000000L,
  159.        1000000000000000000L
  160.     };
  161.     // CHECKSTYLE: resume Indentation check

  163.     /** Serializable UID. */
  164.     private static final long serialVersionUID = 20240711L;

  166.     /** Seconds part. */
  167.     private final long seconds;

  169.     /** AttoSeconds part. */
  170.     private final long attoSeconds;

  172.     /**
  173.      * Build a time by adding several times.
  174.      * @param times times to add
  175.      */
  176.     public TimeOffset(final TimeOffset... times) {
  177.         final RunningSum runningSum = new RunningSum();
  178.         for (final TimeOffset time : times) {
  179.             runningSum.add(time);
  180.         }
  181.         final TimeOffset sum = runningSum.normalize();
  182.         this.seconds     = sum.getSeconds();
  183.         this.attoSeconds = sum.getAttoSeconds();
  184.     }

  186.     /**
  187.      * Build a time from its components.
  188.      * <p>
  189.      * The components will be normalized so that {@link #getAttoSeconds()}
  190.      * returns a value between {@code 0L} and {1000000000000000000L}
  191.      * </p>
  192.      * @param seconds seconds part
  193.      * @param attoSeconds attoseconds part
  194.      */
  195.     public TimeOffset(final long seconds, final long attoSeconds) {
  196.         final long qAtto = attoSeconds / ATTOS_IN_SECOND;
  197.         final long rAtto = attoSeconds - qAtto * ATTOS_IN_SECOND;
  198.         if (rAtto < 0L) {
  199.             this.seconds     = seconds + qAtto - 1L;
  200.             this.attoSeconds = ATTOS_IN_SECOND + rAtto;
  201.         } else {
  202.             this.seconds     = seconds + qAtto;
  203.             this.attoSeconds = rAtto;
  204.         }
  205.     }

  207.     /**
  208.      * Build a time from a value in seconds.
  209.      *
  210.      * @param time time
  211.      */
  212.     public TimeOffset(final double time) {
  213.         if (Double.isNaN(time)) {
  214.             seconds     = 0L;
  215.             attoSeconds = NAN_INDICATOR;
  216.         } else if (time < Long.MIN_VALUE || time > Long.MAX_VALUE) {
  217.             if (time < 0L) {
  218.                 seconds     = Long.MIN_VALUE;
  219.                 attoSeconds = NEGATIVE_INFINITY_INDICATOR;
  220.             } else {
  221.                 seconds     = Long.MAX_VALUE;
  222.                 attoSeconds = POSITIVE_INFINITY_INDICATOR;
  223.             }
  224.         } else {
  225.             final double tiSeconds  = FastMath.rint(time);
  226.             final double subSeconds = time - tiSeconds;
  227.             if (subSeconds < 0L) {
  228.                 seconds     = (long) tiSeconds - 1L;
  229.                 attoSeconds = FastMath.round(subSeconds * ATTOS_IN_SECOND) + ATTOS_IN_SECOND;
  230.             } else {
  231.                 seconds     = (long) tiSeconds;
  232.                 attoSeconds = FastMath.round(subSeconds * ATTOS_IN_SECOND);
  233.             }
  234.         }
  235.     }

  237.     /**
  238.      * Multiplicative constructor.
  239.      * <p>
  240.      * This constructors builds a split time corresponding to {@code factor} ⨉ {@code time}
  241.      * </p>
  242.      * @param factor multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  243.      * @param time base time
  244.      */
  245.     public TimeOffset(final long factor, final TimeOffset time) {
  246.         this(factor < 0 ? time.multiply(-factor).negate() : time.multiply(factor));
  247.     }

  249.     /**
  250.      * Linear combination constructor.
  251.      * <p>
  252.      * This constructors builds a split time corresponding to
  253.      * {@code f1} ⨉ {@code t1} + {@code f2} ⨉ {@code t2}
  254.      * </p>
  255.      * @param f1 first multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  256.      * @param t1 first base time
  257.      * @param f2 second multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  258.      * @param t2 second base time
  259.      */
  260.     public TimeOffset(final long f1, final TimeOffset t1,
  261.                       final long f2, final TimeOffset t2) {
  262.         this(new TimeOffset(f1, t1).add(new TimeOffset(f2, t2)));
  263.     }

  265.     /**
  266.      * Linear combination constructor.
  267.      * <p>
  268.      * This constructors builds a split time corresponding to
  269.      * {@code f1} ⨉ {@code t1} + {@code f2} ⨉ {@code t2} + {@code f3} ⨉ {@code t3}
  270.      * </p>
  271.      * @param f1 first multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  272.      * @param t1 first base time
  273.      * @param f2 second multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  274.      * @param t2 second base time
  275.      * @param f3 third multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  276.      * @param t3 third base time
  277.      */
  278.     public TimeOffset(final long f1, final TimeOffset t1,
  279.                       final long f2, final TimeOffset t2,
  280.                       final long f3, final TimeOffset t3) {
  281.         this(new TimeOffset(f1, t1).add(new TimeOffset(f2, t2)).add(new TimeOffset(f3, t3)));
  282.     }

  284.     /**
  285.      * Linear combination constructor.
  286.      * <p>
  287.      * This constructors builds a split time corresponding to
  288.      * {@code f1} ⨉ {@code t1} + {@code f2} ⨉ {@code t2} + {@code f3} ⨉ {@code t3} + {@code f4} ⨉ {@code t4}
  289.      * </p>
  290.      * @param f1 first multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  291.      * @param t1 first base time
  292.      * @param f2 second multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  293.      * @param t2 second base time
  294.      * @param f3 third multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  295.      * @param t3 third base time
  296.      * @param f4 fourth multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  297.      * @param t4 fourth base time
  298.      */
  299.     public TimeOffset(final long f1, final TimeOffset t1,
  300.                       final long f2, final TimeOffset t2,
  301.                       final long f3, final TimeOffset t3,
  302.                       final long f4, final TimeOffset t4) {
  303.         this(new TimeOffset(f1, t1).
  304.              add(new TimeOffset(f2, t2)).
  305.              add(new TimeOffset(f3, t3)).
  306.              add(new TimeOffset(f4, t4)));
  307.     }

  309.     /**
  310.      * Linear combination constructor.
  311.      * <p>
  312.      * This constructors builds a split time corresponding to
  313.      * {@code f1} ⨉ {@code t1} + {@code f2} ⨉ {@code t2} + {@code f3} ⨉ {@code t3} + {@code f4} ⨉ {@code t4} + {@code f5} ⨉ {@code t5}
  314.      * </p>
  315.      * @param f1 first multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  316.      * @param t1 first base time
  317.      * @param f2 second multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  318.      * @param t2 second base time
  319.      * @param f3 third multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  320.      * @param t3 third base time
  321.      * @param f4 fourth multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  322.      * @param t4 fourth base time
  323.      * @param f5 fifth multiplicative factor (negative values allowed here, contrary to {@link #multiply(long)})
  324.      * @param t5 fifth base time
  325.      */
  326.     public TimeOffset(final long f1, final TimeOffset t1,
  327.                       final long f2, final TimeOffset t2,
  328.                       final long f3, final TimeOffset t3,
  329.                       final long f4, final TimeOffset t4,
  330.                       final long f5, final TimeOffset t5) {
  331.         this(new TimeOffset(f1, t1).
  332.              add(new TimeOffset(f2, t2)).
  333.              add(new TimeOffset(f3, t3)).
  334.              add(new TimeOffset(f4, t4)).
  335.              add(new TimeOffset(f5, t5)));
  336.     }

  338.     /**
  339.      * Build a time from a value defined in some time unit.
  340.      *
  341.      * @param time time
  342.      * @param unit   time unit in which {@code time} is expressed
  343.      */
  344.     public TimeOffset(final long time, final TimeUnit unit) {
  345.         switch (unit) {
  346.             case DAYS: {
  347.                 final long limit = (Long.MAX_VALUE - DAY.seconds / 2) / DAY.seconds;
  348.                 if (time < -limit) {
  349.                     seconds     = Long.MIN_VALUE;
  350.                     attoSeconds = NEGATIVE_INFINITY_INDICATOR;
  351.                 } else if (time > limit) {
  352.                     seconds     = Long.MAX_VALUE;
  353.                     attoSeconds = POSITIVE_INFINITY_INDICATOR;
  354.                 } else {
  355.                     seconds = time * DAY.seconds;
  356.                     attoSeconds = 0L;
  357.                 }
  358.                 break;
  359.             }
  360.             case HOURS: {
  361.                 final long limit = (Long.MAX_VALUE - HOUR.seconds / 2) / HOUR.seconds;
  362.                 if (time < -limit) {
  363.                     seconds     = Long.MIN_VALUE;
  364.                     attoSeconds = NEGATIVE_INFINITY_INDICATOR;
  365.                 } else if (time > limit) {
  366.                     seconds     = Long.MAX_VALUE;
  367.                     attoSeconds = POSITIVE_INFINITY_INDICATOR;
  368.                 } else {
  369.                     seconds     = time * HOUR.seconds;
  370.                     attoSeconds = 0L;
  371.                 }
  372.                 break;
  373.             }
  374.             case MINUTES: {
  375.                 final long limit = (Long.MAX_VALUE - MINUTE.seconds / 2) / MINUTE.seconds;
  376.                 if (time < -limit) {
  377.                     seconds     = Long.MIN_VALUE;
  378.                     attoSeconds = NEGATIVE_INFINITY_INDICATOR;
  379.                 } else if (time > limit) {
  380.                     seconds     = Long.MAX_VALUE;
  381.                     attoSeconds = POSITIVE_INFINITY_INDICATOR;
  382.                 } else {
  383.                     seconds     = time * MINUTE.seconds;
  384.                     attoSeconds = 0L;
  385.                 }
  386.                 break;
  387.             }
  388.             case SECONDS:
  389.                 seconds     = time;
  390.                 attoSeconds = 0L;
  391.                 break;
  392.             case MILLISECONDS: {
  393.                 final long s = time / MILLIS_IN_SECOND;
  394.                 final long r = (time - s * MILLIS_IN_SECOND) * MILLISECOND.attoSeconds;
  395.                 if (r < 0L) {
  396.                     seconds     = s - 1L;
  397.                     attoSeconds = ATTOS_IN_SECOND + r;
  398.                 } else {
  399.                     seconds     = s;
  400.                     attoSeconds = r;
  401.                 }
  402.                 break;
  403.             }
  404.             case MICROSECONDS: {
  405.                 final long s = time / MICROS_IN_SECOND;
  406.                 final long r = (time - s * MICROS_IN_SECOND) * MICROSECOND.attoSeconds;
  407.                 if (r < 0L) {
  408.                     seconds     = s - 1L;
  409.                     attoSeconds = ATTOS_IN_SECOND + r;
  410.                 } else {
  411.                     seconds     = s;
  412.                     attoSeconds = r;
  413.                 }
  414.                 break;
  415.             }
  416.             case NANOSECONDS: {
  417.                 final long s = time / NANOS_IN_SECOND;
  418.                 final long r = (time - s * NANOS_IN_SECOND) * NANOSECOND.attoSeconds;
  419.                 if (r < 0L) {
  420.                     seconds     = s - 1L;
  421.                     attoSeconds = ATTOS_IN_SECOND + r;
  422.                 } else {
  423.                     seconds     = s;
  424.                     attoSeconds = r;
  425.                 }
  426.                 break;
  427.             }
  428.             default:
  429.                 throw new OrekitException(OrekitMessages.UNKNOWN_UNIT, unit.name());
  430.         }
  431.     }

  433.     /** Copy constructor, for internal use only.
  434.      * @param time time to copy
  435.      */
  436.     private TimeOffset(final TimeOffset time) {
  437.         seconds     = time.seconds;
  438.         attoSeconds = time.attoSeconds;
  439.     }

  441.     /** check if the time is zero.
  442.      * @return true if the time is zero
  443.      */
  444.     public boolean isZero() {
  445.         return seconds == 0L && attoSeconds == 0L;
  446.     }

  448.     /** Check if time is finite (i.e. neither {@link #isNaN() NaN} nor {@link #isInfinite() infinite)}.
  449.      * @return true if time is finite
  450.      * @see #isNaN()
  451.      * @see #isInfinite()
  452.      * @see #isNegativeInfinity()
  453.      * @see #isPositiveInfinity()
  454.      */
  455.     public boolean isFinite() {
  456.         return attoSeconds >= 0L;
  457.     }

  459.     /** Check if time is NaN.
  460.      * @return true if time is NaN
  461.      * @see #isFinite()
  462.      * @see #isInfinite()
  463.      * @see #isNegativeInfinity()
  464.      * @see #isPositiveInfinity()
  465.      */
  466.     public boolean isNaN() {
  467.         return attoSeconds == NAN_INDICATOR;
  468.     }

  470.     /** Check if time is infinity.
  471.      * @return true if time is infinity
  472.      * @see #isFinite()
  473.      * @see #isNaN()
  474.      * @see #isNegativeInfinity()
  475.      * @see #isPositiveInfinity()
  476.      */
  477.     public boolean isInfinite() {
  478.         return isPositiveInfinity() || isNegativeInfinity();
  479.     }

  481.     /** Check if time is positive infinity.
  482.      * @return true if time is positive infinity
  483.      * @see #isFinite()
  484.      * @see #isNaN()
  485.      * @see #isInfinite()
  486.      * @see #isNegativeInfinity()
  487.      */
  488.     public boolean isPositiveInfinity() {
  489.         return attoSeconds == POSITIVE_INFINITY_INDICATOR;
  490.     }

  492.     /** Check if time is negative infinity.
  493.      * @return true if time is negative infinity
  494.      * @see #isFinite()
  495.      * @see #isNaN()
  496.      * @see #isInfinite()
  497.      * @see #isPositiveInfinity()
  498.      */
  499.     public boolean isNegativeInfinity() {
  500.         return attoSeconds == NEGATIVE_INFINITY_INDICATOR;
  501.     }

  503.     /** Build a time by adding two times.
  504.      * @param t time to add
  505.      * @return this+t
  506.      */
  507.     public TimeOffset add(final TimeOffset t) {
  508.         final RunningSum runningSum = new RunningSum();
  509.         runningSum.add(this);
  510.         runningSum.add(t);
  511.         return runningSum.normalize();
  512.     }

  514.     /** Build a time by subtracting one time from the instance.
  515.      * @param t time to subtract
  516.      * @return this-t
  517.      */
  518.     public TimeOffset subtract(final TimeOffset t) {
  519.         if (attoSeconds < 0 || t.attoSeconds < 0) {
  520.             // gather all special cases in one big check to avoid rare multiple tests
  521.             if (isNaN() ||
  522.                 t.isNaN() ||
  523.                 isPositiveInfinity() && t.isPositiveInfinity() ||
  524.                 isNegativeInfinity() && t.isNegativeInfinity()) {
  525.                 return NaN;
  526.             } else if (isInfinite()) {
  527.                 // t is either a finite time or the infinity opposite to this
  528.                 return this;
  529.             } else {
  530.                 // this is either a finite time or the infinity opposite to t
  531.                 return t.isPositiveInfinity() ? NEGATIVE_INFINITY : POSITIVE_INFINITY;
  532.             }
  533.         } else {
  534.             // regular subtraction between two finite times
  535.             return new TimeOffset(seconds - t.seconds, attoSeconds - t.attoSeconds);
  536.         }
  537.     }

  539.     /** Multiply the instance by a positive or zero constant.
  540.      * @param p multiplication factor (must be positive)
  541.      * @return this ⨉ p
  542.      */
  543.     public TimeOffset multiply(final long p) {
  544.         if (p < 0) {
  545.             throw new OrekitException(OrekitMessages.NOT_POSITIVE, p);
  546.         }
  547.         if (isFinite()) {
  548.             final TimeOffset abs   = seconds < 0 ? negate() : this;
  549.             final long pHigh   = p / SPLIT;
  550.             final long pLow    = p - pHigh * SPLIT;
  551.             final long sHigh   = abs.seconds / SPLIT;
  552.             final long sLow    = abs.seconds - sHigh * SPLIT;
  553.             final long aHigh   = abs.attoSeconds / SPLIT;
  554.             final long aLow    = abs.attoSeconds - aHigh * SPLIT;
  555.             final long ps1     = pHigh * sLow + pLow * sHigh;
  556.             final long ps0     = pLow * sLow;
  557.             final long pa2     = pHigh * aHigh;
  558.             final long pa1     = pHigh * aLow + pLow * aHigh;
  559.             final long pa1High = pa1 / SPLIT;
  560.             final long pa1Low  = pa1 - pa1High * SPLIT;
  561.             final long pa0     = pLow * aLow;

  563.             // check for overflow
  564.             if (pHigh * sHigh != 0 || ps1 / SPLIT != 0) {
  565.                 throw new OrekitException(LocalizedCoreFormats.OVERFLOW_IN_MULTIPLICATION, abs.seconds, p);
  566.             }

  568.             // here we use the fact that SPLIT * SPLIT = ATTOS_IN_SECOND
  569.             final TimeOffset mul = new TimeOffset(SPLIT * ps1 + ps0 + pa2 + pa1High, SPLIT * pa1Low + pa0);
  570.             return seconds < 0 ? mul.negate() : mul;
  571.         } else {
  572.             // already NaN, +∞ or -∞, unchanged except 0 ⨉ ±∞ = NaN
  573.             return p == 0 ? TimeOffset.NaN : this;
  574.         }
  575.     }

  577.     /** Divide the instance by a positive constant.
  578.      * @param q division factor (must be strictly positive)
  579.      * @return this ÷ q
  580.      */
  581.     public TimeOffset divide(final int q) {
  582.         if (q <= 0) {
  583.             throw new OrekitException(OrekitMessages.NOT_STRICTLY_POSITIVE, q);
  584.         }
  585.         if (isFinite()) {
  586.             final long      sSec  = seconds         / q;
  587.             final long      rSec  = seconds         - sSec * q;
  588.             final long      sK    = ATTOS_IN_SECOND / q;
  589.             final long      rK    = ATTOS_IN_SECOND - sK * q;
  590.             final TimeOffset tsSec = new TimeOffset(0L, sSec);
  591.             final TimeOffset trSec = new TimeOffset(0L, rSec);
  592.             return new TimeOffset(tsSec.multiply(sK).multiply(q),
  593.                                   tsSec.multiply(rK),
  594.                                   trSec.multiply(sK),
  595.                                   // here, we use the fact q is a positive int (not a long!)
  596.                                   // hence rSec * rK < q² does not overflow
  597.                                   new TimeOffset(0L, (attoSeconds + rSec * rK) / q));
  598.         } else {
  599.             // already NaN, +∞ or -∞, unchanged as q > 0
  600.             return this;
  601.         }
  602.     }

  604.     /** Negate the instance.
  605.      * @return new instance corresponding to opposite time
  606.      */
  607.     public TimeOffset negate() {
  608.         // handle special cases
  609.         if (attoSeconds < 0) {
  610.             // gather all special cases in one big check to avoid rare multiple tests
  611.             return isNaN() ? this : (seconds < 0 ? POSITIVE_INFINITY : NEGATIVE_INFINITY);
  612.         } else {
  613.             // the negative number of attoseconds will be normalized back to positive by the constructor
  614.             return new TimeOffset(-seconds, -attoSeconds);
  615.         }
  616.     }

  618.     /** Get the time in some unit.
  619.      * @param unit time unit
  620.      * @return time in this unit, rounded to the closest long,
  621.      * returns arbitrarily {@link Long#MAX_VALUE} for {@link #isNaN() NaN times}
  622.      */
  623.     public long getRoundedTime(final TimeUnit unit) {

  625.         // handle special cases
  626.         if (attoSeconds < 0) {
  627.             // gather all special cases in one big check to avoid rare multiple tests
  628.             return (isNaN() || seconds >= 0) ? Long.MAX_VALUE : Long.MIN_VALUE;
  629.         }

  631.         final long sign = seconds < 0L ? -1L : 1L;
  632.         switch (unit) {
  633.             case DAYS:
  634.                 return sign * ((sign * seconds + DAY.seconds / 2) / DAY.seconds);
  635.             case HOURS:
  636.                 return sign * ((sign * seconds + HOUR.seconds / 2) / HOUR.seconds);
  637.             case MINUTES:
  638.                 return sign * ((sign * seconds + MINUTE.seconds / 2) / MINUTE.seconds);
  639.             case SECONDS:
  640.                 return seconds + ((attoSeconds >= ATTOS_IN_SECOND / 2) ? 1 : 0);
  641.             case MILLISECONDS:
  642.                 return seconds * MILLIS_IN_SECOND +
  643.                        (attoSeconds + MILLISECOND.attoSeconds / 2) / MILLISECOND.attoSeconds;
  644.             case MICROSECONDS:
  645.                 return seconds * MICROS_IN_SECOND +
  646.                        (attoSeconds + MICROSECOND.attoSeconds / 2) / MICROSECOND.attoSeconds;
  647.             case NANOSECONDS:
  648.                 return seconds * NANOS_IN_SECOND +
  649.                        (attoSeconds + NANOSECOND.attoSeconds / 2) / NANOSECOND.attoSeconds;
  650.             default:
  651.                 throw new OrekitException(OrekitMessages.UNKNOWN_UNIT, unit.name());
  652.         }
  653.     }

  655.     /** Get the normalized seconds part of the time.
  656.      * @return normalized seconds part of the time (may be negative)
  657.      */
  658.     public long getSeconds() {
  659.         return seconds;
  660.     }

  662.     /** Get the normalized attoseconds part of the time.
  663.      * <p>
  664.      * The normalized attoseconds is always between {@code 0L} and
  665.      * {@code 1000000000000000000L} for <em>finite</em> ranges. Note that it
  666.      * may reach {@code 1000000000000000000L} if for example the time is less
  667.      * than 1 attosecond <em>before</em> a whole second. It is negative
  668.      * for {@link #isNaN() NaN} or {@link #isInfinite() infinite} times.
  669.      * </p>
  670.      * @return normalized attoseconds part of the time
  671.      */
  672.     public long getAttoSeconds() {
  673.         return attoSeconds;
  674.     }

  676.     /** Get the time collapsed into a single double.
  677.      * <p>
  678.      * Beware that lots of accuracy is lost when combining {@link #getSeconds()} and {@link #getAttoSeconds()}
  679.      * into a single double.
  680.      * </p>
  681.      * @return time as a single double
  682.      */
  683.     public double toDouble() {
  684.         if (isFinite()) {
  685.             // regular value
  686.             long closeSeconds      = seconds;
  687.             long signedAttoSeconds = attoSeconds;
  688.             if (attoSeconds > ATTOS_IN_HALF_SECOND) {
  689.                 // we are closer to next second than to previous one
  690.                 // take this into account in the computation
  691.                 // in order to avoid losing precision
  692.                 closeSeconds++;
  693.                 signedAttoSeconds -= ATTOS_IN_SECOND;
  694.             }
  695.             return closeSeconds + ((double) signedAttoSeconds) / ATTOS_IN_SECOND;
  696.         } else {
  697.             // special values
  698.             return isNaN() ? Double.NaN : FastMath.copySign(Double.POSITIVE_INFINITY, seconds);
  699.         }
  700.     }

  702.     /** Parse a string to produce an accurate split time.
  703.      * <p>
  704.      * This method is more accurate than parsing the string as a double and then
  705.      * calling {@link TimeOffset#TimeOffset(double)} because it reads the before
  706.      * separator and after separator parts in decimal, hence avoiding problems like
  707.      * for example 0.1 not being an exact IEEE754 number.
  708.      * </p>
  709.      * @param s string to parse
  710.      * @return parsed split time
  711.      */
  712.     public static TimeOffset parse(final String s) {

  714.         // decompose the string
  715.         // we use neither Long.parseLong nor Integer.parseInt because we want to avoid
  716.         // performing several loops over the characters as we need to keep track of
  717.         // delimiters decimal point and exponent marker positions
  718.         final int length = s.length();
  719.         long significandSign = 1L;
  720.         int  exponentSign    = 1;
  721.         int  separatorIndex  = length;
  722.         int  exponentIndex   = length;
  723.         long beforeSeparator = 0L;
  724.         long afterSeparator  = 0L;
  725.         int  exponent        = 0;
  726.         int  digitsBefore    = 0;
  727.         int  digitsAfter     = 0;
  728.         int  digitsExponent  = 0;
  729.         int index = 0;
  730.         while (index < length) {

  732.             // current character
  733.             final char c = s.charAt(index);

  735.             if (Character.isDigit(c)) {
  736.                 if (separatorIndex == length) {
  737.                     // we are parsing the part before separator
  738.                     ++digitsBefore;
  739.                     beforeSeparator = beforeSeparator * 10 + c - '0';
  740.                     if (digitsBefore > 19 || beforeSeparator < 0) {
  741.                         // overflow occurred
  742.                         break;
  743.                     }
  744.                 } else if (exponentIndex == length) {
  745.                     // we are parsing the part between separator and exponent
  746.                     if (digitsAfter < DIGITS_ATTOS) {
  747.                         // we never overflow here, we just ignore extra digits
  748.                         afterSeparator = afterSeparator * 10 + c - '0';
  749.                         ++digitsAfter;
  750.                     }
  751.                 } else {
  752.                     // we are parsing the exponent
  753.                     ++digitsExponent;
  754.                     exponent = exponent * 10 + c - '0';
  755.                     if (digitsExponent > 10 || exponent < 0) {
  756.                         // overflow occurred
  757.                         break;
  758.                     }
  759.                 }
  760.             } else if (c == '.' && separatorIndex == length) {
  761.                 separatorIndex = index;
  762.             } else if ((c == 'e' || c == 'E') && exponentIndex == length) {
  763.                 if (separatorIndex == length) {
  764.                     separatorIndex = index;
  765.                 }
  766.                 exponentIndex = index;
  767.             } else if (c == '-') {
  768.                 if (index == 0) {
  769.                     significandSign = -1L;
  770.                 } else if (index == exponentIndex + 1) {
  771.                     exponentSign = -1;
  772.                 } else {
  773.                     break;
  774.                 }
  775.             } else if (c == '+') {
  776.                 if (index == 0) {
  777.                     significandSign = 1L;
  778.                 } else if (index == exponentIndex + 1) {
  779.                     exponentSign = 1;
  780.                 } else {
  781.                     break;
  782.                 }
  783.             } else {
  784.                 break;
  785.             }

  787.             ++index;

  789.         }

  791.         if (length == 0 || index < length) {
  792.             // decomposition failed, either it is a special case or an unparsable string
  793.             if (s.equals("-∞")) {
  794.                 return TimeOffset.NEGATIVE_INFINITY;
  795.             } else if (s.equals("+∞")) {
  796.                 return TimeOffset.POSITIVE_INFINITY;
  797.             } else if (s.equalsIgnoreCase("NaN")) {
  798.                 return TimeOffset.NaN;
  799.             } else {
  800.                 throw new OrekitException(OrekitMessages.CANNOT_PARSE_DATA, s);
  801.             }
  802.         }

  804.         // decomposition was successful, build the split time
  805.         long seconds;
  806.         long attoseconds;
  807.         if (exponentSign < 0) {
  808.             // the part before separator must be split into seconds and attoseconds
  809.             if (exponent >= MULTIPLIERS.length) {
  810.                 seconds = 0L;
  811.                 if (exponent - DIGITS_ATTOS >= MULTIPLIERS.length) {
  812.                     // underflow
  813.                     attoseconds = 0L;
  814.                 } else {
  815.                     attoseconds = beforeSeparator / MULTIPLIERS[exponent - DIGITS_ATTOS];
  816.                 }
  817.             } else {
  818.                 final long secondsMultiplier    = MULTIPLIERS[exponent];
  819.                 final long attoBeforeMultiplier = MULTIPLIERS[DIGITS_ATTOS - exponent];
  820.                 seconds     = beforeSeparator / secondsMultiplier;
  821.                 attoseconds = (beforeSeparator - seconds * secondsMultiplier) * attoBeforeMultiplier;
  822.                 while (digitsAfter + exponent > DIGITS_ATTOS) {
  823.                     // drop least significant digits below one attosecond
  824.                     afterSeparator /= 10;
  825.                     digitsAfter--;
  826.                 }
  827.                 final long attoAfterMultiplier = MULTIPLIERS[DIGITS_ATTOS - exponent - digitsAfter];
  828.                 attoseconds += afterSeparator * attoAfterMultiplier;
  829.             }
  830.         } else {
  831.             // the part after separator must be split into seconds and attoseconds
  832.             if (exponent >= MULTIPLIERS.length) {
  833.                 if (beforeSeparator == 0L && afterSeparator == 0L) {
  834.                     return TimeOffset.ZERO;
  835.                 } else if (significandSign < 0) {
  836.                     return TimeOffset.NEGATIVE_INFINITY;
  837.                 } else {
  838.                     return TimeOffset.POSITIVE_INFINITY;
  839.                 }
  840.             } else {
  841.                 final long secondsMultiplier = MULTIPLIERS[exponent];
  842.                 seconds = beforeSeparator * secondsMultiplier;
  843.                 if (exponent > digitsAfter) {
  844.                     seconds += afterSeparator * MULTIPLIERS[exponent - digitsAfter];
  845.                     attoseconds = 0L;
  846.                 } else {
  847.                     final long q = afterSeparator / MULTIPLIERS[digitsAfter - exponent];
  848.                     seconds    += q;
  849.                     attoseconds = (afterSeparator - q * MULTIPLIERS[digitsAfter - exponent]) *
  850.                                   MULTIPLIERS[DIGITS_ATTOS - digitsAfter + exponent];
  851.                 }
  852.             }
  853.         }

  855.         return new TimeOffset(significandSign * seconds, significandSign * attoseconds);

  857.     }

  859.     /** Compare the instance with another one.
  860.      * <p>
  861.      * Not that in order to be consistent with {@code Double#compareTo(Double)},
  862.      * NaN is considered equal to itself and greater than positive infinity.
  863.      * </p>
  864.      * @param other other time to compare the instance to
  865.      * @return a negative integer, zero, or a positive integer if applying this time
  866.      * to reference date would result in a date being before, simultaneous, or after
  867.      * the date obtained by applying the other time to the same reference date.
  868.      */
  869.     public int compareTo(final TimeOffset other) {
  870.         if (isFinite()) {
  871.             if (other.isFinite()) {
  872.                 return seconds == other.seconds ?
  873.                        Long.compare(attoSeconds, other.attoSeconds) :
  874.                        Long.compare(seconds, other.seconds);
  875.             } else {
  876.                 // if other is ±∞ or NaN, and NaN is considered larger than +∞
  877.                 return other.isNegativeInfinity() ? 1 : -1;
  878.             }
  879.         } else {
  880.             // instance is ±∞ or NaN, and NaN is considered larger than +∞
  881.             if (isNaN()) {
  882.                 // for consistency with Double.compareTo, NaN is considered equal to itself
  883.                 return other.isNaN() ? 0 : 1;
  884.             } else if (other.isNaN()) {
  885.                 return -1;
  886.             } else {
  887.                 // instance is ±∞, other is either finite or ±∞ but not NaN
  888.                 // at infinity, seconds are set to either Long.MIN_VALUE or Long.MAX_VALUE
  889.                 return Long.compare(seconds, other.seconds);
  890.             }
  891.         }
  892.     }

  894.     /** {@inheritDoc} */
  895.     @Override
  896.     public boolean equals(final Object o) {
  897.         if (this == o) {
  898.             return true;
  899.         }
  900.         if (o == null || o.getClass() != this.getClass()) {
  901.             return false;
  902.         }
  903.         final TimeOffset timeOffset = (TimeOffset) o;
  904.         return seconds == timeOffset.seconds && attoSeconds == timeOffset.attoSeconds;
  905.     }

  907.     /** {@inheritDoc} */
  908.     @Override
  909.     public int hashCode() {
  910.         return Long.hashCode(seconds) ^ Long.hashCode(attoSeconds);
  911.     }

  913.     /** Local class for summing several instances. */
  914.     private static class RunningSum {

  916.         /** Number of terms that can be added before normalization is needed. */
  917.         private static final int COUNT_DOWN_MAX = 9;

  919.         /** Seconds part. */
  920.         private long seconds;

  922.         /** AttoSeconds part. */
  923.         private long attoSeconds;

  925.         /** Indicator for NaN presence. */
  926.         private boolean addedNaN;

  928.         /** Indicator for +∞ presence. */
  929.         private boolean addedPositiveInfinity;

  931.         /** Indicator for -∞ presence. */
  932.         private boolean addedNegativeInfinity;

  934.         /** Countdown for checking carry. */
  935.         private int countDown;

  937.         /** Simple constructor.
  938.          */
  939.         RunningSum() {
  940.             countDown = COUNT_DOWN_MAX;
  941.         }

  943.         /** Add one term.
  944.          * @param term term to add
  945.          */
  946.         public void add(final TimeOffset term) {
  947.             if (term.isFinite()) {
  948.                 // regular addition
  949.                 seconds     += term.seconds;
  950.                 attoSeconds += term.attoSeconds;
  951.                 if (--countDown == 0) {
  952.                     // we have added several terms, we should normalize
  953.                     // the fields before attoseconds overflow (it may overflow after 9 additions)
  954.                     normalize();
  955.                 }
  956.             } else if (term.isNegativeInfinity()) {
  957.                 addedNegativeInfinity = true;
  958.             } else if (term.isPositiveInfinity()) {
  959.                 addedPositiveInfinity = true;
  960.             } else {
  961.                 addedNaN = true;
  962.             }
  963.         }

  965.         /** Normalize current running sum.
  966.          * @return normalized value
  967.          */
  968.         public TimeOffset normalize() {

  970.             // after normalization, we will have the equivalent of one entry processed
  971.             countDown = COUNT_DOWN_MAX - 1;

  973.             if (addedNaN || addedNegativeInfinity && addedPositiveInfinity) {
  974.                 // we have built a NaN
  975.                 seconds     = NaN.seconds;
  976.                 attoSeconds = NaN.attoSeconds;
  977.                 return NaN;
  978.             } else if (addedNegativeInfinity) {
  979.                 // we have built -∞
  980.                 seconds     = NEGATIVE_INFINITY.seconds;
  981.                 attoSeconds = NEGATIVE_INFINITY.attoSeconds;
  982.                 return NEGATIVE_INFINITY;
  983.             } else if (addedPositiveInfinity) {
  984.                 // we have built +∞
  985.                 seconds     = POSITIVE_INFINITY.seconds;
  986.                 attoSeconds = POSITIVE_INFINITY.attoSeconds;
  987.                 return POSITIVE_INFINITY;
  988.             } else {
  989.                 // this is a regular time
  990.                 final TimeOffset regular = new TimeOffset(seconds, attoSeconds);
  991.                 seconds     = regular.seconds;
  992.                 attoSeconds = regular.attoSeconds;
  993.                 return regular;
  994.             }
  995.         }

  997.     }

  999. }
Created with JaCoCo 0.8.12.202403310830