Skip to content

Most visited

Recently visited

navigation
Added in API level 1

TreeMap

public class TreeMap
extends AbstractMap<K, V> implements SortedMap<K, V>, NavigableMap<K, V>, Cloneable, Serializable

java.lang.Object
   ↳ java.util.AbstractMap<K, V>
     ↳ java.util.TreeMap<K, V>


A map whose entries are sorted by their keys. All optional operations such as put(K, V) and remove(Object) are supported.

This map sorts keys using either a user-supplied comparator or the key's natural order:

With either a comparator or a natural ordering, comparisons should be consistent with equals. An ordering is consistent with equals if for every pair of keys a and b, a.equals(b) if and only if compare(a, b) == 0.

When the ordering is not consistent with equals the behavior of this class is well defined but does not honor the contract specified by Map. Consider a tree map of case-insensitive strings, an ordering that is not consistent with equals:

   TreeMap map = new TreeMap(String.CASE_INSENSITIVE_ORDER);
   map.put("a", "android");

   // The Map API specifies that the next line should print "null" because
   // "a".equals("A") is false and there is no mapping for upper case "A".
   // But the case insensitive ordering says compare("a", "A") == 0. TreeMap
   // uses only comparators/comparable on keys and so this prints "android".
   System.out.println(map.get("A"));
 

Summary

Public constructors

TreeMap()

Create a natural order, empty tree map whose keys must be mutually comparable and non-null.

TreeMap(Map<? extends K, ? extends V> copyFrom)

Create a natural order tree map populated with the key/value pairs of copyFrom.

TreeMap(Comparator<? super K> comparator)

Create a tree map ordered by comparator.

TreeMap(SortedMap<K, ? extends V> copyFrom)

Create a tree map with the ordering and key/value pairs of copyFrom.

Public methods

Entry<K, V> ceilingEntry(K key)

Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such key.

K ceilingKey(K key)

Returns the least key greater than or equal to the given key, or null if there is no such key.

void clear()

Removes all elements from this Map, leaving it empty.

This implementation calls entrySet().clear().

Object clone()

Creates and returns a copy of this Object.

Comparator<? super K> comparator()

Returns the comparator used to compare keys in this sorted map, or null if the natural ordering is in use.

boolean containsKey(Object key)

Returns whether this Map contains the specified key.

This implementation iterates its key set, looking for a key that key equals.

NavigableSet<K> descendingKeySet()

Returns a reverse order NavigableSet view of the keys contained in this map.

NavigableMap<K, V> descendingMap()

Returns a reverse order view of the mappings contained in this map.

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

Returns a Set containing all of the mappings in this Map.

Entry<K, V> firstEntry()

Returns a key-value mapping associated with the least key in this map, or null if the map is empty.

K firstKey()

Returns the least key in this sorted map.

Entry<K, V> floorEntry(K key)

Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such key.

K floorKey(K key)

Returns the greatest key less than or equal to the given key, or null if there is no such key.

V get(Object key)

Returns the value of the mapping with the specified key.

This implementation iterates its entry set, looking for an entry with a key that key equals.

NavigableMap<K, V> headMap(K to, boolean inclusive)

Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey.

SortedMap<K, V> headMap(K toExclusive)

Returns a sorted map over a range of this sorted map with all keys that are less than the specified endKey.

Equivalent to headMap(toKey, false).

Entry<K, V> higherEntry(K key)

Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such key.

K higherKey(K key)

Returns the least key strictly greater than the given key, or null if there is no such key.

boolean isEmpty()

Returns whether this map is empty.

This implementation compares size() to 0.

Set<K> keySet()

Returns a set of the keys contained in this Map.

This implementation returns a view that calls through this to map.

Entry<K, V> lastEntry()

Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

K lastKey()

Returns the greatest key in this sorted map.

Entry<K, V> lowerEntry(K key)

Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such key.

K lowerKey(K key)

Returns the greatest key strictly less than the given key, or null if there is no such key.

NavigableSet<K> navigableKeySet()

Returns a NavigableSet view of the keys contained in this map.

Entry<K, V> pollFirstEntry()

Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.

Entry<K, V> pollLastEntry()

Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

V put(K key, V value)

