DayRange (Degree Days.net API JavaDoc)

java.lang.Object
- net.degreedays.time.DayRange

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<Day>
```
public final class DayRange
extends java.lang.Object
implements java.lang.Iterable<Day>, java.io.Serializable
```
Specifies a range of one or more days e.g. 2020-01-01 to 2020-12-31.

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

Constructor Summary

Constructors
Constructor and Description

DayRange(Day first, Day last)
Constructs a DayRange object that starts on the specified first day and ends on the specified last day.

Constructors
Constructor and Description
`DayRange(Day first, Day last)` Constructs a `DayRange` object that starts on the specified `first` day and ends on the specified `last` day.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`contains(Day testDay)` Returns `true` if the specified `Day` is contained within this `DayRange`; `false` otherwise.
`boolean`	`contains(DayRange testRange)` Returns `true` if the specified `DayRange` is fully contained within this `DayRange`; `false` otherwise.
`Day`	`dayAt(int zeroBasedIndex)` Returns the non-null `Day` at the specified zero-based index within this `DayRange`.
`int`	`dayCount()` Returns the number of days covered by this `DayRange` (always 1 or more).
`boolean`	`equals(java.lang.Object o)` Returns `true` if `o` is a `DayRange` covering exactly the same days as this `DayRange`; `false` otherwise.
`Day`	`first()` Returns the non-null first `Day` in this `DayRange`.
`MaybeEmptyDayRanges`	`fullCalendarMonthsWithin()` Returns a non-null possibly-empty set of `DayRange` objects representing the full calendar months that are fully contained within this `DayRange`.
`MaybeEmptyDayRanges`	`fullCalendarYearsWithin()` Returns a non-null possibly-empty set of `DayRange` objects representing the full calendar years that are fully contained within this `DayRange`.
`MaybeEmptyDayRanges`	`fullMonthsWithin(StartOfMonth startOfMonth)` Returns a non-null possibly-empty set of `DayRange` objects representing the full months (starting on the specified `StartOfMonth`) that are fully contained within this `DayRange`.
`DayRanges`	`fullOrPartialCalendarMonthsWithin()` Returns a non-null set of `DayRange` objects representing the full-or-partial calendar months that are contained within this `DayRange`.
`DayRanges`	`fullOrPartialCalendarYearsWithin()` Returns a non-null set of `DayRange` objects representing the full-or-partial calendar years that are contained within this `DayRange`.
`DayRanges`	`fullOrPartialMonthsWithin(StartOfMonth startOfMonth)` Returns a non-null set of `DayRange` objects representing the full-or-partial months (starting on the specified `StartOfMonth`) that are contained within this `DayRange`.
`DayRanges`	`fullOrPartialWeeksWithin(DayOfWeek firstDayOfWeek)` Returns a non-null set of `DayRange` objects representing the full-or-partial weeks (starting on the specified `firstDayOfWeek`) that are contained within this `DayRange`.
`DayRanges`	`fullOrPartialYearsWithin(StartOfYear startOfYear)` Returns a non-null set of `DayRange` objects representing the full-or-partial years (starting on the specified `StartOfYear`) that are contained within this `DayRange`.
`MaybeEmptyDayRanges`	`fullWeeksWithin(DayOfWeek firstDayOfWeek)` Returns a non-null possibly-empty set of `DayRange` objects representing the full weeks (starting on the specified `firstDayOfWeek`) that are fully contained within this `DayRange`.
`MaybeEmptyDayRanges`	`fullYearsWithin(StartOfYear startOfYear)` Returns a non-null possibly-empty set of `DayRange` objects representing the full years (starting on the specified `StartOfYear`) that are fully contained within this `DayRange`.
`DayRange`	`greedyUnion(Day dayToIncludeInUnion)` Returns the non-null `DayRange` that includes all the days within this `DayRange`, the specified `Day` (`dayToIncludeInUnion`), and any days between.
`DayRange`	`greedyUnion(DayRange rangeToIncludeInUnion)` Returns the non-null `DayRange` that includes all the days within this `DayRange`, the specified `DayRange` (`rangeToIncludeInUnion`), and any days between.
`int`	`hashCode()` Overridden to ensure consistency with `equals`.
`int`	`indexOf(Day day)` Returns the index of the specified `Day` within this `DayRange`, or -1 if it is not contained within this `DayRange`.
`DayRange`	`intersectionOrNull(DayRange intersectWith)` Returns a `DayRange` covering the days that are contained within both this `DayRange` and the specified `DayRange`, or `null` if there is no such intersection.
`java.util.Iterator<Day>`	`iterator()`
`Day`	`last()` Returns the non-null last `Day` in this `DayRange`.
`DayRanges`	`toDailyDayRanges()` Returns a non-null `DayRanges` object representing each `Day` within this `DayRange` as its own `DayRange` (covering just one day).
`java.lang.String`	`toString()` Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Constructor Detail
  - DayRange
