FieldAbsoluteDate.java

  1. /* Copyright 2002-2018 CS Systèmes d'Information
  2.  * Licensed to CS Systèmes d'Information (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 java.util.Date;
  20. import java.util.TimeZone;

  22. import org.hipparchus.Field;
  23. import org.hipparchus.RealFieldElement;
  24. import org.hipparchus.util.FastMath;
  25. import org.orekit.errors.OrekitException;
  26. import org.orekit.errors.OrekitMessages;
  27. import org.orekit.utils.Constants;

  29. /** This class represents a specific instant in time.

  31.  * <p>Instances of this class are considered to be absolute in the sense
  32.  * that each one represent the occurrence of some event and can be compared
  33.  * to other instances or located in <em>any</em> {@link TimeScale time scale}. In
  34.  * other words the different locations of an event with respect to two different
  35.  * time scales (say {@link TAIScale TAI} and {@link UTCScale UTC} for example) are
  36.  * simply different perspective related to a single object. Only one
  37.  * <code>FieldAbsoluteDate<T></code> instance is needed, both representations being available
  38.  * from this single instance by specifying the time scales as parameter when calling
  39.  * the ad-hoc methods.</p>
  40.  *
  41.  * <p>Since an instance is not bound to a specific time-scale, all methods related
  42.  * to the location of the date within some time scale require to provide the time
  43.  * scale as an argument. It is therefore possible to define a date in one time scale
  44.  * and to use it in another one. An example of such use is to read a date from a file
  45.  * in UTC and write it in another file in TAI. This can be done as follows:</p>
  46.  * <pre>
  47.  *   DateTimeComponents utcComponents = readNextDate();
  48.  *   FieldAbsoluteDate<T> date = new FieldAbsoluteDate<>(utcComponents, TimeScalesFactory.getUTC());
  49.  *   writeNextDate(date.getComponents(TimeScalesFactory.getTAI()));
  50.  * </pre>
  51.  *
  52.  * <p>Two complementary views are available:</p>
  53.  * <ul>
  54.  *   <li><p>location view (mainly for input/output or conversions)</p>
  55.  *   <p>locations represent the coordinate of one event with respect to a
  56.  *   {@link TimeScale time scale}. The related methods are {@link
  57.  *   #FieldAbsoluteDate(Field, DateComponents, TimeComponents, TimeScale)}, {@link
  58.  *   #FieldAbsoluteDate(Field, int, int, int, int, int, double, TimeScale)}, {@link
  59.  *   #FieldAbsoluteDate(Field, int, int, int, TimeScale)}, {@link #FieldAbsoluteDate(Field,
  60.  *   Date, TimeScale)}, {@link #createGPSDate(int, RealFieldElement)}, {@link
  61.  *   #parseCCSDSCalendarSegmentedTimeCode(byte, byte[])}, toString(){@link
  62.  *   #toDate(TimeScale)}, {@link #toString(TimeScale) toString(timeScale)},
  63.  *   {@link #toString()}, and {@link #timeScalesOffset}.</p>
  64.  *   </li>
  65.  *   <li><p>offset view (mainly for physical computation)</p>
  66.  *   <p>offsets represent either the flow of time between two events
  67.  *   (two instances of the class) or durations. They are counted in seconds,
  68.  *   are continuous and could be measured using only a virtually perfect stopwatch.
  69.  *   The related methods are {@link #FieldAbsoluteDate(FieldAbsoluteDate, double)},
  70.  *   {@link #parseCCSDSUnsegmentedTimeCode(Field, byte, byte, byte[], FieldAbsoluteDate)},
  71.  *   {@link #parseCCSDSDaySegmentedTimeCode(Field, byte, byte[], DateComponents)},
  72.  *   {@link #durationFrom(FieldAbsoluteDate)}, {@link #compareTo(FieldAbsoluteDate)}, {@link #equals(Object)}
  73.  *   and {@link #hashCode()}.</p>
  74.  *   </li>
  75.  * </ul>
  76.  * <p>
  77.  * A few reference epochs which are commonly used in space systems have been defined. These
  78.  * epochs can be used as the basis for offset computation. The supported epochs are:
  79.  * {@link #getJulianEpoch(Field)}, {@link #getModifiedJulianEpoch(Field)}, {@link #getFiftiesEpoch(Field)},
  80.  * {@link #getCCSDSEpoch(Field)}, {@link #getGalileoEpoch(Field)}, {@link #getGPSEpoch(Field)},
  81.  * {@link #getJ2000Epoch(Field)}, {@link #getJavaEpoch(Field)}. There are also two factory methods
  82.  * {@link #createJulianEpoch(RealFieldElement)} and {@link #createBesselianEpoch(RealFieldElement)}
  83.  * that can be used to compute other reference epochs like J1900.0 or B1950.0.
  84.  * In addition to these reference epochs, two other constants are defined for convenience:
  85.  * {@link #getPastInfinity(Field)} and {@link #getFutureInfinity(Field)}, which can be used either
  86.  * as dummy dates when a date is not yet initialized, or for initialization of loops searching for
  87.  * a min or max date.
  88.  * </p>
  89.  * <p>
  90.  * Instances of the <code>FieldAbsoluteDate<T></code> class are guaranteed to be immutable.
  91.  * </p>
  92.  * @author Luc Maisonobe
  93.  * @see TimeScale
  94.  * @see TimeStamped
  95.  * @see ChronologicalComparator
  96.  */
  97. public class FieldAbsoluteDate<T extends RealFieldElement<T>>
  98.     implements FieldTimeStamped<T>, TimeShiftable<FieldAbsoluteDate<T>>, Comparable<FieldAbsoluteDate<T>> {

  100.     /** Reference epoch in seconds from 2000-01-01T12:00:00 TAI.
  101.      * <p>Beware, it is not {@link #getJ2000Epoch(Field)} since it is in TAI and not in TT.</p> */
  102.     private final long epoch;

  104.     /** Offset from the reference epoch in seconds. */
  105.     private final  T offset;

  107.     /** Field used by default.*/
  108.     private Field<T> field;

  110.     /** Build an instance from an AbsoluteDate.
  111.      * @param field used by default
  112.      * @param date AbsoluteDate to instantiate as a FieldAbsoluteDate
  113.      */
  114.     public FieldAbsoluteDate(final Field<T> field, final AbsoluteDate date) {
  115.         this.field  = field;
  116.         this.epoch  = date.getEpoch();
  117.         this.offset = field.getZero().add(date.getOffset());
  118.     }

  120.     /** Create an instance with a default value ({@link #getJ2000Epoch(Field)}).
  121.      * @param field field used by default
  122.      */
  123.     public FieldAbsoluteDate(final Field<T> field) {
  124.         final FieldAbsoluteDate<T> j2000 = getJ2000Epoch(field);
  125.         this.field  = j2000.field;
  126.         this.epoch  = j2000.epoch;
  127.         this.offset = j2000.offset;
  128.     }

  130.     /** Build an instance from an elapsed duration since to another instant.
  131.      * <p>It is important to note that the elapsed duration is <em>not</em>
  132.      * the difference between two readings on a time scale. As an example,
  133.      * the duration between the two instants leading to the readings
  134.      * 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the {@link UTCScale UTC}
  135.      * time scale is <em>not</em> 1 second, but a stop watch would have measured
  136.      * an elapsed duration of 2 seconds between these two instances because a leap
  137.      * second was introduced at the end of 2005 in this time scale.</p>
  138.      * <p>This constructor is the reverse of the {@link #durationFrom(FieldAbsoluteDate)}
  139.      * method.</p>
  140.      * @param since start instant of the measured duration
  141.      * @param elapsedDuration physically elapsed duration from the <code>since</code>
  142.      * instant, as measured in a regular time scale
  143.      * @see #durationFrom(FieldAbsoluteDate)
  144.      */
  145.     public FieldAbsoluteDate(final FieldAbsoluteDate<T> since, final T elapsedDuration) {
  146.         this.field = since.field;
  147.         final T sum = since.offset.add(elapsedDuration);
  148.         if (Double.isInfinite(sum.getReal())) {
  149.             offset = sum;
  150.             epoch  = (sum.getReal() < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
  151.         } else {
  152.             // compute sum exactly, using Møller-Knuth TwoSum algorithm without branching
  153.             // the following statements must NOT be simplified, they rely on floating point
  154.             // arithmetic properties (rounding and representable numbers)
  155.             // at the end, the EXACT result of addition since.offset + elapsedDuration
  156.             // is sum + residual, where sum is the closest representable number to the exact
  157.             // result and residual is the missing part that does not fit in the first number
  158.             final double oPrime   = sum.getReal() - elapsedDuration.getReal();
  159.             final double dPrime   = sum.getReal() - oPrime;
  160.             final double deltaO   = since.offset.getReal() - oPrime;
  161.             final double deltaD   = elapsedDuration.getReal() - dPrime;
  162.             final double residual = deltaO + deltaD;
  163.             final long   dl       = (long) FastMath.floor(sum.getReal());
  164.             offset = sum.subtract(dl).add(residual);
  165.             epoch  = since.epoch + dl;
  166.         }
  167.     }

  169.     /** Build an instance from a location (parsed from a string) in a {@link TimeScale time scale}.
  170.      * <p>
  171.      * The supported formats for location are mainly the ones defined in ISO-8601 standard,
  172.      * the exact subset is explained in {@link DateTimeComponents#parseDateTime(String)},
  173.      * {@link DateComponents#parseDate(String)} and {@link TimeComponents#parseTime(String)}.
  174.      * </p>
  175.      * <p>
  176.      * As CCSDS ASCII calendar segmented time code is a trimmed down version of ISO-8601,
  177.      * it is also supported by this constructor.
  178.      * </p>
  179.      * @param field field utilized by default
  180.      * @param location location in the time scale, must be in a supported format
  181.      * @param timeScale time scale
  182.      * @exception IllegalArgumentException if location string is not in a supported format
  183.      */
  184.     public FieldAbsoluteDate(final Field<T> field, final String location, final TimeScale timeScale) {
  185.         this(field, DateTimeComponents.parseDateTime(location), timeScale);
  186.     }

  188.     /** Build an instance from a location in a {@link TimeScale time scale}.
  189.      * @param field field utilized by default
  190.      * @param location location in the time scale
  191.      * @param timeScale time scale
  192.      */
  193.     public FieldAbsoluteDate(final Field<T> field, final DateTimeComponents location, final TimeScale timeScale) {
  194.         this(field, location.getDate(), location.getTime(), timeScale);
  195.     }

  197.     /** Build an instance from a location in a {@link TimeScale time scale}.
  198.      * @param field field utilized by default
  199.      * @param date date location in the time scale
  200.      * @param time time location in the time scale
  201.      * @param timeScale time scale
  202.      */
  203.     public FieldAbsoluteDate(final Field<T> field, final DateComponents date, final TimeComponents time,
  204.                              final TimeScale timeScale) {
  205.         final double seconds  = time.getSecond();
  206.         final double tsOffset = timeScale.offsetToTAI(date, time);

  208.         // compute sum exactly, using Møller-Knuth TwoSum algorithm without branching
  209.         // the following statements must NOT be simplified, they rely on floating point
  210.         // arithmetic properties (rounding and representable numbers)
  211.         // at the end, the EXACT result of addition seconds + tsOffset
  212.         // is sum + residual, where sum is the closest representable number to the exact
  213.         // result and residual is the missing part that does not fit in the first number
  214.         final double sum      = seconds + tsOffset;
  215.         final double sPrime   = sum - tsOffset;
  216.         final double tPrime   = sum - sPrime;
  217.         final double deltaS   = seconds  - sPrime;
  218.         final double deltaT   = tsOffset - tPrime;
  219.         final double residual = deltaS   + deltaT;
  220.         final long   dl       = (long) FastMath.floor(sum);

  222.         offset = field.getZero().add((sum - dl) + residual);

  224.         epoch  = 60l * ((date.getJ2000Day() * 24l + time.getHour()) * 60l +
  225.                         time.getMinute() - time.getMinutesFromUTC() - 720l) + dl;
  226.         this.field = field;

  228.     }

  230.     /** Build an instance from a location in a {@link TimeScale time scale}.
  231.      * @param field field utilized by default
  232.      * @param year year number (may be 0 or negative for BC years)
  233.      * @param month month number from 1 to 12
  234.      * @param day day number from 1 to 31
  235.      * @param hour hour number from 0 to 23
  236.      * @param minute minute number from 0 to 59
  237.      * @param second second number from 0.0 to 60.0 (excluded)
  238.      * @param timeScale time scale
  239.      * @exception IllegalArgumentException if inconsistent arguments
  240.      * are given (parameters out of range)
  241.      */
  242.     public FieldAbsoluteDate(final Field<T> field, final int year, final int month, final int day,
  243.                              final int hour, final int minute, final double second,
  244.                              final TimeScale timeScale) throws IllegalArgumentException {
  245.         this(field, new DateComponents(year, month, day), new TimeComponents(hour, minute, second), timeScale);
  246.     }

  248.     /** Build an instance from a location in a {@link TimeScale time scale}.
  249.      * @param field field utilized by default
  250.      * @param year year number (may be 0 or negative for BC years)
  251.      * @param month month enumerate
  252.      * @param day day number from 1 to 31
  253.      * @param hour hour number from 0 to 23
  254.      * @param minute minute number from 0 to 59
  255.      * @param second second number from 0.0 to 60.0 (excluded)
  256.      * @param timeScale time scale
  257.      * @exception IllegalArgumentException if inconsistent arguments
  258.      * are given (parameters out of range)
  259.      */
  260.     public FieldAbsoluteDate(final Field<T> field, final int year, final Month month, final int day,
  261.                              final int hour, final int minute, final double second,
  262.                              final TimeScale timeScale) throws IllegalArgumentException {
  263.         this(field, new DateComponents(year, month, day), new TimeComponents(hour, minute, second), timeScale);
  264.     }

  266.     /** Build an instance from a location in a {@link TimeScale time scale}.
  267.      * <p>The hour is set to 00:00:00.000.</p>
  268.      * @param field field utilized by default
  269.      * @param date date location in the time scale
  270.      * @param timeScale time scale
  271.      * @exception IllegalArgumentException if inconsistent arguments
  272.      * are given (parameters out of range)
  273.      */
  274.     public FieldAbsoluteDate(final Field<T> field, final DateComponents date, final TimeScale timeScale)
  275.         throws IllegalArgumentException {
  276.         this(field, date, TimeComponents.H00, timeScale);
  277.     }

  279.     /** Build an instance from a location in a {@link TimeScale time scale}.
  280.      * <p>The hour is set to 00:00:00.000.</p>
  281.      * @param field field utilized by default
  282.      * @param year year number (may be 0 or negative for BC years)
  283.      * @param month month number from 1 to 12
  284.      * @param day day number from 1 to 31
  285.      * @param timeScale time scale
  286.      * @exception IllegalArgumentException if inconsistent arguments
  287.      * are given (parameters out of range)
  288.      */
  289.     public FieldAbsoluteDate(final Field<T> field, final int year, final int month, final int day,
  290.                         final TimeScale timeScale) throws IllegalArgumentException {
  291.         this(field, new DateComponents(year, month, day), TimeComponents.H00, timeScale);
  292.     }

  294.     /** Build an instance from a location in a {@link TimeScale time scale}.
  295.      * <p>The hour is set to 00:00:00.000.</p>
  296.      * @param field field utilized by default
  297.      * @param year year number (may be 0 or negative for BC years)
  298.      * @param month month enumerate
  299.      * @param day day number from 1 to 31
  300.      * @param timeScale time scale
  301.      * @exception IllegalArgumentException if inconsistent arguments
  302.      * are given (parameters out of range)
  303.      */
  304.     public FieldAbsoluteDate(final Field<T> field, final int year, final Month month, final int day,
  305.                         final TimeScale timeScale) throws IllegalArgumentException {
  306.         this(field, new DateComponents(year, month, day), TimeComponents.H00, timeScale);
  307.     }

  309.     /** Build an instance from a location in a {@link TimeScale time scale}.
  310.      * @param field field utilized as default
  311.      * @param location location in the time scale
  312.      * @param timeScale time scale
  313.      */
  314.     public FieldAbsoluteDate(final Field<T> field, final Date location, final TimeScale timeScale) {
  315.         this(field, new DateComponents(DateComponents.JAVA_EPOCH,
  316.                                 (int) (location.getTime() / 86400000l)),
  317.                                 new TimeComponents(0.001 * (location.getTime() % 86400000l)),
  318.              timeScale);
  319.     }


  322.     /** Build an instance from an elapsed duration since to another instant.
  323.      * <p>It is important to note that the elapsed duration is <em>not</em>
  324.      * the difference between two readings on a time scale.
  325.      * @param since start instant of the measured duration
  326.      * @param elapsedDuration physically elapsed duration from the <code>since</code>
  327.      * instant, as measured in a regular time scale
  328.      */
  329.     public FieldAbsoluteDate(final FieldAbsoluteDate<T> since, final double elapsedDuration) {
  330.         this.field = since.field;
  331.         final T sum = since.offset.add(elapsedDuration);
  332.         if (Double.isInfinite(sum.getReal())) {
  333.             offset = sum;
  334.             epoch  = (sum.getReal() < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
  335.         } else {
  336.             // compute sum exactly, using Møller-Knuth TwoSum algorithm without branching
  337.             // the following statements must NOT be simplified, they rely on floating point
  338.             // arithmetic properties (rounding and representable numbers)
  339.             // at the end, the EXACT result of addition since.offset + elapsedDuration
  340.             // is sum + residual, where sum is the closest representable number to the exact
  341.             // result and residual is the missing part that does not fit in the first number
  342.             final double oPrime   = sum.getReal() - elapsedDuration;
  343.             final double dPrime   = sum.getReal() - oPrime;
  344.             final double deltaO   = since.offset.getReal() - oPrime;
  345.             final double deltaD   = elapsedDuration - dPrime;
  346.             final double residual = deltaO + deltaD;
  347.             final long   dl       = (long) FastMath.floor(sum.getReal());
  348.             offset = sum.subtract(dl).add(residual);
  349.             epoch  = since.epoch + dl;
  350.         }
  351.     }


  354.     /** Build an instance from an elapsed duration since to another instant.
  355.      * <p>It is important to note that the elapsed duration is <em>not</em>
  356.      * the difference between two readings on a time scale.
  357.      * @param since start instant of the measured duration
  358.      * @param elapsedDuration physically elapsed duration from the <code>since</code>
  359.      * instant, as measured in a regular time scale
  360.      */
  361.     public FieldAbsoluteDate(final AbsoluteDate since, final T elapsedDuration) {
  362.         this.field = elapsedDuration.getField();
  363.         final double dT = since.durationFrom(AbsoluteDate.J2000_EPOCH);
  364.         final T deltaT = elapsedDuration.add(dT);
  365.         final FieldAbsoluteDate<T> j2000 =  getJ2000Epoch(elapsedDuration.getField()).shiftedBy(deltaT);
  366.         offset = j2000.offset;
  367.         epoch = j2000.epoch;
  368.     }

  370.     /** Build an instance from an apparent clock offset with respect to another
  371.      * instant <em>in the perspective of a specific {@link TimeScale time scale}</em>.
  372.      * <p>It is important to note that the apparent clock offset <em>is</em> the
  373.      * difference between two readings on a time scale and <em>not</em> an elapsed
  374.      * duration. As an example, the apparent clock offset between the two instants
  375.      * leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the
  376.      * {@link UTCScale UTC} time scale is 1 second, but the elapsed duration is 2
  377.      * seconds because a leap second has been introduced at the end of 2005 in this
  378.      * time scale.</p>
  379.      * <p>This constructor is the reverse of the {@link #offsetFrom(FieldAbsoluteDate,
  380.      * TimeScale)} method.</p>
  381.      * @param reference reference instant
  382.      * @param apparentOffset apparent clock offset from the reference instant
  383.      * (difference between two readings in the specified time scale)
  384.      * @param timeScale time scale with respect to which the offset is defined
  385.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  386.      */
  387.     public FieldAbsoluteDate(final FieldAbsoluteDate<T> reference, final double apparentOffset, final TimeScale timeScale) {
  388.         this(reference.field, new DateTimeComponents(reference.getComponents(timeScale), apparentOffset),
  389.              timeScale);
  390.     }

  392.     /** Build an instance from a CCSDS Unsegmented Time Code (CUC).
  393.      * <p>
  394.      * CCSDS Unsegmented Time Code is defined in the blue book:
  395.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  396.      * </p>
  397.      * <p>
  398.      * If the date to be parsed is formatted using version 3 of the standard
  399.      * (CCSDS 301.0-B-3 published in 2002) or if the extension of the preamble
  400.      * field introduced in version 4 of the standard is not used, then the
  401.      * {@code preambleField2} parameter can be set to 0.
  402.      * </p>
  403.      * @param field field for the components
  404.      * @param preambleField1 first byte of the field specifying the format, often
  405.      * not transmitted in data interfaces, as it is constant for a given data interface
  406.      * @param preambleField2 second byte of the field specifying the format
  407.      * (added in revision 4 of the CCSDS standard in 2010), often not transmitted in data
  408.      * interfaces, as it is constant for a given data interface (value ignored if presence
  409.      * not signaled in {@code preambleField1})
  410.      * @param timeField byte array containing the time code
  411.      * @param agencyDefinedEpoch reference epoch, ignored if the preamble field
  412.      * specifies the {@link #getCCSDSEpoch(Field) CCSDS reference epoch} is used (and hence
  413.      * may be null in this case)
  414.      * @return an instance corresponding to the specified date
  415.      * @throws OrekitException if preamble is inconsistent with Unsegmented Time Code,
  416.      * or if it is inconsistent with time field, or if agency epoch is needed but not provided
  417.      * @param <T> the type of the field elements
  418.      */
  419.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSUnsegmentedTimeCode(final Field<T> field,
  420.                                                                                                      final byte preambleField1,
  421.                                                                                                      final byte preambleField2,
  422.                                                                                                      final byte[] timeField,
  423.                                                                                                      final FieldAbsoluteDate<T> agencyDefinedEpoch)
  424.         throws OrekitException {

  426.         // time code identification and reference epoch
  427.         final FieldAbsoluteDate<T> epochF;
  428.         switch (preambleField1 & 0x70) {
  429.             case 0x10:
  430.                 // the reference epoch is CCSDS epoch 1958-01-01T00:00:00 TAI
  431.                 epochF = getCCSDSEpoch(field);
  432.                 break;
  433.             case 0x20:
  434.                 // the reference epoch is agency defined
  435.                 if (agencyDefinedEpoch == null) {
  436.                     throw new OrekitException(OrekitMessages.CCSDS_DATE_MISSING_AGENCY_EPOCH);
  437.                 }
  438.                 epochF = agencyDefinedEpoch;
  439.                 break;
  440.             default :
  441.                 throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  442.                                           formatByte(preambleField1));
  443.         }

  445.         // time field lengths
  446.         int coarseTimeLength = 1 + ((preambleField1 & 0x0C) >>> 2);
  447.         int fineTimeLength   = preambleField1 & 0x03;

  449.         if ((preambleField1 & 0x80) != 0x0) {
  450.             // there is an additional octet in preamble field
  451.             coarseTimeLength += (preambleField2 & 0x60) >>> 5;
  452.             fineTimeLength   += (preambleField2 & 0x1C) >>> 2;
  453.         }

  455.         if (timeField.length != coarseTimeLength + fineTimeLength) {
  456.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_LENGTH_TIME_FIELD,
  457.                                       timeField.length, coarseTimeLength + fineTimeLength);
  458.         }

  460.         T seconds = field.getZero();
  461.         for (int i = 0; i < coarseTimeLength; ++i) {
  462.             seconds = seconds.multiply(256).add(field.getZero().add(toUnsigned(timeField[i])));
  463.         }
  464.         T subseconds = field.getZero();
  465.         for (int i = timeField.length - 1; i >= coarseTimeLength; --i) {
  466.             subseconds = (subseconds.add(toUnsigned(timeField[i]))).divide(256);
  467.         }
  468.         return new FieldAbsoluteDate<>(epochF, seconds).shiftedBy(subseconds);

  470.     }

  472.     /** Build an instance from a CCSDS Day Segmented Time Code (CDS).
  473.      * <p>
  474.      * CCSDS Day Segmented Time Code is defined in the blue book:
  475.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  476.      * </p>
  477.      * @param field field for the components
  478.      * @param preambleField field specifying the format, often not transmitted in
  479.      * data interfaces, as it is constant for a given data interface
  480.      * @param timeField byte array containing the time code
  481.      * @param agencyDefinedEpoch reference epoch, ignored if the preamble field
  482.      * specifies the {@link #getCCSDSEpoch(Field) CCSDS reference epoch} is used (and hence
  483.      * may be null in this case)
  484.      * @return an instance corresponding to the specified date
  485.      * @throws OrekitException if preamble is inconsistent with Day Segmented Time Code,
  486.      * or if it is inconsistent with time field, or if agency epoch is needed but not provided,
  487.      * or it UTC time scale cannot be retrieved
  488.      * @param <T> the type of the field elements
  489.      */
  490.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSDaySegmentedTimeCode(final Field<T> field,
  491.                                                                                                       final byte preambleField, final byte[] timeField,
  492.                                                                                                       final DateComponents agencyDefinedEpoch)
  493.         throws OrekitException {

  495.         // time code identification
  496.         if ((preambleField & 0xF0) != 0x40) {
  497.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  498.                                       formatByte(preambleField));
  499.         }

  501.         // reference epoch
  502.         final DateComponents epochDC;
  503.         if ((preambleField & 0x08) == 0x00) {
  504.             // the reference epoch is CCSDS epoch 1958-01-01T00:00:00 TAI
  505.             epochDC = DateComponents.CCSDS_EPOCH;
  506.         } else {
  507.             // the reference epoch is agency defined
  508.             if (agencyDefinedEpoch == null) {
  509.                 throw new OrekitException(OrekitMessages.CCSDS_DATE_MISSING_AGENCY_EPOCH);
  510.             }
  511.             epochDC = agencyDefinedEpoch;
  512.         }

  514.         // time field lengths
  515.         final int daySegmentLength = ((preambleField & 0x04) == 0x0) ? 2 : 3;
  516.         final int subMillisecondLength = (preambleField & 0x03) << 1;
  517.         if (subMillisecondLength == 6) {
  518.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  519.                                       formatByte(preambleField));
  520.         }
  521.         if (timeField.length != daySegmentLength + 4 + subMillisecondLength) {
  522.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_LENGTH_TIME_FIELD,
  523.                                       timeField.length, daySegmentLength + 4 + subMillisecondLength);
  524.         }


  527.         int i   = 0;
  528.         int day = 0;
  529.         while (i < daySegmentLength) {
  530.             day = day * 256 + toUnsigned(timeField[i++]);
  531.         }

  533.         long milliInDay = 0l;
  534.         while (i < daySegmentLength + 4) {
  535.             milliInDay = milliInDay * 256 + toUnsigned(timeField[i++]);
  536.         }
  537.         final int milli   = (int) (milliInDay % 1000l);
  538.         final int seconds = (int) ((milliInDay - milli) / 1000l);

  540.         double subMilli = 0;
  541.         double divisor  = 1;
  542.         while (i < timeField.length) {
  543.             subMilli = subMilli * 256 + toUnsigned(timeField[i++]);
  544.             divisor *= 1000;
  545.         }

  547.         final DateComponents date = new DateComponents(epochDC, day);
  548.         final TimeComponents time = new TimeComponents(seconds);
  549.         return new FieldAbsoluteDate<>(field, date, time, TimeScalesFactory.getUTC()).shiftedBy(milli * 1.0e-3 + subMilli / divisor);

  551.     }

  553.     /** Build an instance from a CCSDS Calendar Segmented Time Code (CCS).
  554.      * <p>
  555.      * CCSDS Calendar Segmented Time Code is defined in the blue book:
  556.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  557.      * </p>
  558.      * @param preambleField field specifying the format, often not transmitted in
  559.      * data interfaces, as it is constant for a given data interface
  560.      * @param timeField byte array containing the time code
  561.      * @return an instance corresponding to the specified date
  562.      * @throws OrekitException if preamble is inconsistent with Calendar Segmented Time Code,
  563.      * or if it is inconsistent with time field, or it UTC time scale cannot be retrieved
  564.      */
  565.     public FieldAbsoluteDate<T> parseCCSDSCalendarSegmentedTimeCode(final byte preambleField, final byte[] timeField)
  566.         throws OrekitException {

  568.         // time code identification
  569.         if ((preambleField & 0xF0) != 0x50) {
  570.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  571.                                       formatByte(preambleField));
  572.         }

  574.         // time field length
  575.         final int length = 7 + (preambleField & 0x07);
  576.         if (length == 14) {
  577.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  578.                                       formatByte(preambleField));
  579.         }
  580.         if (timeField.length != length) {
  581.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_LENGTH_TIME_FIELD,
  582.                                       timeField.length, length);
  583.         }

  585.         // date part in the first four bytes
  586.         final DateComponents date;
  587.         if ((preambleField & 0x08) == 0x00) {
  588.             // month of year and day of month variation
  589.             date = new DateComponents(toUnsigned(timeField[0]) * 256 + toUnsigned(timeField[1]),
  590.                                       toUnsigned(timeField[2]),
  591.                                       toUnsigned(timeField[3]));
  592.         } else {
  593.             // day of year variation
  594.             date = new DateComponents(toUnsigned(timeField[0]) * 256 + toUnsigned(timeField[1]),
  595.                                       toUnsigned(timeField[2]) * 256 + toUnsigned(timeField[3]));
  596.         }

  598.         // time part from bytes 5 to last (between 7 and 13 depending on precision)
  599.         final TimeComponents time = new TimeComponents(toUnsigned(timeField[4]),
  600.                                                        toUnsigned(timeField[5]),
  601.                                                        toUnsigned(timeField[6]));
  602.         double subSecond = 0;
  603.         double divisor   = 1;
  604.         for (int i = 7; i < length; ++i) {
  605.             subSecond = subSecond * 100 + toUnsigned(timeField[i]);
  606.             divisor *= 100;
  607.         }

  609.         return new FieldAbsoluteDate<>(field, date, time, TimeScalesFactory.getUTC()).shiftedBy(subSecond / divisor);

  611.     }

  613.     /** Decode a signed byte as an unsigned int value.
  614.      * @param b byte to decode
  615.      * @return an unsigned int value
  616.      */
  617.     private static int toUnsigned(final byte b) {
  618.         final int i = (int) b;
  619.         return (i < 0) ? 256 + i : i;
  620.     }

  622.     /** Format a byte as an hex string for error messages.
  623.      * @param data byte to format
  624.      * @return a formatted string
  625.      */
  626.     private static String formatByte(final byte data) {
  627.         return "0x" + Integer.toHexString(data).toUpperCase();
  628.     }

  630.     /** Build an instance corresponding to a Julian Day date.
  631.      * @param jd Julian day
  632.      * @param secondsSinceNoon seconds in the Julian day
  633.      * (BEWARE, Julian days start at noon, so 0.0 is noon)
  634.      * @param timeScale time scale in which the seconds in day are defined
  635.      * @return a new instant
  636.      * @param <T> the type of the field elements
  637.      */
  638.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> createJDDate(final int jd, final T secondsSinceNoon,
  639.                                                                                     final TimeScale timeScale) {
  640.         return new FieldAbsoluteDate<>(secondsSinceNoon.getField(), new DateComponents(DateComponents.JULIAN_EPOCH, jd),
  641.                                        TimeComponents.H12, timeScale).shiftedBy(secondsSinceNoon);
  642.     }

  644.     /** Build an instance corresponding to a Modified Julian Day date.
  645.      * @param mjd modified Julian day
  646.      * @param secondsInDay seconds in the day
  647.      * @param timeScale time scale in which the seconds in day are defined
  648.      * @return a new instant
  649.      * @param <T> the type of the field elements
  650.      */
  651.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> createMJDDate(final int mjd, final T secondsInDay,
  652.                                                                                      final TimeScale timeScale) {
  653.         return new FieldAbsoluteDate<>(secondsInDay.getField(),
  654.                                        new DateComponents(DateComponents.MODIFIED_JULIAN_EPOCH, mjd),
  655.                                        TimeComponents.H00,
  656.                                        timeScale).shiftedBy(secondsInDay);
  657.     }

  659.     /** Build an instance corresponding to a GPS date.
  660.      * <p>GPS dates are provided as a week number starting at
  661.      * {@link #getGPSEpoch(Field) GPS epoch} and as a number of milliseconds
  662.      * since week start.</p>
  663.      * @param weekNumber week number since {@link #getGPSEpoch(Field) GPS epoch}
  664.      * @param milliInWeek number of milliseconds since week start
  665.      * @return a new instant
  666.      * @param <T> the type of the field elements
  667.      */
  668.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> createGPSDate(final int weekNumber, final T milliInWeek) {
  669.         final int day = (int) FastMath.floor(milliInWeek.getReal() / (1000.0 * Constants.JULIAN_DAY));
  670.         final T secondsInDay = milliInWeek.divide(1000.0).subtract(day * Constants.JULIAN_DAY);
  671.         return new FieldAbsoluteDate<>(milliInWeek.getField(), new DateComponents(DateComponents.GPS_EPOCH, weekNumber * 7 + day),
  672.                                        TimeComponents.H00, TimeScalesFactory.getGPS()).shiftedBy(secondsInDay);
  673.     }

  675.     /** Build an instance corresponding to a Julian Epoch (JE).
  676.      * <p>According to Lieske paper: <a
  677.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&defaultprint=YES&filetype=.pdf.">
  678.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>, Astronomy and Astrophysics,
  679.      * vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is related to Julian Ephemeris Date as:</p>
  680.      * <pre>
  681.      * JE = 2000.0 + (JED - 2451545.0) / 365.25
  682.      * </pre>
  683.      * <p>
  684.      * This method reverts the formula above and computes an {@code FieldAbsoluteDate<T>} from the Julian Epoch.
  685.      * </p>
  686.      * @param julianEpoch Julian epoch, like 2000.0 for defining the classical reference J2000.0
  687.      * @return a new instant
  688.      * @see #getJ2000Epoch(Field)
  689.      * @see #createBesselianEpoch(RealFieldElement)
  690.      * @param <T> the type of the field elements
  691.      */
  692.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> createJulianEpoch(final T julianEpoch) {
  693.         return new FieldAbsoluteDate<>(getJ2000Epoch(julianEpoch.getField()),
  694.                                        julianEpoch.subtract(2000.0).multiply(Constants.JULIAN_YEAR));
  695.     }

  697.     /** Build an instance corresponding to a Besselian Epoch (BE).
  698.      * <p>According to Lieske paper: <a
  699.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&defaultprint=YES&filetype=.pdf.">
  700.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>, Astronomy and Astrophysics,
  701.      * vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch is related to Julian Ephemeris Date as:</p>
  702.      * <pre>
  703.      * BE = 1900.0 + (JED - 2415020.31352) / 365.242198781
  704.      * </pre>
  705.      * <p>
  706.      * This method reverts the formula above and computes an {@code FieldAbsoluteDate<T>} from the Besselian Epoch.
  707.      * </p>
  708.      * @param besselianEpoch Besselian epoch, like 1950 for defining the classical reference B1950.0
  709.      * @return a new instant
  710.      * @see #createJulianEpoch(RealFieldElement)
  711.      * @param <T> the type of the field elements
  712.      */
  713.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> createBesselianEpoch(final T besselianEpoch) {
  714.         return new FieldAbsoluteDate<>(getJ2000Epoch(besselianEpoch.getField()),
  715.                                        besselianEpoch.subtract(1900).multiply(Constants.BESSELIAN_YEAR).add(
  716.                                        Constants.JULIAN_DAY * (-36525) + Constants.JULIAN_DAY * 0.31352));
  717.     }

  719.     /** Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.
  720.      * <p>Both <code>java.util.Date</code> and {@link DateComponents} classes
  721.      * follow the astronomical conventions and consider a year 0 between
  722.      * years -1 and +1, hence this reference date lies in year -4712 and not
  723.      * in year -4713 as can be seen in other documents or programs that obey
  724.      * a different convention (for example the <code>convcal</code> utility).</p>
  725.      * @param field field for the components
  726.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#JULIAN_EPOCH}
  727.      * @param <T> the type of the field elements
  728.      */
  729.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getJulianEpoch(final Field<T> field) {
  730.         return new FieldAbsoluteDate<>(field, AbsoluteDate.JULIAN_EPOCH);
  731.     }

  733.     /** Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.
  734.      * @param field field for the components
  735.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#MODIFIED_JULIAN_EPOCH}
  736.      * @param <T> the type of the field elements
  737.      */
  738.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getModifiedJulianEpoch(final Field<T> field) {
  739.         return new FieldAbsoluteDate<>(field, AbsoluteDate.MODIFIED_JULIAN_EPOCH);
  740.     }

  742.     /** Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.
  743.      * @param field field for the components
  744.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#FIFTIES_EPOCH}
  745.      * @param <T> the type of the field elements
  746.      */
  747.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getFiftiesEpoch(final Field<T> field) {
  748.         return new FieldAbsoluteDate<>(field, AbsoluteDate.FIFTIES_EPOCH);
  749.     }
  750.     /** Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4):
  751.      * 1958-01-01T00:00:00 International Atomic Time (<em>not</em> UTC).
  752.      * @param field field for the components
  753.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#CCSDS_EPOCH}
  754.      * @param <T> the type of the field elements
  755.      */
  756.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getCCSDSEpoch(final Field<T> field) {
  757.         return new FieldAbsoluteDate<>(field, AbsoluteDate.CCSDS_EPOCH);
  758.     }

  760.     /** Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.
  761.      * @param field field for the components
  762.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#GALILEO_EPOCH}
  763.      * @param <T> the type of the field elements
  764.      */
  765.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getGalileoEpoch(final Field<T> field) {
  766.         return new FieldAbsoluteDate<>(field, AbsoluteDate.GALILEO_EPOCH);
  767.     }

  769.     /** Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
  770.      * @param field field for the components
  771.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#GPS_EPOCH}
  772.      * @param <T> the type of the field elements
  773.      */
  774.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getGPSEpoch(final Field<T> field) {
  775.         return new FieldAbsoluteDate<>(field, AbsoluteDate.GPS_EPOCH);
  776.     }

  778.     /** J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (<em>not</em> UTC).
  779.      * @param field field for the components
  780.      * @see #createJulianEpoch(RealFieldElement)
  781.      * @see #createBesselianEpoch(RealFieldElement)
  782.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#J2000_EPOCH}
  783.      * @param <T> the type of the field elements
  784.      */
  785.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getJ2000Epoch(final Field<T> field) {
  786.         return new FieldAbsoluteDate<>(field, AbsoluteDate.J2000_EPOCH);
  787.     }

  789.     /** Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate.
  790.      * <p>
  791.      * Between 1968-02-01 and 1972-01-01, UTC-TAI = 4.213 170 0s + (MJD - 39 126) x 0.002 592s.
  792.      * As on 1970-01-01 MJD = 40587, UTC-TAI = 8.000082s
  793.      * </p>
  794.      * @param field field for the components
  795.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#JAVA_EPOCH}
  796.      * @param <T> the type of the field elements
  797.      */
  798.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getJavaEpoch(final Field<T> field) {
  799.         return new FieldAbsoluteDate<>(field, AbsoluteDate.JAVA_EPOCH);
  800.     }

  802.     /** Dummy date at infinity in the past direction.
  803.      * @param field field for the components
  804.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#PAST_INFINITY}
  805.      * @param <T> the type of the field elements
  806.      */
  807.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getPastInfinity(final Field<T> field) {
  808.         return new FieldAbsoluteDate<>(field, AbsoluteDate.PAST_INFINITY);
  809.     }

  811.     /** Dummy date at infinity in the future direction.
  812.      * @param field field for the components
  813.      * @return FieldAbsoluteDate<T> FieldAbsoluteDate<T> representing {@link AbsoluteDate#FUTURE_INFINITY}
  814.      * @param <T> the type of the field elements
  815.      */
  816.     public static <T extends RealFieldElement<T>> FieldAbsoluteDate<T> getFutureInfinity(final Field<T> field) {
  817.         return new FieldAbsoluteDate<>(field, AbsoluteDate.FUTURE_INFINITY);
  818.     }

  820.     /** Get a time-shifted date.
  821.      * <p>
  822.      * Calling this method is equivalent to call <code>new FieldAbsoluteDate<>(this, dt)</code>.
  823.      * </p>
  824.      * @param dt time shift in seconds
  825.      * @return a new date, shifted with respect to instance (which is immutable)
  826.      * @see org.orekit.utils.PVCoordinates#shiftedBy(double)
  827.      * @see org.orekit.attitudes.Attitude#shiftedBy(double)
  828.      * @see org.orekit.orbits.Orbit#shiftedBy(double)
  829.      * @see org.orekit.propagation.SpacecraftState#shiftedBy(double)
  830.      */
  831.     public FieldAbsoluteDate<T> shiftedBy(final T dt) {
  832.         return new FieldAbsoluteDate<>(this, dt);
  833.     }

  835.     /** Compute the physically elapsed duration between two instants.
  836.      * <p>The returned duration is the number of seconds physically
  837.      * elapsed between the two instants, measured in a regular time
  838.      * scale with respect to surface of the Earth (i.e either the {@link
  839.      * TAIScale TAI scale}, the {@link TTScale TT scale} or the {@link
  840.      * GPSScale GPS scale}). It is the only method that gives a
  841.      * duration with a physical meaning.</p>
  842.      * <p>This method gives the same result (with less computation)
  843.      * as calling {@link #offsetFrom(FieldAbsoluteDate, TimeScale)}
  844.      * with a second argument set to one of the regular scales cited
  845.      * above.</p>
  846.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  847.      * double)} constructor.</p>
  848.      * @param instant instant to subtract from the instance
  849.      * @return offset in seconds between the two instants (positive
  850.      * if the instance is posterior to the argument)
  851.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  852.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double)
  853.      */
  854.     public T durationFrom(final FieldAbsoluteDate<T> instant) {
  855.         return offset.subtract(instant.offset).add(epoch - instant.epoch);
  856.     }

  858.     /** Compute the physically elapsed duration between two instants.
  859.      * <p>The returned duration is the number of seconds physically
  860.      * elapsed between the two instants, measured in a regular time
  861.      * scale with respect to surface of the Earth (i.e either the {@link
  862.      * TAIScale TAI scale}, the {@link TTScale TT scale} or the {@link
  863.      * GPSScale GPS scale}). It is the only method that gives a
  864.      * duration with a physical meaning.</p>
  865.      * <p>This method gives the same result (with less computation)
  866.      * as calling {@link #offsetFrom(FieldAbsoluteDate, TimeScale)}
  867.      * with a second argument set to one of the regular scales cited
  868.      * above.</p>
  869.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  870.      * double)} constructor.</p>
  871.      * @param instant instant to subtract from the instance
  872.      * @return offset in seconds between the two instants (positive
  873.      * if the instance is posterior to the argument)
  874.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  875.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double)
  876.      */
  877.     public T durationFrom(final AbsoluteDate instant) {
  878.         return offset.subtract(instant.getOffset()).add(epoch - instant.getEpoch());
  879.     }

  881.     /** Compute the apparent clock offset between two instant <em>in the
  882.      * perspective of a specific {@link TimeScale time scale}</em>.
  883.      * <p>The offset is the number of seconds counted in the given
  884.      * time scale between the locations of the two instants, with
  885.      * all time scale irregularities removed (i.e. considering all
  886.      * days are exactly 86400 seconds long). This method will give
  887.      * a result that may not have a physical meaning if the time scale
  888.      * is irregular. For example since a leap second was introduced at
  889.      * the end of 2005, the apparent offset between 2005-12-31T23:59:59
  890.      * and 2006-01-01T00:00:00 is 1 second, but the physical duration
  891.      * of the corresponding time interval as returned by the {@link
  892.      * #durationFrom(FieldAbsoluteDate)} method is 2 seconds.</p>
  893.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  894.      * double, TimeScale)} constructor.</p>
  895.      * @param instant instant to subtract from the instance
  896.      * @param timeScale time scale with respect to which the offset should
  897.      * be computed
  898.      * @return apparent clock offset in seconds between the two instants
  899.      * (positive if the instance is posterior to the argument)
  900.      * @see #durationFrom(FieldAbsoluteDate)
  901.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double, TimeScale)
  902.      */
  903.     public T offsetFrom(final FieldAbsoluteDate<T> instant, final TimeScale timeScale) {
  904.         final long   elapsedDurationA = epoch - instant.epoch;
  905.         final T elapsedDurationB = offset.add(timeScale.offsetFromTAI(this)).
  906.                                    subtract(instant.offset.add(timeScale.offsetFromTAI(instant)));
  907.         return  elapsedDurationB.add(elapsedDurationA);
  908.     }

  910.     /** Compute the offset between two time scales at the current instant.
  911.      * <p>The offset is defined as <i>l₁-l₂</i>
  912.      * where <i>l₁</i> is the location of the instant in
  913.      * the <code>scale1</code> time scale and <i>l₂</i> is the
  914.      * location of the instant in the <code>scale2</code> time scale.</p>
  915.      * @param scale1 first time scale
  916.      * @param scale2 second time scale
  917.      * @return offset in seconds between the two time scales at the
  918.      * current instant
  919.      */
  920.     public T timeScalesOffset(final TimeScale scale1, final TimeScale scale2) {
  921.         return scale1.offsetFromTAI(this).subtract(scale2.offsetFromTAI(this));
  922.     }

  924.     /** Convert the instance to a Java {@link java.util.Date Date}.
  925.      * <p>Conversion to the Date class induces a loss of precision because
  926.      * the Date class does not provide sub-millisecond information. Java Dates
  927.      * are considered to be locations in some times scales.</p>
  928.      * @param timeScale time scale to use
  929.      * @return a {@link java.util.Date Date} instance representing the location
  930.      * of the instant in the time scale
  931.      */
  932.     public Date toDate(final TimeScale timeScale) {
  933.         final double time = epoch + (offset.getReal() + timeScale.offsetFromTAI(this).getReal());
  934.         return new Date(FastMath.round((time + 10957.5 * 86400.0) * 1000));
  935.     }

  937.     /** Split the instance into date/time components.
  938.      * @param timeScale time scale to use
  939.      * @return date/time components
  940.      */
  941.     public DateTimeComponents getComponents(final TimeScale timeScale) {

  943.         if (Double.isInfinite(offset.getReal())) {
  944.             // special handling for past and future infinity
  945.             if (offset.getReal() < 0) {
  946.                 return new DateTimeComponents(DateComponents.MIN_EPOCH, TimeComponents.H00);
  947.             } else {
  948.                 return new DateTimeComponents(DateComponents.MAX_EPOCH,
  949.                                               new TimeComponents(23, 59, 59.999));
  950.             }
  951.         }

  953.         // compute offset from 2000-01-01T00:00:00 in specified time scale exactly,
  954.         // using Møller-Knuth TwoSum algorithm without branching
  955.         // the following statements must NOT be simplified, they rely on floating point
  956.         // arithmetic properties (rounding and representable numbers)
  957.         // at the end, the EXACT result of addition offset + timeScale.offsetFromTAI(this)
  958.         // is sum + residual, where sum is the closest representable number to the exact
  959.         // result and residual is the missing part that does not fit in the first number
  960.         final double taiOffset = timeScale.offsetFromTAI(this).getReal();
  961.         final double sum       = offset.getReal() + taiOffset;
  962.         final double oPrime    = sum - taiOffset;
  963.         final double dPrime    = sum - oPrime;
  964.         final double deltaO    = offset.getReal() - oPrime;
  965.         final double deltaD    = taiOffset - dPrime;
  966.         final double residual  = deltaO + deltaD;

  968.         // split date and time
  969.         final long   carry = (long) FastMath.floor(sum);
  970.         double offset2000B = (sum - carry) + residual;
  971.         long   offset2000A = epoch + carry + 43200l;
  972.         if (offset2000B < 0) {
  973.             offset2000A -= 1;
  974.             offset2000B += 1;
  975.         }
  976.         long time = offset2000A % 86400l;
  977.         if (time < 0l) {
  978.             time += 86400l;
  979.         }
  980.         final int date = (int) ((offset2000A - time) / 86400l);

  982.         // extract calendar elements
  983.         final DateComponents dateComponents = new DateComponents(DateComponents.J2000_EPOCH, date);
  984.         TimeComponents timeComponents = new TimeComponents((int) time, offset2000B);

  986.         if (timeScale.insideLeap(this)) {
  987.             // fix the seconds number to take the leap into account
  988.             timeComponents = new TimeComponents(timeComponents.getHour(), timeComponents.getMinute(),
  989.                                                 timeComponents.getSecond() + timeScale.getLeap(this).getReal());
  990.         }

  992.         // build the components
  993.         return new DateTimeComponents(dateComponents, timeComponents);

  995.     }

  997.     /** Split the instance into date/time components for a local time.
  998.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  999.      * negative Westward UTC)
  1000.      * @return date/time components
  1001.      * @exception OrekitException if UTC time scale cannot be retrieved
  1002.      */
  1003.     public DateTimeComponents getComponents(final int minutesFromUTC)
  1004.         throws OrekitException {

  1006.         final DateTimeComponents utcComponents = getComponents(TimeScalesFactory.getUTC());

  1008.         // shift the date according to UTC offset, but WITHOUT touching the seconds,
  1009.         // as they may exceed 60.0 during a leap seconds introduction,
  1010.         // and we want to preserve these special cases
  1011.         final double seconds = utcComponents.getTime().getSecond();
  1012.         int minute = utcComponents.getTime().getMinute() + minutesFromUTC;
  1013.         final int hourShift;
  1014.         if (minute < 0) {
  1015.             hourShift = (minute - 59) / 60;
  1016.         } else if (minute > 59) {
  1017.             hourShift = minute / 60;
  1018.         } else {
  1019.             hourShift = 0;
  1020.         }
  1021.         minute -= 60 * hourShift;
  1022.         int hour = utcComponents.getTime().getHour() + hourShift;
  1023.         final int dayShift;
  1024.         if (hour < 0) {
  1025.             dayShift = (hour - 23) / 24;
  1026.         } else if (hour > 23) {
  1027.             dayShift = hour / 24;
  1028.         } else {
  1029.             dayShift = 0;
  1030.         }
  1031.         hour -= 24 * dayShift;

  1033.         return new DateTimeComponents(new DateComponents(utcComponents.getDate(), dayShift),
  1034.                                       new TimeComponents(hour, minute, seconds, minutesFromUTC));

  1036.     }

  1038.     /** {@inheritDoc} */
  1039.     public FieldAbsoluteDate<T> getDate() {
  1040.         return this;
  1041.     }

  1043.     /** Get the field.
  1044.      * @return field instance.
  1045.      */
  1046.     public Field<T> getField() {
  1047.         return field;
  1048.     }

  1050.     /** Split the instance into date/time components for a time zone.
  1051.      * @param timeZone time zone
  1052.      * @return date/time components
  1053.      * @exception OrekitException if UTC time scale cannot be retrieved
  1054.      */
  1055.     public DateTimeComponents getComponents( final TimeZone timeZone)
  1056.         throws OrekitException {
  1057.         final long milliseconds = FastMath.round((offsetFrom(getJavaEpoch(field), TimeScalesFactory.getUTC()).getReal()) * 1000);
  1058.         return getComponents(timeZone.getOffset(milliseconds) / 60000);
  1059.     }

  1061.     /** Compare the instance with another date.
  1062.      * @param date other date to compare the instance to
  1063.      * @return a negative integer, zero, or a positive integer as this date
  1064.      * is before, simultaneous, or after the specified date.
  1065.      */
  1066.     public int compareTo(final FieldAbsoluteDate<T> date) {
  1067.         return Double.compare(durationFrom(date).getReal(), 0.0);
  1068.     }


  1071.     /** Check if the instance represent the same time as another instance.
  1072.      * @param date other date
  1073.      * @return true if the instance and the other date refer to the same instant
  1074.      */
  1075.     @SuppressWarnings("unchecked")
  1076.     public boolean equals(final Object date) {

  1078.         if (date == this) {
  1079.             // first fast check
  1080.             return true;
  1081.         }

  1083.         if ((date != null) && (date instanceof FieldAbsoluteDate)) {
  1084.             return durationFrom((FieldAbsoluteDate<T>) date).getReal() == 0.0;
  1085.         }

  1087.         return false;

  1089.     }

  1091.     /** Get a hashcode for this date.
  1092.      * @return hashcode
  1093.      */
  1094.     public int hashCode() {
  1095.         final long l = Double.doubleToLongBits(durationFrom(AbsoluteDate.J2000_EPOCH).getReal());
  1096.         return (int) (l ^ (l >>> 32));
  1097.     }

  1099.     /** Get a String representation of the instant location in UTC time scale.
  1100.      * @return a string representation of the instance,
  1101.      * in ISO-8601 format with milliseconds accuracy
  1102.      */
  1103.     public String toString() {
  1104.         try {
  1105.             return toString(TimeScalesFactory.getUTC());
  1106.         } catch (OrekitException oe) {
  1107.             throw new RuntimeException(oe);
  1108.         }
  1109.     }

  1111.     /** Get a String representation of the instant location.
  1112.      * @param timeScale time scale to use
  1113.      * @return a string representation of the instance,
  1114.      * in ISO-8601 format with milliseconds accuracy
  1115.      */
  1116.     public String toString(final TimeScale timeScale) {
  1117.         return getComponents(timeScale).toString(timeScale.minuteDuration(this));
  1118.     }

  1120.     /** Get a String representation of the instant location for a local time.
  1121.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  1122.      * negative Westward UTC).
  1123.      * @return string representation of the instance,
  1124.      * in ISO-8601 format with milliseconds accuracy
  1125.      * @exception OrekitException if UTC time scale cannot be retrieved
  1126.      */
  1127.     public String toString(final int minutesFromUTC)
  1128.         throws OrekitException {
  1129.         final int minuteDuration = TimeScalesFactory.getUTC().minuteDuration(this);
  1130.         return getComponents(minutesFromUTC).toString(minuteDuration);
  1131.     }

  1133.     /** Get a String representation of the instant location for a time zone.
  1134.      * @param timeZone time zone
  1135.      * @return string representation of the instance,
  1136.      * in ISO-8601 format with milliseconds accuracy
  1137.      * @exception OrekitException if UTC time scale cannot be retrieved
  1138.      */
  1139.     public String toString(final TimeZone timeZone)
  1140.         throws OrekitException {
  1141.         final int minuteDuration = TimeScalesFactory.getUTC().minuteDuration(this);
  1142.         return getComponents(timeZone).toString(minuteDuration);
  1143.     }

  1145.     /** Get a time-shifted date.
  1146.      * <p>
  1147.      * Calling this method is equivalent to call <code>new AbsoluteDate(this, dt)</code>.
  1148.      * </p>
  1149.      * @param dt time shift in seconds
  1150.      * @return a new date, shifted with respect to instance (which is immutable)
  1151.      * @see org.orekit.utils.PVCoordinates#shiftedBy(double)
  1152.      * @see org.orekit.attitudes.Attitude#shiftedBy(double)
  1153.      * @see org.orekit.orbits.Orbit#shiftedBy(double)
  1154.      * @see org.orekit.propagation.SpacecraftState#shiftedBy(double)
  1155.      */

  1157.     @Override
  1158.     public FieldAbsoluteDate<T> shiftedBy(final double dt) {
  1159.         return new FieldAbsoluteDate<>(this, dt);
  1160.     }


  1163.     /** Transform the FieldAbsoluteDate in an AbsoluteDate.
  1164.      * @return AbsoluteDate of the FieldObject
  1165.      * */
  1166.     public AbsoluteDate toAbsoluteDate() {
  1167.         return new AbsoluteDate(epoch, offset.getReal());
  1168.     }

  1170. }

Created with JaCoCo 0.7.9.201702052155