net.degreedays.api.data

Class DatedDataValue

java.lang.Object

net.degreedays.api.data.DataValue

net.degreedays.api.data.DatedDataValue

public abstract class DatedDataValue
extends DataValue

Contains a degree-day value for a specific dated period (a single day or a range of days like a specific week, month, or year).

See Also:

DatedDataSet

This abstract class is not designed to be extended by third-party code, which is why it does not have an accessible constructor.

All concrete subclasses of this abstract class are immutable. You can safely reuse them and call them from multiple threads at once.

Method Summary

Modifier and Type	Method and Description
abstract DayRange	dayRange() Returns a non-null DayRange object indicating the period in time that this DatedDataValue covers.
abstract boolean	equals(java.lang.Object o) Returns true if o is a DatedDataValue object with an equal value(), percentageEstimated(), and dayRange(); false otherwise.
abstract Day	firstDay() Returns the non-null first Day of the period covered by this DatedDataValue.
abstract int	hashCode() Overridden to ensure consistency with equals.
abstract Day	lastDay() Returns the non-null last Day of the period covered by this DatedDataValue.
static DatedDataValue	of(double value, double percentageEstimated, Day singleDay) Returns a non-null DatedDataValue object with the specified value and percentage estimated, and covering just the specified Day.
static DatedDataValue	of(double value, double percentageEstimated, DayRange dayRange) Returns a non-null DatedDataValue object with the specified value and percentage estimated, and covering the specified DayRange.
abstract java.lang.String	toString() Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class net.degreedays.api.data.DataValue

of, percentageEstimated, value

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

dayRange

public abstract DayRange dayRange()

Returns a non-null DayRange object indicating the period in time that this DatedDataValue covers.

See Also:

firstDay()

firstDay

public abstract Day firstDay()

Returns the non-null first Day of the period covered by this DatedDataValue.

This is a convenience/performance method that should run faster (or at least not slower) than calling .dayRange().first(), since calling dayRange() may result in a temporary DayRange object being created. We say "may" because, although at the time of writing it does create a temporary object, this is an implementation detail that might change in the future.

A large request for data (daily data in particular) can easily result in hundreds of thousands of these DatedDataValue objects, each of which occupies memory and typically needs to be used by code that is repeating its operations on every single value in a set. So we've tried to design DatedDataValue to minimize memory footprint and enable fast access to its fields.

If all you want is the first day of the range, then this is the optimal method to call. If you want the last day of the range, then lastDay() is the optimal method to call. But if you need more information then don't hesitate to get the DayRange object as it is very lightweight and creating it is a very fast operation. Choosing the optimal method is very unlikely to make a practical difference unless performance is critically important to you and you're iterating over large quantities of daily data for which the DayRange is largely irrelevant anyway (since for daily data it would only cover a single day).

lastDay

public abstract Day lastDay()

Returns the non-null last Day of the period covered by this DatedDataValue.

See Also:

firstDay()

equals

public abstract boolean equals(java.lang.Object o)

Returns true if o is a DatedDataValue object with an equal value(), percentageEstimated(), and dayRange(); false otherwise.

Overrides:

equals in class DataValue

hashCode

public abstract int hashCode()

Overridden to ensure consistency with equals.

Overrides:

hashCode in class DataValue

toString

public abstract java.lang.String toString()

Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:

toString in class DataValue

of

public static DatedDataValue of(double value,
                                double percentageEstimated,
                                Day singleDay)

Returns a non-null DatedDataValue object with the specified value and percentage estimated, and covering just the specified Day.

The returned DatedDataValue will be equal to the DatedDataValue that would be returned if you called of(double, double, DayRange) passing a DayRange that covered the same single Day only.

Parameters:

value - indicating the value to be held by the returned object (i.e. the degree days).

percentageEstimated - a number, greater than or equal to zero and less than or equal to 100, indicating the extent to which the value is based on estimated data.

singleDay - the Day that the value covers. Cannot be null.

Throws:

java.lang.IllegalArgumentException - if value or percentageEstimated is NaN or infinity, or if percentageEstimated is less than 0 or greater than 100. At the moment an IllegalArgumentException will also be thrown if value is less than zero (since degree-day values are always zero or greater), but this may change in the future if this class is used for other types of data.

java.lang.NullPointerException - if singleDay is null.

of

public static DatedDataValue of(double value,
                                double percentageEstimated,
                                DayRange dayRange)

Returns a non-null DatedDataValue object with the specified value and percentage estimated, and covering the specified DayRange.

If you pass this a DayRange covering just one Day, the returned DatedDataValue will be equal to the DatedDataValue that would be returned by passing that single Day to of(double, double, Day).

Parameters:

value - indicating the value to be held by the returned object (i.e. the degree days).

percentageEstimated - a number, greater than or equal to zero and less than or equal to 100, indicating the extent to which the value is based on estimated data.

dayRange - the range of days that the value covers. Cannot be null.

Throws:

java.lang.IllegalArgumentException - if value or percentageEstimated is NaN or infinity, or if percentageEstimated is less than 0 or greater than 100. At the moment an IllegalArgumentException will also be thrown if value is less than zero (since degree-day values are always zero or greater), but this may change in the future if this class is used for other types of data.

java.lang.NullPointerException - if dayRange is null.