1 package org.djunits.quantity;
2
3 import org.djunits.quantity.def.Quantity;
4 import org.djunits.unit.Unitless;
5 import org.djunits.unit.Units;
6 import org.djunits.unit.si.SIUnit;
7
8 /**
9 * TemperatureDifference is a measure of (difference in) thermal state or average kinetic energy of particles, measured in
10 * kelvins (K). Note that the TemperatureDifference quantity is relative (it measures a difference between temperatures),
11 * whereas the Temperature quantity is absolute.
12 * <p>
13 * Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
14 * for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
15 * distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
16 * @author Alexander Verbraeck
17 */
18 public class TemperatureDifference extends Quantity<TemperatureDifference>
19 {
20 /** Constant with value zero. */
21 public static final TemperatureDifference ZERO = TemperatureDifference.ofSi(0.0);
22
23 /** Constant with value one. */
24 public static final TemperatureDifference ONE = TemperatureDifference.ofSi(1.0);
25
26 /** Constant with value NaN. */
27 @SuppressWarnings("checkstyle:constantname")
28 public static final TemperatureDifference NaN = TemperatureDifference.ofSi(Double.NaN);
29
30 /** Constant with value POSITIVE_INFINITY. */
31 public static final TemperatureDifference POSITIVE_INFINITY = TemperatureDifference.ofSi(Double.POSITIVE_INFINITY);
32
33 /** Constant with value NEGATIVE_INFINITY. */
34 public static final TemperatureDifference NEGATIVE_INFINITY = TemperatureDifference.ofSi(Double.NEGATIVE_INFINITY);
35
36 /** Constant with value MAX_VALUE. */
37 public static final TemperatureDifference POS_MAXVALUE = TemperatureDifference.ofSi(Double.MAX_VALUE);
38
39 /** Constant with value -MAX_VALUE. */
40 public static final TemperatureDifference NEG_MAXVALUE = TemperatureDifference.ofSi(-Double.MAX_VALUE);
41
42 /** */
43 private static final long serialVersionUID = 600L;
44
45 /**
46 * Instantiate a TemperatureDifference quantity with a unit.
47 * @param valueInUnit the value, expressed in the unit
48 * @param unit the unit in which the value is expressed
49 */
50 public TemperatureDifference(final double valueInUnit, final Temperature.Unit unit)
51 {
52 super(valueInUnit, unit);
53 }
54
55 /**
56 * Instantiate a TemperatureDifference quantity with a unit, expressed as a String.
57 * @param valueInUnit the value, expressed in the unit
58 * @param abbreviation the String abbreviation of the unit in which the value is expressed
59 */
60 public TemperatureDifference(final double valueInUnit, final String abbreviation)
61 {
62 this(valueInUnit, Units.resolve(Temperature.Unit.class, abbreviation));
63 }
64
65 /**
66 * Construct TemperatureDifference quantity.
67 * @param value Scalar from which to construct this instance
68 */
69 public TemperatureDifference(final TemperatureDifference value)
70 {
71 super(value.si(), Temperature.Unit.SI);
72 setDisplayUnit(value.getDisplayUnit());
73 }
74
75 /**
76 * Return a TemperatureDifference instance based on an SI value.
77 * @param si the si value
78 * @return the TemperatureDifference instance based on an SI value
79 */
80 public static TemperatureDifference ofSi(final double si)
81 {
82 return new TemperatureDifference(si, Temperature.Unit.SI);
83 }
84
85 @Override
86 public TemperatureDifference instantiateSi(final double si)
87 {
88 return ofSi(si);
89 }
90
91 @Override
92 public SIUnit siUnit()
93 {
94 return Temperature.Unit.SI_UNIT;
95 }
96
97 /**
98 * Returns a TemperatureDifference representation of a textual representation of a value with a unit. The String
99 * representation that can be parsed is the double value in the unit, followed by a localized or English abbreviation of the
100 * unit. Spaces are allowed, but not required, between the value and the unit.
101 * @param text the textual representation to parse into a Temperature
102 * @return the Scalar representation of the value in its unit
103 * @throws IllegalArgumentException when the text cannot be parsed
104 * @throws NullPointerException when the text argument is null
105 */
106 public static TemperatureDifference valueOf(final String text)
107 {
108 return Quantity.valueOf(text, ZERO);
109 }
110
111 /**
112 * Returns a TemperatureDifference based on a value and the textual representation of the unit, which can be localized.
113 * @param valueInUnit the value, expressed in the unit as given by unitString
114 * @param unitString the textual representation of the unit
115 * @return the Scalar representation of the value in its unit
116 * @throws IllegalArgumentException when the unit cannot be parsed or is incorrect
117 * @throws NullPointerException when the unitString argument is null
118 */
119 public static TemperatureDifference of(final double valueInUnit, final String unitString)
120 {
121 return Quantity.of(valueInUnit, unitString, ZERO);
122 }
123
124 @Override
125 public Temperature.Unit getDisplayUnit()
126 {
127 return (Temperature.Unit) super.getDisplayUnit();
128 }
129
130 /**
131 * Add an absolute temperature to this temperature difference, and return a new absolute temperature. The unit of the return
132 * value will be the unit of this temperature difference, and the reference point of the return value will be the reference
133 * point of the given temperature. <code>R.add(A)</code> = unit of R and reference value of A.
134 * @param absoluteTemperature the absolute temperature to add
135 * @return the absolute temperature plus this temperature difference
136 */
137 public final Temperature add(final Temperature absoluteTemperature)
138 {
139 return absoluteTemperature.add(this).setDisplayUnit(getDisplayUnit());
140 }
141
142 /**
143 * Calculate the division of TemperatureDifference and TemperatureDifference, which results in a Dimensionless quantity.
144 * @param v quantity
145 * @return quantity as a division of TemperatureDifference and Temperature
146 */
147 public final Dimensionless divide(final TemperatureDifference v)
148 {
149 return new Dimensionless(this.si() / v.si(), Unitless.BASE);
150 }
151
152 }