1   /* Copyright 2002-2019 CS Systèmes d'Information
2    * Licensed to CS Systèmes d'Information (CS) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * CS licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *   http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.orekit.time;
18  
19  import java.io.Serializable;
20  import java.text.DecimalFormat;
21  import java.text.DecimalFormatSymbols;
22  import java.util.Locale;
23  import java.util.regex.Matcher;
24  import java.util.regex.Pattern;
25  
26  import org.hipparchus.util.FastMath;
27  import org.orekit.errors.OrekitIllegalArgumentException;
28  import org.orekit.errors.OrekitMessages;
29  
30  
31  /** Class representing a time within the day broken up as hour,
32   * minute and second components.
33   * <p>Instances of this class are guaranteed to be immutable.</p>
34   * @see DateComponents
35   * @see DateTimeComponents
36   * @author Luc Maisonobe
37   */
38  public class TimeComponents implements Serializable, Comparable<TimeComponents> {
39  
40      /** Constant for commonly used hour 00:00:00. */
41      public static final TimeComponentsmeComponents">TimeComponents H00   = new TimeComponents(0, 0, 0);
42  
43      /** Constant for commonly used hour 12:00:00. */
44      public static final TimeComponentsTimeComponents">TimeComponents H12 = new TimeComponents(12, 0, 0);
45  
46      /** Serializable UID. */
47      private static final long serialVersionUID = 20160331L;
48  
49      /** Format for hours and minutes. */
50      private static final DecimalFormat TWO_DIGITS = new DecimalFormat("00");
51  
52      /** Format for seconds. */
53      private static final DecimalFormat SECONDS_FORMAT =
54          new DecimalFormat("00.000", new DecimalFormatSymbols(Locale.US));
55  
56      /** Basic and extends formats for local time, with optional timezone. */
57      private static Pattern ISO8601_FORMATS = Pattern.compile("^(\\d\\d):?(\\d\\d):?(\\d\\d(?:[.,]\\d+)?)?(?:Z|([-+]\\d\\d(?::?\\d\\d)?))?$");
58  
59      /** Hour number. */
60      private final int hour;
61  
62      /** Minute number. */
63      private final int minute;
64  
65      /** Second number. */
66      private final double second;
67  
68      /** Offset between the specified date and UTC.
69       * <p>
70       * Always an integral number of minutes, as per ISO-8601 standard.
71       * </p>
72       * @since 7.2
73       */
74      private final int minutesFromUTC;
75  
76      /** Build a time from its clock elements.
77       * <p>Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed
78       * in this method, since they do occur during leap seconds introduction
79       * in the {@link UTCScale UTC} time scale.</p>
80       * @param hour hour number from 0 to 23
81       * @param minute minute number from 0 to 59
82       * @param second second number from 0.0 to 61.0 (excluded)
83       * @exception IllegalArgumentException if inconsistent arguments
84       * are given (parameters out of range)
85       */
86      public TimeComponents(final int hour, final int minute, final double second)
87          throws IllegalArgumentException {
88          this(hour, minute, second, 0);
89      }
90  
91      /** Build a time from its clock elements.
92       * <p>Note that seconds between 60.0 (inclusive) and 61.0 (exclusive) are allowed
93       * in this method, since they do occur during leap seconds introduction
94       * in the {@link UTCScale UTC} time scale.</p>
95       * @param hour hour number from 0 to 23
96       * @param minute minute number from 0 to 59
97       * @param second second number from 0.0 to 61.0 (excluded)
98       * @param minutesFromUTC offset between the specified date and UTC, as an
99       * integral number of minutes, as per ISO-8601 standard
100      * @exception IllegalArgumentException if inconsistent arguments
101      * are given (parameters out of range)
102      * @since 7.2
103      */
104     public TimeComponents(final int hour, final int minute, final double second,
105                           final int minutesFromUTC)
106         throws IllegalArgumentException {
107 
108         // range check
109         if ((hour   < 0) || (hour   >  23) ||
110             (minute < 0) || (minute >  59) ||
111             (second < 0) || (second >= 61.0)) {
112             throw new OrekitIllegalArgumentException(OrekitMessages.NON_EXISTENT_HMS_TIME,
113                                                      hour, minute, second);
114         }
115 
116         this.hour           = hour;
117         this.minute         = minute;
118         this.second         = second;
119         this.minutesFromUTC = minutesFromUTC;
120 
121     }
122 
123     /** Build a time from the second number within the day.
124      * <p>
125      * This constructor is always in UTC (i.e. {@link #getMinutesFromUTC() will return 0}).
126      * </p>
127      * @param secondInDay second number from 0.0 to {@link
128      * org.orekit.utils.Constants#JULIAN_DAY} (excluded)
129      * @exception OrekitIllegalArgumentException if seconds number is out of range
130      */
131     public TimeComponents(final double secondInDay)
132         throws OrekitIllegalArgumentException {
133         this(0, secondInDay);
134     }
135 
136     /** Build a time from the second number within the day.
137      * <p>
138      * The second number is defined here as the sum
139      * {@code secondInDayA + secondInDayB} from 0.0 to {@link
140      * org.orekit.utils.Constants#JULIAN_DAY} (excluded). The two parameters
141      * are used for increased accuracy.
142      * </p>
143      * <p>
144      * This constructor is always in UTC (i.e. {@link #getMinutesFromUTC() will return 0}).
145      * </p>
146      * @param secondInDayA first part of the second number
147      * @param secondInDayB last part of the second number
148      * @exception OrekitIllegalArgumentException if seconds number is out of range
149      */
150     public TimeComponents(final int secondInDayA, final double secondInDayB)
151         throws OrekitIllegalArgumentException {
152 
153         // split the numbers as a whole number of seconds
154         // and a fractional part between 0.0 (included) and 1.0 (excluded)
155         final int carry         = (int) FastMath.floor(secondInDayB);
156         int wholeSeconds        = secondInDayA + carry;
157         final double fractional = secondInDayB - carry;
158 
159         // range check
160         if (wholeSeconds < 0 || wholeSeconds > 86400) {
161             // beware, 86400 must be allowed to cope with leap seconds introduction days
162             throw new OrekitIllegalArgumentException(OrekitMessages.OUT_OF_RANGE_SECONDS_NUMBER,
163                                                      wholeSeconds + fractional);
164         }
165 
166         // extract the time components
167         hour           = wholeSeconds / 3600;
168         wholeSeconds  -= 3600 * hour;
169         minute         = wholeSeconds / 60;
170         wholeSeconds  -= 60 * minute;
171         second         = wholeSeconds + fractional;
172         minutesFromUTC = 0;
173 
174     }
175 
176     /** Parse a string in ISO-8601 format to build a time.
177      * <p>The supported formats are:
178      * <ul>
179      *   <li>basic and extended format local time: hhmmss, hh:mm:ss (with optional decimals in seconds)</li>
180      *   <li>optional UTC time: hhmmssZ, hh:mm:ssZ</li>
181      *   <li>optional signed hours UTC offset: hhmmss+HH, hhmmss-HH, hh:mm:ss+HH, hh:mm:ss-HH</li>
182      *   <li>optional signed basic hours and minutes UTC offset: hhmmss+HHMM, hhmmss-HHMM, hh:mm:ss+HHMM, hh:mm:ss-HHMM</li>
183      *   <li>optional signed extended hours and minutes UTC offset: hhmmss+HH:MM, hhmmss-HH:MM, hh:mm:ss+HH:MM, hh:mm:ss-HH:MM</li>
184      * </ul>
185      *
186      * <p> As shown by the list above, only the complete representations defined in section 4.2
187      * of ISO-8601 standard are supported, neither expended representations nor representations
188      * with reduced accuracy are supported.
189      *
190      * @param string string to parse
191      * @return a parsed time
192      * @exception IllegalArgumentException if string cannot be parsed
193      */
194     public static TimeComponents parseTime(final String string) {
195 
196         // is the date a calendar date ?
197         final Matcher timeMatcher = ISO8601_FORMATS.matcher(string);
198         if (timeMatcher.matches()) {
199             final int    hour      = Integer.parseInt(timeMatcher.group(1));
200             final int    minute    = Integer.parseInt(timeMatcher.group(2));
201             final double second    = timeMatcher.group(3) == null ? 0.0 : Double.parseDouble(timeMatcher.group(3).replace(',', '.'));
202             final String offset    = timeMatcher.group(4);
203             final int    minutesFromUTC;
204             if (offset == null) {
205                 // no offset from UTC is given
206                 minutesFromUTC = 0;
207             } else {
208                 // we need to parse an offset from UTC
209                 // the sign is mandatory and the ':' separator is optional
210                 // so we can have offsets given as -06:00 or +0100
211                 final int sign          = offset.codePointAt(0) == '-' ? -1 : +1;
212                 final int hourOffset    = Integer.parseInt(offset.substring(1, 3));
213                 final int minutesOffset = offset.length() <= 3 ? 0 : Integer.parseInt(offset.substring(offset.length() - 2));
214                 minutesFromUTC          = sign * (minutesOffset + 60 * hourOffset);
215             }
216             return new TimeComponents(hour, minute, second, minutesFromUTC);
217         }
218 
219         throw new OrekitIllegalArgumentException(OrekitMessages.NON_EXISTENT_TIME, string);
220 
221     }
222 
223     /** Get the hour number.
224      * @return hour number from 0 to 23
225      */
226     public int getHour() {
227         return hour;
228     }
229 
230     /** Get the minute number.
231      * @return minute minute number from 0 to 59
232      */
233     public int getMinute() {
234         return minute;
235     }
236 
237     /** Get the seconds number.
238      * @return second second number from 0.0 to 61.0 (excluded). Note that 60 &le; second
239      * &lt; 61 only occurs during a leap second.
240      */
241     public double getSecond() {
242         return second;
243     }
244 
245     /** Get the offset between the specified date and UTC.
246      * <p>
247      * The offset is always an integral number of minutes, as per ISO-8601 standard.
248      * </p>
249      * @return offset in minutes between the specified date and UTC
250      * @since 7.2
251      */
252     public int getMinutesFromUTC() {
253         return minutesFromUTC;
254     }
255 
256     /** Get the second number within the local day, <em>without</em> applying the {@link #getMinutesFromUTC() offset from UTC}.
257      * @return second number from 0.0 to Constants.JULIAN_DAY
258      * @see #getSecondsInUTCDay()
259      * @since 7.2
260      */
261     public double getSecondsInLocalDay() {
262         return second + 60 * minute + 3600 * hour;
263     }
264 
265     /** Get the second number within the UTC day, applying the {@link #getMinutesFromUTC() offset from UTC}.
266      * @return second number from {@link #getMinutesFromUTC() -getMinutesFromUTC()}
267      * to Constants.JULIAN_DAY {@link #getMinutesFromUTC() + getMinutesFromUTC()}
268      * @see #getSecondsInLocalDay()
269      * @since 7.2
270      */
271     public double getSecondsInUTCDay() {
272         return second + 60 * (minute - minutesFromUTC) + 3600 * hour;
273     }
274 
275     /** Get a string representation of the time.
276      * @return string representation of the time
277      */
278     public String toString() {
279         StringBuilder builder  = new StringBuilder().
280                                  append(TWO_DIGITS.format(hour)).append(':').
281                                  append(TWO_DIGITS.format(minute)).append(':').
282                                  append(SECONDS_FORMAT.format(second));
283         if (minutesFromUTC != 0) {
284             builder = builder.
285                       append(minutesFromUTC < 0 ? '-' : '+').
286                       append(TWO_DIGITS.format(FastMath.abs(minutesFromUTC) / 60)).append(':').
287                       append(TWO_DIGITS.format(FastMath.abs(minutesFromUTC) % 60));
288         }
289         return builder.toString();
290     }
291 
292     /** {@inheritDoc} */
293     public int compareTo(final TimeComponents other) {
294         return Double.compare(getSecondsInUTCDay(), other.getSecondsInUTCDay());
295     }
296 
297     /** {@inheritDoc} */
298     public boolean equals(final Object other) {
299         try {
300             final TimeComponentsg/orekit/time/TimeComponents.html#TimeComponents">TimeComponents otherTime = (TimeComponents) other;
301             return otherTime != null &&
302                    hour           == otherTime.hour   &&
303                    minute         == otherTime.minute &&
304                    second         == otherTime.second &&
305                    minutesFromUTC == otherTime.minutesFromUTC;
306         } catch (ClassCastException cce) {
307             return false;
308         }
309     }
310 
311     /** {@inheritDoc} */
312     public int hashCode() {
313         final long bits = Double.doubleToLongBits(second);
314         return ((hour << 16) ^ ((minute - minutesFromUTC) << 8)) ^ (int) (bits ^ (bits >>> 32));
315     }
316 
317 }