1 package org.djunits.quantity;
2
3 import java.util.Locale;
4
5 import org.djunits.quantity.def.Quantity;
6 import org.djunits.unit.UnitInterface;
7 import org.djunits.unit.si.SIUnit;
8 import org.djutils.base.NumberParser;
9 import org.djutils.exceptions.Throw;
10
11 /**
12 * SI quantity, with arbitrary SI unit. The class has <code>as...</code> methods such as <code>asDuration(...)</code>, which
13 * will succeed if the SI unit of the quantity is a duration unit, i.e., 's'.
14 * <p>
15 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
16 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
17 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
18 * @author Alexander Verbraeck
19 */
20 public class SIQuantity extends Quantity<SIQuantity>
21 {
22 /** */
23 private static final long serialVersionUID = 600L;
24
25 /**
26 * Instantiate a SIQuantity quantity with an SI or base value and a display unit.
27 * @param value the quantity value expressed in the SI or base unit
28 * @param displayUnit the display unit to use
29 * @param useSi use SI value when true, use value in unit when false
30 */
31 public SIQuantity(final double value, final SIUnit displayUnit, final boolean useSi)
32 {
33 super(value, displayUnit, useSi);
34 }
35
36 /**
37 * Instantiate a SIQuantity quantity expressed in the given unit.
38 * @param valueInUnit the quantity value expressed in the given unit
39 * @param unit the unit of the value, also acts as the display unit
40 */
41 public SIQuantity(final double valueInUnit, final SIUnit unit)
42 {
43 this(valueInUnit, unit, false);
44 }
45
46 /**
47 * Return a SIQuantity instance based on an SI value.
48 * @param si the si value
49 * @return the SIQuantity instance based on an SI value
50 */
51 public static SIQuantity ofSi(final double si)
52 {
53 return new SIQuantity(si, SIUnit.DIMLESS, true);
54 }
55
56 /**
57 * Instantiate a SIQuantity quantity with an SI or base value and a display unit.
58 * @param siValue the quantity value expressed in the SI or base unit
59 * @param displayUnit the display unit to use
60 * @return the SIQuantity instance based on an SI value with the given display unit
61 */
62 public static SIQuantity ofSi(final double siValue, final SIUnit displayUnit)
63 {
64 return new SIQuantity(siValue, displayUnit, true);
65 }
66
67 @Override
68 public SIQuantity instantiateSi(final double siValue, final UnitInterface<SIQuantity> displayUnit)
69 {
70 return new SIQuantity(siValue, (SIUnit) displayUnit, true);
71 }
72
73 /**
74 * Returns a SIQuantity based on a value expressed in the unit.
75 * @param valueInUnit the value, expressed in the given unit
76 * @param unit the unit of the value, also acts as the display unit
77 * @return ab SIQuantity representation of the value in its unit
78 */
79 public static SIQuantity of(final double valueInUnit, final SIUnit unit)
80 {
81 return new SIQuantity(valueInUnit, unit);
82 }
83
84 @Override
85 public SIUnit getDisplayUnit()
86 {
87 return (SIUnit) super.getDisplayUnit();
88 }
89
90 /**
91 * Returns an SI quantity representation of a textual representation of a value with a unit. The String representation that
92 * can be parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are
93 * allowed, but not required, between the value and the unit.
94 * @param text the textual representation to parse into a SI
95 * @return the Scalar representation of the value in its unit
96 * @throws IllegalArgumentException when the text cannot be parsed
97 * @throws NullPointerException when the text argument is null
98 */
99 public static SIQuantity valueOf(final String text)
100 {
101 Throw.whenNull(text, "Error parsing SI quantity: text to parse is null");
102 Throw.when(text.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty text to parse");
103 try
104 {
105 NumberParser numberParser = new NumberParser().lenient().trailing();
106 double d = numberParser.parseDouble(text);
107 String unitString = text.substring(numberParser.getTrailingPosition()).trim();
108 SIUnit unit = SIUnit.of(unitString);
109 return new SIQuantity(d, unit);
110 }
111 catch (Exception exception)
112 {
113 throw new IllegalArgumentException(
114 "Error parsing SI quantity from " + text + " using Locale " + Locale.getDefault(Locale.Category.FORMAT),
115 exception);
116 }
117 }
118
119 /**
120 * Returns an SI quantity based on a value and the textual representation of the unit, which can be localized.
121 * @param valueInUnit the value, expressed in the unit as given by unitString
122 * @param unitString the textual representation of the unit
123 * @return the Scalar representation of the value in its unit
124 * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
125 * @throws NullPointerException when the unitString argument is null
126 */
127 public static SIQuantity of(final double valueInUnit, final String unitString)
128 {
129 Throw.whenNull(unitString, "Error parsing SI quantity: unitString is null");
130 Throw.when(unitString.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty unitString");
131 SIUnit unit = SIUnit.of(unitString);
132 return new SIQuantity(valueInUnit, unit);
133 }
134
135 }