Side of Software
Dated Collections Library 2.0

sos.dated.util
Interface DatedSortedSet<E,D>

Type Parameters:
E - the type of elements maintained by this dated set
D - the type of dates used by this dated set
All Superinterfaces:
DatedCollection<E,D>, DatedObject<D>, DatedSet<E,D>
All Known Implementing Classes:
TreeSetByDate, TreeSetByElement

public interface DatedSortedSet<E,D>
extends DatedSet<E,D>

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,D). Similarly, to treat a non-dated set as dated, use Adapters.asDatedSortedSet(SortedSet,D,D).

Since:
1.0
See Also:
TreeSetByDate, TreeSetByElement, DatedSet, Adapters.asSortedSet(DatedSortedSet,Object), Adapters.asDatedSortedSet(SortedSet,Object,Object)

Method Summary
 java.util.Comparator<? super E> comparator()
          Returns the comparator used to sorted the elements of this dated set.
 E first(D at)
          Returns the smallest element in this dated set at the specified date.
 DatedSortedSet<E,D> headSet(E toElement)
          Returns a view of this dated set of all elements that precede toElement.
 E last(D at)
          Returns the largest element in this dated set at the specified date.
 DatedSortedSet<E,D> subSet(E fromElement, E toElement)
          Returns a view of this dated set of all elements that fall between fromElement (inclusive) and toElement (exclusive).
 DatedSortedSet<E,D> tailSet(E fromElement)
          Returns a view of this dated set of all elements greater than or equal to fromElement.
 
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

java.util.Comparator<? super E> 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

E first(D at)
Returns the smallest element in this dated set at the specified date.

Parameters:
at - date for which to find the smallest element
Returns:
the smallest element at at
Throws:
java.lang.NullPointerException - if at is null
java.util.NoSuchElementException - if this dated set is empty at at

headSet

DatedSortedSet<E,D> headSet(E 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

E last(D at)
Returns the largest element in this dated set at the specified date.

Parameters:
at - date for which to find the largest element
Returns:
the largest element at at
Throws:
java.lang.NullPointerException - if at is null
java.util.NoSuchElementException - if this dated map is empty at at

subSet

DatedSortedSet<E,D> subSet(E fromElement,
                           E 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

DatedSortedSet<E,D> tailSet(E fromElement)
Returns a view of this dated set of all elements greater than or equal to fromElement. The element fromElement 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 back portion of this ordered dated set starting from the specified element

Side of Software
Dated Collections Library 2.0

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