java.util
Class TreeMap
java.lang.Object
|
+--java.util.AbstractMap
|
+--java.util.TreeMap
All Implemented Interfaces:
SortedMap, Cloneable, Serializable, Map
This class provides a red-black tree implementation of the SortedMap
interface. Elements in the Map will be sorted by either a user-provided
Comparator object, or by the natural ordering of the keys.
The algorithms are adopted from Corman, Leiserson, and Rivest's
Introduction to Algorithms. TreeMap guarantees O(log n)
insertion and deletion of elements. That being said, there is a large
enough constant coefficient in front of that "log n" (overhead involved
in keeping the tree balanced), that TreeMap may not be the best choice
for small collections. If something is already sorted, you may want to
just use a LinkedHashMap to maintain the order while providing O(1) access.
TreeMap is a part of the JDK1.2 Collections API. Null keys are allowed
only if a Comparator is used which can deal with them; natural ordering
cannot cope with null. Null values are always allowed. Note that the
ordering must be
consistent with equals to correctly implement
the Map interface. If this condition is violated, the map is still
well-behaved, but you may have suprising results when comparing it to
other maps.
This implementation is not synchronized. If you need to share this between
multiple threads, do something like:
SortedMap m
= Collections.synchronizedSortedMap(new TreeMap(...));
The iterators are fail-fast, meaning that any structural
modification, except for remove()
called on the iterator
itself, cause the iterator to throw a
ConcurrentModificationException
rather than exhibit
non-deterministic behavior.
Since:Authors:- Jon Zeppieri
- Bryce McKinlay
- Eric Blake <ebb9@email.byu.edu>
See Also:
TreeMap
public TreeMap()
Instantiate a new TreeMap with no elements, using the keys' natural
ordering to sort. All entries in the map must have a key which implements
Comparable, and which are mutually comparable, otherwise map
operations may throw a ClassCastException. Attempts to use
a null key will throw a NullPointerException.
See Also:
TreeMap
public TreeMap(java.util.Comparator c)
Instantiate a new TreeMap with no elements, using the provided comparator
to sort. All entries in the map must have keys which are mutually
comparable by the Comparator, otherwise map operations may throw a
ClassCastException.
Parameters:
TreeMap
public TreeMap(java.util.Map map)
Instantiate a new TreeMap, initializing it with all of the elements in
the provided Map. The elements will be sorted using the natural
ordering of the keys. This algorithm runs in n*log(n) time. All entries
in the map must have keys which implement Comparable and are mutually
comparable, otherwise map operations may throw a
ClassCastException.
Parameters:
Throws:
See Also:
TreeMap
public TreeMap(java.util.SortedMap sm)
Instantiate a new TreeMap, initializing it with all of the elements in
the provided SortedMap. The elements will be sorted using the same
comparator as in the provided SortedMap. This runs in linear time.
Parameters:
Throws:
clear
public void clear()
Clears the Map so it has no keys. This is O(1).
clone
public Object clone()
Returns a shallow clone of this TreeMap. The Map itself is cloned,
but its contents are not.
Returns:
comparator
public Comparator comparator()
Return the comparator used to sort this map, or null if it is by
natural order.
Returns:
containsKey
public boolean containsKey(java.lang.Object key)
Returns true if the map contains a mapping for the given key.
Parameters:
Returns:
- true if the key has a mapping
Throws:
containsValue
public boolean containsValue(java.lang.Object value)
Returns true if the map contains at least one mapping to the given value.
This requires linear time.
Parameters:
Returns:
- true if the value appears in a mapping
entrySet
public Set entrySet()
Returns a "set view" of this TreeMap's entries. The set is backed by
the TreeMap, so changes in one show up in the other. The set supports
element removal, but not element addition.
Note that the iterators for all three views, from keySet(), entrySet(),
and values(), traverse the TreeMap in sorted sequence.
Returns:
- a set view of the entries
See Also:
firstKey
public Object firstKey()
Returns the first (lowest) key in the map.
Returns:
Throws:
get
public Object get(java.lang.Object key)
Return the value in this TreeMap associated with the supplied key,
or null
if the key maps to nothing. NOTE: Since the value
could also be null, you must use containsKey to see if this key
actually maps to something.
Parameters:
Returns:
- what the key maps to, if present
Throws:
See Also:
headMap
public SortedMap headMap(java.lang.Object toKey)
Returns a view of this Map including all entries with keys less than
toKey
. The returned map is backed by the original, so changes
in one appear in the other. The submap will throw an
IllegalArgumentException for any attempt to access or add an
element beyond the specified cutoff. The returned map does not include
the endpoint; if you want inclusion, pass the successor element.
Parameters:
Returns:
- a view of the map less than the cutoff
Throws:
ClassCastException
- if toKey
is not compatible with
the comparator (or is not Comparable, for natural ordering)NullPointerException
- if toKey is null, but the comparator does not
tolerate null elements
keySet
public Set keySet()
Returns a "set view" of this TreeMap's keys. The set is backed by the
TreeMap, so changes in one show up in the other. The set supports
element removal, but not element addition.
Returns:
See Also:
lastKey
public Object lastKey()
Returns the last (highest) key in the map.
Returns:
Throws:
put
public Object put(java.lang.Object key, java.lang.Object value)
Puts the supplied value into the Map, mapped by the supplied key.
The value may be retrieved by any object which equals()
this key. NOTE: Since the prior value could also be null, you must
first use containsKey if you want to see if you are replacing the
key's mapping.
Parameters:
Returns:
- the prior mapping of the key, or null if there was none
Throws:
See Also:
putAll
public void putAll(java.util.Map m)
Copies all elements of the given map into this hashtable. If this table
already has a mapping for a key, the new mapping replaces the current
one.
Parameters:
Throws:
remove
public Object remove(java.lang.Object key)
Removes from the TreeMap and returns the value which is mapped by the
supplied key. If the key maps to nothing, then the TreeMap remains
unchanged, and null
is returned. NOTE: Since the value
could also be null, you must use containsKey to see if you are
actually removing a mapping.
Parameters:
Returns:
- whatever the key mapped to, if present
Throws:
size
public int size()
Returns the number of key-value mappings currently in this Map.
Returns:
subMap
public SortedMap subMap(java.lang.Object fromKey, java.lang.Object toKey)
Returns a view of this Map including all entries with keys greater or
equal to fromKey
and less than toKey
(a
half-open interval). The returned map is backed by the original, so
changes in one appear in the other. The submap will throw an
IllegalArgumentException for any attempt to access or add an
element beyond the specified cutoffs. The returned map includes the low
endpoint but not the high; if you want to reverse this behavior on
either end, pass in the successor element.
Parameters:
Returns:
- a view of the map between the cutoffs
Throws:
tailMap
public SortedMap tailMap(java.lang.Object fromKey)
Returns a view of this Map including all entries with keys greater or
equal to fromKey
. The returned map is backed by the
original, so changes in one appear in the other. The submap will throw an
IllegalArgumentException for any attempt to access or add an
element beyond the specified cutoff. The returned map includes the
endpoint; if you want to exclude it, pass in the successor element.
Parameters:
Returns:
- a view of the map above the cutoff
Throws:
ClassCastException
- if fromKey
is not compatible with
the comparator (or is not Comparable, for natural ordering)NullPointerException
- if fromKey is null, but the comparator
does not tolerate null elements
values
public Collection values()
Returns a "collection view" (or "bag view") of this TreeMap's values.
The collection is backed by the TreeMap, so changes in one show up
in the other. The collection supports element removal, but not element
addition.
Returns:
See Also:
This implementation is not synchronized. If you need to share this between multiple threads, do something like:
SortedMap m = Collections.synchronizedSortedMap(new TreeMap(...));
The iterators are fail-fast, meaning that any structural modification, except for
remove()
called on the iterator itself, cause the iterator to throw aConcurrentModificationException
rather than exhibit non-deterministic behavior.