Side of Software
Dated Collections Library 2.0

sos.dated.util
Interface Dates<D>

Type Parameters:
D - the type of dates used in this series
All Known Implementing Classes:
AbstractDates, TreeDates

public interface Dates<D>

An ordered list of non-overlapping date ranges. Each date range is a pair of date objects representing an interval with a closed start and open end, [d1,d2). Date d2 must be greater than date d1. Programmers may use implementations of this interface to perform date range arithmetic, such as unioning and differencing.

To union date ranges, use addRange to add a single date range and addAll to add any number of date ranges. The following diagram shows the result of adding a Dates object with four ranges to a Dates object with three ranges through a call to addAll.

        [   )     [      )         [        )
  +  [        ) [    )      [  ) [       )
 ---------------------------------------------
     [        ) [        )  [  ) [          )
 
To find the difference between date ranges, use removeRange, removeAll, or retainAll. The following digram shows the result of removing a Dates object with two ranges from a Dates object with three ranges through a call to removeAll.
         [         )   [          )  [             )
  -         [  )     [      ]
 ----------------------------------------------------
         [  )  [   )        [     )  [             )
 

Since:
1.0
See Also:
TreeDates

Method Summary
 Dates<D> addAll(Dates<D> dates)
          Adds all date ranges given by dates to this series of dates (optional operation).
 Dates<D> addRange(D from, D to)
          Adds a date range to this series of dates (optional operation).
 void clear()
          Removes all date ranges from this series of dates (optional operation).
 void complement(D from, D to)
          Modifies this Dates object so that it contains only the ranges not currently in this Dates object (optional operation).
 DateIterator<D> dateIterator()
          Returns a date iterator positioned at the first range in the series.
 DateIterator<D> dateIterator(D at)
          Returns an iterator over the date ranges, starting at the range that contains the specified date.
 boolean equals(java.lang.Object obj)
          Indicates if this series of dates is equivalent to the specified object.
 boolean excludesAll(Dates<D> dates)
          Indicates if this series does not overlap another series of dates.
 boolean excludesRange(D from, D to)
          Indicates if no date range in this series overlaps the specified date range.
 int hashCode()
          Returns the hash code value of this series of dates.
 boolean includes(D at)
          Indicates if a date range in this series contains the specified date.
 boolean includesAll(Dates<D> dates)
          Indicates if this series of dates contains all the date ranges given by dates.
 boolean includesRange(D from, D to)
          Indicates if a date range in this series contains the specified date range.
 boolean isEmpty()
          Indicates if this series of dates is empty.
 Dates<D> removeAll(Dates<D> dates)
          Removes all dates ranges given by dates from this series of dates (optional operation).
 Dates<D> removeRange(D from, D to)
          Removes the specified range from this series of dates (optional operation).
 Dates<D> retainAll(Dates<D> dates)
          Removes all but the date ranges given by dates from this series of dates (optional operation).
 int size()
          Returns the number of date ranges included in this series.
 java.lang.Object[] toDateArray()
          Moves this series of dates to a newly created array of dates, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.
<T> T[]
toDateArray(T[] a)
          Moves this series of dates to either the specified array or to a new array with the same type as the specified array, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.
 

Method Detail

addAll

Dates<D> addAll(Dates<D> dates)
Adds all date ranges given by dates to this series of dates (optional operation).

The returned value indicates when this series of date ranges changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this Dates object.

Parameters:
dates - series of dates to be added
Returns:
a series of dates indicating the date ranges that were added as a result of the call
Throws:
java.lang.NullPointerException - if dates is null
java.lang.UnsupportedOperationException - if this series of dates does not support addAll

addRange

Dates<D> addRange(D from,
                  D to)
Adds a date range to this series of dates (optional operation).

The returned value indicates when this series of date ranges changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this Dates object.

Parameters:
from - start of the date range, inclusive
to - end of the date range, exclusive
Returns:
a series of dates indicating the date ranges that were added as a result of the call
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
java.lang.UnsupportedOperationException - if this series of dates does not support addRange

clear

void clear()
Removes all date ranges from this series of dates (optional operation).

Throws:
java.lang.UnsupportedOperationException - if this series of dates does not support clear

complement

void complement(D from,
                D to)
Modifies this Dates object so that it contains only the ranges not currently in this Dates object (optional operation).

Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
java.lang.UnsupportedOperationException - if this series of dates does not support complement

dateIterator

DateIterator<D> dateIterator()
Returns a date iterator positioned at the first range in the series. A call to this method is equivalent to dateIterator( null ).

Returns:
a date iterator positioned at the first range in the series.

dateIterator

