public class

TreeMap

extends AbstractMap<K, V>
implements Serializable Cloneable SortedMap<K, V>
java.lang.Object
   ↳ java.util.AbstractMap<K, V>
     ↳ java.util.TreeMap<K, V>

Class Overview

TreeMap is an implementation of SortedMap. All optional operations (adding and removing) are supported. The values can be any objects. The keys can be any objects which are comparable to each other either using their natural order or a specified Comparator.

Summary

Public Constructors
TreeMap()
Constructs a new empty TreeMap instance.
TreeMap(Comparator<? super K> comparator)
Constructs a new empty TreeMap instance with the specified comparator.
TreeMap(Map<? extends K, ? extends V> map)
Constructs a new TreeMap instance containing the mappings from the specified map and using natural ordering.
TreeMap(SortedMap<K, ? extends V> map)
Constructs a new TreeMap instance containing the mappings from the specified SortedMap and using the same comparator.
Public Methods
void clear()
Removes all mappings from this TreeMap, leaving it empty.
Object clone()
Returns a new TreeMap with the same mappings, size and comparator as this instance.
Comparator<? super K> comparator()
Returns the comparator used to compare elements in this map.
boolean containsKey(Object key)
Returns whether this map contains the specified key.
boolean containsValue(Object value)
Returns whether this map contains the specified value.
Set<Entry<K, V>> entrySet()
Returns a set containing all of the mappings in this map.
K firstKey()
Returns the first key in this map.
V get(Object key)
Returns the value of the mapping with the specified key.
SortedMap<K, V> headMap(K endKey)
Returns a sorted map over a range of this sorted map with all keys that are less than the specified endKey.
Set<K> keySet()
Returns a set of the keys contained in this map.
K lastKey()
Returns the last key in this map.
V put(K key, V value)
Maps the specified key to the specified value.
void putAll(Map<? extends K, ? extends V> map)
Copies all the mappings in the given map to this map.
V remove(Object key)
Removes the mapping with the specified key from this map.
int size()
Returns the number of mappings in this map.
SortedMap<K, V> subMap(K startKey, K endKey)
Returns a sorted map over a range of this sorted map with all keys greater than or equal to the specified startKey and less than the specified endKey.
SortedMap<K, V> tailMap(K startKey)
Returns a sorted map over a range of this sorted map with all keys that are greater than or equal to the specified startKey.
Collection<V> values()
Returns a collection of the values contained in this map.
[Expand]
Inherited Methods
From class java.util.AbstractMap
From class java.lang.Object
From interface java.util.Map
From interface java.util.SortedMap

Public Constructors

public TreeMap ()

Since: API Level 1

Constructs a new empty TreeMap instance.

public TreeMap (Comparator<? super K> comparator)

Since: API Level 1

Constructs a new empty TreeMap instance with the specified comparator.

Parameters
comparator the comparator to compare keys with.

public TreeMap (Map<? extends K, ? extends V> map)

Since: API Level 1

Constructs a new TreeMap instance containing the mappings from the specified map and using natural ordering.

Parameters
map the mappings to add.
Throws
ClassCastException if a key in the specified map does not implement the Comparable interface, or if the keys in the map cannot be compared.

public TreeMap (SortedMap<K, ? extends V> map)

Since: API Level 1

Constructs a new TreeMap instance containing the mappings from the specified SortedMap and using the same comparator.

Parameters
map the mappings to add.

Public Methods

public void clear ()

Since: API Level 1

Removes all mappings from this TreeMap, leaving it empty.

See Also

public Object clone ()

Since: API Level 1

Returns a new TreeMap with the same mappings, size and comparator as this instance.

Returns
  • a shallow copy of this instance.
See Also

public Comparator<? super K> comparator ()

Since: API Level 1

Returns the comparator used to compare elements in this map.

Returns
  • the comparator or null if the natural ordering is used.

public boolean containsKey (Object key)

Since: API Level 1

Returns whether this map contains the specified key.

Parameters
key the key to search for.
Returns
  • true if this map contains the specified key, false otherwise.
Throws
ClassCastException if the specified key cannot be compared with the keys in this map.
NullPointerException if the specified key is null and the comparator cannot handle null keys.

public boolean containsValue (Object value)

Since: API Level 1

Returns whether this map contains the specified value.

Parameters
value the value to search for.
Returns
  • true if this map contains the specified value, false otherwise.

public Set<Entry<K, V>> entrySet ()

Since: API Level 1

Returns a set containing all of the mappings in this map. Each mapping is an instance of Map.Entry. As the set is backed by this map, changes in one will be reflected in the other. It does not support adding operations.

Returns
  • a set of the mappings.

public K firstKey ()

Since: API Level 1

