1 package org.djunits.quantity;
2
3 import org.djunits.quantity.def.Quantity;
4 import org.djunits.unit.AbstractUnit;
5 import org.djunits.unit.UnitInterface;
6 import org.djunits.unit.UnitRuntimeException;
7 import org.djunits.unit.Unitless;
8 import org.djunits.unit.Units;
9 import org.djunits.unit.scale.IdentityScale;
10 import org.djunits.unit.scale.LinearScale;
11 import org.djunits.unit.scale.Scale;
12 import org.djunits.unit.si.SIPrefix;
13 import org.djunits.unit.si.SIPrefixes;
14 import org.djunits.unit.si.SIUnit;
15 import org.djunits.unit.system.UnitSystem;
16
17 /**
18 * Length is the measure of distance between two points, expressed in meters (m).
19 * <p>
20 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
21 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
22 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
23 * @author Alexander Verbraeck
24 */
25 public class Length extends Quantity<Length>
26 {
27 /** Constant with value zero. */
28 public static final Length ZERO = ofSi(0.0);
29
30 /** Constant with value one. */
31 public static final Length ONE = ofSi(1.0);
32
33 /** Constant with value NaN. */
34 @SuppressWarnings("checkstyle:constantname")
35 public static final Length NaN = ofSi(Double.NaN);
36
37 /** Constant with value POSITIVE_INFINITY. */
38 public static final Length POSITIVE_INFINITY = ofSi(Double.POSITIVE_INFINITY);
39
40 /** Constant with value NEGATIVE_INFINITY. */
41 public static final Length NEGATIVE_INFINITY = ofSi(Double.NEGATIVE_INFINITY);
42
43 /** Constant with value MAX_VALUE. */
44 public static final Length POS_MAXVALUE = ofSi(Double.MAX_VALUE);
45
46 /** Constant with value -MAX_VALUE. */
47 public static final Length NEG_MAXVALUE = ofSi(-Double.MAX_VALUE);
48
49 /** */
50 private static final long serialVersionUID = 600L;
51
52 /**
53 * Instantiate a Length quantity with an SI or base value and a display unit.
54 * @param value the quantity value expressed in the SI or base unit
55 * @param displayUnit the display unit to use
56 * @param useSi use SI value when true, use value in unit when false
57 */
58 public Length(final double value, final Length.Unit displayUnit, final boolean useSi)
59 {
60 super(value, displayUnit, useSi);
61 }
62
63 /**
64 * Instantiate a Length quantity expressed in the given unit.
65 * @param valueInUnit the quantity value expressed in the given unit
66 * @param unit the unit of the value, also acts as the display unit
67 */
68 public Length(final double valueInUnit, final Length.Unit unit)
69 {
70 this(valueInUnit, unit, false);
71 }
72
73 /**
74 * Return a Length instance based on an SI value.
75 * @param si the si value
76 * @return the Length instance based on an SI value
77 */
78 public static Length ofSi(final double si)
79 {
80 return new Length(si, Length.Unit.SI, true);
81 }
82
83 /**
84 * Instantiate a Length quantity with an SI or base value and a display unit.
85 * @param siValue the quantity value expressed in the SI or base unit
86 * @param displayUnit the display unit to use
87 * @return the Length instance based on an SI value with the given display unit
88 */
89 public static Length ofSi(final double siValue, final Length.Unit displayUnit)
90 {
91 return new Length(siValue, displayUnit, true);
92 }
93
94 @Override
95 public Length instantiateSi(final double siValue, final UnitInterface<Length> displayUnit)
96 {
97 return new Length(siValue, (Length.Unit) displayUnit, true);
98 }
99
100 /**
101 * Returns a Length representation of a textual representation of a value with a unit. The String representation that can be
102 * parsed is the double value in the unit, followed by a localized or English abbreviation of the unit. Spaces are allowed,
103 * but not required, between the value and the unit.
104 * @param text the textual representation to parse into a Length
105 * @return the Scalar representation of the value in its unit
106 * @throws IllegalArgumentException when the text cannot be parsed
107 * @throws NullPointerException when the text argument is null
108 */
109 public static Length valueOf(final String text)
110 {
111 return Quantity.valueOf(text, ZERO);
112 }
113
114 /**
115 * Returns a Length based on a value expressed in the unit.
116 * @param valueInUnit the value, expressed in the given unit
117 * @param unit the unit of the value, also acts as the display unit
118 * @return ab Length representation of the value in its unit
119 */
120 public static Length of(final double valueInUnit, final Length.Unit unit)
121 {
122 return new Length(valueInUnit, unit);
123 }
124
125 /**
126 * Returns a Length based on a value and the textual representation of the unit, which can be localized.
127 * @param valueInUnit the value, expressed in the unit as given by unitString
128 * @param unitString the textual representation of the unit
129 * @return the Scalar representation of the value in its unit
130 * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
131 * @throws NullPointerException when the unitString argument is null
132 */
133 public static Length of(final double valueInUnit, final String unitString)
134 {
135 return Quantity.of(valueInUnit, unitString, ZERO);
136 }
137
138 @Override
139 public Length.Unit getDisplayUnit()
140 {
141 return (Length.Unit) super.getDisplayUnit();
142 }
143
144 /**
145 * Add an (absolute) position to this length, and return a position. The unit of the return value will be the unit of this
146 * length, and the reference of the return value will be the reference belonging to the given position.
147 * <code>R.add(A)</code> = unit of R and reference value of A.
148 * @param position the absolute position to add
149 * @return the absolute position plus this length
150 */
151 public Position add(final Position position)
152 {
153 return new Position(new Length(position.si() + si(), getDisplayUnit(), true), position.getReference());
154
155 }
156
157 /**
158 * Calculate the division of Length and Length, which results in a Dimensionless quantity.
159 * @param v quantity
160 * @return quantity as a division of Length and Length
161 */
162 public Dimensionless divide(final Length v)
163 {
164 return new Dimensionless(this.si() / v.si(), Unitless.BASE);
165 }
166
167 /**
168 * Calculate the multiplication of Length and LinearObjectDensity, which results in a Dimensionless quantity.
169 * @param v quantity
170 * @return quantity as a multiplication of Length and LinearObjectDensity
171 */
172 public Dimensionless multiply(final LinearObjectDensity v)
173 {
174 return new Dimensionless(this.si() * v.si(), Unitless.BASE);
175 }
176
177 /**
178 * Calculate the multiplication of Length and Length, which results in a Area quantity.
179 * @param v quantity
180 * @return quantity as a multiplication of Length and Length
181 */
182 public Area multiply(final Length v)
183 {
184 return new Area(this.si() * v.si(), Area.Unit.SI);
185 }
186
187 /**
188 * Calculate the division of Length and LinearObjectDensity, which results in a Area quantity.
189 * @param v quantity
190 * @return quantity as a division of Length and LinearObjectDensity
191 */
192 public Area divide(final LinearObjectDensity v)
193 {
194 return new Area(this.si() / v.si(), Area.Unit.SI);
195 }
196
197 /**
198 * Calculate the division of Length and Area, which results in a LinearObjectDensity quantity.
199 * @param v quantity
200 * @return quantity as a division of Length and Area
201 */
202 public LinearObjectDensity divide(final Area v)
203 {
204 return new LinearObjectDensity(this.si() / v.si(), LinearObjectDensity.Unit.SI);
205 }
206
207 /**
208 * Calculate the multiplication of Length and Area, which results in a Volume quantity.
209 * @param v quantity
210 * @return quantity as a multiplication of Length and Area
211 */
212 public Volume multiply(final Area v)
213 {
214 return new Volume(this.si() * v.si(), Volume.Unit.SI);
215 }
216
217 /**
218 * Calculate the multiplication of Length and Force, which results in a Energy quantity.
219 * @param v quantity
220 * @return quantity as a multiplication of Length and Force
221 */
222 public Energy multiply(final Force v)
223 {
224 return new Energy(this.si() * v.si(), Energy.Unit.SI);
225 }
226
227 /**
228 * Calculate the multiplication of Length and Frequency, which results in a Speed quantity.
229 * @param v quantity
230 * @return quantity as a multiplication of Length and Frequency
231 */
232 public Speed multiply(final Frequency v)
233 {
234 return new Speed(this.si() * v.si(), Speed.Unit.SI);
235 }
236
237 /**
238 * Calculate the division of Length and Duration, which results in a Speed quantity.
239 * @param v quantity
240 * @return quantity as a division of Length and Duration
241 */
242 public Speed divide(final Duration v)
243 {
244 return new Speed(this.si() / v.si(), Speed.Unit.SI);
245 }
246
247 /**
248 * Calculate the division of Length and Speed, which results in a Duration quantity.
249 * @param v quantity
250 * @return quantity as a division of Length and Speed
251 */
252 public Duration divide(final Speed v)
253 {
254 return new Duration(this.si() / v.si(), Duration.Unit.SI);
255 }
256
257 /**
258 * Calculate the multiplication of Length and FlowMass, which results in a Momentum quantity.
259 * @param v quantity
260 * @return quantity as a multiplication of Length and FlowMass
261 */
262 public Momentum multiply(final FlowMass v)
263 {
264 return new Momentum(this.si() * v.si(), Momentum.Unit.SI);
265 }
266
267 @Override
268 public LinearObjectDensity reciprocal()
269 {
270 return LinearObjectDensity.ofSi(1.0 / this.si());
271 }
272
273 /******************************************************************************************************/
274 /********************************************** UNIT CLASS ********************************************/
275 /******************************************************************************************************/
276
277 /**
278 * Length.Unit encodes the length unit.
279 * <p>
280 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved.
281 * See for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
282 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
283 * @author Alexander Verbraeck
284 */
285 @SuppressWarnings("checkstyle:constantname")
286 public static class Unit extends AbstractUnit<Length>
287 {
288 /** Constant for the foot. */
289 public static final double CONST_FT = 0.3048;
290
291 /** Constant for the yard. */
292 public static final double CONST_YD = 3.0 * CONST_FT;
293
294 /** Constant for the inch. */
295 public static final double CONST_IN = CONST_FT / 12.0;
296
297 /** Constant for the mile. */
298 public static final double CONST_MI = 5280.0 * CONST_FT;
299
300 /** Constant for the nautical mile. */
301 public static final double CONST_NM = 1852.0;
302
303 /** Constant for the Astronomical Unit = 149,597,870,700 m. */
304 public static final double CONST_AU = 149_597_870_700.0;
305
306 /** Constant for the lightyear = 9,460,730,472,580,800 m. */
307 public static final double CONST_LY = 9_460_730_472_580_800.0;
308
309 /** Constant for the parsec = AU / tan(1 arcsecond) = AU * 648,000 / PI m. */
310 public static final double CONST_PC = 149_597_870_700.0 * 648_000.0 / Math.PI;
311
312 /** The dimensions of the length: m. */
313 public static final SIUnit SI_UNIT = SIUnit.of("m");
314
315 /** meter. */
316 public static final Length.Unit m =
317 new Length.Unit("m", "m", "meter", IdentityScale.SCALE, UnitSystem.SI_BASE, SIPrefixes.getSiPrefix(""));
318
319 /** The SI or BASE unit. */
320 public static final Length.Unit SI = (Unit) m.generateSiPrefixes(false, false);
321
322 /** decameter. */
323 public static final Length.Unit dam = Units.resolve(Length.Unit.class, "dam");
324
325 /** hectometer. */
326 public static final Length.Unit hm = Units.resolve(Length.Unit.class, "hm");
327
328 /** kilometer. */
329 public static final Length.Unit km = Units.resolve(Length.Unit.class, "km");
330
331 /** decimeter. */
332 public static final Length.Unit dm = Units.resolve(Length.Unit.class, "dm");
333
334 /** centimeter. */
335 public static final Length.Unit cm = Units.resolve(Length.Unit.class, "cm");
336
337 /** millimeter. */
338 public static final Length.Unit mm = Units.resolve(Length.Unit.class, "mm");
339
340 /** micrometer. */
341 public static final Length.Unit mum = Units.resolve(Length.Unit.class, "mum");
342
343 /** nanometer. */
344 public static final Length.Unit nm = Units.resolve(Length.Unit.class, "nm");
345
346 /** picometer. */
347 public static final Length.Unit pm = Units.resolve(Length.Unit.class, "pm");
348
349 /** attometer. */
350 public static final Length.Unit am = Units.resolve(Length.Unit.class, "am");
351
352 /** femtometer. */
353 public static final Length.Unit fm = Units.resolve(Length.Unit.class, "fm");
354
355 /** foot (international) = 0.3048 m = 1/3 yd = 12 inches. */
356 public static final Length.Unit ft =
357 new Length.Unit("ft", "ft", "foot", new LinearScale(CONST_FT), UnitSystem.IMPERIAL, null);
358
359 /** inch (international) = 2.54 cm = 1/36 yd = 1/12 ft. */
360 public static final Length.Unit in =
361 new Length.Unit("in", "in", "inch", new LinearScale(CONST_IN), UnitSystem.IMPERIAL, null);
362
363 /** yard (international) = 0.9144 m = 3 ft = 36 in. */
364 public static final Length.Unit yd =
365 new Length.Unit("yd", "yd", "yard", new LinearScale(CONST_YD), UnitSystem.IMPERIAL, null);
366
367 /** mile (international) = 5280 ft = 1760 yd. */
368 public static final Length.Unit mi =
369 new Length.Unit("mi", "mi", "mile", new LinearScale(CONST_MI), UnitSystem.IMPERIAL, null);
370
371 /** nautical mile (international) = 1852 m. */
372 public static final Length.Unit NM = new Length.Unit("NM", "Nautical Mile", CONST_NM, UnitSystem.OTHER);
373
374 /** Astronomical Unit = 149,597,870,700 m. */
375 public static final Length.Unit AU = new Length.Unit("AU", "Astronomical Unit", CONST_AU, UnitSystem.OTHER);
376
377 /** Lightyear = 9,460,730,472,580,800 m. */
378 public static final Length.Unit ly = new Length.Unit("ly", "lightyear", CONST_LY, UnitSystem.OTHER);
379
380 /** Parsec = AU / tan(1 arcsecond) = AU * 648,000 / PI m. */
381 public static final Length.Unit pc = new Length.Unit("pc", "Parsec", CONST_PC, UnitSystem.OTHER);
382
383 /** Angstrom = 10^-10 m. */
384 public static final Length.Unit A =
385 new Length.Unit("A", "\u00C5", "angstrom", new LinearScale(1.0E-10), UnitSystem.OTHER, null);
386
387 /**
388 * Create a new length unit.
389 * @param id the id or main abbreviation of the unit
390 * @param name the full name of the unit
391 * @param scaleFactorToBaseUnit the scale factor of the unit to convert it TO the base (SI) unit
392 * @param unitSystem the unit system such as SI or IMPERIAL
393 */
394 public Unit(final String id, final String name, final double scaleFactorToBaseUnit, final UnitSystem unitSystem)
395 {
396 super(id, name, scaleFactorToBaseUnit, unitSystem);
397 }
398
399 /**
400 * Return a derived unit for this unit, with textual abbreviation(s) and a display abbreviation.
401 * @param textualAbbreviation the textual abbreviation of the unit, which doubles as the id
402 * @param displayAbbreviation the display abbreviation of the unit
403 * @param name the full name of the unit
404 * @param scale the scale to use to convert from this unit to the standard (e.g., SI, BASE) unit
405 * @param unitSystem unit system, e.g. SI or Imperial
406 * @param siPrefix the SI Prefix of this unit
407 */
408 public Unit(final String textualAbbreviation, final String displayAbbreviation, final String name, final Scale scale,
409 final UnitSystem unitSystem, final SIPrefix siPrefix)
410 {
411 super(textualAbbreviation, displayAbbreviation, name, scale, unitSystem, siPrefix);
412 }
413
414 @Override
415 public SIUnit siUnit()
416 {
417 return SI_UNIT;
418 }
419
420 @Override
421 public Unit getBaseUnit()
422 {
423 return SI;
424 }
425
426 @Override
427 public Length ofSi(final double si, final UnitInterface<Length> displayUnit)
428 {
429 return new Length(si, (Unit) displayUnit, true);
430 }
431
432 @Override
433 public Length.Unit deriveUnit(final String abbreviation, final String name, final double scaleFactor,
434 final UnitSystem unitSystem)
435 {
436 return (Length.Unit) super.deriveUnit(abbreviation, name, scaleFactor, unitSystem);
437 }
438
439 @Override
440 public Length.Unit deriveUnit(final String textualAbbreviation, final String displayAbbreviation, final String name,
441 final double scaleFactor, final UnitSystem unitSystem, final SIPrefix siPrefix)
442 {
443 if (getScale() instanceof LinearScale ls)
444 {
445 return new Length.Unit(textualAbbreviation, displayAbbreviation, name,
446 new LinearScale(ls.getScaleFactorToBaseUnit() * scaleFactor), unitSystem, siPrefix);
447 }
448 throw new UnitRuntimeException("Only possible to derive a unit from a unit with a linear scale");
449 }
450
451 }
452
453 }