net.degreedays.api.data
Class Temperature

java.lang.Object
  extended by net.degreedays.api.data.Temperature
All Implemented Interfaces:
java.io.Serializable

public final class Temperature
extends java.lang.Object
implements 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
Temperature(double value, TemperatureUnit unit)
          Constructs a Temperature object with the specified units and value (rounded to the nearest 0.1 degrees).
 
Method Summary
static Temperature celsius(double value)
          Returns a non-null Temperature object with the specified Celsius temperature rounded to the nearest 0.1 C.
 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.
 int hashCode()
          Overridden to ensure consistency with equals.
 boolean isCelsius()
          Returns true if this temperature has CELSUS units.
 boolean isFahrenheit()
          Returns true if this temperature has FAHRENHEIT units.
 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 -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)

unit

public TemperatureUnit unit()
Returns the non-null unit of this temperature.


isCelsius

public boolean isCelsius()
Returns true if this temperature has CELSUS units.


isFahrenheit

public boolean isFahrenheit()
Returns true if this temperature has FAHRENHEIT units.


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


www.degreedays.net/api/