Interface java.util.SortedMap
- Implementing Classes:
- TreeMap
- public interface SortedMap
- extends Map
A Map that further guarantees that it will be in ascending key order,
sorted according to the natural ordering of its keys (see
Comparable), or by a Comparator provided at SortedMap creation time.
This order is reflected when iterating over 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
(or be accepted by the specified Comparator). Furthermore, all such keys
must be mutually comparable: k1.compareTo(k2) (or
comparator.compare(k1, 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.
Note that the ordering maintained by a SortedMap (whether or not an
explicit Comparator is provided) must be total if the SortedMap is
to correctly implement the Map interface. (See Comparable or Comparator
for a definition of total ordering.) This is so because the Map
interface is defined in terms of the equals operation, but a SortedMap
performs all key comparisons using its compareTo (or compare) method, so
two keys that are deemed equal by this method are, from the standpoint of
the SortedMap, equal. The only JDK class whose natural ordering does not
satisfy this constraint is BigDecimal.
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 order
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 ordering. 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.
- Since:
- JDK1.2
- See Also:
- Map, TreeMap, SortedSet, Comparator, Comparable, Collection, ClassCastException
Method Summary
|
Comparator
|
comparator()
Returns the Comparator associated with this SortedMap, or null
if it uses its keys' natural ordering.
|
Object
|
firstKey()
Returns the first (lowest) key currently in this SortedMap.
|
SortedMap
|
headMap(Object toKey)
Returns a view of the portion of this SortedMap whose keys are
strictly less than toKey.
|
Object
|
lastKey()
Returns the last (highest) key currently in this SortedMap.
|
SortedMap
|
subMap(Object fromKey,
Object toKey)
Returns a view of the portion of this SortedMap whose keys range
from fromKey, inclusive, to toKey, exclusive.
|
SortedMap
|
tailMap(Object fromKey)
Returns a view of the portion of this SortedMap whose keys are greater
than or equal to fromKey.
|
comparator
public Comparator comparator()
- Returns the Comparator associated with this SortedMap, or null
if it uses its keys' natural ordering.
- Returns:
- the Comparator associated with this SortedMap, or null
if it uses its keys' natural ordering.
subMap
public SortedMap subMap(Object fromKey,
Object 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 SortedMap headMap(Object 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 SortedMap tailMap(Object 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 Object 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 Object lastKey()
- Returns the last (highest) key currently in this SortedMap.
- Returns:
- the last (highest) key currently in this SortedMap.
- Throws:
- IllegalStateException - Map is empty.
Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.