Maps the specified key to the specified value.

This base implementation throws UnsupportedOperationException.

V remove(Object key)

Removes a mapping with the specified key from this Map.

This implementation iterates its entry set, removing the entry with a key that key equals.

int size()

Returns the number of mappings in this Map.

This implementation returns its entry set's size.

SortedMap<K, V> subMap(K fromInclusive, K toExclusive)

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.

Equivalent to subMap(fromKey, true, toKey, false).

NavigableMap<K, V> subMap(K from, boolean fromInclusive, K to, boolean toInclusive)

Returns a view of the portion of this map whose keys range from fromKey to toKey.

NavigableMap<K, V> tailMap(K from, boolean inclusive)

Returns a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey.

SortedMap<K, V> tailMap(K fromInclusive)

Returns a sorted map over a range of this sorted map with all keys that are greater than or equal to the specified startKey.

Equivalent to tailMap(fromKey, true).

Inherited methods

From class java.util.AbstractMap
From class java.lang.Object
From interface java.util.Map
From interface java.util.SortedMap
From interface java.util.NavigableMap

Public constructors

TreeMap

Added in API level 1
TreeMap ()

Create a natural order, empty tree map whose keys must be mutually comparable and non-null.

TreeMap

Added in API level 1
TreeMap (Map<? extends K, ? extends V> copyFrom)

Create a natural order tree map populated with the key/value pairs of copyFrom. This map's keys must be mutually comparable and non-null.

Even if copyFrom is a SortedMap, the constructed map will not use copyFrom's ordering. This constructor always creates a naturally-ordered map. Because the TreeMap constructor overloads are ambiguous, prefer to construct a map and populate it in two steps:

   TreeMap customOrderedMap
       = new TreeMap(copyFrom.comparator());
   customOrderedMap.putAll(copyFrom);
 

Parameters
copyFrom Map

TreeMap

Added in API level 1
TreeMap (Comparator<? super K> comparator)

Create a tree map ordered by comparator. This map's keys may only be null if comparator permits.

Parameters
comparator Comparator: the comparator to order elements with, or null to use the natural ordering.

TreeMap

Added in API level 1
TreeMap (SortedMap<K, ? extends V> copyFrom)

Create a tree map with the ordering and key/value pairs of copyFrom. This map's keys may only be null if the copyFrom's ordering permits.

The constructed map will always use copyFrom's ordering. Because the TreeMap constructor overloads are ambiguous, prefer to construct a map and populate it in two steps:

   TreeMap customOrderedMap
       = new TreeMap(copyFrom.comparator());
   customOrderedMap.putAll(copyFrom);
 

Parameters
copyFrom SortedMap

Public methods

ceilingEntry

Added in API level 9
Entry<K, V> ceilingEntry (K key)

Returns a key-value mapping associated with the least key greater than or equal to the given key, or null if there is no such key.

Parameters
key K: the key
Returns
Entry<K, V> an entry with the least key greater than or equal to key, or null if there is no such key

ceilingKey

Added in API level 9
K ceilingKey (K key)

Returns the least key greater than or equal to the given key, or null if there is no such key.

Parameters
key K: the key
Returns
K the least key greater than or equal to key, or null if there is no such key

clear

Added in API level 1
void clear ()

Removes all elements from this Map, leaving it empty.

This implementation calls entrySet().clear().

clone

Added in API level 1
Object clone ()

Creates and returns a copy of this Object. The default implementation returns a so-called "shallow" copy: It creates a new instance of the same class and then copies the field values (including object references) from this instance to the new instance. A "deep" copy, in contrast, would also recursively clone nested objects. A subclass that needs to implement this kind of cloning should call super.clone() to create the new instance and then create deep copies of the nested, mutable objects.

Returns
Object a copy of this object.

comparator

Added in API level 1
Comparator<? super K> comparator ()

Returns the comparator used to compare keys in this sorted map, or null if the natural ordering is in use.

Returns
Comparator<? super K>

containsKey

Added in API level 1
boolean containsKey (Object key)

Returns whether this Map contains the specified key.

This implementation iterates its key set, looking for a key that key equals.