```
public DayRange(Day first,
                Day last)
```
    Constructs a DayRange object that starts on the specified first day and ends on the specified last day.
    If first and last represent the same day, the range will cover that day only.
    
    Parameters:
    
    first - the first day that the DayRange should include. Cannot be null.
    
    last - the last day that the DayRange should include. Cannot be null, and must be equal to or later than first.
    
    Throws:
    
    java.lang.NullPointerException - if first or last is null.
    
    java.lang.IllegalArgumentException - if first is after last.
    
    See Also:
    
    Day.to(Day)
- Method Detail
  - first
```
public Day first()
```
    Returns the non-null first Day in this DayRange.
  - last
```
public Day last()
```
    Returns the non-null last Day in this DayRange.
  - dayCount
```
public int dayCount()
```
    Returns the number of days covered by this DayRange (always 1 or more).
  - dayAt
```
public Day dayAt(int zeroBasedIndex)
```
    Returns the non-null Day at the specified zero-based index within this DayRange.
    
    Parameters:
    
    zeroBasedIndex - the index of the Day to return. Must be greater than or equal to zero and less than dayCount().
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if zeroBasedIndex is less than zero or greater than or equal to dayCount().
    
    See Also:
    
    indexOf(Day)
  - iterator
```
public java.util.Iterator<Day> iterator()
```
    Specified by:
    
    iterator in interface java.lang.Iterable<Day>
  - contains
```
public boolean contains(Day testDay)
```
    Returns true if the specified Day is contained within this DayRange; false otherwise.
    
    Parameters:
    
    testDay - the Day to test for containment within this DayRange.
    
    Returns:
    
    true if testDay is equal to or after the first() day of this DayRange, and equal to or before the last() day of this DayRange; false otherwise.
    
    Throws:
    
    java.lang.NullPointerException - if testDay is null.
  - contains
```
public boolean contains(DayRange testRange)
```
    Returns true if the specified DayRange is fully contained within this DayRange; false otherwise.
    
    Parameters:
    
    testRange - the DayRange to test for containment within this DayRange.
    
    Returns:
    
    true if the first day of testRange is equal to or after the first day of this DayRange, and the last day of testRange is equal to or before the last day of this DayRange; false otherwise.
    
    Throws:
    
    java.lang.NullPointerException - if testRange is null.
  - indexOf
```
public int indexOf(Day day)
```
    Returns the index of the specified Day within this DayRange, or -1 if it is not contained within this DayRange.
    
    Parameters:
    
    day - the Day to return the index of.
    
    Throws:
    
    java.lang.NullPointerException - if day is null.
    
    See Also:
    
    dayAt(int)
  - intersectionOrNull
```
public DayRange intersectionOrNull(DayRange intersectWith)
```
    Returns a DayRange covering the days that are contained within both this DayRange and the specified DayRange, or null if there is no such intersection.
    By definition, a.intersectionOrNull(b) will always give the same result as b.intersectionOrNull(a), provided neither a nor b are null.
    
    Parameters:
    
    intersectWith - the other DayRange that the intersection should be calculated from (together with this DayRange). Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if intersectWith is null.
  - greedyUnion
```
public DayRange greedyUnion(DayRange rangeToIncludeInUnion)
```
    Returns the non-null DayRange that includes all the days within this DayRange, the specified DayRange (rangeToIncludeInUnion), and any days between.
    This method is "greedy" because, if there is a gap between this DayRange and rangeToIncludeInUnion, that gap will be included in the returned DayRange.
    
    Parameters:
    
    rangeToIncludeInUnion - the DayRange that the returned DayRange should include (together with this DayRange and any days between). Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if rangeToIncludeInUnion is null.
  - greedyUnion
```
public DayRange greedyUnion(Day dayToIncludeInUnion)
```
    Returns the non-null DayRange that includes all the days within this DayRange, the specified Day (dayToIncludeInUnion), and any days between.
    This method is "greedy" because, if there is a gap between this DayRange and dayToIncludeInUnion, that gap will be included in the returned DayRange.
    
    Parameters:
    
    dayToIncludeInUnion - the Day that the returned DayRange should include (together with this DayRange and any days between). Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if dayToIncludeInUnion is null.
  - fullWeeksWithin
