public interface java.util.SortedMap<A, B>

java.lang.Object
   |
   +----java.util.SortedMap<A, B>

public interface SortedMap<A, B>
  implements Map<A, B>

A Map that further guarantees that it will be in ascending key order, sorted according to the natural sort method of its keys (see Comparable), or by a Comparator provided at SortedMap creation time. This order is reflected in the SortedMap's Collection views. Several additional operations are provided to take advantage of the ordering. (This interface is the Map analogue of SortedSet.)

All keys inserted into an SortedMap must implement the Comparable interface. Furthermore, all such keys must be mutually comparable: k1.compareTo(k2) must not throw a typeMismatchException for any elements k1 and k2 in the SortedMap. Attempts to violate this restriction will cause the offending method or constructor invocation to throw a ClassCastException.

All general-purpose SortedMap implementation classes should provide four "standard" constructors: 1) A void (no arguments) constructor, which creates an empty SortedMap sorted according to the natural sort method of its keys. 2) A constructor with a single argument of type Comparator, which creates an empty SortedMap sorted according to the specified Comparator. 3) A constructor with a single argument of type Map, which creates a new Map with the same key-value mappings as its argument, sorted according to the keys' natural sort method. 4) A constructor with a single argument of type SortedMap, which creates a new SortedMap with the same key-value mappings and the same ordering as the input SortedMap. There is no way to enforce this recommendation (as interfaces cannot contain constructors) but the JDK implementation (TreeMap) complies.

See also:

Map, TreeMap, SortedSet, Collection, ClassCastException

comparator()

Returns the Comparator associated with this SortedMap, or null if it uses its keys'

firstKey()

Returns the first (lowest) key currently in this SortedMap.

headMap(A)

Returns a view of the portion of this SortedMap whose keys are strictly less than toKey

lastKey()

Returns the last (highest) key currently in this SortedMap.

subMap(A, A)

Returns a view of the portion of this SortedMap whose keys range from fromKey, inclusive,

tailMap(A)

Returns a view of the portion of this SortedMap whose keys are greater than or equal to

public abstract Comparator<A> comparator();

Returns the Comparator associated with this SortedMap, or null if it uses its keys' natural sort method.

Returns:

the Comparator associated with this SortedMap, or null if it uses its keys' natural sort method.

subMap

public abstract SortedMap<A, B> subMap(A fromKey,
                                       A toKey);

Returns a view of the portion of this SortedMap whose keys range from fromKey, inclusive, to toKey, exclusive. The returned SortedMap is backed by this SortedMap, so changes in the returned SortedMap are reflected in this SortedMap, and vice-versa. The returned Map supports all optional Map operations.

The Map returned by this method will throw an IllegalArgumentException if the user attempts to insert a key outside the specified range.

Parameters:

fromKey - low endpoint (inclusive) of the subMap.

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the specified range within this SortedMap.

Throws:

ClassCastException -fromKey or toKey cannot be compared with the keys currently in the SortedMap.

NullPointerException -fromKey or toKey is null and this SortedMap does not tolerate null keys.

IllegalArgumentException -fromKey is greater than toKey.

headMap

public abstract SortedMap<A, B> headMap(A toKey);

Returns a view of the portion of this SortedMap whose keys are strictly less than toKey. The returned SortedMap is backed by this SortedMap, so changes in the returned SortedMap are reflected in this SortedMap, and vice-versa. The returned Map supports all optional Map operations. The Map returned by this method will throw an IllegalArgumentException if the user attempts to insert a key outside the specified range.

Parameters:

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the specified initial range of this SortedMap.

Throws:

ClassCastException -toKey cannot be compared with the keys currently in the SortedMap.

NullPointerException -toKey is null and this SortedMap does not tolerate null keys.

tailMap

public abstract SortedMap<A, B> tailMap(A fromKey);

Returns a view of the portion of this SortedMap whose keys are greater than or equal to fromKey. The returned SortedMap is backed by this SortedMap, so changes in the returned SortedMap are reflected in this SortedMap, and vice-versa. The returned Map supports all optional Map operations.

The Map returned by this method will throw an IllegalArgumentException if the user attempts to insert a key outside the specified range.

Parameters:

toKey - high endpoint (exclusive) of the subMap.

Returns:

a view of the specified final range of this SortedMap.

Throws:

ClassCastException -toKey cannot be compared with the keys currently in the SortedMap.

NullPointerException -fromKey is null and this SortedMap does not tolerate null keys.

firstKey

public abstract A firstKey();

Returns the first (lowest) key currently in this SortedMap.

Returns:

the first (lowest) key currently in this SortedMap.

Throws:

IllegalStateException -Map is empty.

lastKey

public abstract A lastKey();

Returns the last (highest) key currently in this SortedMap.

Returns:

the last (highest) key currently in this SortedMap.

Throws:

IllegalStateException -Map is empty.

java.util.SortedMap.html