Parameters
key Object: the key to search for.
Returns
boolean true if this map contains the specified key, false otherwise.

descendingKeySet

Added in API level 9
NavigableSet<K> descendingKeySet ()

Returns a reverse order NavigableSet view of the keys contained in this map. The set's iterator returns the keys in descending order. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns
NavigableSet<K> a reverse order navigable set view of the keys in this map

descendingMap

Added in API level 9
NavigableMap<K, V> descendingMap ()

Returns a reverse order view of the mappings contained in this map. The descending map is backed by this map, so changes to the map are reflected in the descending map, and vice-versa. If either map is modified while an iteration over a collection view of either map is in progress (except through the iterator's own remove operation), the results of the iteration are undefined.

The returned map has an ordering equivalent to Collections.reverseOrder(comparator()). The expression m.descendingMap().descendingMap() returns a view of m essentially equivalent to m.

Returns
NavigableMap<K, V> a reverse order view of this map

entrySet

Added in API level 1
Set<Entry<K, V>> entrySet ()

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.

Returns
Set<Entry<K, V>> a set of the mappings

firstEntry

Added in API level 9
Entry<K, V> firstEntry ()

Returns a key-value mapping associated with the least key in this map, or null if the map is empty.

Returns
Entry<K, V>

firstKey

Added in API level 1
K firstKey ()

Returns the least key in this sorted map.

Returns
K

floorEntry

Added in API level 9
Entry<K, V> floorEntry (K key)

Returns a key-value mapping associated with the greatest key less than or equal to the given key, or null if there is no such key.

Parameters
key K: the key
Returns
Entry<K, V> an entry with the greatest key less than or equal to key, or null if there is no such key

floorKey

Added in API level 9
K floorKey (K key)

Returns the greatest key less than or equal to the given key, or null if there is no such key.

Parameters
key K: the key
Returns
K the greatest key less than or equal to key, or null if there is no such key

get

Added in API level 1
V get (Object key)

Returns the value of the mapping with the specified key.

This implementation iterates its entry set, looking for an entry with a key that key equals.

Parameters
key Object: the key.
Returns
V the value of the mapping with the specified key, or null if no mapping for the specified key is found.

headMap

Added in API level 9
NavigableMap<K, V> headMap (K to, 
                boolean inclusive)

Returns a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey. The returned map is backed by this map, so changes in the returned map are reflected in this map, and vice-versa. The returned map supports all optional map operations that this map supports.

The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.

Parameters
to K: high endpoint of the keys in the returned map
inclusive boolean: true if the high endpoint is to be included in the returned view
Returns
NavigableMap<K, V> a view of the portion of this map whose keys are less than (or equal to, if inclusive is true) toKey

headMap

Added in API level 1
SortedMap<K, V> headMap (K toExclusive)

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.

Equivalent to headMap(toKey, false).

Parameters
toExclusive K: the high boundary of the range specified.
Returns
SortedMap<K, V> a sorted map where the keys are less than endKey.

higherEntry

Added in API level 9
Entry<K, V> higherEntry (K key)

Returns a key-value mapping associated with the least key strictly greater than the given key, or null if there is no such key.

Parameters
key K: the key
Returns
Entry<K, V> an entry with the least key greater than key, or null if there is no such key

higherKey

Added in API level 9
K higherKey (K key)

Returns the least key strictly greater than the given key, or null if there is no such key.

Parameters
key K: the key
Returns
K the least key greater than key, or null if there is no such key

isEmpty

Added in API level 1
boolean isEmpty ()

Returns whether this map is empty.

This implementation compares size() to 0.

Returns
boolean true if this map has no elements, false otherwise.

keySet

Added in API level 1
Set<K> keySet ()

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.

This implementation returns a view that calls through this to map. Its iterator transforms this map's entry set iterator to return keys.

Returns
Set<K> a set of the keys.

lastEntry

Added in API level 9
Entry<K, V> lastEntry ()

Returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

Returns
Entry<K, V>

lastKey

Added in API level 1
K lastKey ()

Returns the greatest key in this sorted map.

Returns
K

lowerEntry

Added in API level 9
Entry<K, V> lowerEntry (K key)

Returns a key-value mapping associated with the greatest key strictly less than the given key, or null if there is no such key.

Parameters
key K: the key
Returns
Entry<K, V> an entry with the greatest key less than key, or null if there is no such key

lowerKey

Added in API level 9
K lowerKey (K key)

Returns the greatest key strictly less than the given key, or null if there is no such key.

Parameters
key K: the key
Returns
K the greatest key less than key, or null if there is no such key

navigableKeySet

Added in API level 9
NavigableSet<K> navigableKeySet ()

Returns a NavigableSet view of the keys contained in this map. The set's iterator returns the keys in ascending order. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress (except through the iterator's own remove operation), the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. It does not support the add or addAll operations.