Returns the first key in this map.

Returns
  • the first key in this map.
Throws
NoSuchElementException if this map is empty.

public V get (Object key)

Since: API Level 1

Returns the value of the mapping with the specified key.

Parameters
key the key.
Returns
  • the value of the mapping with the specified key.
Throws
ClassCastException if the key cannot be compared with the keys in this map.
NullPointerException if the key is null and the comparator cannot handle null.

public SortedMap<K, V> headMap (K endKey)

Since: API Level 1

Returns a sorted map over a range of this sorted map with all keys that are less than the specified endKey. Changes to the returned sorted map are reflected in this sorted map and vice versa.

Note: The returned map will not allow an insertion of a key outside the specified range.

Parameters
endKey the high boundary of the range specified.
Returns
  • a sorted map where the keys are less than endKey.
Throws
ClassCastException if the specified key cannot be compared with the keys in this map.
NullPointerException if the specified key is null and the comparator cannot handle null keys.
IllegalArgumentException if this map is itself a sorted map over a range of another map and the specified key is outside of its range.

public Set<K> keySet ()

Since: API Level 1

Returns a set of the keys contained in this map. The set is backed by this map so changes to one are reflected by the other. The set does not support adding.

Returns
  • a set of the keys.

public K lastKey ()

Since: API Level 1

Returns the last key in this map.

Returns
  • the last key in this map.
Throws
NoSuchElementException if this map is empty.

public V put (K key, V value)

Since: API Level 1

Maps the specified key to the specified value.

Parameters
key the key.
value the value.
Returns
  • the value of any previous mapping with the specified key or null if there was no mapping.
Throws
ClassCastException if the specified key cannot be compared with the keys in this map.
NullPointerException if the specified key is null and the comparator cannot handle null keys.

public void putAll (Map<? extends K, ? extends V> map)

Since: API Level 1

Copies all the mappings in the given map to this map. These mappings will replace all mappings that this map had for any of the keys currently in the given map.

Parameters
map the map to copy mappings from.
Throws
ClassCastException if a key in the specified map cannot be compared with the keys in this map.
NullPointerException if a key in the specified map is null and the comparator cannot handle null keys.

public V remove (Object key)

Since: API Level 1

Removes the mapping with the specified key from this map.

Parameters
key the key of the mapping to remove.
Returns
  • the value of the removed mapping or null if no mapping for the specified key was found.
Throws
ClassCastException if the specified key cannot be compared with the keys in this map.
NullPointerException if the specified key is null and the comparator cannot handle null keys.

public int size ()

Since: API Level 1

Returns the number of mappings in this map.

Returns
  • the number of mappings in this map.

public SortedMap<K, V> subMap (K startKey, K endKey)

Since: API Level 1

Returns a sorted map over a range of this sorted map with all keys greater than or equal to the specified startKey and less than the specified endKey. Changes to the returned sorted map are reflected in this sorted map and vice versa.

Note: The returned map will not allow an insertion of a key outside the specified range.

Parameters
startKey the low boundary of the range (inclusive).
endKey the high boundary of the range (exclusive),
Returns
  • a sorted map with the key from the specified range.
Throws
ClassCastException if the start or end key cannot be compared with the keys in this map.
NullPointerException if the start or end key is null and the comparator cannot handle null keys.
IllegalArgumentException if the start key is greater than the end key, or if this map is itself a sorted map over a range of another sorted map and the specified range is outside of its range.

public SortedMap<K, V> tailMap (K startKey)

Since: API Level 1

Returns a sorted map over a range of this sorted map with all keys that are greater than or equal to the specified startKey. Changes to the returned sorted map are reflected in this sorted map and vice versa.

Note: The returned map will not allow an insertion of a key outside the specified range.

Parameters
startKey the low boundary of the range specified.
Returns
  • a sorted map where the keys are greater or equal to startKey.
Throws
ClassCastException if the specified key cannot be compared with the keys in this map.
NullPointerException if the specified key is null and the comparator cannot handle null keys.
IllegalArgumentException if this map itself a sorted map over a range of another map and the specified key is outside of its range.

public Collection<V> values ()

Since: API Level 1

Returns a collection of the values contained in this map. The collection is backed by this map so changes to one are reflected by the other. The collection supports remove, removeAll, retainAll and clear operations, and it does not support add or addAll operations.

This method returns a collection which is the subclass of AbstractCollection. The iterator method of this subclass returns a "wrapper object" over the iterator of map's entrySet(). The size method wraps the map's size method and the contains method wraps the map's containsValue method.

The collection is created when this method is called for the first time and returned in response to all subsequent calls. This method may return different collections when multiple concurrent calls occur, since no synchronization is performed.

Returns
  • a collection of the values contained in this map.