```
public MaybeEmptyDayRanges fullWeeksWithin(DayOfWeek firstDayOfWeek)
```
    Returns a non-null possibly-empty set of DayRange objects representing the full weeks (starting on the specified firstDayOfWeek) that are fully contained within this DayRange.
    If you know that this DayRange will contain at least one full week starting on your specified firstDayOfWeek you can call MaybeEmptyDayRanges.notEmpty() on the returned object to get it as a DayRanges. For example:
```
 DayRanges result = dayRange.fullWeeksWithin(DayOfWeek.MONDAY).notEmpty();
 
```
    Parameters:
    
    firstDayOfWeek - indicating the first day of a "week" e.g. DayOfWeek.MONDAY for weeks running from Monday to Sunday (inclusive). Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if firstDayOfWeek is null.
  - fullMonthsWithin
```
public MaybeEmptyDayRanges fullMonthsWithin(StartOfMonth startOfMonth)
```
    Returns a non-null possibly-empty set of DayRange objects representing the full months (starting on the specified StartOfMonth) that are fully contained within this DayRange.
    If you know that this DayRange will contain at least one full month starting on your specified startOfMonth you can call MaybeEmptyDayRanges.notEmpty() on the returned object to get it as a DayRanges. For example:
```
 DayRanges result = dayRange.fullMonthsWithin(StartOfMonth.of(6)).notEmpty();
 
```
    Parameters:
    
    startOfMonth - indicating the first day of a "month" e.g. StartOfMonth.of(1) for calendar months starting on the 1st. Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if startOfMonth is null.
  - fullCalendarMonthsWithin
```
public MaybeEmptyDayRanges fullCalendarMonthsWithin()
```
    Returns a non-null possibly-empty set of DayRange objects representing the full calendar months that are fully contained within this DayRange.
    If you know that this DayRange will contain at least one full calendar month you can call MaybeEmptyDayRanges.notEmpty() on the returned object to get it as a DayRanges. For example:
```
 DayRanges result = dayRange.fullCalendarMonthsWithin().notEmpty();
 
```
  - fullYearsWithin
```
public MaybeEmptyDayRanges fullYearsWithin(StartOfYear startOfYear)
```
    Returns a non-null possibly-empty set of DayRange objects representing the full years (starting on the specified StartOfYear) that are fully contained within this DayRange.
    If you know that this DayRange will contain at least one full year starting on your specified startOfYear you can call MaybeEmptyDayRanges.notEmpty() on the returned object to get it as a DayRanges. For example:
```
 DayRanges result = dayRange.fullYearsWithin(StartOfYear.of(4, 6)).notEmpty();
 
```
    Parameters:
    
    startOfYear - indicating the first day of a "year" e.g. StartOfYear.of(1, 1) for calendar years starting on January 1st. Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if startOfYear is null.
  - fullCalendarYearsWithin
```
public MaybeEmptyDayRanges fullCalendarYearsWithin()
```
    Returns a non-null possibly-empty set of DayRange objects representing the full calendar years that are fully contained within this DayRange.
    If you know that this DayRange will contain at least one full calendar year you can call MaybeEmptyDayRanges.notEmpty() on the returned object to get it as a DayRanges. For example:
```
 DayRanges result = dayRange.fullCalendarYearsWithin().notEmpty();
 
```
  - fullOrPartialWeeksWithin
```
public DayRanges fullOrPartialWeeksWithin(DayOfWeek firstDayOfWeek)
```
    Returns a non-null set of DayRange objects representing the full-or-partial weeks (starting on the specified firstDayOfWeek) that are contained within this DayRange.
    For example, consider calling this method on a DayRange covering Monday 2020-07-20 to Thursday 2020-07-30 (inclusive), and specifying the first day of the week as Monday:
```
 DayRange dayRange = Day.of(2020, 7, 20).to(2020, 7, 30);
 DayRanges dayRanges = dayRange.fullOrPartialWeeksWithin(DayOfWeek.MONDAY);
 
```
    The returned DayRanges object would contain:
    - the full week Monday 2020-07-20 to Sunday 2020-07-26 (inclusive); and
    - the partial week Monday 2020-07-27 to Thursday 2020-07-30 (inclusive).
    Parameters:
    
    firstDayOfWeek - indicating the first day of a "week" e.g. DayOfWeek.MONDAY for weeks running from Monday to Sunday (inclusive). Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if firstDayOfWeek is null.
  - fullOrPartialMonthsWithin
```
public DayRanges fullOrPartialMonthsWithin(StartOfMonth startOfMonth)
```
    Returns a non-null set of DayRange objects representing the full-or-partial months (starting on the specified StartOfMonth) that are contained within this DayRange.
    For example, consider calling this method on a DayRange covering 2020-06-15 to 2020-07-26 (inclusive), and specifying the start of the month as the 6th:
