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, SIUnit>
20 {
21 /** */
22 private static final long serialVersionUID = 600L;
23
24 /**
25 * Instantiate a SI quantity with a unit.
26 * @param value the value, expressed in the unit
27 * @param unit the unit in which the value is expressed
28 */
29 public SIQuantity(final double value, final SIUnit unit)
30 {
31 super(value, unit);
32 }
33
34 /**
35 * Instantiate a SI quantity with a unit, expressed as a String.
36 * @param value 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 value, final String abbreviation)
40 {
41 this(value, 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 instantiate(final double si)
55 {
56 return new SIQuantity(si, getDisplayUnit());
57 }
58
59 @Override
60 public SIUnit siUnit()
61 {
62 return getDisplayUnit();
63 }
64
65 /**
66 * Returns an SI quantity representation of a textual representation of a value with a unit. The String representation that
67 * can be parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are
68 * allowed, but not required, between the value and the unit.
69 * @param text the textual representation to parse into a SI
70 * @return the Scalar representation of the value in its unit
71 * @throws IllegalArgumentException when the text cannot be parsed
72 * @throws NullPointerException when the text argument is null
73 */
74 public static SIQuantity valueOf(final String text)
75 {
76 Throw.whenNull(text, "Error parsing SI quantity: text to parse is null");
77 Throw.when(text.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty text to parse");
78 try
79 {
80 NumberParser numberParser = new NumberParser().lenient().trailing();
81 double d = numberParser.parseDouble(text);
82 String unitString = text.substring(numberParser.getTrailingPosition()).trim();
83 SIUnit unit = SIUnit.of(unitString);
84 return new SIQuantity(d, unit);
85 }
86 catch (Exception exception)
87 {
88 throw new IllegalArgumentException(
89 "Error parsing SI quantity from " + text + " using Locale " + Locale.getDefault(Locale.Category.FORMAT),
90 exception);
91 }
92 }
93
94 /**
95 * Returns an SI quantity based on a value and the textual representation of the unit, which can be localized.
96 * @param value the value to use
97 * @param unitString the textual representation of the unit
98 * @return the Scalar representation of the value in its unit
99 * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
100 * @throws NullPointerException when the unitString argument is null
101 */
102 public static SIQuantity of(final double value, final String unitString)
103 {
104 Throw.whenNull(unitString, "Error parsing SI quantity: unitString is null");
105 Throw.when(unitString.length() == 0, IllegalArgumentException.class, "Error parsing SI quantity: empty unitString");
106 SIUnit unit = SIUnit.of(unitString);
107 return new SIQuantity(value, unit);
108 }
109
110 }