Click or drag to resize

DayRangePeriod Class

A type of Period that is defined explicitly in terms of the range of days that it covers.
Inheritance Hierarchy
SystemObject
  DegreeDays.Api.DataPeriod
    DegreeDays.Api.Data.ImplDayRangePeriod

Namespace:  DegreeDays.Api.Data.Impl
Assembly:  DegreeDays (in DegreeDays.dll) Version: 1.3
Syntax
public sealed class DayRangePeriod : Period

The DayRangePeriod type exposes the following members.

Constructors
  NameDescription
Public methodDayRangePeriod(DayRange)
Constructs a DayRangePeriod object that specifies the period covered by dayRange.
Top
Properties
  NameDescription
Public propertyDayRange
Gets the DayRange that specifies the day(s) that this period covers.
Public propertyMinimumDayRange
Returns the minimum day range that was specified using WithMinimumDayRange(DayRange), or null if no such minimum range was specified.
Top
Methods
  NameDescription
Public methodEquals(Object)
Two Period objects are equal if it can be ascertained that they will always represent the same period in time as each other when compared at the same time and in the same context.
(Inherited from Period.)
Public methodGetHashCode
Overridden to ensure consistency with Equals.
(Inherited from Period.)
Public methodToString
Returns a non-null, non-empty string representation of this instance for logging and debugging purposes.
(Overrides ObjectToString.)
Public methodWithMinimumDayRange(DayRange)
Returns a new DayRangePeriod with the same DayRange as this, but also specifying minimumDayRange as the minimum range required.
Top
Remarks

Widening: interpretation of a DayRangePeriod in the context of a Breakdown

If the boundaries of a DayRangePeriod line up neatly with the date splitting of a Breakdown that contains it, then the calculated data will cover the specified range exactly (or a subset of that range if there isn't enough data to satisfy the request fully). This will always be the case if the period is contained within a DailyBreakdown.

If you put a DayRangePeriod inside a WeeklyBreakdown, MonthlyBreakdown, YearlyBreakdown, or FullYearsAverageBreakdown, then it is up to you whether you ensure that the boundaries of your period line up neatly with the weekly/monthly/yearly splitting of the breakdown. If your period specifies dates that do line up with the breakdown, then those dates will be treated as an exact specification. If your period specifies dates that don't line up with the breakdown, the API will effectively widen the range (at the beginning, or the end, or both boundaries if necessary) to ensure that the returned data covers all the dates that your range specifies (assuming enough data exists to do this).

The following examples should help to make this clearer:

Widening example 1

DayRangePeriod period = 
    new DayRangePeriod(new Day(2010, 10, 19).To(2010, 11, 5));
DatedBreakdown breakdown = new MonthlyBreakdown(period);

In this example you can see that the dates of the period (2010-10-19 to 2010-11-05) do not match up with the calendar months that the MonthlyBreakdown specifies. In this instance the API would widen the range at both the beginning and the end, attempting to return one monthly value for October 2010 and one for November 2010.

If the first day of the specified period was the first day of a breakdown month (e.g. 2010-10-01), the range would not have been widened at the start. Similarly, if the last day of the specified period was the last day of a breakdown month (e.g. 2010-11-30), the range would not have been widened at the end. Widening only occurs when the dates don't line up with the splitting of the breakdown.

Widening example 2

Day singleDay = new Day(2009, 7, 21);
DayRangePeriod period = new DayRangePeriod(singleDay.To(singleDay));
DatedBreakdown breakdown = new YearlyBreakdown(period);

In this example the period is specified to cover just one day: 2009-07-21. Of course, that period, if interpreted explicitly, is not long enough to allow a yearly breakdown.

In this instance the API would widen the range at the beginning and the end, giving 2009-01-01 to 2009-12-31, so that it could return a yearly value for 2009 (the year containing the specified range).

Additional notes on widening

  • When you create a DayRangePeriod object, that object will always contain the exact dates that you specified. Widening can only happen when those dates are being interpreted as part of the data-assembly process.
  • You can use widening to your advantage - passing approximate ranges and relying on the automatic widening can save you some date arithmetic and keep your code simpler.
  • Though be careful if you are fetching larger quantities of data and are concerned about rate limits... If, for example, you use an imprecise DayRangePeriod as part of a request for 12 months of monthly data (e.g. calendar months from 2009-01-14 to 2010-01-13), widening could push that to 13 months (e.g. 2009-01-01 to 2010-01-31), pushing you closer towards your rate limit than you would have wanted. This can't happen if you specify your dates precisely or use LatestValuesPeriod instead of DayRangePeriod.
Thread Safety
Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.
See Also