Temperature (Degree Days.net API JavaDoc)

java.lang.Object
- net.degreedays.api.data.Temperature

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Temperature>
```
public final class Temperature
extends java.lang.Object
implements java.lang.Comparable<Temperature>, java.io.Serializable
```
Defines a temperature value, typically the base temperature of a degree-day calculation.
To create a Temperature object you can use the static factory methods celsius(double) and fahrenheit(double). For example:
```
 Temperature celsiusTemp = Temperature.celsius(15.5);
 Temperature fahrenheitTemp = Temperature.fahrenheit(65);
 
```
You can pass a temperature into a Calculation to define the base temperature that that Calculation should use to calculate degree days. Use a Celsius temperature for Celsius degree days, and a Fahrenheit temperature for Fahrenheit degree days.

Rounding

This class enables temperatures to be defined to the nearest 0.1 degrees (either 0.1 C or 0.1 F). Given the limitations of temperature-recording equipment and methods, it is meaningless to consider temperature differences smaller than this.

When creating a Temperature object, you can pass in any double value within the maximum and minimum limits set by the temperature unit. But the value you pass in will always be rounded to the nearest 0.1 degrees.

For example, a Celsius Temperature created with a value of 15.5 will be equal to one created with 15.456 or 15.543. And a Fahrenheit Temperature created with 65 will be equal to one created with 64.96 or 65.04.

One benefit of this is that you can easily define a range of base temperatures in a loop without worrying too much about the inaccuracies of floating-point arithmetic. The automatic rounding should correct any such issues (e.g. rounding 69.9998 up to 70).
Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.

Constructor Summary

Constructors
Constructor and Description
`Temperature(double value, TemperatureUnit unit)` Constructs a `Temperature` object with the specified units and value (rounded to the nearest 0.1 degrees).

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Temperature`	`celsius(double value)` Returns a non-null `Temperature` object with the specified Celsius temperature rounded to the nearest 0.1 C.
`static java.util.SortedSet<Temperature>`	`celsiusRange(double firstValue, double lastValue, double step)` Returns a non-null low-to-high `SortedSet` of `Temperature` objects, with Celsius values running from `firstValue` to `lastValue` (inclusive), and the specified `step` between each consecutive temperature.
`int`	`compareTo(Temperature comparisonTemperature)` Compares two `Temperature` objects for low-to-high ordering.
`boolean`	`equals(java.lang.Object o)` Two `Temperature` objects can only be equal if they have the same units and temperature value (value comparisons being made after any rounding).
`static Temperature`	`fahrenheit(double value)` Returns a non-null `Temperature` object with the specified Fahrenheit temperature rounded to the nearest 0.1 F.
`static java.util.SortedSet<Temperature>`	`fahrenheitRange(double firstValue, double lastValue, double step)` Returns a non-null low-to-high `SortedSet` of `Temperature` objects, with Fahrenheit values running from `firstValue` to `lastValue` (inclusive), and the specified `step` between each consecutive temperature.
`int`	`hashCode()` Overridden to ensure consistency with `equals`.
`boolean`	`isCelsius()` Returns `true` if this temperature has `CELSIUS` units; `false` otherwise.
`boolean`	`isFahrenheit()` Returns `true` if this temperature has `FAHRENHEIT` units; `false` otherwise.
`java.lang.String`	`toNumericString()` Returns a non-null, non-empty string representation of the numeric base-temperature value, like "50" or "15.5" or "-5" or "33.1", in a format suitable for insertion into the appropriate unit-specific element(s) of the request XML.
`java.lang.String`	`toString()` Returns a non-null, non-empty string representation of the temperature and its units.
`TemperatureUnit`	`unit()` Returns the non-null unit of this temperature.
`double`	`value()` Returns a double representation of the 0.1-precision number stored internally.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Temperature
```
public Temperature(double value,
                   TemperatureUnit unit)
```
    Constructs a Temperature object with the specified units and value (rounded to the nearest 0.1 degrees).
    
    Parameters:
    
    value - a temperature value, the limits of which will depend on the unit
    
    unit - specifying whether the temperature is in Celsius or Fahrenheit. Cannot be null.
    
    Throws:
    
    java.lang.IllegalArgumentException - if value is NaN, or outside the limits allowed by unit.
    
    java.lang.NullPointerException - if unit is null.
    
    See Also:
    
    Rounding, celsius(double), fahrenheit(double)
- Method Detail
  - celsius
```
public static Temperature celsius(double value)
```
    Returns a non-null Temperature object with the specified Celsius temperature rounded to the nearest 0.1 C.
    
    Parameters:
    
    value - a Celsius temperature that's greater than or equal to -273 C (absolute zero) and less than or equal to 3000 C (hotter than the hottest blast furnaces). Note that the base-temperature range over which it would typically make sense to calculate degree days is much smaller than the range allowed by these limits.
    
    Throws:
    
    java.lang.IllegalArgumentException - if value is NaN, less than -273 C, or greater than 3000 C.
    
    See Also:
    
    Rounding, fahrenheit(double)
  - fahrenheit
```
public static Temperature fahrenheit(double value)
```
    Returns a non-null Temperature object with the specified Fahrenheit temperature rounded to the nearest 0.1 F.
    
    Parameters:
    
    value - a Fahrenheit temperature that's greater than or equal to -459.4 F (absolute zero) and less than or equal to 5432 F (hotter than the hottest blast furnaces). Note that the base-temperature range over which it would typically make sense to calculate degree days is much smaller than the range allowed by these limits.
    
    Throws:
    
    java.lang.IllegalArgumentException - if value is NaN, less than -459.4 F, or greater than 5432 F.
    
    See Also:
    
    Rounding, celsius(double)
  - celsiusRange
```
public static java.util.SortedSet<Temperature> celsiusRange(double firstValue,
                                                            double lastValue,
                                                            double step)
```
    Returns a non-null low-to-high SortedSet of Temperature objects, with Celsius values running from firstValue to lastValue (inclusive), and the specified step between each consecutive temperature.
    For example, to get Celsius temperatures between 10°C and 30°C (inclusive), with each temperature being 5°C greater than the last (giving temperatures 10°C, 15°C, 20°C, 25°C, and 30°C):
```
 SortedSet<Temperature> temps = Temperature.celsiusRange(10, 30, 5);
 
```
    Parameters:
    
    firstValue - the Celsius value of the first Temperature to be included in the returned SortedSet. This must be greater than or equal to -273°C and less than or equal to 3000°C.
    
    lastValue - the Celsius value of the last Temperature to be included in the returned SortedSet. This must be greater than or equal to firstValue. Also, like for firstValue, it must be greater than or equal to -273°C and less than or equal to 3000°C.
    
    step - the Celsius temperature difference between each temperature value to be included in the returned SortedSet. Cannot be NaN, and must be greater than zero. It must also be a multiple of 0.1 (the smallest temperature difference allowed), though allowances are made for floating-point imprecision (so for example a step of 0.4999999 will be treated as 0.5).
    
    Throws:
    
    java.lang.IllegalArgumentException - if any of the parameters are NaN; if firstValue or lastValue are outside of their allowed range (-273°C to 3000°C inclusive); if lastValue is less than firstValue; if step is not positive; or if step is not a multiple of 0.1 (allowing for slight deviations caused by floating-point imprecision).
    
    Since:
    
    1.4
    
    See Also:
    
    fahrenheitRange(double, double, double), TemperatureUnit.range(double, double, double)
  - fahrenheitRange
```
public static java.util.SortedSet<Temperature> fahrenheitRange(double firstValue,
                                                               double lastValue,
                                                               double step)
```
    Returns a non-null low-to-high SortedSet of Temperature objects, with Fahrenheit values running from firstValue to lastValue (inclusive), and the specified step between each consecutive temperature.
    For example, to get Fahrenheit temperatures between 50°F and 70°F (inclusive), with each temperature being 5°F greater than the last (giving temperatures 50°F, 55°F, 60°F, 65°F, and 70°F):
```
 SortedSet<Temperature> temps = Temperature.fahrenheitRange(50, 70, 5);
 
