java.util
Class TreeMap<K,V>
- NavigableMap, Cloneable, Map<K,V>, Serializable
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.
TreeMap() - Instantiate a new TreeMap with no elements, using the keys' natural
ordering to sort.
|
TreeMap(K> c) - Instantiate a new TreeMap with no elements, using the provided comparator
to sort.
|
TreeMap(SortedMap sm) - Instantiate a new TreeMap, initializing it with all of the elements in
the provided SortedMap.
|
TreeMap(extends K, V> map) - Instantiate a new TreeMap, initializing it with all of the elements in
the provided Map.
|
SortedMap | V> headMap(K toKey) - Returns a view of this Map including all entries with keys less than
toKey .
|
NavigableMap | V> headMap(K toKey, boolean inclusive) - Returns a view of this Map including all entries with keys less than
(or equal to, if
inclusive is true) toKey .
|
SortedMap | V> subMap(K fromKey, K 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).
|
NavigableMap | V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive) - Returns a view of this Map including all entries with keys greater (or
equal to, if
fromInclusive is true) fromKey and
less than (or equal to, if toInclusive is true)
toKey .
|
SortedMap | V> tailMap(K fromKey) - Returns a view of this Map including all entries with keys greater or
equal to
fromKey .
|
NavigableMap | V> tailMap(K fromKey, boolean inclusive) - Returns a view of this Map including all entries with keys greater or
equal to
fromKey .
|
Entry | ceilingEntry(K key) - Returns the entry associated with the least or lowest key
that is greater than or equal to the specified key, or
null if there is no such key.
|
K | ceilingKey(K key) - Returns the the least or lowest key that is greater than
or equal to the specified key, or
null if
there is no such key.
|
void | clear() - Clears the Map so it has no keys.
|
Object | clone() - Returns a shallow clone of this TreeMap.
|
boolean | containsKey(Object key) - Returns true if the map contains a mapping for the given key.
|
boolean | containsValue(Object value) - Returns true if the map contains at least one mapping to the given value.
|
NavigableSet | descendingKeySet() - Returns a reverse ordered
NavigableSet view of this
map's keys.
|
NavigableMap | descendingMap() - Returns a view of the map in reverse order.
|
Set> | entrySet() - Returns a "set view" of this TreeMap's entries.
|
Entry | firstEntry() - Returns the entry associated with the least or lowest key
in the map, or
null if the map is empty.
|
K | firstKey() - Returns the first (lowest) key in the map.
|
Entry | floorEntry(K key) - Returns the entry associated with the greatest or highest key
that is less than or equal to the specified key, or
null if there is no such key.
|
K | floorKey(K key) - Returns the the greatest or highest key that is less than
or equal to the specified key, or
null if
there is no such key.
|
V | get(Object key) - Return the value in this TreeMap associated with the supplied key,
or
null if the key maps to nothing.
|
Entry | higherEntry(K key) - Returns the entry associated with the least or lowest key
that is strictly greater than the specified key, or
null if there is no such key.
|
K | higherKey(K key) - Returns the the least or lowest key that is strictly
greater than the specified key, or
null if
there is no such key.
|
Set | keySet() - Returns a "set view" of this TreeMap's keys.
|
Entry | lastEntry() - Returns the entry associated with the greatest or highest key
in the map, or
null if the map is empty.
|
K | lastKey() - Returns the last (highest) key in the map.
|
Entry | lowerEntry(K key) - Returns the entry associated with the greatest or highest key
that is strictly less than the specified key, or
null if there is no such key.
|
K | lowerKey(K key) - Returns the the greatest or highest key that is strictly
less than the specified key, or
null if
there is no such key.
|
NavigableSet | navigableKeySet() - Returns a
NavigableSet view of this map's keys.
|
Entry | pollFirstEntry() - Removes and returns the entry associated with the least
or lowest key in the map, or
null if the map
is empty.
|
Entry | pollLastEntry() - Removes and returns the entry associated with the greatest
or highest key in the map, or
null if the map
is empty.
|
V | put(K key, V value) - Puts the supplied value into the Map, mapped by the supplied key.
|
void | putAll(extends K, V> m) - Copies all elements of the given map into this TreeMap.
|
V | remove(Object key) - Removes from the TreeMap and returns the value which is mapped by the
supplied key.
|
int | size() - Returns the number of key-value mappings currently in this Map.
|
Comparator | super K> comparator() - Return the comparator used to sort this map, or null if it is by
natural order.
|
Collection | values() - Returns a "collection view" (or "bag view") of this TreeMap's values.
|
V>> entrySet , clear , clone , containsKey , containsValue , equals , get , hashCode , isEmpty , keySet , put , putAll , remove , size , toString , values |
clone , equals , extends Object> getClass , finalize , hashCode , notify , notifyAll , toString , wait , wait , wait |
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
.
TreeMap
public TreeMap(K> 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
.
c
- the sort order for the keys of this map, or null
for the natural order
TreeMap
public TreeMap(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.
sm
- a SortedMap, whose entries will be put into this TreeMap
TreeMap
public TreeMap(extends K,
V> 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
.
map
- a Map, whose entries will be put into this TreeMap
V> headMap
public SortedMapV> headMap(K 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
or call
headMap(toKey, true)
. This is equivalent to
calling
headMap(toKey, false)
.
toKey
- the (exclusive) cutoff point
- a view of the map less than the cutoff
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
V> headMap
public NavigableMapV> headMap(K toKey,
boolean inclusive)
Returns a view of this Map including all entries with keys less than
(or equal to, if
inclusive
is true)
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.
toKey
- the cutoff pointinclusive
- true if the cutoff point should be included.
- a view of the map less than (or equal to, if
inclusive
is true) the cutoff.
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
V> subMap
public SortedMapV> subMap(K fromKey,
K 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 or call
subMap(K,boolean,K,boolean)
. This call is equivalent to
subMap(fromKey, true, toKey, false)
.
fromKey
- the (inclusive) low cutoff pointtoKey
- the (exclusive) high cutoff point
- a view of the map between the cutoffs
V> subMap
public NavigableMapV> subMap(K fromKey,
boolean fromInclusive,
K toKey,
boolean toInclusive)
Returns a view of this Map including all entries with keys greater (or
equal to, if
fromInclusive
is true)
fromKey
and
less than (or equal to, if
toInclusive
is true)
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 cutoffs.
fromKey
- the low cutoff pointfromInclusive
- true if the low cutoff point should be included.toKey
- the high cutoff pointtoInclusive
- true if the high cutoff point should be included.
- a view of the map for the specified range.
V> tailMap
public SortedMapV> tailMap(K 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.
This is equivalent to calling
tailMap(fromKey, true)
.
fromKey
- the (inclusive) low cutoff point
- a view of the map above the cutoff
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
V> tailMap
public NavigableMapV> tailMap(K fromKey,
boolean inclusive)
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.
fromKey
- the low cutoff pointinclusive
- true if the cutoff point should be included.
- a view of the map above the cutoff
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
ceilingEntry
public Entry ceilingEntry(K key)
Returns the entry associated with the least or lowest key
that is greater than or equal to the specified key, or
null
if there is no such key.
key
- the key relative to the returned entry.
- the entry with the least key greater than or equal
to the given key, or
null
if there is
no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
ceilingKey
public K ceilingKey(K key)
Returns the the least or lowest key that is greater than
or equal to the specified key, or null
if
there is no such key.
key
- the key relative to the returned entry.
- the least key greater than or equal to the given key,
or
null
if there is no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
descendingKeySet
public NavigableSet descendingKeySet()
Returns a reverse ordered
NavigableSet
view of this
map'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.
- a reverse ordered set view of the keys.
descendingMap
public NavigableMap descendingMap()
Returns a view of the map in reverse order. The descending map
is backed by the original map, so that changes affect both maps.
Any changes occurring to either map while an iteration is taking
place (with the exception of a
Iterator.remove()
operation)
result in undefined behaviour from the iteration. The ordering
of the descending map is the same as for a map with a
Comparator
given by
Collections.reverseOrder()
,
and calling
descendingMap()
on the descending map itself
results in a view equivalent to the original map.
- a reverse order view of the map.
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.
- a set view of the entries
firstEntry
public Entry firstEntry()
Returns the entry associated with the least or lowest key
in the map, or null
if the map is empty.
- the lowest entry, or
null
if the map
is empty.
firstKey
public K firstKey()
Returns the first (lowest) key in the map.
floorEntry
public Entry floorEntry(K key)
Returns the entry associated with the greatest or highest key
that is less than or equal to the specified key, or
null
if there is no such key.
key
- the key relative to the returned entry.
- the entry with the greatest key less than or equal
to the given key, or
null
if there is
no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
floorKey
public K floorKey(K key)
Returns the the greatest or highest key that is less than
or equal to the specified key, or null
if
there is no such key.
key
- the key relative to the returned entry.
- the greatest key less than or equal to the given key,
or
null
if there is no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
get
public V get(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.
- get in interface Map<K,V>
- get in interface AbstractMap<K,V>
key
- the key for which to fetch an associated value
- what the key maps to, if present
higherEntry
public Entry higherEntry(K key)
Returns the entry associated with the least or lowest key
that is strictly greater than the specified key, or
null
if there is no such key.
key
- the key relative to the returned entry.
- the entry with the least key greater than
the given key, or
null
if there is
no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
higherKey
public K higherKey(K key)
Returns the the least or lowest key that is strictly
greater than the specified key, or null
if
there is no such key.
key
- the key relative to the returned entry.
- the least key greater than the given key,
or
null
if there is no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
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.
- keySet in interface Map<K,V>
- keySet in interface AbstractMap<K,V>
lastEntry
public Entry lastEntry()
Returns the entry associated with the greatest or highest key
in the map, or null
if the map is empty.
- the highest entry, or
null
if the map
is empty.
lastKey
public K lastKey()
Returns the last (highest) key in the map.
lowerEntry
public Entry lowerEntry(K key)
Returns the entry associated with the greatest or highest key
that is strictly less than the specified key, or
null
if there is no such key.
key
- the key relative to the returned entry.
- the entry with the greatest key less than
the given key, or
null
if there is
no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
lowerKey
public K lowerKey(K key)
Returns the the greatest or highest key that is strictly
less than the specified key, or null
if
there is no such key.
key
- the key relative to the returned entry.
- the greatest key less than the given key,
or
null
if there is no such key.
ClassCastException
- if the specified key can not
be compared with those in the map.NullPointerException
- if the key is null
and this map either uses natural
ordering or a comparator that does
not permit null keys.
navigableKeySet
public NavigableSet navigableKeySet()
Returns a
NavigableSet
view of this map's keys. The set is
backed by the
TreeMap
, so changes in one show up in the other.
Any changes occurring to either while an iteration is taking
place (with the exception of a
Iterator.remove()
operation)
result in undefined behaviour from the iteration. The ordering
The set supports element removal, but not element addition.
- a
NavigableSet
view of the keys.
pollFirstEntry
public Entry pollFirstEntry()
Removes and returns the entry associated with the least
or lowest key in the map, or null
if the map
is empty.
- the removed first entry, or
null
if the
map is empty.
pollLastEntry
public Entry pollLastEntry()
Removes and returns the entry associated with the greatest
or highest key in the map, or null
if the map
is empty.
- the removed last entry, or
null
if the
map is empty.
put
public V put(K key,
V 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.
- put in interface Map<K,V>
- put in interface AbstractMap<K,V>
key
- the key used to locate the valuevalue
- the value to be stored in the Map
- the prior mapping of the key, or null if there was none
putAll
public void putAll(extends K,
V> m)
Copies all elements of the given map into this TreeMap. If this map
already has a mapping for a key, the new mapping replaces the current
one.
- putAll in interface Map<K,V>
- putAll in interface AbstractMap<K,V>
remove
public V remove(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.
- remove in interface Map<K,V>
- remove in interface AbstractMap<K,V>
key
- the key used to locate the value to remove
- whatever the key mapped to, if present
super K> comparator
public Comparator super K> comparator()
Return the comparator used to sort this map, or null if it is by
natural order.
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.
- values in interface Map<K,V>
- values in interface AbstractMap<K,V>
TreeMap.java -- a class providing a basic Red-Black Tree data structure,
mapping Object --> Object
Copyright (C) 1998, 1999, 2000, 2001, 2002, 2004, 2005, 2006 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.