Update #0 - First Release

sources/main/java/com/google/common/collect/RangeMap.java

@@ -0,0 +1,151 @@
+/*
+ * Copyright (C) 2012 The Guava Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.common.collect;
+
+import java.util.Map;
+import java.util.NoSuchElementException;
+
+import javax.annotation.Nullable;
+
+import com.google.common.annotations.Beta;
+
+/**
+ * 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.
+ *
+ * <p>
+ * In contrast to {@link RangeSet}, no "coalescing" is done of
+ * {@linkplain Range#isConnected(Range) connected} ranges, even if they are
+ * mapped to the same value.
+ *
+ * @author Louis Wasserman
+ * @since 14.0
+ */
+@Beta
+public interface RangeMap<K extends Comparable, V> {
+	/**
+	 * Returns the value associated with the specified key, or {@code null} if there
+	 * is no such value.
+	 *
+	 * <p>
+	 * Specifically, if any range in this range map contains the specified key, the
+	 * value associated with that range is returned.
+	 */
+	@Nullable
+	V get(K key);
+
+	/**
+	 * Returns the range containing this key and its associated value, if such a
+	 * range is present in the range map, or {@code null} otherwise.
+	 */
+	@Nullable
+	Map.Entry<Range<K>, V> getEntry(K key);
+
+	/**
+	 * Returns the minimal range {@linkplain Range#encloses(Range) enclosing} the
+	 * ranges in this {@code RangeMap}.
+	 *
+	 * @throws NoSuchElementException if this range map is empty
+	 */
+	Range<K> span();
+
+	/**
+	 * Maps a range to a specified value (optional operation).
+	 *
+	 * <p>
+	 * Specifically, after a call to {@code put(range, value)}, if
+	 * {@link Range#contains(Comparable) range.contains(k)}, then
+	 * {@link #get(Comparable) get(k)} will return {@code value}.
+	 *
+	 * <p>
+	 * If {@code range} {@linkplain Range#isEmpty() is empty}, then this is a no-op.
+	 */
+	void put(Range<K> range, V value);
+
+	/**
+	 * Puts all the associations from {@code rangeMap} into this range map (optional
+	 * operation).
+	 */
+	void putAll(RangeMap<K, V> rangeMap);
+
+	/**
+	 * Removes all associations from this range map (optional operation).
+	 */
+	void clear();
+
+	/**
+	 * Removes all associations from this range map in the specified range (optional
+	 * operation).
+	 *
+	 * <p>
+	 * If {@code !range.contains(k)}, {@link #get(Comparable) get(k)} will return
+	 * the same result before and after a call to {@code remove(range)}. If
+	 * {@code range.contains(k)}, then after a call to {@code remove(range)},
+	 * {@code get(k)} will return {@code null}.
+	 */
+	void remove(Range<K> range);
+
+	/**
+	 * Returns a view of this range map as an unmodifiable {@code Map<Range<K>, V>}.
+	 * Modifications to this range map are guaranteed to read through to the
+	 * returned {@code Map}.
+	 *
+	 * <p>
+	 * It is guaranteed that no empty ranges will be in the returned {@code Map}.
+	 */
+	Map<Range<K>, V> asMapOfRanges();
+
+	/**
+	 * Returns a view of the part of this range map that intersects with
+	 * {@code range}.
+	 * 
+	 * <p>
+	 * For example, if {@code rangeMap} had the entries
+	 * {@code [1, 5] => "foo", (6, 8) => "bar", (10, \u2025) => "baz"} then
+	 * {@code rangeMap.subRangeMap(Range.open(3, 12))} would return a range map with
+	 * the entries {@code (3, 5) => "foo", (6, 8) => "bar", (10, 12) => "baz"}.
+	 * 
+	 * <p>
+	 * The returned range map supports all optional operations that this range map
+	 * supports, except for {@code asMapOfRanges().iterator().remove()}.
+	 * 
+	 * <p>
+	 * The returned range map will throw an {@link IllegalArgumentException} on an
+	 * attempt to insert a range not {@linkplain Range#encloses(Range) enclosed} by
+	 * {@code range}.
+	 */
+	RangeMap<K, V> subRangeMap(Range<K> range);
+
+	/**
+	 * Returns {@code true} if {@code obj} is another {@code RangeMap} that has an
+	 * equivalent {@link #asMapOfRanges()}.
+	 */
+	@Override
+	boolean equals(@Nullable Object o);
+
+	/**
+	 * Returns {@code asMapOfRanges().hashCode()}.
+	 */
+	@Override
+	int hashCode();
+
+	/**
+	 * Returns a readable string representation of this range map.
+	 */
+	@Override
+	String toString();
+}