FieldAbsoluteDate.java

  1. /* Copyright 2002-2022 CS GROUP
  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;

  18. import java.util.Date;
  19. import java.util.TimeZone;

  20. import org.hipparchus.Field;
  21. import org.hipparchus.CalculusFieldElement;
  22. import org.hipparchus.util.FastMath;
  23. import org.hipparchus.util.MathUtils;
  24. import org.hipparchus.util.MathUtils.FieldSumAndResidual;
  25. import org.hipparchus.util.MathUtils.SumAndResidual;
  26. import org.orekit.annotation.DefaultDataContext;
  27. import org.orekit.data.DataContext;
  28. import org.orekit.errors.OrekitException;
  29. import org.orekit.errors.OrekitMessages;
  30. import org.orekit.utils.Constants;

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

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

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

  105.     /** Field used by default.*/
  106.     private Field<T> field;

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

  116.     /** Create an instance with a default value ({@link #getJ2000Epoch(Field)}).
  117.      *
  118.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  119.      *
  120.      * @param field field used by default
  121.      * @see #FieldAbsoluteDate(Field, AbsoluteDate)
  122.      */
  123.     @DefaultDataContext
  124.     public FieldAbsoluteDate(final Field<T> field) {
  125.         final FieldAbsoluteDate<T> j2000 = getJ2000Epoch(field);
  126.         this.field  = j2000.field;
  127.         this.epoch  = j2000.epoch;
  128.         this.offset = j2000.offset;
  129.     }

  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.         // Use 2Sum for high precision.
  148.         final FieldSumAndResidual<T> sumAndResidual = MathUtils.twoSum(since.offset, elapsedDuration);
  149.         if (Double.isInfinite(sumAndResidual.getSum().getReal())) {
  150.             offset = sumAndResidual.getSum();
  151.             epoch = (sumAndResidual.getSum().getReal() < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
  152.         } else {
  153.             final long dl = (long) FastMath.floor(sumAndResidual.getSum().getReal());
  154.             offset = sumAndResidual.getSum().subtract(dl).add(sumAndResidual.getResidual());
  155.             epoch = since.epoch + dl;
  156.         }
  157.     }

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

  176.     /** Build an instance from a location in a {@link TimeScale time scale}.
  177.      * @param field field utilized by default
  178.      * @param location location in the time scale
  179.      * @param timeScale time scale
  180.      */
  181.     public FieldAbsoluteDate(final Field<T> field, final DateTimeComponents location, final TimeScale timeScale) {
  182.         this(field, location.getDate(), location.getTime(), timeScale);
  183.     }

  184.     /** Build an instance from a location in a {@link TimeScale time scale}.
  185.      * @param field field utilized by default
  186.      * @param date date location in the time scale
  187.      * @param time time location in the time scale
  188.      * @param timeScale time scale
  189.      */
  190.     public FieldAbsoluteDate(final Field<T> field, final DateComponents date, final TimeComponents time,
  191.                              final TimeScale timeScale) {
  192.         final double seconds  = time.getSecond();
  193.         final double tsOffset = timeScale.offsetToTAI(date, time);

  194.         // Use 2Sum for high precision.
  195.         final SumAndResidual sumAndResidual = MathUtils.twoSum(seconds, tsOffset);
  196.         final long dl = (long) FastMath.floor(sumAndResidual.getSum());

  197.         offset = field.getZero().add((sumAndResidual.getSum() - dl) + sumAndResidual.getResidual());

  198.         epoch  = 60l * ((date.getJ2000Day() * 24l + time.getHour()) * 60l +
  199.                         time.getMinute() - time.getMinutesFromUTC() - 720l) + dl;
  200.         this.field = field;

  201.     }

  202.     /** Build an instance from a location in a {@link TimeScale time scale}.
  203.      * @param field field utilized by default
  204.      * @param year year number (may be 0 or negative for BC years)
  205.      * @param month month number from 1 to 12
  206.      * @param day day number from 1 to 31
  207.      * @param hour hour number from 0 to 23
  208.      * @param minute minute number from 0 to 59
  209.      * @param second second number from 0.0 to 60.0 (excluded)
  210.      * @param timeScale time scale
  211.      * @exception IllegalArgumentException if inconsistent arguments
  212.      * are given (parameters out of range)
  213.      */
  214.     public FieldAbsoluteDate(final Field<T> field, final int year, final int month, final int day,
  215.                              final int hour, final int minute, final double second,
  216.                              final TimeScale timeScale) throws IllegalArgumentException {
  217.         this(field, new DateComponents(year, month, day), new TimeComponents(hour, minute, second), timeScale);
  218.     }

  219.     /** Build an instance from a location in a {@link TimeScale time scale}.
  220.      * @param field field utilized by default
  221.      * @param year year number (may be 0 or negative for BC years)
  222.      * @param month month enumerate
  223.      * @param day day number from 1 to 31
  224.      * @param hour hour number from 0 to 23
  225.      * @param minute minute number from 0 to 59
  226.      * @param second second number from 0.0 to 60.0 (excluded)
  227.      * @param timeScale time scale
  228.      * @exception IllegalArgumentException if inconsistent arguments
  229.      * are given (parameters out of range)
  230.      */
  231.     public FieldAbsoluteDate(final Field<T> field, final int year, final Month month, final int day,
  232.                              final int hour, final int minute, final double second,
  233.                              final TimeScale timeScale) throws IllegalArgumentException {
  234.         this(field, new DateComponents(year, month, day), new TimeComponents(hour, minute, second), timeScale);
  235.     }

  236.     /** Build an instance from a location in a {@link TimeScale time scale}.
  237.      * <p>The hour is set to 00:00:00.000.</p>
  238.      * @param field field utilized by default
  239.      * @param date date location in the time scale
  240.      * @param timeScale time scale
  241.      * @exception IllegalArgumentException if inconsistent arguments
  242.      * are given (parameters out of range)
  243.      */
  244.     public FieldAbsoluteDate(final Field<T> field, final DateComponents date, final TimeScale timeScale)
  245.         throws IllegalArgumentException {
  246.         this(field, date, TimeComponents.H00, timeScale);
  247.     }

  248.     /** Build an instance from a location in a {@link TimeScale time scale}.
  249.      * <p>The hour is set to 00:00:00.000.</p>
  250.      * @param field field utilized by default
  251.      * @param year year number (may be 0 or negative for BC years)
  252.      * @param month month number from 1 to 12
  253.      * @param day day number from 1 to 31
  254.      * @param timeScale time scale
  255.      * @exception IllegalArgumentException if inconsistent arguments
  256.      * are given (parameters out of range)
  257.      */
  258.     public FieldAbsoluteDate(final Field<T> field, final int year, final int month, final int day,
  259.                         final TimeScale timeScale) throws IllegalArgumentException {
  260.         this(field, new DateComponents(year, month, day), TimeComponents.H00, timeScale);
  261.     }

  262.     /** Build an instance from a location in a {@link TimeScale time scale}.
  263.      * <p>The hour is set to 00:00:00.000.</p>
  264.      * @param field field utilized by default
  265.      * @param year year number (may be 0 or negative for BC years)
  266.      * @param month month enumerate
  267.      * @param day day number from 1 to 31
  268.      * @param timeScale time scale
  269.      * @exception IllegalArgumentException if inconsistent arguments
  270.      * are given (parameters out of range)
  271.      */
  272.     public FieldAbsoluteDate(final Field<T> field, final int year, final Month month, final int day,
  273.                         final TimeScale timeScale) throws IllegalArgumentException {
  274.         this(field, new DateComponents(year, month, day), TimeComponents.H00, timeScale);
  275.     }

  276.     /** Build an instance from a location in a {@link TimeScale time scale}.
  277.      * @param field field utilized as default
  278.      * @param location location in the time scale
  279.      * @param timeScale time scale
  280.      */
  281.     public FieldAbsoluteDate(final Field<T> field, final Date location, final TimeScale timeScale) {
  282.         this(field, new DateComponents(DateComponents.JAVA_EPOCH,
  283.                                 (int) (location.getTime() / 86400000l)),
  284.                                 new TimeComponents(0.001 * (location.getTime() % 86400000l)),
  285.              timeScale);
  286.     }


  287.     /** Build an instance from an elapsed duration since to another instant.
  288.      * <p>It is important to note that the elapsed duration is <em>not</em>
  289.      * the difference between two readings on a time scale.
  290.      * @param since start instant of the measured duration
  291.      * @param elapsedDuration physically elapsed duration from the <code>since</code>
  292.      * instant, as measured in a regular time scale
  293.      */
  294.     public FieldAbsoluteDate(final FieldAbsoluteDate<T> since, final double elapsedDuration) {
  295.         this(since.epoch, elapsedDuration, since.offset);
  296.     }


  297.     /** Build an instance from an elapsed duration since to another instant.
  298.      * <p>It is important to note that the elapsed duration is <em>not</em>
  299.      * the difference between two readings on a time scale.
  300.      * @param since start instant of the measured duration
  301.      * @param elapsedDuration physically elapsed duration from the <code>since</code>
  302.      * instant, as measured in a regular time scale
  303.      */
  304.     public FieldAbsoluteDate(final AbsoluteDate since, final T elapsedDuration) {
  305.         this(since.getEpoch(), since.getOffset(), elapsedDuration);
  306.     }

  307.     /** Build an instance from an apparent clock offset with respect to another
  308.      * instant <em>in the perspective of a specific {@link TimeScale time scale}</em>.
  309.      * <p>It is important to note that the apparent clock offset <em>is</em> the
  310.      * difference between two readings on a time scale and <em>not</em> an elapsed
  311.      * duration. As an example, the apparent clock offset between the two instants
  312.      * leading to the readings 2005-12-31T23:59:59 and 2006-01-01T00:00:00 in the
  313.      * {@link UTCScale UTC} time scale is 1 second, but the elapsed duration is 2
  314.      * seconds because a leap second has been introduced at the end of 2005 in this
  315.      * time scale.</p>
  316.      * <p>This constructor is the reverse of the {@link #offsetFrom(FieldAbsoluteDate,
  317.      * TimeScale)} method.</p>
  318.      * @param reference reference instant
  319.      * @param apparentOffset apparent clock offset from the reference instant
  320.      * (difference between two readings in the specified time scale)
  321.      * @param timeScale time scale with respect to which the offset is defined
  322.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  323.      */
  324.     public FieldAbsoluteDate(final FieldAbsoluteDate<T> reference, final double apparentOffset, final TimeScale timeScale) {
  325.         this(reference.field, new DateTimeComponents(reference.getComponents(timeScale), apparentOffset),
  326.              timeScale);
  327.     }

  328.     /** Build an instance from mixed double and field raw components.
  329.      * @param epoch reference epoch in seconds from 2000-01-01T12:00:00 TAI
  330.      * @param tA double part of offset since reference epoch
  331.      * @param tB field part of offset since reference epoch
  332.      * @since 9.3
  333.      */
  334.     private FieldAbsoluteDate(final long epoch, final double tA, final T tB) {
  335.         this.field = tB.getField();
  336.         // Use 2Sum for high precision.
  337.         final FieldSumAndResidual<T> sumAndResidual = MathUtils.twoSum(field.getZero().add(tA), tB);
  338.         if (Double.isInfinite(sumAndResidual.getSum().getReal())) {
  339.             this.offset = sumAndResidual.getSum();
  340.             this.epoch = (sumAndResidual.getSum().getReal() < 0) ? Long.MIN_VALUE : Long.MAX_VALUE;
  341.         } else {
  342.             final long dl = (long) FastMath.floor(sumAndResidual.getSum().getReal());
  343.             this.offset = sumAndResidual.getSum().subtract(dl).add(sumAndResidual.getResidual());
  344.             this.epoch = epoch + dl;
  345.         }
  346.     }

  347.     /** Build an instance from a CCSDS Unsegmented Time Code (CUC).
  348.      * <p>
  349.      * CCSDS Unsegmented Time Code is defined in the blue book:
  350.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  351.      * </p>
  352.      * <p>
  353.      * If the date to be parsed is formatted using version 3 of the standard
  354.      * (CCSDS 301.0-B-3 published in 2002) or if the extension of the preamble
  355.      * field introduced in version 4 of the standard is not used, then the
  356.      * {@code preambleField2} parameter can be set to 0.
  357.      * </p>
  358.      *
  359.      * <p>This method uses the {@link DataContext#getDefault() default data context} if
  360.      * the CCSDS epoch is used.
  361.      *
  362.      * @param field field for the components
  363.      * @param preambleField1 first byte of the field specifying the format, often
  364.      * not transmitted in data interfaces, as it is constant for a given data interface
  365.      * @param preambleField2 second byte of the field specifying the format
  366.      * (added in revision 4 of the CCSDS standard in 2010), often not transmitted in data
  367.      * interfaces, as it is constant for a given data interface (value ignored if presence
  368.      * not signaled in {@code preambleField1})
  369.      * @param timeField byte array containing the time code
  370.      * @param agencyDefinedEpoch reference epoch, ignored if the preamble field
  371.      * specifies the {@link #getCCSDSEpoch(Field) CCSDS reference epoch} is used (and hence
  372.      * may be null in this case)
  373.      * @return an instance corresponding to the specified date
  374.      * @param <T> the type of the field elements
  375.      * @see #parseCCSDSUnsegmentedTimeCode(Field, byte, byte, byte[], FieldAbsoluteDate,
  376.      * FieldAbsoluteDate)
  377.      */
  378.     @DefaultDataContext
  379.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSUnsegmentedTimeCode(final Field<T> field,
  380.                                                                                                      final byte preambleField1,
  381.                                                                                                      final byte preambleField2,
  382.                                                                                                      final byte[] timeField,
  383.                                                                                                      final FieldAbsoluteDate<T> agencyDefinedEpoch) {
  384.         return parseCCSDSUnsegmentedTimeCode(field, preambleField1, preambleField2,
  385.                 timeField, agencyDefinedEpoch,
  386.                 new FieldAbsoluteDate<>(
  387.                         field,
  388.                         DataContext.getDefault().getTimeScales().getCcsdsEpoch()));
  389.     }

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

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

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

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

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

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

  468.     }

  469.     /** Build an instance from a CCSDS Day Segmented Time Code (CDS).
  470.      * <p>
  471.      * CCSDS Day Segmented Time Code is defined in the blue book:
  472.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  473.      * </p>
  474.      *
  475.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  476.      *
  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.      * @param <T> the type of the field elements
  486.      * @see #parseCCSDSDaySegmentedTimeCode(Field, byte, byte[], DateComponents,
  487.      * TimeScale)
  488.      */
  489.     @DefaultDataContext
  490.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSDaySegmentedTimeCode(final Field<T> field,
  491.                                                                                                       final byte preambleField, final byte[] timeField,
  492.                                                                                                       final DateComponents agencyDefinedEpoch) {
  493.         return parseCCSDSDaySegmentedTimeCode(field, preambleField, timeField,
  494.                 agencyDefinedEpoch, DataContext.getDefault().getTimeScales().getUTC());
  495.     }

  496.     /**
  497.      * Build an instance from a CCSDS Day Segmented Time Code (CDS).
  498.      * <p>
  499.      * CCSDS Day Segmented Time Code is defined in the blue book: CCSDS Time Code Format
  500.      * (CCSDS 301.0-B-4) published in November 2010
  501.      * </p>
  502.      *
  503.      * @param <T>                the type of the field elements
  504.      * @param field              field for the components
  505.      * @param preambleField      field specifying the format, often not transmitted in
  506.      *                           data interfaces, as it is constant for a given data
  507.      *                           interface
  508.      * @param timeField          byte array containing the time code
  509.      * @param agencyDefinedEpoch reference epoch, ignored if the preamble field specifies
  510.      *                           the {@link #getCCSDSEpoch(Field) CCSDS reference epoch}
  511.      *                           is used (and hence may be null in this case)
  512.      * @param utc                time scale used to compute date and time components.
  513.      * @return an instance corresponding to the specified date
  514.      * @since 10.1
  515.      */
  516.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> parseCCSDSDaySegmentedTimeCode(
  517.             final Field<T> field,
  518.             final byte preambleField,
  519.             final byte[] timeField,
  520.             final DateComponents agencyDefinedEpoch,
  521.             final TimeScale utc) {

  522.         // time code identification
  523.         if ((preambleField & 0xF0) != 0x40) {
  524.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  525.                                       formatByte(preambleField));
  526.         }

  527.         // reference epoch
  528.         final DateComponents epochDC;
  529.         if ((preambleField & 0x08) == 0x00) {
  530.             // the reference epoch is CCSDS epoch 1958-01-01T00:00:00 TAI
  531.             epochDC = DateComponents.CCSDS_EPOCH;
  532.         } else {
  533.             // the reference epoch is agency defined
  534.             if (agencyDefinedEpoch == null) {
  535.                 throw new OrekitException(OrekitMessages.CCSDS_DATE_MISSING_AGENCY_EPOCH);
  536.             }
  537.             epochDC = agencyDefinedEpoch;
  538.         }

  539.         // time field lengths
  540.         final int daySegmentLength = ((preambleField & 0x04) == 0x0) ? 2 : 3;
  541.         final int subMillisecondLength = (preambleField & 0x03) << 1;
  542.         if (subMillisecondLength == 6) {
  543.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  544.                                       formatByte(preambleField));
  545.         }
  546.         if (timeField.length != daySegmentLength + 4 + subMillisecondLength) {
  547.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_LENGTH_TIME_FIELD,
  548.                                       timeField.length, daySegmentLength + 4 + subMillisecondLength);
  549.         }


  550.         int i   = 0;
  551.         int day = 0;
  552.         while (i < daySegmentLength) {
  553.             day = day * 256 + toUnsigned(timeField[i++]);
  554.         }

  555.         long milliInDay = 0l;
  556.         while (i < daySegmentLength + 4) {
  557.             milliInDay = milliInDay * 256 + toUnsigned(timeField[i++]);
  558.         }
  559.         final int milli   = (int) (milliInDay % 1000l);
  560.         final int seconds = (int) ((milliInDay - milli) / 1000l);

  561.         double subMilli = 0;
  562.         double divisor  = 1;
  563.         while (i < timeField.length) {
  564.             subMilli = subMilli * 256 + toUnsigned(timeField[i++]);
  565.             divisor *= 1000;
  566.         }

  567.         final DateComponents date = new DateComponents(epochDC, day);
  568.         final TimeComponents time = new TimeComponents(seconds);
  569.         return new FieldAbsoluteDate<>(field, date, time, utc).shiftedBy(milli * 1.0e-3 + subMilli / divisor);

  570.     }

  571.     /** Build an instance from a CCSDS Calendar Segmented Time Code (CCS).
  572.      * <p>
  573.      * CCSDS Calendar Segmented Time Code is defined in the blue book:
  574.      * CCSDS Time Code Format (CCSDS 301.0-B-4) published in November 2010
  575.      * </p>
  576.      *
  577.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  578.      *
  579.      * @param preambleField field specifying the format, often not transmitted in
  580.      * data interfaces, as it is constant for a given data interface
  581.      * @param timeField byte array containing the time code
  582.      * @return an instance corresponding to the specified date
  583.      * @see #parseCCSDSCalendarSegmentedTimeCode(byte, byte[], TimeScale)
  584.      */
  585.     @DefaultDataContext
  586.     public FieldAbsoluteDate<T> parseCCSDSCalendarSegmentedTimeCode(final byte preambleField, final byte[] timeField) {
  587.         return parseCCSDSCalendarSegmentedTimeCode(preambleField, timeField,
  588.                 DataContext.getDefault().getTimeScales().getUTC());
  589.     }

  590.     /**
  591.      * Build an instance from a CCSDS Calendar Segmented Time Code (CCS).
  592.      * <p>
  593.      * CCSDS Calendar Segmented Time Code is defined in the blue book: CCSDS Time Code
  594.      * Format (CCSDS 301.0-B-4) published in November 2010
  595.      * </p>
  596.      *
  597.      * @param preambleField field specifying the format, often not transmitted in data
  598.      *                      interfaces, as it is constant for a given data interface
  599.      * @param timeField     byte array containing the time code
  600.      * @param utc           time scale used to compute date and time components.
  601.      * @return an instance corresponding to the specified date
  602.      * @since 10.1
  603.      */
  604.     public FieldAbsoluteDate<T> parseCCSDSCalendarSegmentedTimeCode(
  605.             final byte preambleField,
  606.             final byte[] timeField,
  607.             final TimeScale utc) {

  608.         // time code identification
  609.         if ((preambleField & 0xF0) != 0x50) {
  610.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  611.                                       formatByte(preambleField));
  612.         }

  613.         // time field length
  614.         final int length = 7 + (preambleField & 0x07);
  615.         if (length == 14) {
  616.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_PREAMBLE_FIELD,
  617.                                       formatByte(preambleField));
  618.         }
  619.         if (timeField.length != length) {
  620.             throw new OrekitException(OrekitMessages.CCSDS_DATE_INVALID_LENGTH_TIME_FIELD,
  621.                                       timeField.length, length);
  622.         }

  623.         // date part in the first four bytes
  624.         final DateComponents date;
  625.         if ((preambleField & 0x08) == 0x00) {
  626.             // month of year and day of month variation
  627.             date = new DateComponents(toUnsigned(timeField[0]) * 256 + toUnsigned(timeField[1]),
  628.                                       toUnsigned(timeField[2]),
  629.                                       toUnsigned(timeField[3]));
  630.         } else {
  631.             // day of year variation
  632.             date = new DateComponents(toUnsigned(timeField[0]) * 256 + toUnsigned(timeField[1]),
  633.                                       toUnsigned(timeField[2]) * 256 + toUnsigned(timeField[3]));
  634.         }

  635.         // time part from bytes 5 to last (between 7 and 13 depending on precision)
  636.         final TimeComponents time = new TimeComponents(toUnsigned(timeField[4]),
  637.                                                        toUnsigned(timeField[5]),
  638.                                                        toUnsigned(timeField[6]));
  639.         double subSecond = 0;
  640.         double divisor   = 1;
  641.         for (int i = 7; i < length; ++i) {
  642.             subSecond = subSecond * 100 + toUnsigned(timeField[i]);
  643.             divisor *= 100;
  644.         }

  645.         return new FieldAbsoluteDate<>(field, date, time, utc).shiftedBy(subSecond / divisor);

  646.     }

  647.     /** Decode a signed byte as an unsigned int value.
  648.      * @param b byte to decode
  649.      * @return an unsigned int value
  650.      */
  651.     private static int toUnsigned(final byte b) {
  652.         final int i = (int) b;
  653.         return (i < 0) ? 256 + i : i;
  654.     }

  655.     /** Format a byte as an hex string for error messages.
  656.      * @param data byte to format
  657.      * @return a formatted string
  658.      */
  659.     private static String formatByte(final byte data) {
  660.         return "0x" + Integer.toHexString(data).toUpperCase();
  661.     }

  662.     /** Build an instance corresponding to a Julian Day date.
  663.      * @param jd Julian day
  664.      * @param secondsSinceNoon seconds in the Julian day
  665.      * (BEWARE, Julian days start at noon, so 0.0 is noon)
  666.      * @param timeScale time scale in which the seconds in day are defined
  667.      * @return a new instant
  668.      * @param <T> the type of the field elements
  669.      */
  670.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJDDate(final int jd, final T secondsSinceNoon,
  671.                                                                                     final TimeScale timeScale) {
  672.         return new FieldAbsoluteDate<>(secondsSinceNoon.getField(), new DateComponents(DateComponents.JULIAN_EPOCH, jd),
  673.                                        TimeComponents.H12, timeScale).shiftedBy(secondsSinceNoon);
  674.     }

  675.     /** Build an instance corresponding to a Modified Julian Day date.
  676.      * @param mjd modified Julian day
  677.      * @param secondsInDay seconds in the day
  678.      * @param timeScale time scale in which the seconds in day are defined
  679.      * @return a new instant
  680.      * @param <T> the type of the field elements
  681.      */
  682.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createMJDDate(final int mjd, final T secondsInDay,
  683.                                                                                      final TimeScale timeScale) {
  684.         return new FieldAbsoluteDate<>(secondsInDay.getField(),
  685.                                        new DateComponents(DateComponents.MODIFIED_JULIAN_EPOCH, mjd),
  686.                                        TimeComponents.H00,
  687.                                        timeScale).shiftedBy(secondsInDay);
  688.     }

  689.     /** Build an instance corresponding to a GPS date.
  690.      *
  691.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  692.      *
  693.      * <p>GPS dates are provided as a week number starting at
  694.      * {@link #getGPSEpoch(Field) GPS epoch} and as a number of milliseconds
  695.      * since week start.</p>
  696.      * @param weekNumber week number since {@link #getGPSEpoch(Field) GPS epoch}
  697.      * @param milliInWeek number of milliseconds since week start
  698.      * @return a new instant
  699.      * @param <T> the type of the field elements
  700.      * @see #createGPSDate(int, CalculusFieldElement, TimeScale)
  701.      */
  702.     @DefaultDataContext
  703.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createGPSDate(final int weekNumber, final T milliInWeek) {
  704.         return createGPSDate(weekNumber, milliInWeek,
  705.                 DataContext.getDefault().getTimeScales().getGPS());
  706.     }

  707.     /**
  708.      * Build an instance corresponding to a GPS date.
  709.      * <p>GPS dates are provided as a week number starting at
  710.      * {@link #getGPSEpoch(Field) GPS epoch} and as a number of milliseconds since week
  711.      * start.</p>
  712.      *
  713.      * @param <T>         the type of the field elements
  714.      * @param weekNumber  week number since {@link #getGPSEpoch(Field) GPS epoch}
  715.      * @param milliInWeek number of milliseconds since week start
  716.      * @param gps         GPS time scale.
  717.      * @return a new instant
  718.      * @since 10.1
  719.      */
  720.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createGPSDate(
  721.             final int weekNumber,
  722.             final T milliInWeek,
  723.             final TimeScale gps) {

  724.         final int day = (int) FastMath.floor(milliInWeek.getReal() / (1000.0 * Constants.JULIAN_DAY));
  725.         final T secondsInDay = milliInWeek.divide(1000.0).subtract(day * Constants.JULIAN_DAY);
  726.         return new FieldAbsoluteDate<>(milliInWeek.getField(), new DateComponents(DateComponents.GPS_EPOCH, weekNumber * 7 + day),
  727.                                        TimeComponents.H00, gps).shiftedBy(secondsInDay);
  728.     }

  729.     /** Build an instance corresponding to a Julian Epoch (JE).
  730.      * <p>According to Lieske paper: <a
  731.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&amp;defaultprint=YES&amp;filetype=.pdf.">
  732.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>, Astronomy and Astrophysics,
  733.      * vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is related to Julian Ephemeris Date as:
  734.      * <pre>JE = 2000.0 + (JED - 2451545.0) / 365.25</pre>
  735.      * <p>This method reverts the formula above and computes an {@code FieldAbsoluteDate<T>} from the Julian Epoch.
  736.      *
  737.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  738.      *
  739.      * @param <T> the type of the field elements
  740.      * @param julianEpoch Julian epoch, like 2000.0 for defining the classical reference J2000.0
  741.      * @return a new instant
  742.      * @see #getJ2000Epoch(Field)
  743.      * @see #createBesselianEpoch(CalculusFieldElement)
  744.      * @see #createJulianEpoch(CalculusFieldElement, TimeScales)
  745.      */
  746.     @DefaultDataContext
  747.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJulianEpoch(final T julianEpoch) {
  748.         return createJulianEpoch(julianEpoch,
  749.                 DataContext.getDefault().getTimeScales());
  750.     }

  751.     /**
  752.      * Build an instance corresponding to a Julian Epoch (JE).
  753.      * <p>According to Lieske paper: <a
  754.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&amp;defaultprint=YES&amp;filetype=.pdf.">
  755.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>,
  756.      * Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Julian Epoch is
  757.      * related to Julian Ephemeris Date as:
  758.      * <pre>JE = 2000.0 + (JED - 2451545.0) / 365.25</pre>
  759.      * <p>This method reverts the formula above and computes an {@code
  760.      * FieldAbsoluteDate<T>} from the Julian Epoch.
  761.      *
  762.      * @param <T>         the type of the field elements
  763.      * @param julianEpoch Julian epoch, like 2000.0 for defining the classical reference
  764.      *                    J2000.0
  765.      * @param timeScales  used in the computation.
  766.      * @return a new instant
  767.      * @see #getJ2000Epoch(Field)
  768.      * @see #createBesselianEpoch(CalculusFieldElement)
  769.      * @see TimeScales#createJulianEpoch(double)
  770.      * @since 10.1
  771.      */
  772.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createJulianEpoch(
  773.             final T julianEpoch,
  774.             final TimeScales timeScales) {

  775.         final Field<T> field = julianEpoch.getField();
  776.         return new FieldAbsoluteDate<>(new FieldAbsoluteDate<>(field, timeScales.getJ2000Epoch()),
  777.                                        julianEpoch.subtract(2000.0).multiply(Constants.JULIAN_YEAR));
  778.     }

  779.     /** Build an instance corresponding to a Besselian Epoch (BE).
  780.      * <p>According to Lieske paper: <a
  781.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&amp;defaultprint=YES&amp;filetype=.pdf.">
  782.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>, Astronomy and Astrophysics,
  783.      * vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch is related to Julian Ephemeris Date as:</p>
  784.      * <pre>
  785.      * BE = 1900.0 + (JED - 2415020.31352) / 365.242198781
  786.      * </pre>
  787.      * <p>
  788.      * This method reverts the formula above and computes an {@code FieldAbsoluteDate<T>} from the Besselian Epoch.
  789.      * </p>
  790.      *
  791.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  792.      *
  793.      * @param <T> the type of the field elements
  794.      * @param besselianEpoch Besselian epoch, like 1950 for defining the classical reference B1950.0
  795.      * @return a new instant
  796.      * @see #createJulianEpoch(CalculusFieldElement)
  797.      * @see #createBesselianEpoch(CalculusFieldElement, TimeScales)
  798.      */
  799.     @DefaultDataContext
  800.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createBesselianEpoch(final T besselianEpoch) {
  801.         return createBesselianEpoch(besselianEpoch,
  802.                 DataContext.getDefault().getTimeScales());
  803.     }

  804.     /**
  805.      * Build an instance corresponding to a Besselian Epoch (BE).
  806.      * <p>According to Lieske paper: <a
  807.      * href="http://articles.adsabs.harvard.edu/cgi-bin/nph-iarticle_query?1979A%26A....73..282L&amp;defaultprint=YES&amp;filetype=.pdf.">
  808.      * Precession Matrix Based on IAU (1976) System of Astronomical Constants</a>,
  809.      * Astronomy and Astrophysics, vol. 73, no. 3, Mar. 1979, p. 282-284, Besselian Epoch
  810.      * is related to Julian Ephemeris Date as:</p>
  811.      * <pre>
  812.      * BE = 1900.0 + (JED - 2415020.31352) / 365.242198781
  813.      * </pre>
  814.      * <p>
  815.      * This method reverts the formula above and computes an {@code FieldAbsoluteDate<T>}
  816.      * from the Besselian Epoch.
  817.      * </p>
  818.      *
  819.      * @param <T>            the type of the field elements
  820.      * @param besselianEpoch Besselian epoch, like 1950 for defining the classical
  821.      *                       reference B1950.0
  822.      * @param timeScales     used in the computation.
  823.      * @return a new instant
  824.      * @see #createJulianEpoch(CalculusFieldElement)
  825.      * @see TimeScales#createBesselianEpoch(double)
  826.      * @since 10.1
  827.      */
  828.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> createBesselianEpoch(
  829.             final T besselianEpoch,
  830.             final TimeScales timeScales) {

  831.         final Field<T> field = besselianEpoch.getField();
  832.         return new FieldAbsoluteDate<>(new FieldAbsoluteDate<>(field, timeScales.getJ2000Epoch()),
  833.                                        besselianEpoch.subtract(1900).multiply(Constants.BESSELIAN_YEAR).add(
  834.                                        Constants.JULIAN_DAY * (-36525) + Constants.JULIAN_DAY * 0.31352));
  835.     }

  836.     /** Reference epoch for julian dates: -4712-01-01T12:00:00 Terrestrial Time.
  837.      * <p>Both <code>java.util.Date</code> and {@link DateComponents} classes
  838.      * follow the astronomical conventions and consider a year 0 between
  839.      * years -1 and +1, hence this reference date lies in year -4712 and not
  840.      * in year -4713 as can be seen in other documents or programs that obey
  841.      * a different convention (for example the <code>convcal</code> utility).</p>
  842.      *
  843.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  844.      *
  845.      * @param <T> the type of the field elements
  846.      * @param field field for the components
  847.      * @return the reference epoch for julian dates as a FieldAbsoluteDate
  848.      * @see AbsoluteDate#JULIAN_EPOCH
  849.      * @see TimeScales#getJulianEpoch()
  850.      */
  851.     @DefaultDataContext
  852.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJulianEpoch(final Field<T> field) {
  853.         return new FieldAbsoluteDate<>(field,
  854.                 DataContext.getDefault().getTimeScales().getJulianEpoch());
  855.     }

  856.     /** Reference epoch for modified julian dates: 1858-11-17T00:00:00 Terrestrial Time.
  857.      *
  858.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  859.      *
  860.      * @param <T> the type of the field elements
  861.      * @param field field for the components
  862.      * @return the reference epoch for modified julian dates as a FieldAbsoluteDate
  863.      * @see AbsoluteDate#MODIFIED_JULIAN_EPOCH
  864.      * @see TimeScales#getModifiedJulianEpoch()
  865.      */
  866.     @DefaultDataContext
  867.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getModifiedJulianEpoch(final Field<T> field) {
  868.         return new FieldAbsoluteDate<>(field,
  869.                 DataContext.getDefault().getTimeScales().getModifiedJulianEpoch());
  870.     }

  871.     /** Reference epoch for 1950 dates: 1950-01-01T00:00:00 Terrestrial Time.
  872.      *
  873.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  874.      *
  875.      * @param <T> the type of the field elements
  876.      * @param field field for the components
  877.      * @return the reference epoch for 1950 dates as a FieldAbsoluteDate
  878.      * @see AbsoluteDate#FIFTIES_EPOCH
  879.      * @see TimeScales#getFiftiesEpoch()
  880.      */
  881.     @DefaultDataContext
  882.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getFiftiesEpoch(final Field<T> field) {
  883.         return new FieldAbsoluteDate<>(field,
  884.                 DataContext.getDefault().getTimeScales().getFiftiesEpoch());
  885.     }

  886.     /** Reference epoch for CCSDS Time Code Format (CCSDS 301.0-B-4):
  887.      *
  888.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  889.      *
  890.      * 1958-01-01T00:00:00 International Atomic Time (<em>not</em> UTC).
  891.      * @param <T> the type of the field elements
  892.      * @param field field for the components
  893.      * @return the reference epoch for CCSDS Time Code Format as a FieldAbsoluteDate
  894.      * @see AbsoluteDate#CCSDS_EPOCH
  895.      * @see TimeScales#getCcsdsEpoch()
  896.      */
  897.     @DefaultDataContext
  898.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getCCSDSEpoch(final Field<T> field) {
  899.         return new FieldAbsoluteDate<>(field,
  900.                 DataContext.getDefault().getTimeScales().getCcsdsEpoch());
  901.     }

  902.     /** Reference epoch for Galileo System Time: 1999-08-22T00:00:00 UTC.
  903.      *
  904.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  905.      *
  906.      * @param <T> the type of the field elements
  907.      * @param field field for the components
  908.      * @return the reference epoch for Galileo System Time as a FieldAbsoluteDate
  909.      * @see AbsoluteDate#GALILEO_EPOCH
  910.      * @see TimeScales#getGalileoEpoch()
  911.      */
  912.     @DefaultDataContext
  913.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getGalileoEpoch(final Field<T> field) {
  914.         return new FieldAbsoluteDate<>(field,
  915.                 DataContext.getDefault().getTimeScales().getGalileoEpoch());
  916.     }

  917.     /** Reference epoch for GPS weeks: 1980-01-06T00:00:00 GPS time.
  918.      *
  919.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  920.      *
  921.      * @param <T> the type of the field elements
  922.      * @param field field for the components
  923.      * @return the reference epoch for GPS weeks as a FieldAbsoluteDate
  924.      * @see AbsoluteDate#GPS_EPOCH
  925.      * @see TimeScales#getGpsEpoch()
  926.      */
  927.     @DefaultDataContext
  928.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getGPSEpoch(final Field<T> field) {
  929.         return new FieldAbsoluteDate<>(field,
  930.                 DataContext.getDefault().getTimeScales().getGpsEpoch());
  931.     }

  932.     /** J2000.0 Reference epoch: 2000-01-01T12:00:00 Terrestrial Time (<em>not</em> UTC).
  933.      *
  934.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  935.      *
  936.      * @param <T> the type of the field elements
  937.      * @param field field for the components
  938.      * @return the J2000.0 reference epoch as a FieldAbsoluteDate
  939.      * @see #createJulianEpoch(CalculusFieldElement)
  940.      * @see AbsoluteDate#J2000_EPOCH
  941.      * @see TimeScales#getJ2000Epoch()
  942.      */
  943.     @DefaultDataContext
  944.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJ2000Epoch(final Field<T> field) {
  945.         return new FieldAbsoluteDate<>(field,
  946.                 DataContext.getDefault().getTimeScales().getJ2000Epoch());
  947.     }

  948.     /** Java Reference epoch: 1970-01-01T00:00:00 Universal Time Coordinate.
  949.      *
  950.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  951.      *
  952.      * <p>
  953.      * Between 1968-02-01 and 1972-01-01, UTC-TAI = 4.213 170 0s + (MJD - 39 126) x 0.002 592s.
  954.      * As on 1970-01-01 MJD = 40587, UTC-TAI = 8.000082s
  955.      * </p>
  956.      * @param <T> the type of the field elements
  957.      * @param field field for the components
  958.      * @return the Java reference epoch as a FieldAbsoluteDate
  959.      * @see AbsoluteDate#JAVA_EPOCH
  960.      * @see TimeScales#getJavaEpoch()
  961.      */
  962.     @DefaultDataContext
  963.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getJavaEpoch(final Field<T> field) {
  964.         return new FieldAbsoluteDate<>(field,
  965.                 DataContext.getDefault().getTimeScales().getJavaEpoch());
  966.     }

  967.     /** Dummy date at infinity in the past direction.
  968.      * @param <T> the type of the field elements
  969.      * @param field field for the components
  970.      * @return a dummy date at infinity in the past direction as a FieldAbsoluteDate
  971.      * @see AbsoluteDate#PAST_INFINITY
  972.      * @see TimeScales#getPastInfinity()
  973.      */
  974.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getPastInfinity(final Field<T> field) {
  975.         return new FieldAbsoluteDate<>(field, AbsoluteDate.PAST_INFINITY);
  976.     }

  977.     /** Dummy date at infinity in the future direction.
  978.      * @param <T> the type of the field elements
  979.      * @param field field for the components
  980.      * @return a dummy date at infinity in the future direction as a FieldAbsoluteDate
  981.      * @see AbsoluteDate#FUTURE_INFINITY
  982.      * @see TimeScales#getFutureInfinity()
  983.      */
  984.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getFutureInfinity(final Field<T> field) {
  985.         return new FieldAbsoluteDate<>(field, AbsoluteDate.FUTURE_INFINITY);
  986.     }

  987.     /**
  988.      * Get an arbitrary date. Useful when a non-null date is needed but its values does
  989.      * not matter.
  990.      *
  991.      * @param <T>   the type of the field elements
  992.      * @param field field for the components
  993.      * @return an arbitrary date.
  994.      */
  995.     public static <T extends CalculusFieldElement<T>> FieldAbsoluteDate<T> getArbitraryEpoch(
  996.             final Field<T> field) {

  997.         return new FieldAbsoluteDate<>(field, AbsoluteDate.ARBITRARY_EPOCH);
  998.     }


  999.     /** Get a time-shifted date.
  1000.      * <p>
  1001.      * Calling this method is equivalent to call {@code new FieldAbsoluteDate&lt;&gt;(this, dt)}.
  1002.      * </p>
  1003.      * @param dt time shift in seconds
  1004.      * @return a new date, shifted with respect to instance (which is immutable)
  1005.      * @see org.orekit.utils.PVCoordinates#shiftedBy(double)
  1006.      * @see org.orekit.attitudes.Attitude#shiftedBy(double)
  1007.      * @see org.orekit.orbits.Orbit#shiftedBy(double)
  1008.      * @see org.orekit.propagation.SpacecraftState#shiftedBy(double)
  1009.      */
  1010.     public FieldAbsoluteDate<T> shiftedBy(final T dt) {
  1011.         return new FieldAbsoluteDate<>(this, dt);
  1012.     }

  1013.     /** Compute the physically elapsed duration between two instants.
  1014.      * <p>The returned duration is the number of seconds physically
  1015.      * elapsed between the two instants, measured in a regular time
  1016.      * scale with respect to surface of the Earth (i.e either the {@link
  1017.      * TAIScale TAI scale}, the {@link TTScale TT scale} or the {@link
  1018.      * GPSScale GPS scale}). It is the only method that gives a
  1019.      * duration with a physical meaning.</p>
  1020.      * <p>This method gives the same result (with less computation)
  1021.      * as calling {@link #offsetFrom(FieldAbsoluteDate, TimeScale)}
  1022.      * with a second argument set to one of the regular scales cited
  1023.      * above.</p>
  1024.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  1025.      * double)} constructor.</p>
  1026.      * @param instant instant to subtract from the instance
  1027.      * @return offset in seconds between the two instants (positive
  1028.      * if the instance is posterior to the argument)
  1029.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  1030.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double)
  1031.      */
  1032.     public T durationFrom(final FieldAbsoluteDate<T> instant) {
  1033.         return offset.subtract(instant.offset).add(epoch - instant.epoch);
  1034.     }

  1035.     /** Compute the physically elapsed duration between two instants.
  1036.      * <p>The returned duration is the number of seconds physically
  1037.      * elapsed between the two instants, measured in a regular time
  1038.      * scale with respect to surface of the Earth (i.e either the {@link
  1039.      * TAIScale TAI scale}, the {@link TTScale TT scale} or the {@link
  1040.      * GPSScale GPS scale}). It is the only method that gives a
  1041.      * duration with a physical meaning.</p>
  1042.      * <p>This method gives the same result (with less computation)
  1043.      * as calling {@link #offsetFrom(FieldAbsoluteDate, TimeScale)}
  1044.      * with a second argument set to one of the regular scales cited
  1045.      * above.</p>
  1046.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  1047.      * double)} constructor.</p>
  1048.      * @param instant instant to subtract from the instance
  1049.      * @return offset in seconds between the two instants (positive
  1050.      * if the instance is posterior to the argument)
  1051.      * @see #offsetFrom(FieldAbsoluteDate, TimeScale)
  1052.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double)
  1053.      */
  1054.     public T durationFrom(final AbsoluteDate instant) {
  1055.         return offset.subtract(instant.getOffset()).add(epoch - instant.getEpoch());
  1056.     }

  1057.     /** Compute the apparent clock offset between two instant <em>in the
  1058.      * perspective of a specific {@link TimeScale time scale}</em>.
  1059.      * <p>The offset is the number of seconds counted in the given
  1060.      * time scale between the locations of the two instants, with
  1061.      * all time scale irregularities removed (i.e. considering all
  1062.      * days are exactly 86400 seconds long). This method will give
  1063.      * a result that may not have a physical meaning if the time scale
  1064.      * is irregular. For example since a leap second was introduced at
  1065.      * the end of 2005, the apparent offset between 2005-12-31T23:59:59
  1066.      * and 2006-01-01T00:00:00 is 1 second, but the physical duration
  1067.      * of the corresponding time interval as returned by the {@link
  1068.      * #durationFrom(FieldAbsoluteDate)} method is 2 seconds.</p>
  1069.      * <p>This method is the reverse of the {@link #FieldAbsoluteDate(FieldAbsoluteDate,
  1070.      * double, TimeScale)} constructor.</p>
  1071.      * @param instant instant to subtract from the instance
  1072.      * @param timeScale time scale with respect to which the offset should
  1073.      * be computed
  1074.      * @return apparent clock offset in seconds between the two instants
  1075.      * (positive if the instance is posterior to the argument)
  1076.      * @see #durationFrom(FieldAbsoluteDate)
  1077.      * @see #FieldAbsoluteDate(FieldAbsoluteDate, double, TimeScale)
  1078.      */
  1079.     public T offsetFrom(final FieldAbsoluteDate<T> instant, final TimeScale timeScale) {
  1080.         final long   elapsedDurationA = epoch - instant.epoch;
  1081.         final T elapsedDurationB = offset.add(timeScale.offsetFromTAI(this)).
  1082.                                    subtract(instant.offset.add(timeScale.offsetFromTAI(instant)));
  1083.         return  elapsedDurationB.add(elapsedDurationA);
  1084.     }

  1085.     /** Compute the offset between two time scales at the current instant.
  1086.      * <p>The offset is defined as <i>l₁-l₂</i>
  1087.      * where <i>l₁</i> is the location of the instant in
  1088.      * the <code>scale1</code> time scale and <i>l₂</i> is the
  1089.      * location of the instant in the <code>scale2</code> time scale.</p>
  1090.      * @param scale1 first time scale
  1091.      * @param scale2 second time scale
  1092.      * @return offset in seconds between the two time scales at the
  1093.      * current instant
  1094.      */
  1095.     public T timeScalesOffset(final TimeScale scale1, final TimeScale scale2) {
  1096.         return scale1.offsetFromTAI(this).subtract(scale2.offsetFromTAI(this));
  1097.     }

  1098.     /** Convert the instance to a Java {@link java.util.Date Date}.
  1099.      * <p>Conversion to the Date class induces a loss of precision because
  1100.      * the Date class does not provide sub-millisecond information. Java Dates
  1101.      * are considered to be locations in some times scales.</p>
  1102.      * @param timeScale time scale to use
  1103.      * @return a {@link java.util.Date Date} instance representing the location
  1104.      * of the instant in the time scale
  1105.      */
  1106.     public Date toDate(final TimeScale timeScale) {
  1107.         final double time = epoch + (offset.getReal() + timeScale.offsetFromTAI(this).getReal());
  1108.         return new Date(FastMath.round((time + 10957.5 * 86400.0) * 1000));
  1109.     }

  1110.     /** Split the instance into date/time components.
  1111.      * @param timeScale time scale to use
  1112.      * @return date/time components
  1113.      */
  1114.     public DateTimeComponents getComponents(final TimeScale timeScale) {

  1115.         if (Double.isInfinite(offset.getReal())) {
  1116.             // special handling for past and future infinity
  1117.             if (offset.getReal() < 0) {
  1118.                 return new DateTimeComponents(DateComponents.MIN_EPOCH, TimeComponents.H00);
  1119.             } else {
  1120.                 return new DateTimeComponents(DateComponents.MAX_EPOCH,
  1121.                                               new TimeComponents(23, 59, 59.999));
  1122.             }
  1123.         }

  1124.         // Compute offset from 2000-01-01T00:00:00 in specified time scale.
  1125.         // Use 2Sum for high accuracy.
  1126.         final double taiOffset = timeScale.offsetFromTAI(this).getReal();
  1127.         final SumAndResidual sumAndResidual = MathUtils.twoSum(offset.getReal(), taiOffset);

  1128.         // split date and time
  1129.         final long   carry = (long) FastMath.floor(sumAndResidual.getSum());
  1130.         double offset2000B = (sumAndResidual.getSum() - carry) + sumAndResidual.getResidual();
  1131.         long   offset2000A = epoch + carry + 43200l;
  1132.         if (offset2000B < 0) {
  1133.             offset2000A -= 1;
  1134.             offset2000B += 1;
  1135.         }
  1136.         long time = offset2000A % 86400l;
  1137.         if (time < 0l) {
  1138.             time += 86400l;
  1139.         }
  1140.         final int date = (int) ((offset2000A - time) / 86400l);

  1141.         // extract calendar elements
  1142.         final DateComponents dateComponents = new DateComponents(DateComponents.J2000_EPOCH, date);
  1143.         // extract time element, accounting for leap seconds
  1144.         final double leap =
  1145.                 timeScale.insideLeap(this) ? timeScale.getLeap(this.toAbsoluteDate()) : 0;
  1146.         final int minuteDuration = timeScale.minuteDuration(this);
  1147.         final TimeComponents timeComponents =
  1148.                 TimeComponents.fromSeconds((int) time, offset2000B, leap, minuteDuration);

  1149.         // build the components
  1150.         return new DateTimeComponents(dateComponents, timeComponents);

  1151.     }

  1152.     /** Split the instance into date/time components for a local time.
  1153.      *
  1154.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  1155.      *
  1156.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  1157.      * negative Westward UTC)
  1158.      * @return date/time components
  1159.      * @see #getComponents(int, TimeScale)
  1160.      */
  1161.     @DefaultDataContext
  1162.     public DateTimeComponents getComponents(final int minutesFromUTC) {
  1163.         return getComponents(minutesFromUTC,
  1164.                 DataContext.getDefault().getTimeScales().getUTC());
  1165.     }

  1166.     /**
  1167.      * Split the instance into date/time components for a local time.
  1168.      *
  1169.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  1170.      *                       negative Westward UTC)
  1171.      * @param utc            time scale used to compute date and time components.
  1172.      * @return date/time components
  1173.      * @since 10.1
  1174.      */
  1175.     public DateTimeComponents getComponents(final int minutesFromUTC,
  1176.                                             final TimeScale utc) {

  1177.         final DateTimeComponents utcComponents = getComponents(utc);

  1178.         // shift the date according to UTC offset, but WITHOUT touching the seconds,
  1179.         // as they may exceed 60.0 during a leap seconds introduction,
  1180.         // and we want to preserve these special cases
  1181.         final double seconds = utcComponents.getTime().getSecond();
  1182.         int minute = utcComponents.getTime().getMinute() + minutesFromUTC;
  1183.         final int hourShift;
  1184.         if (minute < 0) {
  1185.             hourShift = (minute - 59) / 60;
  1186.         } else if (minute > 59) {
  1187.             hourShift = minute / 60;
  1188.         } else {
  1189.             hourShift = 0;
  1190.         }
  1191.         minute -= 60 * hourShift;
  1192.         int hour = utcComponents.getTime().getHour() + hourShift;
  1193.         final int dayShift;
  1194.         if (hour < 0) {
  1195.             dayShift = (hour - 23) / 24;
  1196.         } else if (hour > 23) {
  1197.             dayShift = hour / 24;
  1198.         } else {
  1199.             dayShift = 0;
  1200.         }
  1201.         hour -= 24 * dayShift;

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

  1204.     }

  1205.     /** {@inheritDoc} */
  1206.     public FieldAbsoluteDate<T> getDate() {
  1207.         return this;
  1208.     }

  1209.     /** Get the field.
  1210.      * @return field instance.
  1211.      */
  1212.     public Field<T> getField() {
  1213.         return field;
  1214.     }

  1215.     /** Split the instance into date/time components for a time zone.
  1216.      *
  1217.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  1218.      *
  1219.      * @param timeZone time zone
  1220.      * @return date/time components
  1221.      * @see #getComponents(TimeZone, TimeScale)
  1222.      */
  1223.     @DefaultDataContext
  1224.     public DateTimeComponents getComponents(final TimeZone timeZone) {
  1225.         return getComponents(timeZone, DataContext.getDefault().getTimeScales().getUTC());
  1226.     }

  1227.     /** Split the instance into date/time components for a time zone.
  1228.      * @param timeZone time zone
  1229.      * @param utc            time scale used to compute date and time components.
  1230.      * @return date/time components
  1231.      * @since 10.1
  1232.      */
  1233.     public DateTimeComponents getComponents(final TimeZone timeZone,
  1234.                                             final TimeScale utc) {
  1235.         final FieldAbsoluteDate<T> javaEpoch =
  1236.                 new FieldAbsoluteDate<>(field, DateComponents.JAVA_EPOCH, utc);
  1237.         final long milliseconds = FastMath.round((offsetFrom(javaEpoch, utc).getReal()) * 1000);
  1238.         return getComponents(timeZone.getOffset(milliseconds) / 60000, utc);
  1239.     }

  1240.     /** Compare the instance with another date.
  1241.      * @param date other date to compare the instance to
  1242.      * @return a negative integer, zero, or a positive integer as this date
  1243.      * is before, simultaneous, or after the specified date.
  1244.      */
  1245.     public int compareTo(final FieldAbsoluteDate<T> date) {
  1246.         return Double.compare(durationFrom(date).getReal(), 0.0);
  1247.     }


  1248.     /** Check if the instance represents the same time as another instance.
  1249.      * @param date other date
  1250.      * @return true if the instance and the other date refer to the same instant
  1251.      */
  1252.     @SuppressWarnings("unchecked")
  1253.     public boolean equals(final Object date) {

  1254.         if (date == this) {
  1255.             // first fast check
  1256.             return true;
  1257.         }

  1258.         if (date instanceof FieldAbsoluteDate) {
  1259.             return durationFrom((FieldAbsoluteDate<T>) date).getReal() == 0.0;
  1260.         }

  1261.         return false;

  1262.     }

  1263.     /** Check if the instance represents the same time as another.
  1264.      * @param other the instant to compare this date to
  1265.      * @return true if the instance and the argument refer to the same instant
  1266.      * @see #isCloseTo(FieldTimeStamped, double)
  1267.      * @since 10.1
  1268.      */
  1269.     public boolean isEqualTo(final FieldTimeStamped<T> other) {
  1270.         return this.equals(other.getDate());
  1271.     }

  1272.     /** Check if the instance time is close to another.
  1273.      * @param other the instant to compare this date to
  1274.      * @param tolerance the separation, in seconds, under which the two instants will be considered close to each other
  1275.      * @return true if the duration between the instance and the argument is strictly below the tolerance
  1276.      * @see #isEqualTo(FieldTimeStamped)
  1277.      * @since 10.1
  1278.      */
  1279.     public boolean isCloseTo(final FieldTimeStamped<T> other, final double tolerance) {
  1280.         return FastMath.abs(this.durationFrom(other.getDate()).getReal()) < tolerance;
  1281.     }

  1282.     /** Check if the instance represents a time that is strictly before another.
  1283.      * @param other the instant to compare this date to
  1284.      * @return true if the instance is strictly before the argument when ordering chronologically
  1285.      * @see #isBeforeOrEqualTo(FieldTimeStamped)
  1286.      * @since 10.1
  1287.      */
  1288.     public boolean isBefore(final FieldTimeStamped<T> other) {
  1289.         return this.compareTo(other.getDate()) < 0;
  1290.     }

  1291.     /** Check if the instance represents a time that is strictly after another.
  1292.      * @param other the instant to compare this date to
  1293.      * @return true if the instance is strictly after the argument when ordering chronologically
  1294.      * @see #isAfterOrEqualTo(FieldTimeStamped)
  1295.      * @since 10.1
  1296.      */
  1297.     public boolean isAfter(final FieldTimeStamped<T> other) {
  1298.         return this.compareTo(other.getDate()) > 0;
  1299.     }

  1300.     /** Check if the instance represents a time that is before or equal to another.
  1301.      * @param other the instant to compare this date to
  1302.      * @return true if the instance is before (or equal to) the argument when ordering chronologically
  1303.      * @see #isBefore(FieldTimeStamped)
  1304.      * @since 10.1
  1305.      */
  1306.     public boolean isBeforeOrEqualTo(final FieldTimeStamped<T> other) {
  1307.         return this.isEqualTo(other) || this.isBefore(other);
  1308.     }

  1309.     /** Check if the instance represents a time that is after or equal to another.
  1310.      * @param other the instant to compare this date to
  1311.      * @return true if the instance is after (or equal to) the argument when ordering chronologically
  1312.      * @see #isAfterOrEqualTo(FieldTimeStamped)
  1313.      * @since 10.1
  1314.      */
  1315.     public boolean isAfterOrEqualTo(final FieldTimeStamped<T> other) {
  1316.         return this.isEqualTo(other) || this.isAfter(other);
  1317.     }

  1318.     /** Check if the instance represents a time that is strictly between two others representing
  1319.      * the boundaries of a time span. The two boundaries can be provided in any order: in other words,
  1320.      * whether <code>boundary</code> represents a time that is before or after <code>otherBoundary</code> will
  1321.      * not change the result of this method.
  1322.      * @param boundary one end of the time span
  1323.      * @param otherBoundary the other end of the time span
  1324.      * @return true if the instance is strictly between the two arguments when ordering chronologically
  1325.      * @see #isBetweenOrEqualTo(FieldTimeStamped, FieldTimeStamped)
  1326.      * @since 10.1
  1327.      */
  1328.     public boolean isBetween(final FieldTimeStamped<T> boundary, final FieldTimeStamped<T> otherBoundary) {
  1329.         final FieldTimeStamped<T> beginning;
  1330.         final FieldTimeStamped<T> end;
  1331.         if (boundary.getDate().isBefore(otherBoundary)) {
  1332.             beginning = boundary;
  1333.             end = otherBoundary;
  1334.         } else {
  1335.             beginning = otherBoundary;
  1336.             end = boundary;
  1337.         }
  1338.         return this.isAfter(beginning) && this.isBefore(end);
  1339.     }

  1340.     /** Check if the instance represents a time that is between two others representing
  1341.      * the boundaries of a time span, or equal to one of them. The two boundaries can be provided in any order:
  1342.      * in other words, whether <code>boundary</code> represents a time that is before or after
  1343.      * <code>otherBoundary</code> will not change the result of this method.
  1344.      * @param boundary one end of the time span
  1345.      * @param otherBoundary the other end of the time span
  1346.      * @return true if the instance is between the two arguments (or equal to at least one of them)
  1347.      * when ordering chronologically
  1348.      * @see #isBetween(FieldTimeStamped, FieldTimeStamped)
  1349.      * @since 10.1
  1350.      */
  1351.     public boolean isBetweenOrEqualTo(final FieldTimeStamped<T> boundary, final FieldTimeStamped<T> otherBoundary) {
  1352.         return this.isEqualTo(boundary) || this.isEqualTo(otherBoundary) || this.isBetween(boundary, otherBoundary);
  1353.     }

  1354.     /** Get a hashcode for this date.
  1355.      * @return hashcode
  1356.      */
  1357.     public int hashCode() {
  1358.         final long l = Double.doubleToLongBits(durationFrom(AbsoluteDate.ARBITRARY_EPOCH).getReal());
  1359.         return (int) (l ^ (l >>> 32));
  1360.     }

  1361.     /**
  1362.      * Get a String representation of the instant location with up to 16 digits of
  1363.      * precision for the seconds value.
  1364.      *
  1365.      * <p> Since this method is used in exception messages and error handling every
  1366.      * effort is made to return some representation of the instant. If UTC is available
  1367.      * from the default data context then it is used to format the string in UTC. If not
  1368.      * then TAI is used. Finally if the prior attempts fail this method falls back to
  1369.      * converting this class's internal representation to a string.
  1370.      *
  1371.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  1372.      *
  1373.      * @return a string representation of the instance, in ISO-8601 format if UTC is
  1374.      * available from the default data context.
  1375.      * @see AbsoluteDate#toString()
  1376.      * @see #toString(TimeScale)
  1377.      * @see DateTimeComponents#toString(int, int)
  1378.      */
  1379.     @DefaultDataContext
  1380.     public String toString() {
  1381.         return toAbsoluteDate().toString();
  1382.     }

  1383.     /**
  1384.      * Get a String representation of the instant location in ISO-8601 format without the
  1385.      * UTC offset and with up to 16 digits of precision for the seconds value.
  1386.      *
  1387.      * @param timeScale time scale to use
  1388.      * @return a string representation of the instance.
  1389.      * @see DateTimeComponents#toString(int, int)
  1390.      */
  1391.     public String toString(final TimeScale timeScale) {
  1392.         return getComponents(timeScale).toStringWithoutUtcOffset();
  1393.     }

  1394.     /** Get a String representation of the instant location for a local time.
  1395.      *
  1396.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  1397.      *
  1398.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  1399.      * negative Westward UTC).
  1400.      * @return string representation of the instance,
  1401.      * in ISO-8601 format with milliseconds accuracy
  1402.      * @see #toString(int, TimeScale)
  1403.      */
  1404.     @DefaultDataContext
  1405.     public String toString(final int minutesFromUTC) {
  1406.         return toString(minutesFromUTC,
  1407.                 DataContext.getDefault().getTimeScales().getUTC());
  1408.     }

  1409.     /**
  1410.      * Get a String representation of the instant location for a local time.
  1411.      *
  1412.      * @param minutesFromUTC offset in <em>minutes</em> from UTC (positive Eastwards UTC,
  1413.      *                       negative Westward UTC).
  1414.      * @param utc            time scale used to compute date and time components.
  1415.      * @return string representation of the instance, in ISO-8601 format with milliseconds
  1416.      * accuracy
  1417.      * @since 10.1
  1418.      */
  1419.     public String toString(final int minutesFromUTC, final TimeScale utc) {
  1420.         final int minuteDuration = utc.minuteDuration(this);
  1421.         return getComponents(minutesFromUTC, utc).toString(minuteDuration);
  1422.     }

  1423.     /** Get a String representation of the instant location for a time zone.
  1424.      *
  1425.      * <p>This method uses the {@link DataContext#getDefault() default data context}.
  1426.      *
  1427.      * @param timeZone time zone
  1428.      * @return string representation of the instance,
  1429.      * in ISO-8601 format with milliseconds accuracy
  1430.      * @see #toString(TimeZone, TimeScale)
  1431.      */
  1432.     @DefaultDataContext
  1433.     public String toString(final TimeZone timeZone) {
  1434.         return toString(timeZone, DataContext.getDefault().getTimeScales().getUTC());
  1435.     }

  1436.     /**
  1437.      * Get a String representation of the instant location for a time zone.
  1438.      *
  1439.      * @param timeZone time zone
  1440.      * @param utc      time scale used to compute date and time components.
  1441.      * @return string representation of the instance, in ISO-8601 format with milliseconds
  1442.      * accuracy
  1443.      * @since 10.1
  1444.      */
  1445.     public String toString(final TimeZone timeZone, final TimeScale utc) {
  1446.         final int minuteDuration = utc.minuteDuration(this);
  1447.         return getComponents(timeZone, utc).toString(minuteDuration);
  1448.     }

  1449.     /** Get a time-shifted date.
  1450.      * <p>
  1451.      * Calling this method is equivalent to call <code>new AbsoluteDate(this, dt)</code>.
  1452.      * </p>
  1453.      * @param dt time shift in seconds
  1454.      * @return a new date, shifted with respect to instance (which is immutable)
  1455.      * @see org.orekit.utils.PVCoordinates#shiftedBy(double)
  1456.      * @see org.orekit.attitudes.Attitude#shiftedBy(double)
  1457.      * @see org.orekit.orbits.Orbit#shiftedBy(double)
  1458.      * @see org.orekit.propagation.SpacecraftState#shiftedBy(double)
  1459.      */

  1460.     @Override
  1461.     public FieldAbsoluteDate<T> shiftedBy(final double dt) {
  1462.         return new FieldAbsoluteDate<>(this, dt);
  1463.     }


  1464.     /** Transform the FieldAbsoluteDate in an AbsoluteDate.
  1465.      * @return AbsoluteDate of the FieldObject
  1466.      * */
  1467.     public AbsoluteDate toAbsoluteDate() {
  1468.         return new AbsoluteDate(epoch, offset.getReal());
  1469.     }

  1470. }