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, Temperature.Unit>
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 value the value, expressed in the unit
48 * @param unit the unit in which the value is expressed
49 */
50 public TemperatureDifference(final double value, final Temperature.Unit unit)
51 {
52 super(value, unit);
53 }
54
55 /**
56 * Instantiate a TemperatureDifference quantity with a unit, expressed as a String.
57 * @param value 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 value, final String abbreviation)
61 {
62 this(value, 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 instantiate(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 value the value to use
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 value, final String unitString)
120 {
121 return Quantity.of(value, unitString, ZERO);
122 }
123
124 /**
125 * Add an absolute temperature to this temperature difference, and return a new absolute temperature. The unit of the return
126 * value will be the unit of this temperature difference, and the reference point of the return value will be the reference
127 * point of the given temperature. <code>R.add(A)</code> = unit of R and reference value of A.
128 * @param absoluteTemperature the absolute temperature to add
129 * @return the absolute temperature plus this temperature difference
130 */
131 public final Temperature add(final Temperature absoluteTemperature)
132 {
133 return absoluteTemperature.add(this).setDisplayUnit(getDisplayUnit());
134 }
135
136 /**
137 * Calculate the division of TemperatureDifference and TemperatureDifference, which results in a Dimensionless quantity.
138 * @param v quantity
139 * @return quantity as a division of TemperatureDifference and Temperature
140 */
141 public final Dimensionless divide(final TemperatureDifference v)
142 {
143 return new Dimensionless(this.si() / v.si(), Unitless.BASE);
144 }
145
146 }