DateTimeComponents.java

  1. /* Copyright 2002-2025 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;

  19. import java.io.Serializable;

  21. import java.util.concurrent.TimeUnit;
  22. import org.hipparchus.util.FastMath;
  23. import org.orekit.utils.Constants;

  25. /** Holder for date and time components.
  26.  * <p>This class is a simple holder with no processing methods.</p>
  27.  * <p>Instance of this class are guaranteed to be immutable.</p>
  28.  * @see AbsoluteDate
  29.  * @see DateComponents
  30.  * @see TimeComponents
  31.  * @author Luc Maisonobe
  32.  */
  33. public class DateTimeComponents implements Serializable, Comparable<DateTimeComponents> {

  35.     /**
  36.      * The Julian Epoch.
  37.      *
  38.      * @see TimeScales#getJulianEpoch()
  39.      */
  40.     public static final DateTimeComponents JULIAN_EPOCH =
  41.             new DateTimeComponents(DateComponents.JULIAN_EPOCH, TimeComponents.H12);

  43.     /** Serializable UID. */
  44.     private static final long serialVersionUID = 20240720L;

  46.     /** Date component. */
  47.     private final DateComponents date;

  49.     /** Time component. */
  50.     private final TimeComponents time;

  52.     /** Build a new instance from its components.
  53.      * @param date date component
  54.      * @param time time component
  55.      */
  56.     public DateTimeComponents(final DateComponents date, final TimeComponents time) {
  57.         this.date = date;
  58.         this.time = time;
  59.     }

  61.     /** Build an instance from raw level components.
  62.      * @param year year number (may be 0 or negative for BC years)
  63.      * @param month month number from 1 to 12
  64.      * @param day day number from 1 to 31
  65.      * @param hour hour number from 0 to 23
  66.      * @param minute minute number from 0 to 59
  67.      * @param second second number from 0.0 to 60.0 (excluded)
  68.      * @exception IllegalArgumentException if inconsistent arguments
  69.      * are given (parameters out of range, february 29 for non-leap years,
  70.      * dates during the gregorian leap in 1582 ...)
  71.      */
  72.     public DateTimeComponents(final int year, final int month, final int day,
  73.                               final int hour, final int minute, final double second)
  74.         throws IllegalArgumentException {
  75.         this(year, month, day, hour, minute, new TimeOffset(second));
  76.     }

  78.     /** Build an instance from raw level components.
  79.      * @param year year number (may be 0 or negative for BC years)
  80.      * @param month month number from 1 to 12
  81.      * @param day day number from 1 to 31
  82.      * @param hour hour number from 0 to 23
  83.      * @param minute minute number from 0 to 59
  84.      * @param second second number from 0.0 to 60.0 (excluded)
  85.      * @exception IllegalArgumentException if inconsistent arguments
  86.      * are given (parameters out of range, february 29 for non-leap years,
  87.      * dates during the gregorian leap in 1582 ...)
  88.      * @since 13.0
  89.      */
  90.     public DateTimeComponents(final int year, final int month, final int day,
  91.                               final int hour, final int minute, final TimeOffset second)
  92.         throws IllegalArgumentException {
  93.         this.date = new DateComponents(year, month, day);
  94.         this.time = new TimeComponents(hour, minute, second);
  95.     }

  97.     /** Build an instance from raw level components.
  98.      * @param year year number (may be 0 or negative for BC years)
  99.      * @param month month enumerate
  100.      * @param day day number from 1 to 31
  101.      * @param hour hour number from 0 to 23
  102.      * @param minute minute number from 0 to 59
  103.      * @param second second number from 0.0 to 60.0 (excluded)
  104.      * @exception IllegalArgumentException if inconsistent arguments
  105.      * are given (parameters out of range, february 29 for non-leap years,
  106.      * dates during the gregorian leap in 1582 ...)
  107.      */
  108.     public DateTimeComponents(final int year, final Month month, final int day,
  109.                               final int hour, final int minute, final double second)
  110.         throws IllegalArgumentException {
  111.         this(year, month, day, hour, minute, new TimeOffset(second));
  112.     }

  114.     /** Build an instance from raw level components.
  115.      * @param year year number (may be 0 or negative for BC years)
  116.      * @param month month enumerate
  117.      * @param day day number from 1 to 31
  118.      * @param hour hour number from 0 to 23
  119.      * @param minute minute number from 0 to 59
  120.      * @param second second number from 0.0 to 60.0 (excluded)
  121.      * @exception IllegalArgumentException if inconsistent arguments
  122.      * are given (parameters out of range, february 29 for non-leap years,
  123.      * dates during the gregorian leap in 1582 ...)
  124.      * @since 13.0
  125.      */
  126.     public DateTimeComponents(final int year, final Month month, final int day,
  127.                               final int hour, final int minute, final TimeOffset second)
  128.         throws IllegalArgumentException {
  129.         this.date = new DateComponents(year, month, day);
  130.         this.time = new TimeComponents(hour, minute, second);
  131.     }

  133.     /** Build an instance from raw level components.
  134.      * <p>The hour is set to 00:00:00.000.</p>
  135.      * @param year year number (may be 0 or negative for BC years)
  136.      * @param month month number from 1 to 12
  137.      * @param day day number from 1 to 31
  138.      * @exception IllegalArgumentException if inconsistent arguments
  139.      * are given (parameters out of range, february 29 for non-leap years,
  140.      * dates during the gregorian leap in 1582 ...)
  141.      */
  142.     public DateTimeComponents(final int year, final int month, final int day)
  143.         throws IllegalArgumentException {
  144.         this.date = new DateComponents(year, month, day);
  145.         this.time = TimeComponents.H00;
  146.     }

  148.     /** Build an instance from raw level components.
  149.      * <p>The hour is set to 00:00:00.000.</p>
  150.      * @param year year number (may be 0 or negative for BC years)
  151.      * @param month month enumerate
  152.      * @param day day number from 1 to 31
  153.      * @exception IllegalArgumentException if inconsistent arguments
  154.      * are given (parameters out of range, february 29 for non-leap years,
  155.      * dates during the gregorian leap in 1582 ...)
  156.      */
  157.     public DateTimeComponents(final int year, final Month month, final int day)
  158.         throws IllegalArgumentException {
  159.         this.date = new DateComponents(year, month, day);
  160.         this.time = TimeComponents.H00;
  161.     }

  163.     /** Build an instance from a seconds offset with respect to another one.
  164.      * @param reference reference date/time
  165.      * @param offset offset from the reference in seconds
  166.      * @see #offsetFrom(DateTimeComponents)
  167.      */
  168.     public DateTimeComponents(final DateTimeComponents reference, final double offset) {
  169.         this(reference, new TimeOffset(offset));
  170.     }

  172.     /** Build an instance from a seconds offset with respect to another one.
  173.      * @param reference reference date/time
  174.      * @param offset offset from the reference in seconds
  175.      * @see #offsetFrom(DateTimeComponents)
  176.      * @since 13.0
  177.      */
  178.     public DateTimeComponents(final DateTimeComponents reference, final TimeOffset offset) {

  180.         // extract linear data from reference date/time
  181.         int    day     = reference.getDate().getJ2000Day();
  182.         TimeOffset seconds = reference.getTime().getSplitSecondsInLocalDay();

  184.         // apply offset
  185.         seconds = seconds.add(offset);

  187.         // fix range
  188.         final int dayShift = (int) FastMath.floor(seconds.toDouble() / Constants.JULIAN_DAY);
  189.         if (dayShift != 0) {
  190.             seconds = seconds.subtract(new TimeOffset(dayShift * TimeOffset.DAY.getSeconds(), 0L));
  191.         }
  192.         day     += dayShift;
  193.         final TimeComponents tmpTime = new TimeComponents(seconds);

  195.         // set up components
  196.         this.date = new DateComponents(day);
  197.         this.time = new TimeComponents(tmpTime.getHour(), tmpTime.getMinute(), tmpTime.getSplitSecond(),
  198.                                        reference.getTime().getMinutesFromUTC());

  200.     }

  202.     /** Build an instance from a seconds offset with respect to another one.
  203.      * @param reference reference date/time
  204.      * @param offset offset from the reference
  205.      * @param timeUnit the {@link TimeUnit} for the offset
  206.      * @see #offsetFrom(DateTimeComponents, TimeUnit)
  207.      * @since 12.1
  208.      */
  209.     public DateTimeComponents(final DateTimeComponents reference,
  210.                               final long offset, final TimeUnit timeUnit) {

  212.         // extract linear data from reference date/time
  213.         int       day     = reference.getDate().getJ2000Day();
  214.         TimeOffset seconds = reference.getTime().getSplitSecondsInLocalDay();

  216.         // apply offset
  217.         seconds = seconds.add(new TimeOffset(offset, timeUnit));

  219.         // fix range
  220.         final long dayShift = seconds.getSeconds() / TimeOffset.DAY.getSeconds() +
  221.                               (seconds.getSeconds() < 0L ? -1L : 0L);
  222.         if (dayShift != 0) {
  223.             seconds = seconds.subtract(new TimeOffset(dayShift, TimeOffset.DAY));
  224.             day    += dayShift;
  225.         }
  226.         final TimeComponents tmpTime = new TimeComponents(seconds);

  228.         // set up components
  229.         this.date = new DateComponents(day);
  230.         this.time = new TimeComponents(tmpTime.getHour(), tmpTime.getMinute(), tmpTime.getSplitSecond(),
  231.             reference.getTime().getMinutesFromUTC());

  233.     }

  235.     /** Parse a string in ISO-8601 format to build a date/time.
  236.      * <p>The supported formats are all date formats supported by {@link DateComponents#parseDate(String)}
  237.      * and all time formats supported by {@link TimeComponents#parseTime(String)} separated
  238.      * by the standard time separator 'T', or date components only (in which case a 00:00:00 hour is
  239.      * implied). Typical examples are 2000-01-01T12:00:00Z or 1976W186T210000.
  240.      * </p>
  241.      * @param string string to parse
  242.      * @return a parsed date/time
  243.      * @exception IllegalArgumentException if string cannot be parsed
  244.      */
  245.     public static DateTimeComponents parseDateTime(final String string) {

  247.         // is there a time ?
  248.         final int tIndex = string.indexOf('T');
  249.         if (tIndex > 0) {
  250.             return new DateTimeComponents(DateComponents.parseDate(string.substring(0, tIndex)),
  251.                                           TimeComponents.parseTime(string.substring(tIndex + 1)));
  252.         }

  254.         return new DateTimeComponents(DateComponents.parseDate(string), TimeComponents.H00);

  256.     }

  258.     /** Compute the seconds offset between two instances.
  259.      * @param dateTime dateTime to subtract from the instance
  260.      * @return offset in seconds between the two instants
  261.      * (positive if the instance is posterior to the argument)
  262.      * @see #DateTimeComponents(DateTimeComponents, TimeOffset)
  263.      */
  264.     public double offsetFrom(final DateTimeComponents dateTime) {
  265.         final int dateOffset = date.getJ2000Day() - dateTime.date.getJ2000Day();
  266.         final TimeOffset timeOffset = time.getSplitSecondsInUTCDay().
  267.                                      subtract(dateTime.time.getSplitSecondsInUTCDay());
  268.         return Constants.JULIAN_DAY * dateOffset + timeOffset.toDouble();
  269.     }

  271.     /** Compute the seconds offset between two instances.
  272.      * @param dateTime dateTime to subtract from the instance
  273.      * @param timeUnit the desired {@link TimeUnit}
  274.      * @return offset in the given timeunit between the two instants (positive
  275.      * if the instance is posterior to the argument), rounded to the nearest integer {@link TimeUnit}
  276.      * @see #DateTimeComponents(DateTimeComponents, long, TimeUnit)
  277.      * @since 12.1
  278.      */
  279.     public long offsetFrom(final DateTimeComponents dateTime, final TimeUnit timeUnit) {
  280.         final int dateOffset = date.getJ2000Day() - dateTime.date.getJ2000Day();
  281.         final TimeOffset timeOffset = time.getSplitSecondsInUTCDay().
  282.                                      subtract(dateTime.time.getSplitSecondsInUTCDay());
  283.         return TimeOffset.DAY.getRoundedTime(timeUnit) * dateOffset + timeOffset.getRoundedTime(timeUnit);
  284.     }

  286.     /** Get the date component.
  287.      * @return date component
  288.      */
  289.     public DateComponents getDate() {
  290.         return date;
  291.     }

  293.     /** Get the time component.
  294.      * @return time component
  295.      */
  296.     public TimeComponents getTime() {
  297.         return time;
  298.     }

  300.     /** {@inheritDoc} */
  301.     public int compareTo(final DateTimeComponents other) {
  302.         final int dateComparison = date.compareTo(other.date);
  303.         if (dateComparison < 0) {
  304.             return -1;
  305.         } else if (dateComparison > 0) {
  306.             return 1;
  307.         }
  308.         return time.compareTo(other.time);
  309.     }

  311.     /** {@inheritDoc} */
  312.     public boolean equals(final Object other) {
  313.         try {
  314.             final DateTimeComponents otherDateTime = (DateTimeComponents) other;
  315.             return otherDateTime != null &&
  316.                    date.equals(otherDateTime.date) && time.equals(otherDateTime.time);
  317.         } catch (ClassCastException cce) {
  318.             return false;
  319.         }
  320.     }

  322.     /** {@inheritDoc} */
  323.     public int hashCode() {
  324.         return (date.hashCode() << 16) ^ time.hashCode();
  325.     }

  327.     /** Return a string representation of this pair.
  328.      * <p>The format used is ISO8601 including the UTC offset.</p>
  329.      * @return string representation of this pair
  330.      */
  331.     public String toString() {
  332.         return date.toString() + 'T' + time.toString();
  333.     }

  335.     /**
  336.      * Get a string representation of the date-time without the offset from UTC. The
  337.      * format used is ISO6801, except without the offset from UTC.
  338.      *
  339.      * @return a string representation of the date-time.
  340.      * @see #toStringWithoutUtcOffset(int, int)
  341.      * @see #toString(int, int)
  342.      * @see #toStringRfc3339()
  343.      */
  344.     public String toStringWithoutUtcOffset() {
  345.         return date.toString() + 'T' + time.toStringWithoutUtcOffset();
  346.     }


  349.     /**
  350.      * Return a string representation of this date-time, rounded to millisecond
  351.      * precision.
  352.      *
  353.      * <p>The format used is ISO8601 including the UTC offset.</p>
  354.      *
  355.      * @param minuteDuration 60, 61, or 62 seconds depending on the date being close to a
  356.      *                       leap second introduction and the magnitude of the leap
  357.      *                       second.
  358.      * @return string representation of this date, time, and UTC offset
  359.      * @see #toString(int, int)
  360.      */
  361.     public String toString(final int minuteDuration) {
  362.         return toString(minuteDuration, 3);
  363.     }

  365.     /**
  366.      * Return a string representation of this date-time, rounded to the given precision.
  367.      *
  368.      * <p>The format used is ISO8601 including the UTC offset.</p>
  369.      *
  370.      * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
  371.      *                       to a leap second introduction and the magnitude of the leap
  372.      *                       second.
  373.      * @param fractionDigits the number of digits to include after the decimal point in
  374.      *                       the string representation of the seconds. The date and time
  375.      *                       is first rounded as necessary. {@code fractionDigits} must
  376.      *                       be greater than or equal to {@code 0}.
  377.      * @return string representation of this date, time, and UTC offset
  378.      * @see #toStringRfc3339()
  379.      * @see #toStringWithoutUtcOffset()
  380.      * @see #toStringWithoutUtcOffset(int, int)
  381.      * @since 11.0
  382.      */
  383.     public String toString(final int minuteDuration, final int fractionDigits) {
  384.         return toStringWithoutUtcOffset(minuteDuration, fractionDigits) +
  385.                 time.formatUtcOffset();
  386.     }

  388.     /**
  389.      * Return a string representation of this date-time, rounded to the given precision.
  390.      *
  391.      * <p>The format used is ISO8601 without the UTC offset.</p>
  392.      *
  393.      * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
  394.      *                       to a leap second introduction and the magnitude of the leap
  395.      *                       second.
  396.      * @param fractionDigits the number of digits to include after the decimal point in
  397.      *                       the string representation of the seconds. The date and time
  398.      *                       is first rounded as necessary. {@code fractionDigits} must
  399.      *                       be greater than or equal to {@code 0}.
  400.      * @return string representation of this date, time, and UTC offset
  401.      * @see #toStringRfc3339()
  402.      * @see #toStringWithoutUtcOffset()
  403.      * @see #toString(int, int)
  404.      * @since 11.1
  405.      */
  406.     public String toStringWithoutUtcOffset(final int minuteDuration,
  407.                                            final int fractionDigits) {
  408.         final DateTimeComponents rounded = roundIfNeeded(minuteDuration, fractionDigits);
  409.         return rounded.getDate().toString() + 'T' +
  410.                rounded.getTime().toStringWithoutUtcOffset(fractionDigits);
  411.     }

  413.     /**
  414.      * Round this date-time to the given precision if needed to prevent rounding up to an
  415.      * invalid seconds number. This is useful, for example, when writing custom date-time
  416.      * formatting methods so one does not, e.g., end up with "60.0" seconds during a
  417.      * normal minute when the value of seconds is {@code 59.999}. This method will instead
  418.      * round up the minute, hour, day, month, and year as needed.
  419.      *
  420.      * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
  421.      *                       to a leap second introduction and the magnitude of the leap
  422.      *                       second.
  423.      * @param fractionDigits the number of decimal digits after the decimal point in the
  424.      *                       seconds number that will be printed. This date-time is
  425.      *                       rounded to {@code fractionDigits} after the decimal point if
  426.      *                       necessary to prevent rounding up to {@code minuteDuration}.
  427.      *                       {@code fractionDigits} must be greater than or equal to
  428.      *                       {@code 0}.
  429.      * @return a date-time within {@code 0.5 * 10**-fractionDigits} seconds of this, and
  430.      * with a seconds number that will not round up to {@code minuteDuration} when rounded
  431.      * to {@code fractionDigits} after the decimal point.
  432.      * @since 11.3
  433.      */
  434.     public DateTimeComponents roundIfNeeded(final int minuteDuration, final int fractionDigits) {

  436.         final TimeComponents wrappedTime = time.wrapIfNeeded(minuteDuration, fractionDigits);
  437.         if (wrappedTime == time) {
  438.             // no wrapping was needed
  439.             return this;
  440.         } else {
  441.             if (wrappedTime.getHour() < time.getHour()) {
  442.                 // we have wrapped around next day
  443.                 return new DateTimeComponents(new DateComponents(date, 1), wrappedTime);
  444.             } else {
  445.                 // only the time was wrapped
  446.                 return new DateTimeComponents(date, wrappedTime);
  447.             }
  448.         }

  450.     }

  452.     /**
  453.      * Represent the given date and time as a string according to the format in RFC 3339.
  454.      * RFC3339 is a restricted subset of ISO 8601 with a well defined grammar. This method
  455.      * includes enough precision to represent the point in time without rounding up to the
  456.      * next minute.
  457.      *
  458.      * <p>RFC3339 is unable to represent BC years, years of 10000 or more, time zone
  459.      * offsets of 100 hours or more, or NaN. In these cases the value returned from this
  460.      * method will not be valid RFC3339 format.
  461.      *
  462.      * @return RFC 3339 format string.
  463.      * @see <a href="https://tools.ietf.org/html/rfc3339#page-8">RFC 3339</a>
  464.      * @see AbsoluteDate#toStringRfc3339(TimeScale)
  465.      * @see #toString(int, int)
  466.      * @see #toStringWithoutUtcOffset()
  467.      */
  468.     public String toStringRfc3339() {
  469.         final DateComponents d = this.getDate();
  470.         final TimeComponents t = this.getTime();
  471.         // date
  472.         final String dateString = String.format("%04d-%02d-%02dT",
  473.                 d.getYear(), d.getMonth(), d.getDay());
  474.         // time
  475.         final String timeString;
  476.         if (!t.getSplitSecondsInLocalDay().isZero()) {
  477.             final String formatted = t.toStringWithoutUtcOffset(18);
  478.             int last = formatted.length() - 1;
  479.             while (formatted.charAt(last) == '0') {
  480.                 // we want to remove final zeros
  481.                 --last;
  482.             }
  483.             if (formatted.charAt(last) == '.') {
  484.                 // remove the decimal point if no decimals follow
  485.                 --last;
  486.             }
  487.             timeString = formatted.substring(0, last + 1);
  488.         } else {
  489.             // shortcut for midnight local time
  490.             timeString = "00:00:00";
  491.         }
  492.         // offset
  493.         final int minutesFromUTC = t.getMinutesFromUTC();
  494.         final String timeZoneString;
  495.         if (minutesFromUTC == 0) {
  496.             timeZoneString = "Z";
  497.         } else {
  498.             // sign must be accounted for separately because there is no -0 in Java.
  499.             final String sign = minutesFromUTC < 0 ? "-" : "+";
  500.             final int utcOffset = FastMath.abs(minutesFromUTC);
  501.             final int hourOffset = utcOffset / 60;
  502.             final int minuteOffset = utcOffset % 60;
  503.             timeZoneString = sign + String.format("%02d:%02d", hourOffset, minuteOffset);
  504.         }
  505.         return dateString + timeString + timeZoneString;
  506.     }

  508. }
Created with JaCoCo 0.8.12.202403310830