sos.dated.util
Interface Dates

All Known Implementing Classes:

AbstractDates, TreeDates

public interface Dates

An ordered list of non-overlapping date ranges. Each date range is a pair of java.util.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	addAll(Dates dates) Adds all date ranges given by dates to this series of dates.
Dates	addRange(java.util.Date from, java.util.Date to) Adds a date range to this series of dates.
void	clear() Removes all date ranges from this series of dates.
void	complement() Modifies this Dates object so that it contains only the ranges not currently in this Dates object.
DateIterator	dateIterator() Returns a date iterator positioned at the first range in the series.
DateIterator	dateIterator(java.util.Date date) Returns an iterator over the date ranges, beginning with from, inclusive, and ending with to, exclusive.
boolean	equals(java.lang.Object obj) Indicates if this series of dates is equivalent to the specified object.
boolean	excludesAll(Dates dates) Indicates if this series does not overlap another series of dates.
boolean	excludesRange(java.util.Date from, java.util.Date 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(java.util.Date date) Indicates if a date range in this series contains the specified date.
boolean	includesAll(Dates dates) Indicates if this series of dates contains all the date ranges given by dates.
boolean	includesRange(java.util.Date from, java.util.Date 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	removeAll(Dates dates) Removes all dates ranges given by dates from this series of dates.
Dates	removeRange(java.util.Date from, java.util.Date to) Removes the specified range from this series of dates.
Dates	retainAll(Dates dates) Removes all but the date ranges given by dates from this series of dates.
int	size() Returns the number of date ranges included in this series.
java.util.Date[]	toDateArray() Converts this series of dates to an 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.
java.util.Date[]	toDateArray(java.util.Date[] a) Converts this series of dates to an 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.

Method Detail

addAll

public Dates addAll(Dates dates)

Adds all date ranges given by dates to this series of dates.

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

addRange

public Dates addRange(java.util.Date from,
                      java.util.Date to)

Adds a date range to this series of dates.

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

clear

public void clear()

Removes all date ranges from this series of dates.

complement

public void complement()

Modifies this Dates object so that it contains only the ranges not currently in this Dates object.

dateIterator

public DateIterator dateIterator()

Returns a date iterator positioned at the first range in the series. A call to this method is equivalent to dateIterator(DatedObject.MIN_DATE).

Returns:

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

dateIterator

public DateIterator dateIterator(java.util.Date date)

Returns an iterator over the date ranges, beginning with from, inclusive, and ending with to, exclusive.

Returns:

an iterator over the date ranges, constrained to the specified range

equals

public 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

public boolean excludesAll(Dates 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

public boolean excludesRange(java.util.Date from,
                             java.util.Date 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

hashCode

public 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

public boolean includes(java.util.Date date)

Indicates if a date range in this series contains the specified date.

Parameters:

date - date to test for inclusion

Returns:

true if this series of dates contains the specified date

Throws:

java.lang.NullPointerException - if date is null

includesAll

public boolean includesAll(Dates 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

public boolean includesRange(java.util.Date from,
                             java.util.Date 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

isEmpty

public boolean isEmpty()

Indicates if this series of dates is empty.

Returns:

true if no date ranges exist in this series

removeAll

public Dates removeAll(Dates dates)

Removes all dates ranges given by dates from this series of dates.

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

removeRange

public Dates removeRange(java.util.Date from,
                         java.util.Date to)

Removes the specified range from this series of dates.

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

retainAll

public Dates retainAll(Dates dates)

Removes all but the date ranges given by dates from this series of dates.

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

size

public int size()

Returns the number of date ranges included in this series.

Returns:

the number of date ranges included in this series.

toDateArray

public java.util.Date[] toDateArray()

Converts this series of dates to an 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

public java.util.Date[] toDateArray(java.util.Date[] a)

Converts this series of dates to an 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