1 package org.djunits.unit;
2
3 import org.djunits.quantity.def.Quantity;
4 import org.djunits.unit.scale.Scale;
5 import org.djunits.unit.si.SIPrefix;
6 import org.djunits.unit.si.SIUnit;
7 import org.djunits.unit.system.UnitSystem;
8
9 /**
10 * UnitInterface defines the contract for a unit.
11 * <p>
12 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
13 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
14 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
15 * @author Alexander Verbraeck
16 * @param <U> The unit type
17 * @param <Q> the quantity type
18 */
19 public interface Unit<U extends Unit<U, Q>, Q extends Quantity<Q>>
20 {
21 /**
22 * Return the id, which is the main abbreviation, of the unit.
23 * @return the id (main abbreviation) of the unit
24 */
25 String getId();
26
27 /**
28 * Retrieve the scale of this unit.
29 * @return the scale of this unit
30 */
31 Scale getScale();
32
33 /**
34 * Retrieve the unit system of this unit.
35 * @return unitSystem the unit system of this unit
36 */
37 UnitSystem getUnitSystem();
38
39 /**
40 * Return the SI unit for this unit.
41 * @return the SI unit for this unit
42 */
43 SIUnit siUnit();
44
45 /**
46 * Convert a value expressed in this unit to its base (SI) value.
47 * @param value the value expressed in this unit
48 * @return the value converted to its SI value
49 */
50 default double toBaseValue(final double value)
51 {
52 return getScale().toIdentityScale(value);
53 }
54
55 /**
56 * Convert an SI value to a value expressed in this unit.
57 * @param si the SI value
58 * @return the value converted to this unit
59 */
60 default double fromBaseValue(final double si)
61 {
62 return getScale().fromIdentityScale(si);
63 }
64
65 /**
66 * Return the base unit for this unit.
67 * @return the base unit for this unit
68 */
69 U getBaseUnit();
70
71 /**
72 * Retrieve the display abbreviation, and apply localization when possible.
73 * @return the (localized) display abbreviation
74 */
75 String getDisplayAbbreviation();
76
77 /**
78 * Retrieve the textual abbreviation, which doubles as the id of the unit. Apply localization when possible.
79 * @return the (localized) textual abbreviation
80 */
81 String getTextualAbbreviation();
82
83 /**
84 * Return the name, which is the main written explanation, of the unit. Apply localization when possible.
85 * @return the (localized) name of the unit
86 */
87 String getName();
88
89 /**
90 * Retrieve the stored display abbreviation, without localization.
91 * @return the stored (non-localized) display abbreviation
92 */
93 String getStoredDisplayAbbreviation();
94
95 /**
96 * Retrieve the stored textual abbreviation, which doubles as the id of the unit. Do not apply localization.
97 * @return the stored (non-localized) textual abbreviation
98 */
99 String getStoredTextualAbbreviation();
100
101 /**
102 * Return the name, which is the main written explanation, of the unit. Do not apply localization.
103 * @return the stored (non-localized) name of the unit
104 */
105 String getStoredName();
106
107 /**
108 * Set the SI-prefix so it can be localized if necessary.
109 * @param siPrefix the SI-prefix to set
110 * @return the unit for method chaining
111 */
112 U setSiPrefix(SIPrefix siPrefix);
113
114 /**
115 * Set the SI-prefix so it can be localized if necessary. This method does NOT handle kilo-prefixes.
116 * @param prefix the string-representation of the SI-prefix to set
117 * @return the unit for method chaining
118 */
119 U setSiPrefix(String prefix);
120
121 /**
122 * Set the SI-prefix so it can be localized if necessary. This method handles kilo-prefixes.
123 * @param prefix the string-representation of the SI-prefix to set
124 * @return the unit for method chaining
125 */
126 U setSiPrefixKilo(String prefix);
127
128 /**
129 * Set the SI-prefix so it can be localized if necessary. This method handles per-unit prefixes.
130 * @param prefix the string-representation of the SI-prefix to set
131 * @return the unit for method chaining
132 */
133 U setSiPrefixPer(String prefix);
134
135 /**
136 * Return the SI-prefix so it can be localized if necessary.
137 * @return the SI-prefix of this unit, or null when the unit has no SI-prefix
138 */
139 SIPrefix getSiPrefix();
140
141 /**
142 * Return an SI-quantity for this unit with a value.
143 * @param si the value in SI or BASE units
144 * @return an SI-quantity for this unit with the given si-value
145 */
146 Q ofSi(double si);
147
148 /**
149 * Return a quantity for this unit where the value is expressed in the current unit. When the unit is, e.g., kilometer, and
150 * the value is 10.0, the quantity returned will be 10 km, internally stored as 10,000 m with a displayUnit in km.
151 * @param value the value in the current unit
152 * @return a quantity with the value in the current unit
153 */
154 @SuppressWarnings("unchecked")
155 default Q quantityInUnit(final double value)
156 {
157 Q quantity = ofSi(getScale().toIdentityScale(value));
158 quantity.setDisplayUnit((U) this);
159 return quantity;
160 }
161 }