sos.dated.util
Interface DatedSortedMap<K,V,D>

Type Parameters:

K - the type of keys maintained by this dated map

V - the type of values maintained by this dated map

D - the type of dates used by this dated map

All Superinterfaces:

DatedMap<K,V,D>, DatedObject<D>

All Known Implementing Classes:

TreeMapByDate, TreeMapByKey

public interface DatedSortedMap<K,V,D>
extends DatedMap<K,V,D>

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,D). Similarly, to treat a non-dated map as dated, use Adapters.asDatedSortedMap(SortedMap,D,D).

Since:

1.0

See Also:

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

Nested Class Summary

Nested classes/interfaces inherited from interface sos.dated.util.DatedMap

DatedMap.Entry<K,V,D>

Method Summary

java.util.Comparator<? super K>	comparator() Returns the comparator used to sorted the keys of this dated map.
K	firstKey(D at) Returns the smallest key in this dated map at the specified date.
DatedSortedMap<K,V,D>	headMap(K toKey) Returns a view of this dated map of all mappings whose keys precede toKey.
K	lastKey(D at) Returns the largest key in this dated map at the specified date.
DatedSortedMap<K,V,D>	subMap(K fromKey, K toKey) Returns a view of this dated map of all mappings whose keys fall between fromKey (inclusive) and toKey (exclusive).
DatedSortedMap<K,V,D>	tailMap(K fromKey) Returns a view of this dated map of all mappings whose keys are greater than or equal to fromKey.

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

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

K firstKey(D at)

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

Parameters:

at - date for which to find the smallest key

Returns:

the smallest key at at

Throws:

java.lang.NullPointerException - if at is null

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

headMap

DatedSortedMap<K,V,D> headMap(K 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

K lastKey(D at)

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

Parameters:

at - date for which to find the largest key

Returns:

the largest key at at

Throws:

java.lang.NullPointerException - if at is null

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

subMap

DatedSortedMap<K,V,D> subMap(K fromKey,
                             K 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

DatedSortedMap<K,V,D> tailMap(K fromKey)

Returns a view of this dated map of all mappings whose keys are greater than or equal to fromKey. The key fromKey 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 back portion of this ordered dated map starting from the specified key