RangeMap
Date: 2016-05-24

com.google.common.collect

## Interface RangeMap<K extends java.lang.Comparable,V>

- All Known Implementing Classes:
    ImmutableRangeMap, TreeRangeMap

      @Beta
      public interface RangeMap<K extends java.lang.Comparable,V>

  A mapping from disjoint nonempty ranges to non-null values. Queries look up the value associated with the range (if any) that contains a specified key.

  In contrast to `RangeSet`, no "coalescing" is done of connected ranges, even if they are mapped to the same value.

  Since:
    14.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map<Range<K>,V>` | `asDescendingMapOfRanges()` Returns a view of this range map as an unmodifiable `Map<Range<K>, V>`.
    `java.util.Map<Range<K>,V>` | `asMapOfRanges()` Returns a view of this range map as an unmodifiable `Map<Range<K>, V>`.
    `void` | `clear()` Removes all associations from this range map (optional operation).
    `boolean` | `equals(java.lang.Object o)` Returns `true` if `obj` is another `RangeMap` that has an equivalent `asMapOfRanges()`.
    `V` | `get(K key)` Returns the value associated with the specified key, or `null` if there is no such value.
    `java.util.Map.Entry<Range<K>,V>` | `getEntry(K key)` Returns the range containing this key and its associated value, if such a range is present in the range map, or `null` otherwise.
    `int` | `hashCode()` Returns `asMapOfRanges().hashCode()`.
    `void` | `put(Range<K> range, V value)` Maps a range to a specified value (optional operation).
    `void` | `putAll(RangeMap<K,V> rangeMap)` Puts all the associations from `rangeMap` into this range map (optional operation).
    `void` | `remove(Range<K> range)` Removes all associations from this range map in the specified range (optional operation).
    `Range<K>` | `span()` Returns the minimal range enclosing the ranges in this `RangeMap`.
    `RangeMap<K,V>` | `subRangeMap(Range<K> range)` Returns a view of the part of this range map that intersects with `range`.
    `java.lang.String` | `toString()` Returns a readable string representation of this range map.

- - ### Method Detail

    - #### get

          @Nullable
          V get(K key)

      Returns the value associated with the specified key, or `null` if there is no such value.

      Specifically, if any range in this range map contains the specified key, the value associated with that range is returned.

    - #### getEntry

          @Nullable
          java.util.Map.Entry<Range<K>,V> getEntry(K key)

      Returns the range containing this key and its associated value, if such a range is present in the range map, or `null` otherwise.

    - #### span

          Range<K> span()

      Returns the minimal range enclosing the ranges in this `RangeMap`.
      Throws:
        `NoSuchElementException` - if this range map is empty

    - #### put

          void put(Range<K> range,
                 V value)

      Maps a range to a specified value (optional operation).

      Specifically, after a call to `put(range, value)`, if `range.contains(k)`, then `get(k)` will return `value`.

      If `range` is empty, then this is a no-op.

    - #### putAll

          void putAll(RangeMap<K,V> rangeMap)

      Puts all the associations from `rangeMap` into this range map (optional operation).

    - #### clear

          void clear()

      Removes all associations from this range map (optional operation).

    - #### remove

          void remove(Range<K> range)

      Removes all associations from this range map in the specified range (optional operation).

      If `!range.contains(k)`, `get(k)` will return the same result before and after a call to `remove(range)`. If `range.contains(k)`, then after a call to `remove(range)`, `get(k)` will return `null`.

    - #### asMapOfRanges

          java.util.Map<Range<K>,V> asMapOfRanges()

      Returns a view of this range map as an unmodifiable `Map<Range<K>, V>`. Modifications to this range map are guaranteed to read through to the returned `Map`.

      The returned `Map` iterates over entries in ascending order of the bounds of the `Range` entries.

      It is guaranteed that no empty ranges will be in the returned `Map`.

    - #### asDescendingMapOfRanges

          java.util.Map<Range<K>,V> asDescendingMapOfRanges()

      Returns a view of this range map as an unmodifiable `Map<Range<K>, V>`. Modifications to this range map are guaranteed to read through to the returned `Map`.

      The returned `Map` iterates over entries in descending order of the bounds of the `Range` entries.

      It is guaranteed that no empty ranges will be in the returned `Map`.

      Since:
        19.0

    - #### subRangeMap

          RangeMap<K,V> subRangeMap(Range<K> range)

      Returns a view of the part of this range map that intersects with `range`.

      For example, if `rangeMap` had the entries `[1, 5] => "foo", (6, 8) => "bar", (10, ‥) => "baz"` then `rangeMap.subRangeMap(Range.open(3, 12))` would return a range map with the entries `(3, 5) => "foo", (6, 8) => "bar", (10, 12) => "baz"`.

      The returned range map supports all optional operations that this range map supports, except for `asMapOfRanges().iterator().remove()`.

      The returned range map will throw an `IllegalArgumentException` on an attempt to insert a range not enclosed by `range`.

    - #### equals

          boolean equals(@Nullable
                       java.lang.Object o)

      Returns `true` if `obj` is another `RangeMap` that has an equivalent `asMapOfRanges()`.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          int hashCode()

      Returns `asMapOfRanges().hashCode()`.
      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### toString

          java.lang.String toString()

      Returns a readable string representation of this range map.
      Overrides:
        `toString` in class `java.lang.Object`