747 lines
24 KiB
Java
747 lines
24 KiB
Java
/*
|
|
* 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 java.io.Serializable;
|
|
import java.util.Comparator;
|
|
import java.util.Iterator;
|
|
import java.util.NoSuchElementException;
|
|
import java.util.SortedSet;
|
|
|
|
import javax.annotation.Nullable;
|
|
|
|
import com.google.common.annotations.GwtCompatible;
|
|
import com.google.common.base.Equivalence;
|
|
import com.google.common.base.Function;
|
|
import com.google.common.base.Predicate;
|
|
|
|
/**
|
|
* A range (or "interval") defines the <i>boundaries</i> 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 <i>iterate</i> over these
|
|
* contained values. To do so, pass this range instance and an appropriate
|
|
* {@link DiscreteDomain} to {@link ContiguousSet#create}.
|
|
*
|
|
* <h3>Types of ranges</h3>
|
|
*
|
|
* <p>
|
|
* Each end of the range may be bounded or unbounded. If bounded, there is an
|
|
* associated <i>endpoint</i> value, and the range is considered to be either
|
|
* <i>open</i> (does not include the endpoint) or <i>closed</i> (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 <i>x</i> such that <i>statement</i>.")
|
|
*
|
|
* <blockquote>
|
|
* <table>
|
|
* <tr>
|
|
* <td><b>Notation</b>
|
|
* <td><b>Definition</b>
|
|
* <td><b>Factory method</b>
|
|
* <tr>
|
|
* <td>{@code (a..b)}
|
|
* <td>{@code {x | a < x < b}}
|
|
* <td>{@link Range#open open}
|
|
* <tr>
|
|
* <td>{@code [a..b]}
|
|
* <td>{@code {x | a <= x <= b}}
|
|
* <td>{@link Range#closed closed}
|
|
* <tr>
|
|
* <td>{@code (a..b]}
|
|
* <td>{@code {x | a < x <= b}}
|
|
* <td>{@link Range#openClosed openClosed}
|
|
* <tr>
|
|
* <td>{@code [a..b)}
|
|
* <td>{@code {x | a <= x < b}}
|
|
* <td>{@link Range#closedOpen closedOpen}
|
|
* <tr>
|
|
* <td>{@code (a..+∞)}
|
|
* <td>{@code {x | x > a}}
|
|
* <td>{@link Range#greaterThan greaterThan}
|
|
* <tr>
|
|
* <td>{@code [a..+∞)}
|
|
* <td>{@code {x | x >= a}}
|
|
* <td>{@link Range#atLeast atLeast}
|
|
* <tr>
|
|
* <td>{@code (-∞..b)}
|
|
* <td>{@code {x | x < b}}
|
|
* <td>{@link Range#lessThan lessThan}
|
|
* <tr>
|
|
* <td>{@code (-∞..b]}
|
|
* <td>{@code {x | x <= b}}
|
|
* <td>{@link Range#atMost atMost}
|
|
* <tr>
|
|
* <td>{@code (-∞..+∞)}
|
|
* <td>{@code {x}}
|
|
* <td>{@link Range#all all}
|
|
* </table>
|
|
* </blockquote>
|
|
*
|
|
* <p>
|
|
* 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:
|
|
*
|
|
* <ul>
|
|
* <li>{@code [a..a]} : a singleton range
|
|
* <li>{@code [a..a); (a..a]} : {@linkplain #isEmpty empty} ranges; also valid
|
|
* <li>{@code (a..a)} : <b>invalid</b>; an exception will be thrown
|
|
* </ul>
|
|
*
|
|
* <h3>Warnings</h3>
|
|
*
|
|
* <ul>
|
|
* <li>Use immutable value types only, if at all possible. If you must use a
|
|
* mutable type, <b>do not</b> allow the endpoint instances to mutate after the
|
|
* range is created!
|
|
* <li>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}.
|
|
* <li>A class which implements {@code Comparable<UnrelatedType>} 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. <b>This may change in the
|
|
* future.</b>
|
|
* </ul>
|
|
*
|
|
* <h3>Other notes</h3>
|
|
*
|
|
* <ul>
|
|
* <li>Instances of this type are obtained using the static factory methods in
|
|
* this class.
|
|
* <li>Ranges are <i>convex</i>: 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<Integer>} can never be used to represent, say, "all <i>prime</i>
|
|
* numbers from 1 to 100."
|
|
* <li>When evaluated as a {@link Predicate}, a range yields the same result as
|
|
* invoking {@link #contains}.
|
|
* <li>Terminology note: a range {@code a} is said to be the <i>maximal</i>
|
|
* range having property <i>P</i> if, for all ranges {@code b} also having
|
|
* property <i>P</i>, {@code a.encloses(b)}. Likewise, {@code a} is
|
|
* <i>minimal</i> when {@code b.encloses(a)} for all {@code b} having property
|
|
* <i>P</i>. See, for example, the definition of {@link #intersection
|
|
* intersection}.
|
|
* </ul>
|
|
*
|
|
* <h3>Further reading</h3>
|
|
*
|
|
* <p>
|
|
* See the Guava User Guide article on <a href=
|
|
* "http://code.google.com/p/guava-libraries/wiki/RangesExplained">{@code Range}</a>.
|
|
*
|
|
* @author Kevin Bourrillion
|
|
* @author Gregory Kick
|
|
* @since 10.0
|
|
*/
|
|
@GwtCompatible
|
|
@SuppressWarnings("rawtypes")
|
|
public final class Range<C extends Comparable> implements Predicate<C>, Serializable {
|
|
|
|
private static final Function<Range, Cut> LOWER_BOUND_FN = new Function<Range, Cut>() {
|
|
@Override
|
|
public Cut apply(Range range) {
|
|
return range.lowerBound;
|
|
}
|
|
};
|
|
|
|
@SuppressWarnings("unchecked")
|
|
static <C extends Comparable<?>> Function<Range<C>, Cut<C>> lowerBoundFn() {
|
|
return (Function) LOWER_BOUND_FN;
|
|
}
|
|
|
|
private static final Function<Range, Cut> UPPER_BOUND_FN = new Function<Range, Cut>() {
|
|
@Override
|
|
public Cut apply(Range range) {
|
|
return range.upperBound;
|
|
}
|
|
};
|
|
|
|
@SuppressWarnings("unchecked")
|
|
static <C extends Comparable<?>> Function<Range<C>, Cut<C>> upperBoundFn() {
|
|
return (Function) UPPER_BOUND_FN;
|
|
}
|
|
|
|
static final Ordering<Range<?>> RANGE_LEX_ORDERING = new Ordering<Range<?>>() {
|
|
@Override
|
|
public int compare(Range<?> left, Range<?> right) {
|
|
return ComparisonChain.start().compare(left.lowerBound, right.lowerBound)
|
|
.compare(left.upperBound, right.upperBound).result();
|
|
}
|
|
};
|
|
|
|
static <C extends Comparable<?>> Range<C> create(Cut<C> lowerBound, Cut<C> upperBound) {
|
|
return new Range<C>(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 <i>or equal
|
|
* to</i> {@code upper}
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> 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}
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> 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}
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> 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}
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> 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}
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> range(C lower, BoundType lowerType, C upper, BoundType upperType) {
|
|
checkNotNull(lowerType);
|
|
checkNotNull(upperType);
|
|
|
|
Cut<C> lowerBound = (lowerType == BoundType.OPEN) ? Cut.aboveValue(lower) : Cut.belowValue(lower);
|
|
Cut<C> 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 <C extends Comparable<?>> Range<C> lessThan(C endpoint) {
|
|
return create(Cut.<C>belowAll(), Cut.belowValue(endpoint));
|
|
}
|
|
|
|
/**
|
|
* Returns a range that contains all values less than or equal to
|
|
* {@code endpoint}.
|
|
*
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> atMost(C endpoint) {
|
|
return create(Cut.<C>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 <C extends Comparable<?>> Range<C> 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 <C extends Comparable<?>> Range<C> greaterThan(C endpoint) {
|
|
return create(Cut.aboveValue(endpoint), Cut.<C>aboveAll());
|
|
}
|
|
|
|
/**
|
|
* Returns a range that contains all values greater than or equal to
|
|
* {@code endpoint}.
|
|
*
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> atLeast(C endpoint) {
|
|
return create(Cut.belowValue(endpoint), Cut.<C>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 <C extends Comparable<?>> Range<C> 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<Comparable> ALL = new Range<Comparable>(Cut.belowAll(), Cut.aboveAll());
|
|
|
|
/**
|
|
* Returns a range that contains every value of type {@code C}.
|
|
*
|
|
* @since 14.0
|
|
*/
|
|
@SuppressWarnings("unchecked")
|
|
public static <C extends Comparable<?>> Range<C> 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 <C extends Comparable<?>> Range<C> 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 parameters are not <i>mutually
|
|
* comparable</i>
|
|
* @throws NoSuchElementException if {@code values} is empty
|
|
* @throws NullPointerException if any of {@code values} is null
|
|
* @since 14.0
|
|
*/
|
|
public static <C extends Comparable<?>> Range<C> encloseAll(Iterable<C> values) {
|
|
checkNotNull(values);
|
|
if (values instanceof ContiguousSet) {
|
|
return ((ContiguousSet<C>) values).range();
|
|
}
|
|
Iterator<C> 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<C> lowerBound;
|
|
final Cut<C> upperBound;
|
|
|
|
private Range(Cut<C> lowerBound, Cut<C> upperBound) {
|
|
if (lowerBound.compareTo(upperBound) > 0 || lowerBound == Cut.<C>aboveAll()
|
|
|| upperBound == Cut.<C>belowAll()) {
|
|
throw new IllegalArgumentException("Invalid range: " + toString(lowerBound, upperBound));
|
|
}
|
|
this.lowerBound = checkNotNull(lowerBound);
|
|
this.upperBound = checkNotNull(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 <i>invalid</i> and can't be constructed at all.)
|
|
*
|
|
* <p>
|
|
* Note that certain discrete ranges such as the integer range {@code (3..4)}
|
|
* are <b>not</b> 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<? extends C> values) {
|
|
if (Iterables.isEmpty(values)) {
|
|
return true;
|
|
}
|
|
|
|
// this optimizes testing equality of two range-backed sets
|
|
if (values instanceof SortedSet) {
|
|
SortedSet<? extends C> 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:
|
|
*
|
|
* <ul>
|
|
* <li>{@code [3..6]} encloses {@code [4..5]}
|
|
* <li>{@code (3..6)} encloses {@code (3..6)}
|
|
* <li>{@code [3..6]} encloses {@code [4..4)} (even though the latter is empty)
|
|
* <li>{@code (3..6]} does not enclose {@code [3..6]}
|
|
* <li>{@code [4..5]} does not enclose {@code (3..6)} (even though it contains
|
|
* every value contained by the latter range)
|
|
* <li>{@code [3..6]} does not enclose {@code (1..1]} (even though it contains
|
|
* every value contained by the latter range)
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* 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.
|
|
*
|
|
* <p>
|
|
* Being reflexive, antisymmetric and transitive, the {@code encloses} relation
|
|
* defines a <i>partial order</i> 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<C> 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}.
|
|
*
|
|
* <p>
|
|
* For example,
|
|
* <ul>
|
|
* <li>{@code [2, 4)} and {@code [5, 7)} are not connected
|
|
* <li>{@code [2, 4)} and {@code [3, 5)} are connected, because both enclose
|
|
* {@code [3, 4)}
|
|
* <li>{@code [2, 4)} and {@code [4, 6)} are connected, because both enclose the
|
|
* empty range {@code [4, 4)}
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* 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}.
|
|
*
|
|
* <p>
|
|
* The connectedness relation is both reflexive and symmetric, but does not form
|
|
* an {@linkplain Equivalence equivalence relation} as it is not transitive.
|
|
*
|
|
* <p>
|
|
* 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<C> 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.
|
|
*
|
|
* <p>
|
|
* 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)}.
|
|
*
|
|
* <p>
|
|
* The intersection exists if and only if the two ranges are
|
|
* {@linkplain #isConnected connected}.
|
|
*
|
|
* <p>
|
|
* 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<C> intersection(Range<C> 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<C> newLower = (lowerCmp >= 0) ? lowerBound : connectedRange.lowerBound;
|
|
Cut<C> newUpper = (upperCmp <= 0) ? upperBound : connectedRange.upperBound;
|
|
return create(newLower, newUpper);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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)}.
|
|
*
|
|
* <p>
|
|
* <i>If</i> the input ranges are {@linkplain #isConnected connected}, the
|
|
* returned range can also be called their <i>union</i>. If they are not, note
|
|
* that the span might contain values that are not contained in either input
|
|
* range.
|
|
*
|
|
* <p>
|
|
* 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<C> span(Range<C> 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<C> newLower = (lowerCmp <= 0) ? lowerBound : other.lowerBound;
|
|
Cut<C> 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:
|
|
*
|
|
* <ul>
|
|
* <li>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))}
|
|
* <li>uniqueness: unless {@code a.isEmpty()},
|
|
* {@code ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, domain))}
|
|
* implies {@code a.canonical(domain).equals(b.canonical(domain))}
|
|
* <li>idempotence:
|
|
* {@code a.canonical(domain).canonical(domain).equals(a.canonical(domain))}
|
|
* </ul>
|
|
*
|
|
* <p>
|
|
* Furthermore, this method guarantees that the range returned will be one of
|
|
* the following canonical forms:
|
|
*
|
|
* <ul>
|
|
* <li>[start..end)
|
|
* <li>[start..+∞)
|
|
* <li>(-∞..end) (only if type {@code C} is unbounded below)
|
|
* <li>(-∞..+∞) (only if type {@code C} is unbounded below)
|
|
* </ul>
|
|
*/
|
|
public Range<C> canonical(DiscreteDomain<C> domain) {
|
|
checkNotNull(domain);
|
|
Cut<C> lower = lowerBound.canonical(domain);
|
|
Cut<C> 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 <b>not</b> 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('\u2025');
|
|
upperBound.describeAsUpperBound(sb);
|
|
return sb.toString();
|
|
}
|
|
|
|
/**
|
|
* Used to avoid http://bugs.sun.com/view_bug.do?bug_id=6558557
|
|
*/
|
|
private static <T> SortedSet<T> cast(Iterable<T> iterable) {
|
|
return (SortedSet<T>) 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);
|
|
}
|
|
|
|
private static final long serialVersionUID = 0;
|
|
}
|