net.degreedays.api.data
Class TimeSeriesDataSet

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

public final class TimeSeriesDataSet
extends DataSet
implements java.io.Serializable

Contains a set of time-series data (e.g. hourly temperature data) generated to fulfil a TimeSeriesDataSpec for a specific Location.

See TimeSeriesDataSpec for example code showing how to get a TimeSeriesDataSet of hourly temperature data from the API.

Since:
1.2
See Also:
DatedDataSet, AverageDataSet

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.


Nested Class Summary
static class TimeSeriesDataSet.Builder
          A builder class for creating immutable TimeSeriesDataSet objects e.g. for testing purposes.
 
Method Summary
 boolean equals(java.lang.Object o)
          Returns true if o is a TimeSeriesDataSet containing equal values and with an equal percentageEstimated().
 DayRange fullRange()
          Returns a non-null DayRange object indicating the period of time that is covered by this TimeSeriesDataSet's values.
 TimeSeriesDataValue[] getValues()
          Returns a non-null, non-empty, chronologically-ordered array of the TimeSeriesDataValue objects that make up this TimeSeriesDataSet.
 TimeSeriesDataValue[] getValuesWithin(Day day)
          Returns a non-null, possibly-empty, chronologically-ordered array of the TimeSeriesDataValue objects from this TimeSeriesDataSet that fall within the specified Day.
 TimeSeriesDataValue[] getValuesWithin(DayRange dayRange)
          Returns a non-null, possibly-empty, chronologically-ordered array of the TimeSeriesDataValue objects from this TimeSeriesDataSet that fall within the specified DayRange.
 int hashCode()
          Overridden to ensure consistency with equals.
 double percentageEstimated()
          Returns a number between 0 and 100 (both inclusive), indicating the overall extent to which this DataSet is based on estimated data.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 TimeSeriesDataValue valueAt(int index)
          Returns the non-null TimeSeriesDataValue at the specified index, which must be between 0 (inclusive) and valueCount() (exclusive).
 int valueCount()
          Returns the number of values held by this TimeSeriesDataSet object, which will always be greater than zero.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

percentageEstimated

public double percentageEstimated()
Description copied from class: DataSet
Returns a number between 0 and 100 (both inclusive), indicating the overall extent to which this DataSet is based on estimated data.

Generally speaking, data with a lower percentage-estimated figure is likely to be more reliable than data with a higher percentage-estimated figure.

Specified by:
percentageEstimated in class DataSet

fullRange

public DayRange fullRange()
Returns a non-null DayRange object indicating the period of time that is covered by this TimeSeriesDataSet's values.

Specified by:
fullRange in class DataSet

valueCount

public int valueCount()
Returns the number of values held by this TimeSeriesDataSet object, which will always be greater than zero.

See Also:
valueAt(int), getValues()

valueAt

public TimeSeriesDataValue valueAt(int index)
Returns the non-null TimeSeriesDataValue at the specified index, which must be between 0 (inclusive) and valueCount() (exclusive).

Parameters:
index - a number, greater than or equal to zero, and less than valueCount() indicating which value should be returned. Values are stored in consecutive order, so a greater index means a later value.
Throws:
java.lang.IndexOutOfBoundsException - if index is less than zero or greater than or equal to valueCount().
See Also:
getValues()

getValues

public TimeSeriesDataValue[] getValues()
Returns a non-null, non-empty, chronologically-ordered array of the TimeSeriesDataValue objects that make up this TimeSeriesDataSet.

The returned array can be modified freely without affecting the immutability of this TimeSeriesDataSet or the arrays returned by past, concurrent, or future calls to this method. This is possible because a new array is generated with each call to this method. Bear this in mind if you're iterating over all the values... The following example is fine, as getValues() is only called once:

 // This is fine:
 for (TimeSeriesDataValue v : dataSet.getValues()) {
     // Do something with v.
 }
 
 // This is fine too:
 TimeSeriesDataValue[] values = dataSet.getValues();
 for (int i = 0; i < values.length; i++) {
     TimeSeriesDataValue v = values[i];
     // Do something with v.
 }
 

But you definitely don't want to do something like:

 // Don't do it like this!
 for (int i = 0; i < dataSet.getValues().length; i++) {
     TimeSeriesDataValue v = dataSet.getValues()[i];
     // Do something with v.
 }
 

In the bad example immediately above, two fresh arrays are created for each iteration of the loop. Looping over the values like this would be very bad for performance.

See Also:
valueAt(int), valueCount()

getValuesWithin

public TimeSeriesDataValue[] getValuesWithin(DayRange dayRange)
Returns a non-null, possibly-empty, chronologically-ordered array of the TimeSeriesDataValue objects from this TimeSeriesDataSet that fall within the specified DayRange.

The returned array can be modified freely without affecting this immutable TimeSeriesDataSet or any arrays returned by past, concurrent, or future calls to this method.

Parameters:
dayRange - the day range of interest. Cannot be null.
Throws:
java.lang.NullPointerException - if dayRange is null.

getValuesWithin

public TimeSeriesDataValue[] getValuesWithin(Day day)
Returns a non-null, possibly-empty, chronologically-ordered array of the TimeSeriesDataValue objects from this TimeSeriesDataSet that fall within the specified Day.

The returned array can be modified freely without affecting this immutable TimeSeriesDataSet or any arrays returned by past, concurrent, or future calls to this method.

Parameters:
day - the day of interest. Cannot be null.
Throws:
java.lang.NullPointerException - if day is null.

equals

public boolean equals(java.lang.Object o)
Returns true if o is a TimeSeriesDataSet containing equal values and with an equal percentageEstimated().

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overridden to ensure consistency with equals.

Overrides:
hashCode in class java.lang.Object

toString

public 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 java.lang.Object


www.degreedays.net/api/