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 @Override
35 public SIQuantity instantiateSi(final double si)
36 {
37 return new SIQuantity(si, getDisplayUnit());
38 }
39
40 @Override
41 public SIUnit getDisplayUnit()
42 {
43 return (SIUnit) super.getDisplayUnit();
44 }
45
46 @Override
47 public SIUnit siUnit()
48 {
49 return getDisplayUnit();
50 }
51
52 /**
53 * Returns an SI quantity representation of a textual representation of a value with a unit. The String representation that
54 * can be parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are
55 * allowed, but not required, between the value and the unit.
56 * @param text the textual representation to parse into a SI
57 * @return the Scalar representation of the value in its unit
58 * @throws IllegalArgumentException when the text cannot be parsed
59 * @throws NullPointerException when the text argument is null
60 */
61 public static SIQuantity valueOf(final String text)
62 {
63 Throw.whenNull(text, "Error parsing SI quantity: text to parse is null");
64 Throw.when(text.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty text to parse");
65 try
66 {
67 NumberParser numberParser = new NumberParser().lenient().trailing();
68 double d = numberParser.parseDouble(text);
69 String unitString = text.substring(numberParser.getTrailingPosition()).trim();
70 SIUnit unit = SIUnit.of(unitString);
71 return new SIQuantity(d, unit);
72 }
73 catch (Exception exception)
74 {
75 throw new IllegalArgumentException(
76 "Error parsing SI quantity from " + text + " using Locale " + Locale.getDefault(Locale.Category.FORMAT),
77 exception);
78 }
79 }
80
81 /**
82 * Returns an SI quantity based on a value and the textual representation of the unit, which can be localized.
83 * @param valueInUnit the value, expressed in the unit as given by unitString
84 * @param unitString the textual representation of the unit
85 * @return the Scalar representation of the value in its unit
86 * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
87 * @throws NullPointerException when the unitString argument is null
88 */
89 public static SIQuantity of(final double valueInUnit, final String unitString)
90 {
91 Throw.whenNull(unitString, "Error parsing SI quantity: unitString is null");
92 Throw.when(unitString.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty unitString");
93 SIUnit unit = SIUnit.of(unitString);
94 return new SIQuantity(valueInUnit, unit);
95 }
96
97 }