DateIterator<D> dateIterator(D at)
Returns an iterator over the date ranges, starting at the range that contains the specified date. Passing null as the argument will return an iterator positioned at the beginning of the series.

Parameters:
at - date to position the iteration
Returns:
an iterator over the date ranges, positioned immediately before the date range that contains the specified date

equals

boolean equals(java.lang.Object obj)
Indicates if this series of dates is equivalent to the specified object.

Overrides:
equals in class java.lang.Object
Parameters:
obj - object to be compared to this series of dates
Returns:
true if this series equals obj

excludesAll

boolean excludesAll(Dates<D> dates)
Indicates if this series does not overlap another series of dates.

Parameters:
dates - date ranges to test for exclusion
Returns:
true if no date range of this series overlaps a date range of the specified series
Throws:
java.lang.NullPointerException - if dates is null

excludesRange

boolean excludesRange(D from,
                      D to)
Indicates if no date range in this series overlaps the specified date range.

Parameters:
from - start of date range (inclusive) to test for exclusion
to - end of date range (exclusive) to test for exclusion
Returns:
true if no date range of this series overlaps the specified date range
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

hashCode

int hashCode()
Returns the hash code value of this series of dates. The value of a Dates object is defined to be
   hashCode += 31 * ( from.hashCode() + to.hashCode() );
 
for each range [from,to) in this object.

Overrides:
hashCode in class java.lang.Object
Returns:
the hash code value of this series of dates.

includes

boolean includes(D at)
Indicates if a date range in this series contains the specified date.

Parameters:
at - date to test for inclusion
Returns:
true if this series of dates contains the specified date
Throws:
java.lang.NullPointerException - if at is null

includesAll

boolean includesAll(Dates<D> dates)
Indicates if this series of dates contains all the date ranges given by dates.

Parameters:
dates - date ranges to test for inclusion
Returns:
true if this series of dates contains all of the specified date ranges
Throws:
java.lang.NullPointerException - if dates is null

includesRange

boolean includesRange(D from,
                      D to)
Indicates if a date range in this series contains the specified date range.

Parameters:
from - start of date range (inclusive) to test for inclusion
to - end of date range (exclusive) to test for inclusion
Returns:
true if this series of dates contains the specified date range
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null

isEmpty

boolean isEmpty()
Indicates if this series of dates is empty.

Returns:
true if no date ranges exist in this series

removeAll

Dates<D> removeAll(Dates<D> dates)
Removes all dates ranges given by dates from this series of dates (optional operation).

The returned value indicates when this series of date ranges changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this Dates object.

Parameters:
dates - date ranges to be removed
Returns:
a series of dates indicating the date ranges that were removed as a result of the call
Throws:
java.lang.NullPointerException - if dates is null
java.lang.UnsupportedOperationException - if this series of dates does not support removeAll

removeRange

Dates<D> removeRange(D from,
                     D to)
Removes the specified range from this series of dates (optional operation).

The returned value indicates when this series of date ranges changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this Dates object.

Parameters:
from - start of date range to remove (inclusive)
to - end of date range to remove (exclusive)
Returns:
a series of dates indicating the date ranges that were removed as a result of the call
Throws:
java.lang.IllegalArgumentException - if from does not precede to
java.lang.NullPointerException - if from or to is null
java.lang.UnsupportedOperationException - if this series of dates does not support removeRange

retainAll

Dates<D> retainAll(Dates<D> dates)
Removes all but the date ranges given by dates from this series of dates (optional operation).

The returned value indicates when this series of date ranges changed as a result of the call and is applicable only for the specified date range. It may be read-only, and it is not tied to this Dates object.

Parameters:
dates - date ranges to retain
Returns:
a series of dates indicating the date ranges that were removed as a result of the call
Throws:
java.lang.NullPointerException - if dates is null
java.lang.UnsupportedOperationException - if this series of dates does not support removeAll

size

int size()
Returns the number of date ranges included in this series.

Returns:
the number of date ranges included in this series.

toDateArray

java.lang.Object[] toDateArray()
Moves this series of dates to a newly created array of dates, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.

Returns:
an array of dates representing this series of dates

toDateArray

<T> T[] toDateArray(T[] a)
Moves this series of dates to either the specified array or to a new array with the same type as the specified array, where a date at an even index represents the start (inclusive) of a range and a date at an odd index represents the end (exclusive) of a range.

Returns:
an array of dates representing this series of dates
Throws:
java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of the dates in this series
java.lang.NullPointerException - if a is null

Side of Software
Dated Collections Library 2.0

Copyright 2003-09 Side of Software (SOS). All rights reserved.