DateTimeComponents.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;

  19. import java.io.Serializable;
  20. import java.text.DecimalFormat;
  21. import java.text.DecimalFormatSymbols;
  22. import java.util.Locale;

  24. import org.hipparchus.util.FastMath;
  25. import org.orekit.utils.Constants;

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

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

  45.     /** Serializable UID. */
  46.     private static final long serialVersionUID = 5061129505488924484L;

  48.     /** Date component. */
  49.     private final DateComponents date;

  51.     /** Time component. */
  52.     private final TimeComponents time;

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

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

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

  99.     /** Build an instance from raw level components.
  100.      * <p>The hour is set to 00:00:00.000.</p>
  101.      * @param year year number (may be 0 or negative for BC years)
  102.      * @param month month number from 1 to 12
  103.      * @param day day number from 1 to 31
  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 int month, final int day)
  109.         throws IllegalArgumentException {
  110.         this.date = new DateComponents(year, month, day);
  111.         this.time = TimeComponents.H00;
  112.     }

  114.     /** Build an instance from raw level components.
  115.      * <p>The hour is set to 00:00:00.000.</p>
  116.      * @param year year number (may be 0 or negative for BC years)
  117.      * @param month month enumerate
  118.      * @param day day number from 1 to 31
  119.      * @exception IllegalArgumentException if inconsistent arguments
  120.      * are given (parameters out of range, february 29 for non-leap years,
  121.      * dates during the gregorian leap in 1582 ...)
  122.      */
  123.     public DateTimeComponents(final int year, final Month month, final int day)
  124.         throws IllegalArgumentException {
  125.         this.date = new DateComponents(year, month, day);
  126.         this.time = TimeComponents.H00;
  127.     }

  129.     /** Build an instance from a seconds offset with respect to another one.
  130.      * @param reference reference date/time
  131.      * @param offset offset from the reference in seconds
  132.      * @see #offsetFrom(DateTimeComponents)
  133.      */
  134.     public DateTimeComponents(final DateTimeComponents reference,
  135.                               final double offset) {

  137.         // extract linear data from reference date/time
  138.         int    day     = reference.getDate().getJ2000Day();
  139.         double seconds = reference.getTime().getSecondsInLocalDay();

  141.         // apply offset
  142.         seconds += offset;

  144.         // fix range
  145.         final int dayShift = (int) FastMath.floor(seconds / Constants.JULIAN_DAY);
  146.         seconds -= Constants.JULIAN_DAY * dayShift;
  147.         day     += dayShift;
  148.         final TimeComponents tmpTime = new TimeComponents(seconds);

  150.         // set up components
  151.         this.date = new DateComponents(day);
  152.         this.time = new TimeComponents(tmpTime.getHour(), tmpTime.getMinute(), tmpTime.getSecond(),
  153.                                        reference.getTime().getMinutesFromUTC());

  155.     }

  157.     /** Parse a string in ISO-8601 format to build a date/time.
  158.      * <p>The supported formats are all date formats supported by {@link DateComponents#parseDate(String)}
  159.      * and all time formats supported by {@link TimeComponents#parseTime(String)} separated
  160.      * by the standard time separator 'T', or date components only (in which case a 00:00:00 hour is
  161.      * implied). Typical examples are 2000-01-01T12:00:00Z or 1976W186T210000.
  162.      * </p>
  163.      * @param string string to parse
  164.      * @return a parsed date/time
  165.      * @exception IllegalArgumentException if string cannot be parsed
  166.      */
  167.     public static DateTimeComponents parseDateTime(final String string) {

  169.         // is there a time ?
  170.         final int tIndex = string.indexOf('T');
  171.         if (tIndex > 0) {
  172.             return new DateTimeComponents(DateComponents.parseDate(string.substring(0, tIndex)),
  173.                                           TimeComponents.parseTime(string.substring(tIndex + 1)));
  174.         }

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

  178.     }

  180.     /** Compute the seconds offset between two instances.
  181.      * @param dateTime dateTime to subtract from the instance
  182.      * @return offset in seconds between the two instants
  183.      * (positive if the instance is posterior to the argument)
  184.      * @see #DateTimeComponents(DateTimeComponents, double)
  185.      */
  186.     public double offsetFrom(final DateTimeComponents dateTime) {
  187.         final int dateOffset = date.getJ2000Day() - dateTime.date.getJ2000Day();
  188.         final double timeOffset = time.getSecondsInUTCDay() - dateTime.time.getSecondsInUTCDay();
  189.         return Constants.JULIAN_DAY * dateOffset + timeOffset;
  190.     }

  192.     /** Get the date component.
  193.      * @return date component
  194.      */
  195.     public DateComponents getDate() {
  196.         return date;
  197.     }

  199.     /** Get the time component.
  200.      * @return time component
  201.      */
  202.     public TimeComponents getTime() {
  203.         return time;
  204.     }

  206.     /** {@inheritDoc} */
  207.     public int compareTo(final DateTimeComponents other) {
  208.         final int dateComparison = date.compareTo(other.date);
  209.         if (dateComparison < 0) {
  210.             return -1;
  211.         } else if (dateComparison > 0) {
  212.             return 1;
  213.         }
  214.         return time.compareTo(other.time);
  215.     }

  217.     /** {@inheritDoc} */
  218.     public boolean equals(final Object other) {
  219.         try {
  220.             final DateTimeComponents otherDateTime = (DateTimeComponents) other;
  221.             return otherDateTime != null &&
  222.                    date.equals(otherDateTime.date) && time.equals(otherDateTime.time);
  223.         } catch (ClassCastException cce) {
  224.             return false;
  225.         }
  226.     }

  228.     /** {@inheritDoc} */
  229.     public int hashCode() {
  230.         return (date.hashCode() << 16) ^ time.hashCode();
  231.     }

  233.     /** Return a string representation of this pair.
  234.      * <p>The format used is ISO8601 including the UTC offset.</p>
  235.      * @return string representation of this pair
  236.      */
  237.     public String toString() {
  238.         return date.toString() + 'T' + time.toString();
  239.     }

  241.     /**
  242.      * Get a string representation of the date-time without the offset from UTC. The
  243.      * format used is ISO6801, except without the offset from UTC.
  244.      *
  245.      * @return a string representation of the date-time.
  246.      * @see #toStringWithoutUtcOffset(int, int)
  247.      * @see #toString(int, int)
  248.      * @see #toStringRfc3339()
  249.      */
  250.     public String toStringWithoutUtcOffset() {
  251.         return date.toString() + 'T' + time.toStringWithoutUtcOffset();
  252.     }


  255.     /**
  256.      * Return a string representation of this date-time, rounded to millisecond
  257.      * precision.
  258.      *
  259.      * <p>The format used is ISO8601 including the UTC offset.</p>
  260.      *
  261.      * @param minuteDuration 60, 61, or 62 seconds depending on the date being close to a
  262.      *                       leap second introduction and the magnitude of the leap
  263.      *                       second.
  264.      * @return string representation of this date, time, and UTC offset
  265.      * @see #toString(int, int)
  266.      */
  267.     public String toString(final int minuteDuration) {
  268.         return toString(minuteDuration, 3);
  269.     }

  271.     /**
  272.      * Return a string representation of this date-time, rounded to the given precision.
  273.      *
  274.      * <p>The format used is ISO8601 including the UTC offset.</p>
  275.      *
  276.      * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
  277.      *                       to a leap second introduction and the magnitude of the leap
  278.      *                       second.
  279.      * @param fractionDigits the number of digits to include after the decimal point in
  280.      *                       the string representation of the seconds. The date and time
  281.      *                       is first rounded as necessary. {@code fractionDigits} must
  282.      *                       be greater than or equal to {@code 0}.
  283.      * @return string representation of this date, time, and UTC offset
  284.      * @see #toStringRfc3339()
  285.      * @see #toStringWithoutUtcOffset()
  286.      * @see #toStringWithoutUtcOffset(int, int)
  287.      * @since 11.0
  288.      */
  289.     public String toString(final int minuteDuration, final int fractionDigits) {
  290.         return toStringWithoutUtcOffset(minuteDuration, fractionDigits) +
  291.                 time.formatUtcOffset();
  292.     }

  294.     /**
  295.      * Return a string representation of this date-time, rounded to the given precision.
  296.      *
  297.      * <p>The format used is ISO8601 without the UTC offset.</p>
  298.      *
  299.      * @param minuteDuration 59, 60, 61, or 62 seconds depending on the date being close
  300.      *                       to a leap second introduction and the magnitude of the leap
  301.      *                       second.
  302.      * @param fractionDigits the number of digits to include after the decimal point in
  303.      *                       the string representation of the seconds. The date and time
  304.      *                       is first rounded as necessary. {@code fractionDigits} must
  305.      *                       be greater than or equal to {@code 0}.
  306.      * @return string representation of this date, time, and UTC offset
  307.      * @see #toStringRfc3339()
  308.      * @see #toStringWithoutUtcOffset()
  309.      * @see #toString(int, int)
  310.      * @since 11.1
  311.      */
  312.     public String toStringWithoutUtcOffset(final int minuteDuration,
  313.                                            final int fractionDigits) {
  314.         final DecimalFormat secondsFormat =
  315.                 new DecimalFormat("00", new DecimalFormatSymbols(Locale.US));
  316.         secondsFormat.setMaximumFractionDigits(fractionDigits);
  317.         secondsFormat.setMinimumFractionDigits(fractionDigits);
  318.         DateComponents roundedDate = this.date;
  319.         TimeComponents roundedTime = this.time;
  320.         double second = time.getSecond();
  321.         final double wrap = minuteDuration - 0.5 * FastMath.pow(10, -fractionDigits);
  322.         if (second >= wrap) {
  323.             // we should wrap around to the next minute
  324.             int minute = time.getMinute();
  325.             int hour   = time.getHour();
  326.             int j2000  = date.getJ2000Day();
  327.             second = 0;
  328.             ++minute;
  329.             if (minute > 59) {
  330.                 minute = 0;
  331.                 ++hour;
  332.                 if (hour > 23) {
  333.                     hour = 0;
  334.                     ++j2000;
  335.                 }
  336.             }
  337.             roundedDate = new DateComponents(j2000);
  338.             roundedTime = new TimeComponents(hour, minute, second);
  339.         }
  340.         return roundedDate.toString() + 'T' +
  341.                 roundedTime.toStringWithoutUtcOffset(secondsFormat);
  342.     }

  344.     /**
  345.      * Represent the given date and time as a string according to the format in RFC 3339.
  346.      * RFC3339 is a restricted subset of ISO 8601 with a well defined grammar. This method
  347.      * includes enough precision to represent the point in time without rounding up to the
  348.      * next minute.
  349.      *
  350.      * <p>RFC3339 is unable to represent BC years, years of 10000 or more, time zone
  351.      * offsets of 100 hours or more, or NaN. In these cases the value returned from this
  352.      * method will not be valid RFC3339 format.
  353.      *
  354.      * @return RFC 3339 format string.
  355.      * @see <a href="https://tools.ietf.org/html/rfc3339#page-8">RFC 3339</a>
  356.      * @see AbsoluteDate#toStringRfc3339(TimeScale)
  357.      * @see #toString(int, int)
  358.      * @see #toStringWithoutUtcOffset()
  359.      */
  360.     public String toStringRfc3339() {
  361.         final DateComponents d = this.getDate();
  362.         final TimeComponents t = this.getTime();
  363.         // date
  364.         final String dateString = String.format("%04d-%02d-%02dT",
  365.                 d.getYear(), d.getMonth(), d.getDay());
  366.         // time
  367.         final String timeString;
  368.         if (t.getSecondsInLocalDay() != 0) {
  369.             final DecimalFormat format = new DecimalFormat("00.##############", new DecimalFormatSymbols(Locale.US));
  370.             timeString = String.format("%02d:%02d:", t.getHour(), t.getMinute()) +
  371.                     format.format(t.getSecond());
  372.         } else {
  373.             // shortcut for midnight local time
  374.             timeString = "00:00:00";
  375.         }
  376.         // offset
  377.         final int minutesFromUTC = t.getMinutesFromUTC();
  378.         final String timeZoneString;
  379.         if (minutesFromUTC == 0) {
  380.             timeZoneString = "Z";
  381.         } else {
  382.             // sign must be accounted for separately because there is no -0 in Java.
  383.             final String sign = minutesFromUTC < 0 ? "-" : "+";
  384.             final int utcOffset = FastMath.abs(minutesFromUTC);
  385.             final int hourOffset = utcOffset / 60;
  386.             final int minuteOffset = utcOffset % 60;
  387.             timeZoneString = sign + String.format("%02d:%02d", hourOffset, minuteOffset);
  388.         }
  389.         return dateString + timeString + timeZoneString;
  390.     }

  392. }
Created with JaCoCo 0.8.7.202105040129