sos.dated.util
Interface DatedSortedMap

All Superinterfaces:

DatedMap, DatedObject

All Known Implementing Classes:

TreeMapByDate, TreeMapByKey

public interface DatedSortedMap

extends DatedMap

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

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

Since:

1.0

See Also:

TreeMapByDate, TreeMapByKey, DatedMap, Adapters.asSortedMap(DatedSortedMap,Date), Adapters.asDatedSortedMap(SortedMap,Date,Date)

Nested Class Summary

Nested classes inherited from class sos.dated.util.DatedMap

DatedMap.Entry

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 keys of this dated map.
java.lang.Object	firstKey(java.util.Date date) Returns the smallest key in this dated map at the specified date.
DatedSortedMap	headMap(java.lang.Object toKey) Returns a view of this dated map of all mappings whose keys precede toKey.
java.lang.Object	lastKey(java.util.Date date) Returns the largest key in this dated map at the specified date.
DatedSortedMap	subMap(java.lang.Object fromKey, java.lang.Object toKey) Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive).
DatedSortedMap	tailMap(java.lang.Object fromKey) Returns a view of this dated map of all mappings whose keys are greater than or equal to toKey.

Methods inherited from interface sos.dated.util.DatedMap

clear, containsKey, containsKeyThroughout, containsValue, containsValueThroughout, entrySet, equals, excludesKeyThroughout, excludesValueThroughout, get, get, hashCode, hasSizeThroughout, isEmpty, isEmptyThroughout, keySet, put, putAll, remove, size, values

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 keys of this dated map. A returned null value indicates that this dated map uses the keys' natural ordering.

Returns:

the comparator that orders the keys (may be null)

firstKey

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

Returns the smallest key in this dated map at the specified date.

Parameters:

date - date for which to find the smallest key

Returns:

the smallest key at date

Throws:

java.lang.NullPointerException - if date is null

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

headMap

public DatedSortedMap headMap(java.lang.Object toKey)

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

Parameters:

toKey - upper bound of the keys of the returned map (exclusive)

Returns:

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

lastKey

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

Returns the largest key in this dated map at the specified date.

Parameters:

date - date for which to find the largest key

Returns:

the largest key at date

Throws:

java.lang.NullPointerException - if date is null

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

subMap

public DatedSortedMap subMap(java.lang.Object fromKey,
                             java.lang.Object toKey)

Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive). Neither key has to appear in this dated map. The returned map is a fully functional dated sorted map that is closely tied to this map. Changes to either will be reflected in the other. Any attempt to add a key outside the specified key range will throw an IllegalArgumentException.

Parameters:

fromKey - lower bound of the keys of the returned map (inclusive)

toKey - upper bound of the keys of the returned map (exclusive)

Returns:

the middle portion of this ordered dated map from fromKey (inclusive) to toKey (exclusive)

tailMap

public DatedSortedMap tailMap(java.lang.Object fromKey)

Returns a view of this dated map of all mappings whose keys are greater than or equal to toKey. The key toKey does not have to appear in this dated map. The returned map is a fully functional dated sorted map that is closely tied to this map. Changes to either will be reflected in the other. Any attempt to add a key less than fromKey will throw an IllegalArgumentException.

Parameters:

fromKey - lower bound of the keys of the returned map (inclusive)

Returns:

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