Returns
NavigableSet<K> a navigable set view of the keys in this map

pollFirstEntry

Added in API level 9
Entry<K, V> pollFirstEntry ()

Removes and returns a key-value mapping associated with the least key in this map, or null if the map is empty.

Returns
Entry<K, V> the removed first entry of this map, or null if this map is empty

pollLastEntry

Added in API level 9
Entry<K, V> pollLastEntry ()

Removes and returns a key-value mapping associated with the greatest key in this map, or null if the map is empty.

Returns
Entry<K, V> the removed last entry of this map, or null if this map is empty

put

Added in API level 1
V put (K key, 
                V value)

Maps the specified key to the specified value.

This base implementation throws UnsupportedOperationException.

Parameters
key K: the key.
value V: the value.
Returns
V the value of any previous mapping with the specified key or null if there was no mapping.

remove

Added in API level 1
V remove (Object key)

Removes a mapping with the specified key from this Map.

This implementation iterates its entry set, removing the entry with a key that key equals.

Parameters
key Object: the key of the mapping to remove.
Returns
V the value of the removed mapping or null if no mapping for the specified key was found.

size

Added in API level 1
int size ()

Returns the number of mappings in this Map.

This implementation returns its entry set's size.

Returns
int the number of mappings in this Map.

subMap

Added in API level 1
SortedMap<K, V> subMap (K fromInclusive, 
                K toExclusive)

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.

Equivalent to subMap(fromKey, true, toKey, false).

Parameters
fromInclusive K: the low boundary of the range (inclusive).
toExclusive K: the high boundary of the range (exclusive),
Returns
SortedMap<K, V> a sorted map with the key from the specified range.

subMap

Added in API level 9
NavigableMap<K, V> subMap (K from, 
                boolean fromInclusive, 
                K to, 
                boolean toInclusive)

Returns a view of the portion of this map whose keys range from fromKey to toKey. If fromKey and toKey are equal, the returned map is empty unless fromExclusive and toExclusive are both true. The returned map is backed by this map, so changes in the returned map are reflected in this map, and vice-versa. The returned map supports all optional map operations that this map supports.

The returned map will throw an IllegalArgumentException on an attempt to insert a key outside of its range, or to construct a submap either of whose endpoints lie outside its range.

Parameters
from K: low endpoint of the keys in the returned map
fromInclusive boolean: true if the low endpoint is to be included in the returned view
to K: high endpoint of the keys in the returned map
toInclusive boolean: true if the high endpoint is to be included in the returned view
Returns
NavigableMap<K, V> a view of the portion of this map whose keys range from fromKey to toKey

tailMap

Added in API level 9
NavigableMap<K, V> tailMap (K from, 
                boolean inclusive)

Returns a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey. The returned map is backed by this map, so changes in the returned map are reflected in this map, and vice-versa. The returned map supports all optional map operations that this map supports.

The returned map will throw an IllegalArgumentException on an attempt to insert a key outside its range.

Parameters
from K: low endpoint of the keys in the returned map
inclusive boolean: true if the low endpoint is to be included in the returned view
Returns
NavigableMap<K, V> a view of the portion of this map whose keys are greater than (or equal to, if inclusive is true) fromKey

tailMap

Added in API level 1
SortedMap<K, V> tailMap (K fromInclusive)

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.

Equivalent to tailMap(fromKey, true).

Parameters
fromInclusive K: the low boundary of the range specified.
Returns
SortedMap<K, V> a sorted map where the keys are greater or equal to startKey.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.