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