## com.google.common.collect
Class ImmutableSortedMap<K,V>

    java.lang.Object
      com.google.common.collect.ImmutableMap<K,V>
          com.google.common.collect.ImmutableSortedMap<K,V>

All Implemented Interfaces:
  Serializable, Map<K,V>, NavigableMap<K,V>, SortedMap<K,V>

    @GwtCompatible(serializable=true,
                   emulated=true)
    public abstract class ImmutableSortedMap<K,V>

extends ImmutableMap<K,V>
implements NavigableMap<K,V>

An immutable `SortedMap`. Does not permit null keys or values.

Unlike `Collections.unmodifiableSortedMap(java.util.SortedMap<K, ? extends V>)`, which is a view of a separate map which can still change, an instance of `ImmutableSortedMap` contains its own data and will never change. `ImmutableSortedMap` is convenient for `public static final` maps ("constant maps") and also lets you easily make a "defensive copy" of a map provided to your class by a caller.

Note: Although this class is not final, it cannot be subclassed as it has no public or protected constructors. Thus, instances of this class are guaranteed to be immutable.

See the Guava User Guide article on immutable collections.

Since:
  2.0 (imported from Google Collections Library; implements `NavigableMap` since 12.0)
Author:
  Jared Levy, Louis Wasserman
See Also:
  Serialized Form

Nested Class Summary
`static class` `ImmutableSortedMap.Builder<K,V>` A builder for creating immutable sorted map instances, especially `public static final` maps ("constant maps").

Nested classes/interfaces inherited from interface java.util.Map
`Map.Entry<K,V>`

Method Summary

`static

`<K,V> ImmutableSortedMap.Builder<K,V>`

`

`builder()`
Deprecated. Use `naturalOrder()`, which offers better type-safety.

`Map.Entry<K,V>` `ceilingEntry(K key)`
`K` `ceilingKey(K key)`
`Comparator<? super K>` `comparator()` Returns the comparator that orders the keys, which is `Ordering.natural()` when the natural ordering of the keys is used.
`boolean` `containsValue(Object value)`

`static

`<K,V> ImmutableSortedMap<K,V>`

`

`copyOf(Map<? extends K,? extends V> map)`
Returns an immutable map containing the same entries as `map`, sorted by the natural ordering of the keys.

`static

`<K,V> ImmutableSortedMap<K,V>`

`

`copyOf(Map<? extends K,? extends V> map, Comparator<? super K> comparator)`
Returns an immutable map containing the same entries as `map`, with keys sorted by the provided comparator.

`static

`<K,V> ImmutableSortedMap<K,V>`

`

`copyOfSorted(SortedMap<K,? extends V> map)`
Returns an immutable map containing the same entries as the provided sorted map, with the same ordering.

`ImmutableSortedSet<K>` `descendingKeySet()`
`ImmutableSortedMap<K,V>` `descendingMap()`
`ImmutableSet<Map.Entry<K,V>>` `entrySet()` Returns an immutable set of the mappings in this map, sorted by the key ordering.
`Map.Entry<K,V>` `firstEntry()`
`K` `firstKey()`
`Map.Entry<K,V>` `floorEntry(K key)`
`K` `floorKey(K key)`
`ImmutableSortedMap<K,V>` `headMap(K toKey)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than `toKey`.
`abstract ImmutableSortedMap<K,V>` `headMap(K toKey, boolean inclusive)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than (or equal to, if `inclusive`) `toKey`.
`Map.Entry<K,V>` `higherEntry(K key)`
`K` `higherKey(K key)`
`abstract ImmutableSortedSet<K>` `keySet()` Returns an immutable sorted set of the keys in this map.
`Map.Entry<K,V>` `lastEntry()`
`K` `lastKey()`
`Map.Entry<K,V>` `lowerEntry(K key)`
`K` `lowerKey(K key)`

`static

`<K extends Comparable<K>,V> ImmutableSortedMap.Builder<K,V>`

`

`naturalOrder()`
Returns a builder that creates immutable sorted maps whose keys are ordered by their natural ordering.

`ImmutableSortedSet<K>` `navigableKeySet()`

`static

`<K,V> ImmutableSortedMap<K,V>`

`

`of()`
Returns the empty sorted map.

`static

`<K extends Comparable<? super K>,V> ImmutableSortedMap<K,V>`

`

`of(K k1, V v1)`
Returns an immutable map containing a single entry.

`static

`<K extends Comparable<? super K>,V> ImmutableSortedMap<K,V>`

`

`of(K k1, V v1, K k2, V v2)`
Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

