sos.dated.util
Interface DatedSortedSet

All Superinterfaces:

DatedCollection, DatedObject, DatedSet

All Known Implementing Classes:

TreeSetByDate, TreeSetByElement

public interface DatedSortedSet

extends DatedSet

A dated set whose elements are ordered. A dated sorted set is a dated set whose iterator returns the elements in order, where the order is defined either by the elements' natural ordering or by a Comparator object.

This interface is based on the interface java.util.SortedSet. It does not extend java.util.SortedSet directly, however, because at least one date is needed. To make a dated sorted set appear like a non-dated sorted set, use Adapters.asSortedSet(DatedSortedSet,Date). Similarly, to treat a non-dated set as dated, use Adapters.asDatedSortedSet(SortedSet,Date,Date).

Since:

1.0

See Also:

TreeSetByDate, TreeSetByElement, DatedSet, Adapters.asSortedSet(DatedSortedSet,Date), Adapters.asDatedSortedSet(SortedSet,Date,Date)

Field Summary

Fields inherited from interface sos.dated.util.DatedObject

MAX_DATE, MIN_DATE

Method Summary

java.util.Comparator	comparator() Returns the comparator used to sorted the elements of this dated set.
java.lang.Object	first(java.util.Date date) Returns the smallest element in this dated set at the specified date.
DatedSortedSet	headSet(java.lang.Object toElement) Returns a view of this dated set of all elements that precede toElement.
java.lang.Object	last(java.util.Date date) Returns the largest element in this dated set at the specified date.
DatedSortedSet	subSet(java.lang.Object fromElement, java.lang.Object toElement) Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive).
DatedSortedSet	tailSet(java.lang.Object fromElement) Returns a view of this dated set of all elements greater than or equal to toElement.

Methods inherited from interface sos.dated.util.DatedSet

equals, hashCode

Methods inherited from interface sos.dated.util.DatedCollection

add, addAll, clear, contains, containsAll, containsThroughout, excludesThroughout, hasSizeThroughout, isEmpty, isEmptyThroughout, iterator, remove, removeAll, retainAll, size, toArray, toArray

Methods inherited from interface sos.dated.util.DatedObject

dateIterator, dateIterator, equals, hashCode, toString

Method Detail

comparator

public java.util.Comparator comparator()

Returns the comparator used to sorted the elements of this dated set. A returned null value indicates that this dated set uses the elements' natural ordering.

Returns:

the comparator that orders the elements (may be null)

first

public java.lang.Object first(java.util.Date date)

Returns the smallest element in this dated set at the specified date.

Parameters:

date - date for which to find the smallest element

Returns:

the smallest element at date

Throws:

java.lang.NullPointerException - if date is null

java.util.NoSuchElementException - if this dated set is empty at date

headSet

public DatedSortedSet headSet(java.lang.Object toElement)

Returns a view of this dated set of all elements that precede toElement. The element toElement does not have to appear in this dated set nor will it ever appear in the returned set. The returned set is a fully functional dated sorted set that is tied to this set. Changes to either will be reflected in the other. Any attempt to add an element greater than or equal to toElement will throw an IllegalArgumentException.

Parameters:

toElement - upper bound of the elements of the returned set (exclusive)

Returns:

the front portion of this ordered dated set up to, but not including, the specified element

last

public java.lang.Object last(java.util.Date date)

Returns the largest element in this dated set at the specified date.

Parameters:

date - date for which to find the largest element

Returns:

the largest element at date

Throws:

java.lang.NullPointerException - if date is null

java.util.NoSuchElementException - if this dated map is empty at date

subSet

public DatedSortedSet subSet(java.lang.Object fromElement,
                             java.lang.Object toElement)

Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive). Neither element has to appear in this dated set. The returned set is a fully functional dated sorted set that is closely tied to this set. Changes to either will be reflected in the other. Any attempt to add an element outside the specified range will throw an IllegalArgumentException.

Parameters:

fromElement - lower bound of the elements of the returned set (inclusive)

toElement - upper bound of the elements of the returned set (exclusive)

Returns:

the middle portion of this ordered dated set from fromElement (inclusive) to toElement (exclusive)

tailSet

public DatedSortedSet tailSet(java.lang.Object fromElement)

Returns a view of this dated set of all elements greater than or equal to toElement. The element toElement does not have to appear in this dated set. The returned set is a fully functional dated sorted set that is closely tied to this set. Changes to either will be reflected in the other. Any attempt to add an element less than fromElement will throw an IllegalArgumentException.

Parameters:

fromElement - lower bound of the elements of the returned set (inclusive)

Returns:

the front portion of this ordered dated map up to, but not including, the specified key