```
 DayRange dayRange = Day.of(2020, 6, 15).to(2020, 7, 26);
 DayRanges dayRanges = dayRange.fullOrPartialMonthsWithin(StartOfMonth.of(6));
 
```
    The returned DayRanges object would contain:
    - the partial month 2020-06-15 to 2020-07-05 (inclusive); and
    - the partial month 2020-07-06 to 2020-07-26 (inclusive).
    Parameters:
    
    startOfMonth - indicating the first day of a "month" e.g. StartOfMonth.of(1) for calendar months starting on the 1st. Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if startOfMonth is null.
  - fullOrPartialCalendarMonthsWithin
```
public DayRanges fullOrPartialCalendarMonthsWithin()
```
    Returns a non-null set of DayRange objects representing the full-or-partial calendar months that are contained within this DayRange.
    For example, consider calling this method on a DayRange covering 2020-05-15 to 2020-07-26 (inclusive):
```
 DayRange dayRange = Day.of(2020, 5, 15).to(2020, 7, 26);
 DayRanges dayRanges = dayRange.fullOrPartialCalendarMonthsWithin();
 
```
    The returned DayRanges object would contain:
    - the partial month 2020-05-15 to 2020-05-31 (inclusive);
    - the full month 2020-06-01 to 2020-06-30 (inclusive); and
    - the partial month 2020-07-01 to 2020-07-26 (inclusive).
  - fullOrPartialYearsWithin
```
public DayRanges fullOrPartialYearsWithin(StartOfYear startOfYear)
```
    Returns a non-null set of DayRange objects representing the full-or-partial years (starting on the specified StartOfYear) that are contained within this DayRange.
    For example, consider calling this method on a DayRange covering 2019-02-15 to 2020-07-26 (inclusive), and specifying the start of the year as April 6th:
```
 DayRange dayRange = Day.of(2019, 2, 15).to(2020, 7, 26);
 DayRanges dayRanges = dayRange.fullOrPartialYearsWithin(StartOfYear.of(4, 6));
 
```
    The returned DayRanges object would contain:
    - the partial year 2019-02-15 to 2019-04-05 (inclusive);
    - the full year 2019-04-06 to 2020-04-05 (inclusive); and
    - the partial year 2020-04-06 to 2020-07-26 (inclusive).
    Parameters:
    
    startOfYear - indicating the first day of a "year" e.g. StartOfYear.of(1, 1) for calendar years starting on January 1st. Cannot be null.
    
    Throws:
    
    java.lang.NullPointerException - if startOfYear is null.
  - fullOrPartialCalendarYearsWithin
```
public DayRanges fullOrPartialCalendarYearsWithin()
```
    Returns a non-null set of DayRange objects representing the full-or-partial calendar years that are contained within this DayRange.
    For example, consider calling this method on a DayRange covering 2018-05-15 to 2020-07-26 (inclusive):
```
 DayRange dayRange = Day.of(2018, 5, 15).to(2020, 7, 26);
 DayRanges dayRanges = dayRange.fullOrPartialCalendarYearsWithin();
 
```
    The returned DayRanges object would contain:
    - the partial year 2018-05-15 to 2018-12-31 (inclusive);
    - the full year 2019-01-01 to 2019-12-31 (inclusive); and
    - the partial year 2020-01-01 to 2020-07-26 (inclusive).
  - toDailyDayRanges
```
public DayRanges toDailyDayRanges()
```
    Returns a non-null DayRanges object representing each Day within this DayRange as its own DayRange (covering just one day).
    This is not as inefficient as it sounds for a large DayRange (e.g. one covering many years), as the returned DayRanges object will not actually create the individual single-day DayRange objects within it unless/until they are accessed.
  - equals
```
public boolean equals(java.lang.Object o)
```
    Returns true if o is a DayRange covering exactly the same days as this DayRange; false otherwise.
    
    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 DayRange

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

DayRange

Method Detail

first

last

dayCount

dayAt

iterator

contains

contains

indexOf

intersectionOrNull

greedyUnion

greedyUnion

fullWeeksWithin

fullMonthsWithin

fullCalendarMonthsWithin

fullYearsWithin

fullCalendarYearsWithin

fullOrPartialWeeksWithin

fullOrPartialMonthsWithin

fullOrPartialCalendarMonthsWithin

fullOrPartialYearsWithin

fullOrPartialCalendarYearsWithin

toDailyDayRanges

equals

hashCode

toString