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.