All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.collect.Range Maven / Gradle / Ivy

Go to download

Guava is a suite of core and expanded libraries that include utility classes, google's collections, io classes, and much much more.

There is a newer version: 33.3.0-jre
Show newest version
/*
 * Copyright (C) 2008 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 static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.GwtCompatible;
import com.google.common.base.Equivalence;
import com.google.common.base.Function;
import com.google.common.base.Predicate;
import java.io.Serializable;
import java.util.Comparator;
import java.util.Iterator;
import java.util.NoSuchElementException;
import java.util.SortedSet;
import org.checkerframework.checker.nullness.qual.Nullable;

/**
 * A range (or "interval") defines the boundaries around a contiguous span of values of some
 * {@code Comparable} type; for example, "integers from 1 to 100 inclusive." Note that it is not
 * possible to iterate over these contained values. To do so, pass this range instance and an
 * appropriate {@link DiscreteDomain} to {@link ContiguousSet#create}.
 *
 * 

Types of ranges

* *

Each end of the range may be bounded or unbounded. If bounded, there is an associated * endpoint value, and the range is considered to be either open (does not include the * endpoint) or closed (includes the endpoint) on that side. With three possibilities on each * side, this yields nine basic types of ranges, enumerated below. (Notation: a square bracket * ({@code [ ]}) indicates that the range is closed on that side; a parenthesis ({@code ( )}) means * it is either open or unbounded. The construct {@code {x | statement}} is read "the set of all * x such that statement.") * *

* * * *
Range Types
Notation Definition Factory method *
{@code (a..b)} {@code {x | a < x < b}} {@link Range#open open} *
{@code [a..b]} {@code {x | a <= x <= b}}{@link Range#closed closed} *
{@code (a..b]} {@code {x | a < x <= b}} {@link Range#openClosed openClosed} *
{@code [a..b)} {@code {x | a <= x < b}} {@link Range#closedOpen closedOpen} *
{@code (a..+∞)} {@code {x | x > a}} {@link Range#greaterThan greaterThan} *
{@code [a..+∞)} {@code {x | x >= a}} {@link Range#atLeast atLeast} *
{@code (-∞..b)} {@code {x | x < b}} {@link Range#lessThan lessThan} *
{@code (-∞..b]} {@code {x | x <= b}} {@link Range#atMost atMost} *
{@code (-∞..+∞)}{@code {x}} {@link Range#all all} *
* *
* *

When both endpoints exist, the upper endpoint may not be less than the lower. The endpoints * may be equal only if at least one of the bounds is closed: * *

    *
  • {@code [a..a]} : a singleton range *
  • {@code [a..a); (a..a]} : {@linkplain #isEmpty empty} ranges; also valid *
  • {@code (a..a)} : invalid; an exception will be thrown *
* *

Warnings

* *
    *
  • Use immutable value types only, if at all possible. If you must use a mutable type, do * not allow the endpoint instances to mutate after the range is created! *
  • Your value type's comparison method should be {@linkplain Comparable consistent with * equals} if at all possible. Otherwise, be aware that concepts used throughout this * documentation such as "equal", "same", "unique" and so on actually refer to whether {@link * Comparable#compareTo compareTo} returns zero, not whether {@link Object#equals equals} * returns {@code true}. *
  • A class which implements {@code Comparable} is very broken, and will cause * undefined horrible things to happen in {@code Range}. For now, the Range API does not * prevent its use, because this would also rule out all ungenerified (pre-JDK1.5) data types. * This may change in the future. *
* *

Other notes

* *
    *
  • Instances of this type are obtained using the static factory methods in this class. *
  • Ranges are convex: whenever two values are contained, all values in between them * must also be contained. More formally, for any {@code c1 <= c2 <= c3} of type {@code C}, * {@code r.contains(c1) && r.contains(c3)} implies {@code r.contains(c2)}). This means that a * {@code Range} can never be used to represent, say, "all prime numbers from * 1 to 100." *
  • When evaluated as a {@link Predicate}, a range yields the same result as invoking {@link * #contains}. *
  • Terminology note: a range {@code a} is said to be the maximal range having property * P if, for all ranges {@code b} also having property P, {@code a.encloses(b)}. * Likewise, {@code a} is minimal when {@code b.encloses(a)} for all {@code b} having * property P. See, for example, the definition of {@link #intersection intersection}. *
* *

Further reading

* *

See the Guava User Guide article on {@code Range}. * * @author Kevin Bourrillion * @author Gregory Kick * @since 10.0 */ @GwtCompatible @SuppressWarnings("rawtypes") public final class Range extends RangeGwtSerializationDependencies implements Predicate, Serializable { static class LowerBoundFn implements Function { static final LowerBoundFn INSTANCE = new LowerBoundFn(); @Override public Cut apply(Range range) { return range.lowerBound; } } static class UpperBoundFn implements Function { static final UpperBoundFn INSTANCE = new UpperBoundFn(); @Override public Cut apply(Range range) { return range.upperBound; } } @SuppressWarnings("unchecked") static > Function, Cut> lowerBoundFn() { return (Function) LowerBoundFn.INSTANCE; } @SuppressWarnings("unchecked") static > Function, Cut> upperBoundFn() { return (Function) UpperBoundFn.INSTANCE; } static > Ordering> rangeLexOrdering() { return (Ordering>) (Ordering) RangeLexOrdering.INSTANCE; } static > Range create(Cut lowerBound, Cut upperBound) { return new Range(lowerBound, upperBound); } /** * Returns a range that contains all values strictly greater than {@code lower} and strictly less * than {@code upper}. * * @throws IllegalArgumentException if {@code lower} is greater than or equal to {@code * upper} * @throws ClassCastException if {@code lower} and {@code upper} are not mutually comparable * @since 14.0 */ public static > Range open(C lower, C upper) { return create(Cut.aboveValue(lower), Cut.belowValue(upper)); } /** * Returns a range that contains all values greater than or equal to {@code lower} and less than * or equal to {@code upper}. * * @throws IllegalArgumentException if {@code lower} is greater than {@code upper} * @throws ClassCastException if {@code lower} and {@code upper} are not mutually comparable * @since 14.0 */ public static > Range closed(C lower, C upper) { return create(Cut.belowValue(lower), Cut.aboveValue(upper)); } /** * Returns a range that contains all values greater than or equal to {@code lower} and strictly * less than {@code upper}. * * @throws IllegalArgumentException if {@code lower} is greater than {@code upper} * @throws ClassCastException if {@code lower} and {@code upper} are not mutually comparable * @since 14.0 */ public static > Range closedOpen(C lower, C upper) { return create(Cut.belowValue(lower), Cut.belowValue(upper)); } /** * Returns a range that contains all values strictly greater than {@code lower} and less than or * equal to {@code upper}. * * @throws IllegalArgumentException if {@code lower} is greater than {@code upper} * @throws ClassCastException if {@code lower} and {@code upper} are not mutually comparable * @since 14.0 */ public static > Range openClosed(C lower, C upper) { return create(Cut.aboveValue(lower), Cut.aboveValue(upper)); } /** * Returns a range that contains any value from {@code lower} to {@code upper}, where each * endpoint may be either inclusive (closed) or exclusive (open). * * @throws IllegalArgumentException if {@code lower} is greater than {@code upper} * @throws ClassCastException if {@code lower} and {@code upper} are not mutually comparable * @since 14.0 */ public static > Range range( C lower, BoundType lowerType, C upper, BoundType upperType) { checkNotNull(lowerType); checkNotNull(upperType); Cut lowerBound = (lowerType == BoundType.OPEN) ? Cut.aboveValue(lower) : Cut.belowValue(lower); Cut upperBound = (upperType == BoundType.OPEN) ? Cut.belowValue(upper) : Cut.aboveValue(upper); return create(lowerBound, upperBound); } /** * Returns a range that contains all values strictly less than {@code endpoint}. * * @since 14.0 */ public static > Range lessThan(C endpoint) { return create(Cut.belowAll(), Cut.belowValue(endpoint)); } /** * Returns a range that contains all values less than or equal to {@code endpoint}. * * @since 14.0 */ public static > Range atMost(C endpoint) { return create(Cut.belowAll(), Cut.aboveValue(endpoint)); } /** * Returns a range with no lower bound up to the given endpoint, which may be either inclusive * (closed) or exclusive (open). * * @since 14.0 */ public static > Range upTo(C endpoint, BoundType boundType) { switch (boundType) { case OPEN: return lessThan(endpoint); case CLOSED: return atMost(endpoint); default: throw new AssertionError(); } } /** * Returns a range that contains all values strictly greater than {@code endpoint}. * * @since 14.0 */ public static > Range greaterThan(C endpoint) { return create(Cut.aboveValue(endpoint), Cut.aboveAll()); } /** * Returns a range that contains all values greater than or equal to {@code endpoint}. * * @since 14.0 */ public static > Range atLeast(C endpoint) { return create(Cut.belowValue(endpoint), Cut.aboveAll()); } /** * Returns a range from the given endpoint, which may be either inclusive (closed) or exclusive * (open), with no upper bound. * * @since 14.0 */ public static > Range downTo(C endpoint, BoundType boundType) { switch (boundType) { case OPEN: return greaterThan(endpoint); case CLOSED: return atLeast(endpoint); default: throw new AssertionError(); } } private static final Range ALL = new Range<>(Cut.belowAll(), Cut.aboveAll()); /** * Returns a range that contains every value of type {@code C}. * * @since 14.0 */ @SuppressWarnings("unchecked") public static > Range all() { return (Range) ALL; } /** * Returns a range that {@linkplain Range#contains(Comparable) contains} only the given value. The * returned range is {@linkplain BoundType#CLOSED closed} on both ends. * * @since 14.0 */ public static > Range singleton(C value) { return closed(value, value); } /** * Returns the minimal range that {@linkplain Range#contains(Comparable) contains} all of the * given values. The returned range is {@linkplain BoundType#CLOSED closed} on both ends. * * @throws ClassCastException if the values are not mutually comparable * @throws NoSuchElementException if {@code values} is empty * @throws NullPointerException if any of {@code values} is null * @since 14.0 */ public static > Range encloseAll(Iterable values) { checkNotNull(values); if (values instanceof SortedSet) { SortedSet set = cast(values); Comparator comparator = set.comparator(); if (Ordering.natural().equals(comparator) || comparator == null) { return closed(set.first(), set.last()); } } Iterator valueIterator = values.iterator(); C min = checkNotNull(valueIterator.next()); C max = min; while (valueIterator.hasNext()) { C value = checkNotNull(valueIterator.next()); min = Ordering.natural().min(min, value); max = Ordering.natural().max(max, value); } return closed(min, max); } final Cut lowerBound; final Cut upperBound; private Range(Cut lowerBound, Cut upperBound) { this.lowerBound = checkNotNull(lowerBound); this.upperBound = checkNotNull(upperBound); if (lowerBound.compareTo(upperBound) > 0 || lowerBound == Cut.aboveAll() || upperBound == Cut.belowAll()) { throw new IllegalArgumentException("Invalid range: " + toString(lowerBound, upperBound)); } } /** Returns {@code true} if this range has a lower endpoint. */ public boolean hasLowerBound() { return lowerBound != Cut.belowAll(); } /** * Returns the lower endpoint of this range. * * @throws IllegalStateException if this range is unbounded below (that is, {@link * #hasLowerBound()} returns {@code false}) */ public C lowerEndpoint() { return lowerBound.endpoint(); } /** * Returns the type of this range's lower bound: {@link BoundType#CLOSED} if the range includes * its lower endpoint, {@link BoundType#OPEN} if it does not. * * @throws IllegalStateException if this range is unbounded below (that is, {@link * #hasLowerBound()} returns {@code false}) */ public BoundType lowerBoundType() { return lowerBound.typeAsLowerBound(); } /** Returns {@code true} if this range has an upper endpoint. */ public boolean hasUpperBound() { return upperBound != Cut.aboveAll(); } /** * Returns the upper endpoint of this range. * * @throws IllegalStateException if this range is unbounded above (that is, {@link * #hasUpperBound()} returns {@code false}) */ public C upperEndpoint() { return upperBound.endpoint(); } /** * Returns the type of this range's upper bound: {@link BoundType#CLOSED} if the range includes * its upper endpoint, {@link BoundType#OPEN} if it does not. * * @throws IllegalStateException if this range is unbounded above (that is, {@link * #hasUpperBound()} returns {@code false}) */ public BoundType upperBoundType() { return upperBound.typeAsUpperBound(); } /** * Returns {@code true} if this range is of the form {@code [v..v)} or {@code (v..v]}. (This does * not encompass ranges of the form {@code (v..v)}, because such ranges are invalid and * can't be constructed at all.) * *

Note that certain discrete ranges such as the integer range {@code (3..4)} are not * considered empty, even though they contain no actual values. In these cases, it may be helpful * to preprocess ranges with {@link #canonical(DiscreteDomain)}. */ public boolean isEmpty() { return lowerBound.equals(upperBound); } /** * Returns {@code true} if {@code value} is within the bounds of this range. For example, on the * range {@code [0..2)}, {@code contains(1)} returns {@code true}, while {@code contains(2)} * returns {@code false}. */ public boolean contains(C value) { checkNotNull(value); // let this throw CCE if there is some trickery going on return lowerBound.isLessThan(value) && !upperBound.isLessThan(value); } /** * @deprecated Provided only to satisfy the {@link Predicate} interface; use {@link #contains} * instead. */ @Deprecated @Override public boolean apply(C input) { return contains(input); } /** * Returns {@code true} if every element in {@code values} is {@linkplain #contains contained} in * this range. */ public boolean containsAll(Iterable values) { if (Iterables.isEmpty(values)) { return true; } // this optimizes testing equality of two range-backed sets if (values instanceof SortedSet) { SortedSet set = cast(values); Comparator comparator = set.comparator(); if (Ordering.natural().equals(comparator) || comparator == null) { return contains(set.first()) && contains(set.last()); } } for (C value : values) { if (!contains(value)) { return false; } } return true; } /** * Returns {@code true} if the bounds of {@code other} do not extend outside the bounds of this * range. Examples: * *

    *
  • {@code [3..6]} encloses {@code [4..5]} *
  • {@code (3..6)} encloses {@code (3..6)} *
  • {@code [3..6]} encloses {@code [4..4)} (even though the latter is empty) *
  • {@code (3..6]} does not enclose {@code [3..6]} *
  • {@code [4..5]} does not enclose {@code (3..6)} (even though it contains every value * contained by the latter range) *
  • {@code [3..6]} does not enclose {@code (1..1]} (even though it contains every value * contained by the latter range) *
* *

Note that if {@code a.encloses(b)}, then {@code b.contains(v)} implies {@code * a.contains(v)}, but as the last two examples illustrate, the converse is not always true. * *

Being reflexive, antisymmetric and transitive, the {@code encloses} relation defines a * partial order over ranges. There exists a unique {@linkplain Range#all maximal} range * according to this relation, and also numerous {@linkplain #isEmpty minimal} ranges. Enclosure * also implies {@linkplain #isConnected connectedness}. */ public boolean encloses(Range other) { return lowerBound.compareTo(other.lowerBound) <= 0 && upperBound.compareTo(other.upperBound) >= 0; } /** * Returns {@code true} if there exists a (possibly empty) range which is {@linkplain #encloses * enclosed} by both this range and {@code other}. * *

For example, * *

    *
  • {@code [2, 4)} and {@code [5, 7)} are not connected *
  • {@code [2, 4)} and {@code [3, 5)} are connected, because both enclose {@code [3, 4)} *
  • {@code [2, 4)} and {@code [4, 6)} are connected, because both enclose the empty range * {@code [4, 4)} *
* *

Note that this range and {@code other} have a well-defined {@linkplain #span union} and * {@linkplain #intersection intersection} (as a single, possibly-empty range) if and only if this * method returns {@code true}. * *

The connectedness relation is both reflexive and symmetric, but does not form an {@linkplain * Equivalence equivalence relation} as it is not transitive. * *

Note that certain discrete ranges are not considered connected, even though there are no * elements "between them." For example, {@code [3, 5]} is not considered connected to {@code [6, * 10]}. In these cases, it may be desirable for both input ranges to be preprocessed with {@link * #canonical(DiscreteDomain)} before testing for connectedness. */ public boolean isConnected(Range other) { return lowerBound.compareTo(other.upperBound) <= 0 && other.lowerBound.compareTo(upperBound) <= 0; } /** * Returns the maximal range {@linkplain #encloses enclosed} by both this range and {@code * connectedRange}, if such a range exists. * *

For example, the intersection of {@code [1..5]} and {@code (3..7)} is {@code (3..5]}. The * resulting range may be empty; for example, {@code [1..5)} intersected with {@code [5..7)} * yields the empty range {@code [5..5)}. * *

The intersection exists if and only if the two ranges are {@linkplain #isConnected * connected}. * *

The intersection operation is commutative, associative and idempotent, and its identity * element is {@link Range#all}). * * @throws IllegalArgumentException if {@code isConnected(connectedRange)} is {@code false} */ public Range intersection(Range connectedRange) { int lowerCmp = lowerBound.compareTo(connectedRange.lowerBound); int upperCmp = upperBound.compareTo(connectedRange.upperBound); if (lowerCmp >= 0 && upperCmp <= 0) { return this; } else if (lowerCmp <= 0 && upperCmp >= 0) { return connectedRange; } else { Cut newLower = (lowerCmp >= 0) ? lowerBound : connectedRange.lowerBound; Cut newUpper = (upperCmp <= 0) ? upperBound : connectedRange.upperBound; return create(newLower, newUpper); } } /** * Returns the maximal range lying between this range and {@code otherRange}, if such a range * exists. The resulting range may be empty if the two ranges are adjacent but non-overlapping. * *

For example, the gap of {@code [1..5]} and {@code (7..10)} is {@code (5..7]}. The resulting * range may be empty; for example, the gap between {@code [1..5)} {@code [5..7)} yields the empty * range {@code [5..5)}. * *

The gap exists if and only if the two ranges are either disconnected or immediately adjacent * (any intersection must be an empty range). * *

The gap operation is commutative. * * @throws IllegalArgumentException if this range and {@code otherRange} have a nonempty * intersection * @since 27.0 */ public Range gap(Range otherRange) { boolean isThisFirst = this.lowerBound.compareTo(otherRange.lowerBound) < 0; Range firstRange = isThisFirst ? this : otherRange; Range secondRange = isThisFirst ? otherRange : this; return create(firstRange.upperBound, secondRange.lowerBound); } /** * Returns the minimal range that {@linkplain #encloses encloses} both this range and {@code * other}. For example, the span of {@code [1..3]} and {@code (5..7)} is {@code [1..7)}. * *

If the input ranges are {@linkplain #isConnected connected}, the returned range can * also be called their union. If they are not, note that the span might contain values * that are not contained in either input range. * *

Like {@link #intersection(Range) intersection}, this operation is commutative, associative * and idempotent. Unlike it, it is always well-defined for any two input ranges. */ public Range span(Range other) { int lowerCmp = lowerBound.compareTo(other.lowerBound); int upperCmp = upperBound.compareTo(other.upperBound); if (lowerCmp <= 0 && upperCmp >= 0) { return this; } else if (lowerCmp >= 0 && upperCmp <= 0) { return other; } else { Cut newLower = (lowerCmp <= 0) ? lowerBound : other.lowerBound; Cut newUpper = (upperCmp >= 0) ? upperBound : other.upperBound; return create(newLower, newUpper); } } /** * Returns the canonical form of this range in the given domain. The canonical form has the * following properties: * *

    *
  • equivalence: {@code a.canonical().contains(v) == a.contains(v)} for all {@code v} (in * other words, {@code ContiguousSet.create(a.canonical(domain), domain).equals( * ContiguousSet.create(a, domain))} *
  • uniqueness: unless {@code a.isEmpty()}, {@code ContiguousSet.create(a, * domain).equals(ContiguousSet.create(b, domain))} implies {@code * a.canonical(domain).equals(b.canonical(domain))} *
  • idempotence: {@code a.canonical(domain).canonical(domain).equals(a.canonical(domain))} *
* *

Furthermore, this method guarantees that the range returned will be one of the following * canonical forms: * *

    *
  • [start..end) *
  • [start..+∞) *
  • (-∞..end) (only if type {@code C} is unbounded below) *
  • (-∞..+∞) (only if type {@code C} is unbounded below) *
*/ public Range canonical(DiscreteDomain domain) { checkNotNull(domain); Cut lower = lowerBound.canonical(domain); Cut upper = upperBound.canonical(domain); return (lower == lowerBound && upper == upperBound) ? this : create(lower, upper); } /** * Returns {@code true} if {@code object} is a range having the same endpoints and bound types as * this range. Note that discrete ranges such as {@code (1..4)} and {@code [2..3]} are not * equal to one another, despite the fact that they each contain precisely the same set of values. * Similarly, empty ranges are not equal unless they have exactly the same representation, so * {@code [3..3)}, {@code (3..3]}, {@code (4..4]} are all unequal. */ @Override public boolean equals(@Nullable Object object) { if (object instanceof Range) { Range other = (Range) object; return lowerBound.equals(other.lowerBound) && upperBound.equals(other.upperBound); } return false; } /** Returns a hash code for this range. */ @Override public int hashCode() { return lowerBound.hashCode() * 31 + upperBound.hashCode(); } /** * Returns a string representation of this range, such as {@code "[3..5)"} (other examples are * listed in the class documentation). */ @Override public String toString() { return toString(lowerBound, upperBound); } private static String toString(Cut lowerBound, Cut upperBound) { StringBuilder sb = new StringBuilder(16); lowerBound.describeAsLowerBound(sb); sb.append(".."); upperBound.describeAsUpperBound(sb); return sb.toString(); } /** Used to avoid http://bugs.sun.com/view_bug.do?bug_id=6558557 */ private static SortedSet cast(Iterable iterable) { return (SortedSet) iterable; } Object readResolve() { if (this.equals(ALL)) { return all(); } else { return this; } } @SuppressWarnings("unchecked") // this method may throw CCE static int compareOrThrow(Comparable left, Comparable right) { return left.compareTo(right); } /** Needed to serialize sorted collections of Ranges. */ private static class RangeLexOrdering extends Ordering> implements Serializable { static final Ordering> INSTANCE = new RangeLexOrdering(); @Override public int compare(Range left, Range right) { return ComparisonChain.start() .compare(left.lowerBound, right.lowerBound) .compare(left.upperBound, right.upperBound) .result(); } private static final long serialVersionUID = 0; } private static final long serialVersionUID = 0; }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy