DatedDataSet (Degree Days.net API JavaDoc)

java.lang.Object
- net.degreedays.api.data.DataSet
- - net.degreedays.api.data.DatedDataSet

All Implemented Interfaces:

java.io.Serializable
```
public final class DatedDataSet
extends DataSet
implements java.io.Serializable
```
Contains a set of dated data (e.g. daily/weekly/monthly degree days) generated to fulfil a DatedDataSpec for a specific Location.

See DatedDataSpec for example code showing how to fetch a DatedDataSet of degree days from the API.

See Also:

AverageDataSet, TimeSeriesDataSet

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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DatedDataSet.Builder
A builder class for creating immutable DatedDataSet objects e.g. for testing purposes.

Nested Classes
Modifier and Type	Class and Description
`static class`	`DatedDataSet.Builder` A builder class for creating immutable `DatedDataSet` objects e.g. for testing purposes.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`equals(java.lang.Object o)` Returns `true` if `o` is a `DatedDataSet` containing equal values covering equal dates, and with an equal `percentageEstimated()`.
`DayRange`	`fullRange()` Returns a non-null `DayRange` object indicating the period of time that is covered by this `DatedDataSet`'s values.
`DatedDataValue[]`	`getValues()` Returns a non-null, non-empty, chronologically-ordered array of the `DatedDataValue` objects that make up this `DatedDataSet`.
`int`	`hashCode()` Overridden to ensure consistency with `equals`.
`boolean`	`isContiguous()` Returns `true` if each contained `DatedDataValue` starts the day after the previous `DatedDataValue` ended (i.e. no gaps); `false` otherwise.
`boolean`	`isDailyData()` Returns `true` if this `DatedDataSet` contains a contiguous (no gaps) set of day-long values, as is the case for daily-breakdown data returned by the API.
`boolean`	`isMonthlyData()` Returns `true` if this `DatedDataSet` contains a contiguous (no gaps) set of month-long values, as is the case for monthly-breakdown data returned by the API.
`boolean`	`isWeeklyData()` Returns `true` if this `DatedDataSet` contains a contiguous (no gaps) set of week-long values, as is the case for weekly-breakdown data returned by the API.
`boolean`	`isYearlyData()` Returns `true` if this `DatedDataSet` contains a contiguous (no gaps) set of year-long values, as is the case for yearly-breakdown data returned by the API.
`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.
`AverageDataSet`	`transformToAverage(AverageBreakdown targetBreakdown)` Returns a new `AverageDataSet` object, based on the data contained within `this`, but transformed to fit the `targetBreakdown`.
`DatedDataSet`	`transformToDated(DatedBreakdown targetBreakdown)` Returns a new `DatedDataSet` object, based on the data contained within `this`, but transformed to fit the `targetBreakdown`.
`DatedDataValue`	`valueAt(int index)` Returns the `DatedDataValue` at the specified `index`, which must be between `0` (inclusive) and `valueCount()` (exclusive).
`int`	`valueCount()` Returns the number of values held by this `DatedDataSet` 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
  - valueCount
```
public int valueCount()
```
    Returns the number of values held by this DatedDataSet object, which will always be greater than zero.
    
    See Also:
    
    valueAt(int), getValues()
  - valueAt
```
public DatedDataValue valueAt(int index)
```
    Returns the DatedDataValue 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 DatedDataValue[] getValues()
```
    Returns a non-null, non-empty, chronologically-ordered array of the DatedDataValue objects that make up this DatedDataSet.
    The returned array can be modified freely without affecting the immutability of this DatedDataSet 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 (DatedDataValue v : dataSet.getValues()) {
     // Do something with v.
 }
 
 // This is fine too:
 DatedDataValue[] values = dataSet.getValues();
 for (int i = 0; i < values.length; i++) {
     DatedDataValue 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++) {
     DatedDataValue 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, particularly if this set contains daily data with thousands of values.
    See Also:
    
    valueAt(int), valueCount()
  - fullRange
```
public DayRange fullRange()
```
    Returns a non-null DayRange object indicating the period of time that is covered by this DatedDataSet's values.
    
    Specified by:
    
    fullRange in class DataSet
  - isContiguous
```
public boolean isContiguous()
```
    Returns true if each contained DatedDataValue starts the day after the previous DatedDataValue ended (i.e. no gaps); false otherwise.
    This will always return true for daily, weekly, monthly, or yearly data returned by the API.
    
    Since:
    
    1.2
  - isDailyData
```
public boolean isDailyData()
```
    Returns true if this DatedDataSet contains a contiguous (no gaps) set of day-long values, as is the case for daily-breakdown data returned by the API.
  - isWeeklyData
```
public boolean isWeeklyData()
```
    Returns true if this DatedDataSet contains a contiguous (no gaps) set of week-long values, as is the case for weekly-breakdown data returned by the API. Weekly data can have any DayOfWeek as the first day of the week, so long as it's consistent.
  - isMonthlyData
```
public boolean isMonthlyData()
```
    Returns true if this DatedDataSet contains a contiguous (no gaps) set of month-long values, as is the case for monthly-breakdown data returned by the API. Monthly data can have any StartOfMonth, so long as it's consistent.
  - isYearlyData
```
public boolean isYearlyData()
```
    Returns true if this DatedDataSet contains a contiguous (no gaps) set of year-long values, as is the case for yearly-breakdown data returned by the API. Yearly data can have any StartOfYear, so long as it's consistent.
  - transformToAverage
```
public AverageDataSet transformToAverage(AverageBreakdown targetBreakdown)
                                  throws DataTransformException
```
    Returns a new AverageDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.
    If targetBreakdown cannot be satisfied fully using the data contained within this, this method will return a partial set of data if it can. For example, if your target is a 5-year average breakdown, but this only covers 3 full years, then assuming those 3 full years overlap with the target, this method will return a 3-year average data set. But many sorts of transformations just aren't possible... For example, you can't turn weekly or yearly data into an average data set. Not without losing accuracy anyway, which this method will not do.
    
    This method will work on daily or monthly data (provided the months in the monthly data start on the first of the month).
    
    Be prepared for a DataTransformException if you have any doubt about whether it will be possible to get the breakdown you want from the data you have.
    
    Parameters:
    
    targetBreakdown - specifies the breakdown that the returned data should have. Cannot be null.
    
    Returns:
    
    a new AverageDataSet with the targetBreakdown.
    
    Throws:
    
    DataTransformException - if the method is unable to transform the data contained within this into data with the targetBreakdown.
    
    java.lang.NullPointerException - if targetBreakdown is null.
  - transformToDated
```
public DatedDataSet transformToDated(DatedBreakdown targetBreakdown)
                              throws DataTransformException
```
    Returns a new DatedDataSet object, based on the data contained within this, but transformed to fit the targetBreakdown.
    If targetBreakdown cannot be satisfied fully using the data contained within this, this method will return a partial set of data if it can. For example, if your target breakdown is a WeeklyBreakdown with a Period that is longer than that covered by this, then, assuming there is overlap, this method will return weekly data covering as much of the period as it can. But many sorts of transformations just aren't possible - for example, a data set covering only 2009 can never be transformed into a data set covering 2010, and monthly data can never be turned into daily data. Not without losing accuracy anyway, which this method will not do.
    
    This method is generally best called on sets of daily data. Daily data is the ideal starting point for all other breakdowns.
    
    Be prepared for a DataTransformException if you have any doubt about whether it will be possible to get the breakdown you want from the data you have.
    
    Parameters:
    
    targetBreakdown - specifies the breakdown that the returned data should have. Cannot be null.
    
    Returns:
    
    a new DatedDataSet with the targetBreakdown.
    
    Throws:
    
    DataTransformException - if the method is unable to transform the data contained within this into data with the targetBreakdown.
    
    java.lang.NullPointerException - if targetBreakdown is null.
  - equals
```
public boolean equals(java.lang.Object o)
```
    Returns true if o is a DatedDataSet containing equal values covering equal dates, 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

Class DatedDataSet

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

percentageEstimated

valueCount

valueAt

getValues

fullRange

isContiguous

isDailyData

isWeeklyData

isMonthlyData

isYearlyData

transformToAverage

transformToDated

equals

hashCode

toString