```
    Parameters:
    
    firstValue - the Fahrenheit value of the first Temperature to be included in the returned SortedSet. This must be greater than or equal to -459.4°F and less than or equal to 5432°F.
    
    lastValue - the Fahrenheit value of the last Temperature to be included in the returned SortedSet. This must be greater than or equal to firstValue. Also, like for firstValue, it must be greater than or equal to -459.4°F and less than or equal to 5432°F.
    
    step - the Fahrenheit temperature difference between each temperature value to be included in the returned SortedSet. Cannot be NaN, and must be greater than zero. It must also be a multiple of 0.1 (the smallest temperature difference allowed), though allowances are made for floating-point imprecision (so for example a step of 0.4999999 will be treated as 0.5).
    
    Throws:
    
    java.lang.IllegalArgumentException - if any of the parameters are NaN; if firstValue or lastValue are outside of their allowed range (-459.4°F to 5432°F inclusive); if lastValue is less than firstValue; if step is not positive; or if step is not a multiple of 0.1 (allowing for slight deviations caused by floating-point imprecision).
    
    Since:
    
    1.4
    
    See Also:
    
    celsiusRange(double, double, double), TemperatureUnit.range(double, double, double)
  - unit
```
public TemperatureUnit unit()
```
    Returns the non-null unit of this temperature.
  - isCelsius
```
public boolean isCelsius()
```
    Returns true if this temperature has CELSIUS units; false otherwise.
  - isFahrenheit
```
public boolean isFahrenheit()
```
    Returns true if this temperature has FAHRENHEIT units; false otherwise.
  - value
```
public final double value()
```
    Returns a double representation of the 0.1-precision number stored internally. Because of rounding, this might not be exactly the same as the double that this instance was created with.
  - toNumericString
```
public final java.lang.String toNumericString()
```
    Returns a non-null, non-empty string representation of the numeric base-temperature value, like "50" or "15.5" or "-5" or "33.1", in a format suitable for insertion into the appropriate unit-specific element(s) of the request XML. (The request XML requires that base temperatures be whole numbers or numbers with a maximum of 1 digit after the decimal point, with "." for any decimal separator, and no thousands separator.)
  - toString
```
public final java.lang.String toString()
```
    Returns a non-null, non-empty string representation of the temperature and its units. For a Celsius temperature this will return a string like "15.5 C" or "18 C" or "-5 C" or "-12.1 C"; for a Fahrenheit temperature this will return a string like "65 F" or "55.9 F" or "-13.2 F" or "-10 F". Whatever the system's international settings, "." will be used as the decimal separator, and there will never be a thousands separator.
    
    Overrides:
    
    toString in class java.lang.Object
  - equals
```
public final boolean equals(java.lang.Object o)
```
    Two Temperature objects can only be equal if they have the same units and temperature value (value comparisons being made after any rounding). A Celsius temperature and a Fahrenheit temperature can never be equal: this method does not do any conversion between units.
    
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public final int hashCode()
```
    Overridden to ensure consistency with equals.
    
    Overrides:
    
    hashCode in class java.lang.Object
  - compareTo
```
public int compareTo(Temperature comparisonTemperature)
```
    Compares two Temperature objects for low-to-high ordering. If two temperatures have different units but are exactly equivalent (like how 18°C is exactly equivalent to 64.4°F), the Celsius temperature will be ordered first.
    
    Specified by:
    
    compareTo in interface java.lang.Comparable<Temperature>
    
    Parameters:
    
    comparisonTemperature - the Temperature to be compared. Cannot be null.
    
    Returns:
    
    a negative integer if this Temperature is lower than comparisonTemperature or exactly equivalent with this temperature being in Celsius and comparisonTemperature being in Fahrenheit; zero if this Temperature is equal to comparisonTemperature (in unit() and in value()); or a positive integer if this Temperature is greater than comparisonTemperature or exactly equivalent with this temperature being in Fahrenheit and comparisonTemperature being in Celsius.
    
    Throws:
    
    java.lang.NullPointerException - if comparisonTemperature is null.
    
    Since:
    
    1.4

Class Temperature

Rounding

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Temperature

Method Detail

celsius

fahrenheit

celsiusRange

fahrenheitRange

unit

isCelsius

isFahrenheit

value

toNumericString

toString

equals

hashCode

compareTo