View Javadoc
1   package org.djunits.value.vdouble.scalar;
2   
3   import java.util.Locale;
4   
5   import org.djunits.unit.DurationUnit;
6   import org.djunits.unit.TimeUnit;
7   import org.djunits.value.vdouble.scalar.base.AbstractDoubleScalarAbs;
8   import org.djutils.base.NumberParser;
9   import org.djutils.exceptions.Throw;
10  
11  import jakarta.annotation.Generated;
12  
13  /**
14   * Easy access methods for the Absolute Time DoubleScalar.
15   * <p>
16   * Copyright (c) 2013-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. <br>
17   * All rights reserved. <br>
18   * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>.
19   * <p>
20   * Note that when the offset of a stored absolute Time becomes large, precision of a double might not be enough for the required
21   * resolution of a Time. A double has around 16 significant digits (52 bit mantissa). This means that when we need to have a
22   * double Time with TimeUnit.BASE as its unit, the largest value where the ms precision is reached is 2^51 = 2.3E15, which is
23   * around 71000 years. This is sufficient to store a date in the 21st Century with a BASE or an Epoch offset precise to a
24   * microsecond.
25   * </p>
26   * @author <a href="https://www.tudelft.nl/averbraeck">Alexander Verbraeck</a>
27   * @author <a href="https://www.tudelft.nl/staff/p.knoppers/">Peter Knoppers</a>
28   */
29  @Generated(value = "org.djunits.generator.GenerateDJUNIT", date = "2023-04-30T13:59:27.633664900Z")
30  public class Time extends AbstractDoubleScalarAbs<TimeUnit, Time, DurationUnit, Duration>
31  {
32      /** */
33      private static final long serialVersionUID = 20150901L;
34  
35      /** Constant with value zero. */
36      public static final Time ZERO = new Time(0.0, TimeUnit.DEFAULT);
37  
38      /**
39       * Construct Time scalar.
40       * @param value double; value
41       * @param unit TimeUnit; unit for the double value
42       */
43      public Time(final double value, final TimeUnit unit)
44      {
45          super(value, unit);
46      }
47  
48      /**
49       * Construct Time scalar.
50       * @param value Time; Scalar from which to construct this instance
51       */
52      public Time(final Time value)
53      {
54          super(value);
55      }
56  
57      /** {@inheritDoc} */
58      @Override
59      public final Time instantiateAbs(final double value, final TimeUnit unit)
60      {
61          return new Time(value, unit);
62      }
63  
64      /** {@inheritDoc} */
65      @Override
66      public final Duration instantiateRel(final double value, final DurationUnit unit)
67      {
68          return new Duration(value, unit);
69      }
70  
71      /**
72       * Construct Time scalar.
73       * @param value double; value in SI units
74       * @return Time; the new scalar with the SI value
75       */
76      public static final Time instantiateSI(final double value)
77      {
78          return new Time(value, TimeUnit.DEFAULT);
79      }
80  
81      /**
82       * Interpolate between two values.
83       * @param zero Time; the low value
84       * @param one Time; the high value
85       * @param ratio double; the ratio between 0 and 1, inclusive
86       * @return Time; a Scalar at the ratio between
87       */
88      public static Time interpolate(final Time zero, final Time one, final double ratio)
89      {
90          return new Time(zero.getInUnit() * (1 - ratio) + one.getInUnit(zero.getDisplayUnit()) * ratio, zero.getDisplayUnit());
91      }
92  
93      /**
94       * Return the maximum value of two absolute scalars.
95       * @param a1 Time; the first scalar
96       * @param a2 Time; the second scalar
97       * @return Time; the maximum value of two absolute scalars
98       */
99      public static Time max(final Time a1, final Time a2)
100     {
101         return a1.gt(a2) ? a1 : a2;
102     }
103 
104     /**
105      * Return the maximum value of more than two absolute scalars.
106      * @param a1 Time; the first scalar
107      * @param a2 Time; the second scalar
108      * @param an Time...; the other scalars
109      * @return the maximum value of more than two absolute scalars
110      */
111     public static Time max(final Time a1, final Time a2, final Time... an)
112     {
113         Time maxa = a1.gt(a2) ? a1 : a2;
114         for (Time a : an)
115         {
116             if (a.gt(maxa))
117             {
118                 maxa = a;
119             }
120         }
121         return maxa;
122     }
123 
124     /**
125      * Return the minimum value of two absolute scalars.
126      * @param a1 Time; the first scalar
127      * @param a2 Time; the second scalar
128      * @return the minimum value of two absolute scalars
129      */
130     public static Time min(final Time a1, final Time a2)
131     {
132         return a1.lt(a2) ? a1 : a2;
133     }
134 
135     /**
136      * Return the minimum value of more than two absolute scalars.
137      * @param a1 Time; the first scalar
138      * @param a2 Time; the second scalar
139      * @param an Time...; the other scalars
140      * @return the minimum value of more than two absolute scalars
141      */
142     public static Time min(final Time a1, final Time a2, final Time... an)
143     {
144         Time mina = a1.lt(a2) ? a1 : a2;
145         for (Time a : an)
146         {
147             if (a.lt(mina))
148             {
149                 mina = a;
150             }
151         }
152         return mina;
153     }
154 
155     /**
156      * Returns a Time representation of a textual representation of a value with a unit. The String representation that can be
157      * parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are allowed,
158      * but not required, between the value and the unit.
159      * @param text String; the textual representation to parse into a Time
160      * @return Time; the Scalar representation of the value in its unit
161      * @throws IllegalArgumentException when the text cannot be parsed
162      * @throws NullPointerException when the text argument is null
163      */
164     public static Time valueOf(final String text)
165     {
166         Throw.whenNull(text, "Error parsing Time: text to parse is null");
167         Throw.when(text.length() == 0, IllegalArgumentException.class, "Error parsing Time: empty text to parse");
168         try
169         {
170             NumberParser numberParser = new NumberParser().lenient().trailing();
171             double d = numberParser.parseDouble(text);
172             String unitString = text.substring(numberParser.getTrailingPosition()).trim();
173             TimeUnit unit = TimeUnit.BASE.getUnitByAbbreviation(unitString);
174             if (unit == null)
175                 throw new IllegalArgumentException("Unit " + unitString + " not found");
176             return new Time(d, unit);
177         }
178         catch (Exception exception)
179         {
180             throw new IllegalArgumentException(
181                     "Error parsing Time from " + text + " using Locale " + Locale.getDefault(Locale.Category.FORMAT),
182                     exception);
183         }
184     }
185 
186     /**
187      * Returns a Time based on a value and the textual representation of the unit, which can be localized.
188      * @param value double; the value to use
189      * @param unitString String; the textual representation of the unit
190      * @return Time; the Scalar representation of the value in its unit
191      * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
192      * @throws NullPointerException when the unitString argument is null
193      */
194     public static Time of(final double value, final String unitString)
195     {
196         Throw.whenNull(unitString, "Error parsing Time: unitString is null");
197         Throw.when(unitString.length() == 0, IllegalArgumentException.class, "Error parsing Time: empty unitString");
198         TimeUnit unit = TimeUnit.BASE.getUnitByAbbreviation(unitString);
199         if (unit != null)
200         {
201             return new Time(value, unit);
202         }
203         throw new IllegalArgumentException("Error parsing Time with unit " + unitString);
204     }
205 
206 }