`static

`<K extends Comparable<? super K>,V> ImmutableSortedMap<K,V>`

`

`of(K k1, V v1, K k2, V v2, K k3, V v3)`
Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

`static

`<K extends Comparable<? super K>,V> ImmutableSortedMap<K,V>`

`

`of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)`
Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

`static

`<K extends Comparable<? super K>,V> ImmutableSortedMap<K,V>`

`

`of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)`
Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

`static

`<K,V> ImmutableSortedMap.Builder<K,V>`

`

`orderedBy(Comparator<K> comparator)`
Returns a builder that creates immutable sorted maps with an explicit comparator.

`Map.Entry<K,V>` `pollFirstEntry()`
`Map.Entry<K,V>` `pollLastEntry()`

`static

`<K extends Comparable<K>,V> ImmutableSortedMap.Builder<K,V>`

`

`reverseOrder()`
Returns a builder that creates immutable sorted maps whose keys are ordered by the reverse of their natural ordering.

`int` `size()`
`ImmutableSortedMap<K,V>` `subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys ranges from `fromKey` to `toKey`, inclusive or exclusive as indicated by the boolean flags.
`ImmutableSortedMap<K,V>` `subMap(K fromKey, K toKey)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys ranges from `fromKey`, inclusive, to `toKey`, exclusive.
`ImmutableSortedMap<K,V>` `tailMap(K fromKey)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are greater than or equals to `fromKey`.
`abstract ImmutableSortedMap<K,V>` `tailMap(K fromKey, boolean inclusive)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are greater than (or equal to, if `inclusive`) `fromKey`.
`abstract ImmutableCollection<V>` `values()` Returns an immutable collection of the values in this map, sorted by the ordering of the corresponding keys.

