|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.degreedays.api.data.DataSet
net.degreedays.api.data.DatedDataSet
public final class DatedDataSet
Contains a set of dated data (e.g. daily/weekly/monthly degree days)
generated to fulfil a DatedDataSpec
for a specific Location
.
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 |
DatedDataSet.Builder
A builder class for creating immutable DatedDataSet objects
e.g. for testing purposes. |
Method Summary | |
---|---|
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 an array of the DatedDataValue objects that make up
this DatedDataSet . |
int |
hashCode()
Overridden to ensure consistency with equals . |
boolean |
isDailyData()
Returns true if each of the values contained within this
DatedDataSet covers one day. |
boolean |
isMonthlyData()
Returns true if each of the values contained within this
DatedDataSet covers one month. |
boolean |
isWeeklyData()
Returns true if each of the values contained within this
DatedDataSet covers one week. |
boolean |
isYearlyData()
Returns true if each of the values contained within this
DatedDataSet covers one year. |
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 |
---|
public double percentageEstimated()
DataSet
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.
percentageEstimated
in class DataSet
public int valueCount()
DatedDataSet
object, which will always be greater than zero.
valueAt(int)
,
getValues()
public DatedDataValue valueAt(int index)
DatedDataValue
at the specified
index
, which must be between 0
(inclusive) and
valueCount()
(exclusive).
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.
java.lang.IndexOutOfBoundsException
- if index
is less than zero
or greater than or equal to valueCount()
.getValues()
public DatedDataValue[] getValues()
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. } // as is this: 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.
valueAt(int)
,
valueCount()
public DayRange fullRange()
DayRange
object indicating the period of
time that is covered by this DatedDataSet
's
values.
fullRange
in class DataSet
public boolean isDailyData()
true
if each of the values contained within this
DatedDataSet
covers one day.
Note that a DatedDataSet
will always hold contiguous
dated values, so daily data means an ordered run of consecutive days.
public boolean isWeeklyData()
true
if each of the values contained within this
DatedDataSet
covers one week. Weekly data can have any
DayOfWeek
as the first day of the week, so long as it's
consistent.
Note that a DatedDataSet
will always hold contiguous dated
values, so weekly data means an ordered run of consecutive weeks.
public boolean isMonthlyData()
true
if each of the values contained within this
DatedDataSet
covers one month. Monthly data can have any
StartOfMonth
, so long as it's consistent.
Note that a DatedDataSet
will always hold contiguous dated
values, so monthly data means an ordered run of consecutive months.
public boolean isYearlyData()
true
if each of the values contained within this
DatedDataSet
covers one year. Yearly data can have any
StartOfYear
, so long as it's consistent.
Note that a DatedDataSet
will always hold contiguous dated
values, so yearly data means an ordered run of consecutive years.
public AverageDataSet transformToAverage(AverageBreakdown targetBreakdown) throws DataTransformException
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.
targetBreakdown
- a non-null object that specifies the breakdown
that the returned data should have.
AverageDataSet
with the
targetBreakdown
.
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.public DatedDataSet transformToDated(DatedBreakdown targetBreakdown) throws DataTransformException
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.
targetBreakdown
- a non-null object that specifies the breakdown
that the returned data should have.
DatedDataSet
with the
targetBreakdown
.
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.public boolean equals(java.lang.Object o)
true
if o
is a
DatedDataSet
containing equal values covering equal dates,
and with an equal percentageEstimated()
.
equals
in class java.lang.Object
public int hashCode()
equals
.
hashCode
in class java.lang.Object
public java.lang.String toString()
The exact details of the representation are unspecified and subject to change.
toString
in class java.lang.Object
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |