ImmutableSortedMap
Date: 2016-05-24

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:
    java.io.Serializable, java.util.Map<K,V>, java.util.NavigableMap<K,V>, java.util.SortedMap<K,V>

      @GwtCompatible(serializable=true,
                     emulated=true)
      public final class ImmutableSortedMap<K,V>
      extends ImmutableMap<K,V>
      implements java.util.NavigableMap<K,V>

  A `NavigableMap` whose contents will never change, with many other important properties detailed at `ImmutableCollection`.

  Warning: as with any sorted collection, you are strongly advised not to use a `Comparator` or `Comparable` type whose comparison behavior is inconsistent with equals. That is, `a.compareTo(b)` or `comparator.compare(a, b)` should equal zero if and only if `a.equals(b)`. If this advice is not followed, the resulting map will not correctly obey its specification.

  See the Guava User Guide article on immutable collections.

  Since:
    2.0 (implements `NavigableMap` since 12.0)
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `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

      `java.util.Map.Entry<K,V>`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K,V> ImmutableSortedMap.Builder<K,V>` | `builder()` Deprecated. Use `naturalOrder()`, which offers better type-safety.
    `java.util.Map.Entry<K,V>` | `ceilingEntry(K key)`
    `K` | `ceilingKey(K key)`
    `java.util.Comparator<? super K>` | `comparator()` Returns the comparator that orders the keys, which is `Ordering.natural()` when the natural ordering of the keys is used.
    `static <K,V> ImmutableSortedMap<K,V>` | `copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)` Returns an immutable map containing the given entries, with keys sorted by the provided comparator.
    `static <K,V> ImmutableSortedMap<K,V>` | `copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries, java.util.Comparator<? super K> comparator)` Returns an immutable map containing the given entries, with keys sorted by the provided comparator.
    `static <K,V> ImmutableSortedMap<K,V>` | `copyOf(java.util.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(java.util.Map<? extends K,? extends V> map, java.util.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(java.util.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<java.util.Map.Entry<K,V>>` | `entrySet()` Returns an immutable set of the mappings in this map, sorted by the key ordering.
    `java.util.Map.Entry<K,V>` | `firstEntry()`
    `K` | `firstKey()`
    `java.util.Map.Entry<K,V>` | `floorEntry(K key)`
    `K` | `floorKey(K key)`
    `V` | `get(java.lang.Object key)`
    `ImmutableSortedMap<K,V>` | `headMap(K toKey)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than `toKey`.
    `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`.
    `java.util.Map.Entry<K,V>` | `higherEntry(K key)`
    `K` | `higherKey(K key)`
    `ImmutableSortedSet<K>` | `keySet()` Returns an immutable sorted set of the keys in this map.
    `java.util.Map.Entry<K,V>` | `lastEntry()`
    `K` | `lastKey()`
    `java.util.Map.Entry<K,V>` | `lowerEntry(K key)`
    `K` | `lowerKey(K key)`
    `static <K extends java.lang.Comparable<?>,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 java.lang.Comparable<? super K>,V> ImmutableSortedMap<K,V>` | `of(K k1, V v1)` Returns an immutable map containing a single entry.
    `static <K extends java.lang.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 java.lang.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 java.lang.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 java.lang.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(java.util.Comparator<K> comparator)` Returns a builder that creates immutable sorted maps with an explicit comparator.
    `java.util.Map.Entry<K,V>` | `pollFirstEntry()` Deprecated. Unsupported operation.
    `java.util.Map.Entry<K,V>` | `pollLastEntry()` Deprecated. Unsupported operation.
    `static <K extends java.lang.Comparable<?>,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`.
    `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`.
    `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

      `asMultimap, clear, containsKey, containsValue, equals, 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, containsValue, equals, 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 java.lang.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 java.lang.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:
        `java.lang.IllegalArgumentException` - if the two keys are equal according to their natural ordering

    - #### of

          public static <K extends java.lang.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:
        `java.lang.IllegalArgumentException` - if any two keys are equal according to their natural ordering

    - #### of

          public static <K extends java.lang.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:
        `java.lang.IllegalArgumentException` - if any two keys are equal according to their natural ordering

    - #### of

          public static <K extends java.lang.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:
        `java.lang.IllegalArgumentException` - if any two keys are equal according to their natural ordering

    - #### copyOf

          public static <K,V> ImmutableSortedMap<K,V> copyOf(java.util.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:
        `java.lang.ClassCastException` - if the keys in `map` are not mutually comparable
        `java.lang.NullPointerException` - if any key or value in `map` is null
        `java.lang.IllegalArgumentException` - if any two keys are equal according to their natural ordering

    - #### copyOf

          public static <K,V> ImmutableSortedMap<K,V> copyOf(java.util.Map<? extends K,? extends V> map,
                                             java.util.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:
        `java.lang.NullPointerException` - if any key or value in `map` is null
        `java.lang.IllegalArgumentException` - if any two keys are equal according to the comparator

    - #### copyOf

          @Beta
          public static <K,V> ImmutableSortedMap<K,V> copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries)

      Returns an immutable map containing the given entries, with keys sorted by the provided comparator.

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

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

    - #### copyOf

          @Beta
          public static <K,V> ImmutableSortedMap<K,V> copyOf(java.lang.Iterable<? extends java.util.Map.Entry<? extends K,? extends V>> entries,
                                                  java.util.Comparator<? super K> comparator)

      Returns an immutable map containing the given entries, with keys sorted by the provided comparator.
      Throws:
        `java.lang.NullPointerException` - if any key or value in `map` is null
        `java.lang.IllegalArgumentException` - if any two keys are equal according to the comparator
      Since:
        19.0

    - #### copyOfSorted

          public static <K,V> ImmutableSortedMap<K,V> copyOfSorted(java.util.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:
        `java.lang.NullPointerException` - if any key or value in `map` is null

    - #### naturalOrder

          public static <K extends java.lang.Comparable<?>,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.

    - #### orderedBy

          public static <K,V> ImmutableSortedMap.Builder<K,V> orderedBy(java.util.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:
        `java.lang.NullPointerException` - if `comparator` is null

    - #### reverseOrder

          public static <K extends java.lang.Comparable<?>,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.

    - #### size

          public int size()

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

    - #### get

          public V get(@Nullable
              java.lang.Object key)

      Specified by:
        `get` in interface `java.util.Map<K,V>`
      Specified by:
        `get` in class `ImmutableMap<K,V>`

    - #### entrySet

          public ImmutableSet<java.util.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 `java.util.Map<K,V>`
      Specified by:
        `entrySet` in interface `java.util.SortedMap<K,V>`
      Overrides:
        `entrySet` in class `ImmutableMap<K,V>`

    - #### keySet

          public ImmutableSortedSet<K> keySet()

      Returns an immutable sorted set of the keys in this map.
      Specified by:
        `keySet` in interface `java.util.Map<K,V>`
      Specified by:
        `keySet` in interface `java.util.SortedMap<K,V>`
      Overrides:
        `keySet` in class `ImmutableMap<K,V>`

    - #### values

          public 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 `java.util.Map<K,V>`
      Specified by:
        `values` in interface `java.util.SortedMap<K,V>`
      Overrides:
        `values` in class `ImmutableMap<K,V>`

    - #### comparator

          public java.util.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 `java.util.SortedMap<K,V>`

    - #### firstKey

          public K firstKey()

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

    - #### lastKey

          public K lastKey()

      Specified by:
        `lastKey` in interface `java.util.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 `java.util.NavigableMap<K,V>`
      Specified by:
        `headMap` in interface `java.util.SortedMap<K,V>`

    - #### headMap

          public 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 `java.util.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 `java.util.NavigableMap<K,V>`
      Specified by:
        `subMap` in interface `java.util.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 `java.util.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 `java.util.NavigableMap<K,V>`
      Specified by:
        `tailMap` in interface `java.util.SortedMap<K,V>`

    - #### tailMap

          public 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 `java.util.NavigableMap<K,V>`
      Since:
        12.0

    - #### lowerEntry

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

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

    - #### lowerKey

          public K lowerKey(K key)

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

    - #### floorEntry

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

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

    - #### floorKey

          public K floorKey(K key)

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

    - #### ceilingEntry

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

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

    - #### ceilingKey

          public K ceilingKey(K key)

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

    - #### higherEntry

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

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

    - #### higherKey

          public K higherKey(K key)

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

    - #### firstEntry

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

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

    - #### lastEntry

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

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

    - #### pollFirstEntry

          @Deprecated
          public final java.util.Map.Entry<K,V> pollFirstEntry()

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `pollFirstEntry` in interface `java.util.NavigableMap<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### pollLastEntry

          @Deprecated
          public final java.util.Map.Entry<K,V> pollLastEntry()

      Deprecated. Unsupported operation.
      Guaranteed to throw an exception and leave the map unmodified.
      Specified by:
        `pollLastEntry` in interface `java.util.NavigableMap<K,V>`
      Throws:
        `java.lang.UnsupportedOperationException` - always

    - #### descendingMap

          public ImmutableSortedMap<K,V> descendingMap()

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

    - #### navigableKeySet

          public ImmutableSortedSet<K> navigableKeySet()

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

    - #### descendingKeySet

          public ImmutableSortedSet<K> descendingKeySet()

      Specified by:
        `descendingKeySet` in interface `java.util.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:
        `java.lang.UnsupportedOperationException` - always