Methods inherited from class com.google.common.collect.ImmutableMap
`clear, containsKey, equals, get, hashCode, isEmpty, put, putAll, remove, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.util.Map
`clear, containsKey, equals, get, hashCode, isEmpty, put, putAll, remove`

Method Detail

### of

    public static <K,V> ImmutableSortedMap<K,V> of()

  Returns the empty sorted map.

### of

    public static <K extends Comparable<? super K>,V> ImmutableSortedMap<K,V> of(K k1,
                                                                                 V v1)

  Returns an immutable map containing a single entry.

### of

    public static <K extends Comparable<? super K>,V> ImmutableSortedMap<K,V> of(K k1,
                                                                                 V v1,
                                                                                 K k2,
                                                                                 V v2)

  Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

  Throws:
    `IllegalArgumentException` - if the two keys are equal according to their natural ordering

### of

    public static <K extends Comparable<? super K>,V> ImmutableSortedMap<K,V> of(K k1,
                                                                                 V v1,
                                                                                 K k2,
                                                                                 V v2,
                                                                                 K k3,
                                                                                 V v3)

  Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

  Throws:
    `IllegalArgumentException` - if any two keys are equal according to their natural ordering

### of

    public static <K extends Comparable<? super K>,V> ImmutableSortedMap<K,V> of(K k1,
                                                                                 V v1,
                                                                                 K k2,
                                                                                 V v2,
                                                                                 K k3,
                                                                                 V v3,
                                                                                 K k4,
                                                                                 V v4)

  Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

  Throws:
    `IllegalArgumentException` - if any two keys are equal according to their natural ordering

### of

    public static <K extends Comparable<? super K>,V> ImmutableSortedMap<K,V> of(K k1,
                                                                                 V v1,
                                                                                 K k2,
                                                                                 V v2,
                                                                                 K k3,
                                                                                 V v3,
                                                                                 K k4,
                                                                                 V v4,
                                                                                 K k5,
                                                                                 V v5)

  Returns an immutable sorted map containing the given entries, sorted by the natural ordering of their keys.

  Throws:
    `IllegalArgumentException` - if any two keys are equal according to their natural ordering

### copyOf

    public static <K,V> ImmutableSortedMap<K,V> copyOf(Map<? extends K,? extends V> map)

  Returns an immutable map containing the same entries as `map`, sorted by the natural ordering of the keys.

  Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

  This method is not type-safe, as it may be called on a map with keys that are not mutually comparable.

  Throws:
    `ClassCastException` - if the keys in `map` are not mutually comparable
    `NullPointerException` - if any key or value in `map` is null
    `IllegalArgumentException` - if any two keys are equal according to their natural ordering

### copyOf

    public static <K,V> ImmutableSortedMap<K,V> copyOf(Map<? extends K,? extends V> map,
                                                       Comparator<? super K> comparator)

  Returns an immutable map containing the same entries as `map`, with keys sorted by the provided comparator.

  Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

  Throws:
    `NullPointerException` - if any key or value in `map` is null
    `IllegalArgumentException` - if any two keys are equal according to the comparator

### copyOfSorted

    public static <K,V> ImmutableSortedMap<K,V> copyOfSorted(SortedMap<K,? extends V> map)

  Returns an immutable map containing the same entries as the provided sorted map, with the same ordering.

  Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.

  Throws:
    `NullPointerException` - if any key or value in `map` is null

### naturalOrder

    public static <K extends Comparable<K>,V> ImmutableSortedMap.Builder<K,V> naturalOrder()

  Returns a builder that creates immutable sorted maps whose keys are ordered by their natural ordering. The sorted maps use `Ordering.natural()` as the comparator.

  Note: the type parameter `K` extends `Comparable<K>` rather than `Comparable<? super K>` as a workaround for javac bug 6468354.

### orderedBy

    public static <K,V> ImmutableSortedMap.Builder<K,V> orderedBy(Comparator<K> comparator)

  Returns a builder that creates immutable sorted maps with an explicit comparator. If the comparator has a more general type than the map's keys, such as creating a `SortedMap<Integer, String>` with a `Comparator<Number>`, use the `ImmutableSortedMap.Builder` constructor instead.

  Throws:
    `NullPointerException` - if `comparator` is null

### reverseOrder

    public static <K extends Comparable<K>,V> ImmutableSortedMap.Builder<K,V> reverseOrder()

  Returns a builder that creates immutable sorted maps whose keys are ordered by the reverse of their natural ordering.

  Note: the type parameter `K` extends `Comparable<K>` rather than `Comparable<? super K>` as a workaround for javac bug 6468354.

### size

    public int size()

  Specified by:
    `size` in interface `Map<K,V>`

### containsValue

    public boolean containsValue(@Nullable
                                 Object value)

  Specified by:
    `containsValue` in interface `Map<K,V>`
  Overrides:
    `containsValue` in class `ImmutableMap<K,V>`

### entrySet

    public ImmutableSet<Map.Entry<K,V>> entrySet()

  Returns an immutable set of the mappings in this map, sorted by the key ordering.

  Specified by:
    `entrySet` in interface `Map<K,V>`
  Specified by:
    `entrySet` in interface `SortedMap<K,V>`
  Overrides:
    `entrySet` in class `ImmutableMap<K,V>`

### keySet

    public abstract ImmutableSortedSet<K> keySet()

  Returns an immutable sorted set of the keys in this map.

  Specified by:
    `keySet` in interface `Map<K,V>`
  Specified by:
    `keySet` in interface `SortedMap<K,V>`
  Overrides:
    `keySet` in class `ImmutableMap<K,V>`

### values

    public abstract ImmutableCollection<V> values()

  Returns an immutable collection of the values in this map, sorted by the ordering of the corresponding keys.

  Specified by:
    `values` in interface `Map<K,V>`
  Specified by:
    `values` in interface `SortedMap<K,V>`
  Overrides:
    `values` in class `ImmutableMap<K,V>`

### comparator

    public Comparator<? super K> comparator()

  Returns the comparator that orders the keys, which is `Ordering.natural()` when the natural ordering of the keys is used. Note that its behavior is not consistent with `TreeMap.comparator()`, which returns `null` to indicate natural ordering.

  Specified by:
    `comparator` in interface `SortedMap<K,V>`

### firstKey

    public K firstKey()

  Specified by:
    `firstKey` in interface `SortedMap<K,V>`

### lastKey

    public K lastKey()

  Specified by:
    `lastKey` in interface `SortedMap<K,V>`

### headMap

    public ImmutableSortedMap<K,V> headMap(K toKey)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than `toKey`.

  The `SortedMap.headMap(K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `toKey` greater than an earlier `toKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `toKey`.

  Specified by:
    `headMap` in interface `NavigableMap<K,V>`
  Specified by:
    `headMap` in interface `SortedMap<K,V>`

### headMap

    public abstract ImmutableSortedMap<K,V> headMap(K toKey,
                                                    boolean inclusive)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than (or equal to, if `inclusive`) `toKey`.

  The `SortedMap.headMap(K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `toKey` greater than an earlier `toKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `toKey`.

  Specified by:
    `headMap` in interface `NavigableMap<K,V>`
  Since:
    12.0

### subMap

    public ImmutableSortedMap<K,V> subMap(K fromKey,
                                          K toKey)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys ranges from `fromKey`, inclusive, to `toKey`, exclusive.

  The `SortedMap.subMap(K, K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `fromKey` less than an earlier `fromKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `fromKey`. Similarly, this method keeps the original `toKey`, instead of throwing an exception, if passed a `toKey` greater than an earlier `toKey`.

  Specified by:
    `subMap` in interface `NavigableMap<K,V>`
  Specified by:
    `subMap` in interface `SortedMap<K,V>`

### subMap

    public ImmutableSortedMap<K,V> subMap(K fromKey,
                                          boolean fromInclusive,
                                          K toKey,
                                          boolean toInclusive)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys ranges from `fromKey` to `toKey`, inclusive or exclusive as indicated by the boolean flags.

  The `SortedMap.subMap(K, K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `fromKey` less than an earlier `fromKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `fromKey`. Similarly, this method keeps the original `toKey`, instead of throwing an exception, if passed a `toKey` greater than an earlier `toKey`.

  Specified by:
    `subMap` in interface `NavigableMap<K,V>`
  Since:
    12.0

### tailMap

    public ImmutableSortedMap<K,V> tailMap(K fromKey)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are greater than or equals to `fromKey`.

  The `SortedMap.tailMap(K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `fromKey` less than an earlier `fromKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `fromKey`.

  Specified by:
    `tailMap` in interface `NavigableMap<K,V>`
  Specified by:
    `tailMap` in interface `SortedMap<K,V>`

### tailMap

    public abstract ImmutableSortedMap<K,V> tailMap(K fromKey,
                                                    boolean inclusive)

  This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are greater than (or equal to, if `inclusive`) `fromKey`.

  The `SortedMap.tailMap(K)` documentation states that a submap of a submap throws an `IllegalArgumentException` if passed a `fromKey` less than an earlier `fromKey`. However, this method doesn't throw an exception in that situation, but instead keeps the original `fromKey`.

  Specified by:
    `tailMap` in interface `NavigableMap<K,V>`
  Since:
    12.0

### lowerEntry

    public Map.Entry<K,V> lowerEntry(K key)

  Specified by:
    `lowerEntry` in interface `NavigableMap<K,V>`

### lowerKey

    public K lowerKey(K key)

  Specified by:
    `lowerKey` in interface `NavigableMap<K,V>`

### floorEntry

    public Map.Entry<K,V> floorEntry(K key)

  Specified by:
    `floorEntry` in interface `NavigableMap<K,V>`

### floorKey

    public K floorKey(K key)

  Specified by:
    `floorKey` in interface `NavigableMap<K,V>`

### ceilingEntry

    public Map.Entry<K,V> ceilingEntry(K key)

  Specified by:
    `ceilingEntry` in interface `NavigableMap<K,V>`

### ceilingKey

    public K ceilingKey(K key)

  Specified by:
    `ceilingKey` in interface `NavigableMap<K,V>`

### higherEntry

    public Map.Entry<K,V> higherEntry(K key)

  Specified by:
    `higherEntry` in interface `NavigableMap<K,V>`

### higherKey

    public K higherKey(K key)

  Specified by:
    `higherKey` in interface `NavigableMap<K,V>`

### firstEntry

    public Map.Entry<K,V> firstEntry()

  Specified by:
    `firstEntry` in interface `NavigableMap<K,V>`

### lastEntry

    public Map.Entry<K,V> lastEntry()

  Specified by:
    `lastEntry` in interface `NavigableMap<K,V>`

### pollFirstEntry

    public final Map.Entry<K,V> pollFirstEntry()

  Specified by:
    `pollFirstEntry` in interface `NavigableMap<K,V>`

### pollLastEntry

    public final Map.Entry<K,V> pollLastEntry()

  Specified by:
    `pollLastEntry` in interface `NavigableMap<K,V>`

### descendingMap

    public ImmutableSortedMap<K,V> descendingMap()

  Specified by:
    `descendingMap` in interface `NavigableMap<K,V>`

### navigableKeySet

    public ImmutableSortedSet<K> navigableKeySet()

  Specified by:
    `navigableKeySet` in interface `NavigableMap<K,V>`

### descendingKeySet

    public ImmutableSortedSet<K> descendingKeySet()

  Specified by:
    `descendingKeySet` in interface `NavigableMap<K,V>`

### builder

    @Deprecated
    public static <K,V> ImmutableSortedMap.Builder<K,V> builder()

  Deprecated. Use `naturalOrder()`, which offers better type-safety.

  Not supported. Use `naturalOrder()`, which offers better type-safety, instead. This method exists only to hide `ImmutableMap.builder()` from consumers of `ImmutableSortedMap`.

  Throws:
    `UnsupportedOperationException` - always

Copyright © 2010-2012. All Rights Reserved.