Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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>, SortedMap<K,V>

    public class ImmutableSortedMap<K,V>

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

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

Unlike `Collections.unmodifiableSortedMap(java.util.SortedMap)`, 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.

Author:
  Jared Levy
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.
`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)` Returns `true` if this map maps one or more keys to the specified 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.
`ImmutableSet<Map.Entry<K,V>>` | `entrySet()` Returns an immutable set of the mappings in this map, sorted by the key ordering.
`K` | `firstKey()` Returns the first (lowest) key currently in this map.
`V` | `get(Object key)` Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.
`ImmutableSortedMap<K,V>` | `headMap(K toKey)` This method returns a `ImmutableSortedMap`, consisting of the entries whose keys are less than `toKey`.
`ImmutableSortedSet<K>` | `keySet()` Returns an immutable sorted set of the keys in this map.
`K` | `lastKey()` Returns the last (highest) key currently in this map.
`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.
`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.
`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()` Returns the number of key-value mappings in this map.
`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`.
`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, 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, 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.

  Note: Despite what the method name suggests, if `map` is an `ImmutableSortedMap`, it may be returned instead of a copy.

  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.

  Note: Despite what the method name suggests, if `map` is an `ImmutableSortedMap`, it may be returned instead of a copy.

  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.

  Note: Despite what the method name suggests, if `map` is an `ImmutableSortedMap`, it may be returned instead of a copy.

  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()

  Description copied from interface: `java.util.Map`
  Returns the number of key-value mappings in this map. If the map contains more than `Integer.MAX_VALUE` elements, returns `Integer.MAX_VALUE`.

  Specified by:
    `size` in interface `Map<K,V>`
  Returns:
    the number of key-value mappings in this map

### get

    public V get(@Nullable
                 Object key)

  Description copied from interface: `java.util.Map`
  Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key.

  More formally, if this map contains a mapping from a key `k` to a value `v` such that `(key==null ? k==null : key.equals(k))`, then this method returns `v`; otherwise it returns `null`. (There can be at most one such mapping.)

  If this map permits null values, then a return value of `null` does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to `null`. The `containsKey` operation may be used to distinguish these two cases.

  Specified by:
    `get` in interface `Map<K,V>`
  Specified by:
    `get` in class `ImmutableMap<K,V>`
  Parameters:
    `key` - the key whose associated value is to be returned
  Returns:
    the value to which the specified key is mapped, or `null` if this map contains no mapping for the key

### containsValue

    public boolean containsValue(@Nullable
                                 Object value)

  Description copied from interface: `java.util.Map`
  Returns `true` if this map maps one or more keys to the specified value. More formally, returns `true` if and only if this map contains at least one mapping to a value `v` such that `(value==null ? v==null : value.equals(v))`. This operation will probably require time linear in the map size for most implementations of the `Map` interface.

  Specified by:
    `containsValue` in interface `Map<K,V>`
  Specified by:
    `containsValue` in class `ImmutableMap<K,V>`
  Parameters:
    `value` - value whose presence in this map is to be tested
  Returns:
    `true` if this map maps one or more keys to the specified value

### 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>`
  Specified by:
    `entrySet` in class `ImmutableMap<K,V>`
  Returns:
    a set view of the mappings contained in this map

### keySet

    public 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>`
  Specified by:
    `keySet` in class `ImmutableMap<K,V>`
  Returns:
    a set view of the keys contained in this map

### 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 `Map<K,V>`
  Specified by:
    `values` in interface `SortedMap<K,V>`
  Specified by:
    `values` in class `ImmutableMap<K,V>`
  Returns:
    a collection view of the values contained in this map

### 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>`
  Returns:
    the comparator used to order the keys in this map, or `null` if this map uses the natural ordering of its keys

### firstKey

    public K firstKey()

  Description copied from interface: `java.util.SortedMap`
  Returns the first (lowest) key currently in this map.

  Specified by:
    `firstKey` in interface `SortedMap<K,V>`
  Returns:
    the first (lowest) key currently in this map

### lastKey

    public K lastKey()

  Description copied from interface: `java.util.SortedMap`
  Returns the last (highest) key currently in this map.

  Specified by:
    `lastKey` in interface `SortedMap<K,V>`
  Returns:
    the last (highest) key currently in this map

### 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 `SortedMap<K,V>`
  Parameters:
    `toKey` - high endpoint (exclusive) of the keys in the returned map
  Returns:
    a view of the portion of this map whose keys are strictly less than `toKey`

### 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 `SortedMap<K,V>`
  Parameters:
    `fromKey` - low endpoint (inclusive) of the keys in the returned map
    `toKey` - high endpoint (exclusive) of the keys in the returned map
  Returns:
    a view of the portion of this map whose keys range from `fromKey`, inclusive, to `toKey`, exclusive

### 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 `SortedMap<K,V>`
  Parameters:
    `fromKey` - low endpoint (inclusive) of the keys in the returned map
  Returns:
    a view of the portion of this map whose keys are greater than or equal to `fromKey`

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD