com.google.common.collect
Class Range<C extends java.lang.Comparable>

java.lang.Object
  extended by com.google.common.collect.Range<C>
All Implemented Interfaces:
Predicate<C>, java.io.Serializable

@GwtCompatible
public final class Range<C extends java.lang.Comparable>
extends java.lang.Object
implements Predicate<C>, java.io.Serializable

A range (or "interval") defines the boundaries around a contiguous span of values of some 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 DiscreteDomain to ContiguousSet.create(com.google.common.collect.Range, com.google.common.collect.DiscreteDomain).

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 ([ ]) indicates that the range is closed on that side; a parenthesis (( )) means it is either open or unbounded. The construct {x | statement} is read "the set of all x such that statement.")

Notation Definition Factory method
(a..b) {x | a < x < b} open
[a..b] {x | a <= x <= b}closed
(a..b] {x | a < x <= b} openClosed
[a..b) {x | a <= x < b} closedOpen
(a..+???) {x | x > a} greaterThan
[a..+???) {x | x >= a} atLeast
(-???..b) {x | x < b} lessThan
(-???..b] {x | x <= b} atMost
(-???..+???){x} 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:

Warnings

Other notes

Further reading

See the Guava User Guide article on Range.

Since:
10.0
See Also:
Serialized Form

Method Summary
static
<C extends java.lang.Comparable<?>>
Range<C>
all()
          Returns a range that contains every value of type C.
 boolean apply(C input)
          Equivalent to contains(C); provided only to satisfy the Predicate interface.
 ContiguousSet<C> asSet(DiscreteDomain<C> domain)
          Deprecated. Use ContiguousSet.create(range, domain) instead.
static
<C extends java.lang.Comparable<?>>
Range<C>
atLeast(C endpoint)
          Returns a range that contains all values greater than or equal to endpoint.
static
<C extends java.lang.Comparable<?>>
Range<C>
atMost(C endpoint)
          Returns a range that contains all values less than or equal to endpoint.
 Range<C> canonical(DiscreteDomain<C> domain)
          Returns the canonical form of this range in the given domain.
static
<C extends java.lang.Comparable<?>>
Range<C>
closed(C lower, C upper)
          Returns a range that contains all values greater than or equal to lower and less than or equal to upper.
static
<C extends java.lang.Comparable<?>>
Range<C>
closedOpen(C lower, C upper)
          Returns a range that contains all values greater than or equal to lower and strictly less than upper.
 boolean contains(C value)
          Returns true if value is within the bounds of this range.
 boolean containsAll(java.lang.Iterable<? extends C> values)
          Returns true if every element in values is contained in this range.
static
<C extends java.lang.Comparable<?>>
Range<C>
downTo(C endpoint, BoundType boundType)
          Returns a range from the given endpoint, which may be either inclusive (closed) or exclusive (open), with no upper bound.
static
<C extends java.lang.Comparable<?>>
Range<C>
encloseAll(java.lang.Iterable<C> values)
          Returns the minimal range that contains all of the given values.
 boolean encloses(Range<C> other)
          Returns true if the bounds of other do not extend outside the bounds of this range.
 boolean equals(java.lang.Object object)
          Returns true if object is a range having the same endpoints and bound types as this range.
static
<C extends java.lang.Comparable<?>>
Range<C>
greaterThan(C endpoint)
          Returns a range that contains all values strictly greater than endpoint.
 int hashCode()
          Returns a hash code for this range.
 boolean hasLowerBound()
          Returns true if this range has a lower endpoint.
 boolean hasUpperBound()
          Returns true if this range has an upper endpoint.
 Range<C> intersection(Range<C> connectedRange)
          Returns the maximal range enclosed by both this range and connectedRange, if such a range exists.
 boolean isConnected(Range<C> other)
          Returns true if there exists a (possibly empty) range which is enclosed by both this range and other.
 boolean isEmpty()
          Returns true if this range is of the form [v..v) or (v..v].
static
<C extends java.lang.Comparable<?>>
Range<C>
lessThan(C endpoint)
          Returns a range that contains all values strictly less than endpoint.
 BoundType lowerBoundType()
          Returns the type of this range's lower bound: BoundType.CLOSED if the range includes its lower endpoint, BoundType.OPEN if it does not.
 C lowerEndpoint()
          Returns the lower endpoint of this range.
static
<C extends java.lang.Comparable<?>>
Range<C>
open(C lower, C upper)
          Returns a range that contains all values strictly greater than lower and strictly less than upper.
static
<C extends java.lang.Comparable<?>>
Range<C>
openClosed(C lower, C upper)
          Returns a range that contains all values strictly greater than lower and less than or equal to upper.
static
<C extends java.lang.Comparable<?>>
Range<C>
range(C lower, BoundType lowerType, C upper, BoundType upperType)
          Returns a range that contains any value from lower to upper, where each endpoint may be either inclusive (closed) or exclusive (open).
static
<C extends java.lang.Comparable<?>>
Range<C>
singleton(C value)
          Returns a range that contains only the given value.
 Range<C> span(Range<C> other)
          Returns the minimal range that encloses both this range and other.
 java.lang.String toString()
          Returns a string representation of this range, such as "[3..5)" (other examples are listed in the class documentation).
 BoundType upperBoundType()
          Returns the type of this range's upper bound: BoundType.CLOSED if the range includes its upper endpoint, BoundType.OPEN if it does not.
 C upperEndpoint()
          Returns the upper endpoint of this range.
static
<C extends java.lang.Comparable<?>>
Range<C>
upTo(C endpoint, BoundType boundType)
          Returns a range with no lower bound up to the given endpoint, which may be either inclusive (closed) or exclusive (open).
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

open

public static <C extends java.lang.Comparable<?>> Range<C> open(C lower,
                                                                C upper)
Returns a range that contains all values strictly greater than lower and strictly less than upper.

Throws:
java.lang.IllegalArgumentException - if lower is greater than or equal to upper
Since:
14.0

closed

public static <C extends java.lang.Comparable<?>> Range<C> closed(C lower,
                                                                  C upper)
Returns a range that contains all values greater than or equal to lower and less than or equal to upper.

Throws:
java.lang.IllegalArgumentException - if lower is greater than upper
Since:
14.0

closedOpen

public static <C extends java.lang.Comparable<?>> Range<C> closedOpen(C lower,
                                                                      C upper)
Returns a range that contains all values greater than or equal to lower and strictly less than upper.

Throws:
java.lang.IllegalArgumentException - if lower is greater than upper
Since:
14.0

openClosed

public static <C extends java.lang.Comparable<?>> Range<C> openClosed(C lower,
                                                                      C upper)
Returns a range that contains all values strictly greater than lower and less than or equal to upper.

Throws:
java.lang.IllegalArgumentException - if lower is greater than upper
Since:
14.0

range

public static <C extends java.lang.Comparable<?>> Range<C> range(C lower,
                                                                 BoundType lowerType,
                                                                 C upper,
                                                                 BoundType upperType)
Returns a range that contains any value from lower to upper, where each endpoint may be either inclusive (closed) or exclusive (open).

Throws:
java.lang.IllegalArgumentException - if lower is greater than upper
Since:
14.0

lessThan

public static <C extends java.lang.Comparable<?>> Range<C> lessThan(C endpoint)
Returns a range that contains all values strictly less than endpoint.

Since:
14.0

atMost

public static <C extends java.lang.Comparable<?>> Range<C> atMost(C endpoint)
Returns a range that contains all values less than or equal to endpoint.

Since:
14.0

upTo

public static <C extends java.lang.Comparable<?>> Range<C> upTo(C endpoint,
                                                                BoundType boundType)
Returns a range with no lower bound up to the given endpoint, which may be either inclusive (closed) or exclusive (open).

Since:
14.0

greaterThan

public static <C extends java.lang.Comparable<?>> Range<C> greaterThan(C endpoint)
Returns a range that contains all values strictly greater than endpoint.

Since:
14.0

atLeast

public static <C extends java.lang.Comparable<?>> Range<C> atLeast(C endpoint)
Returns a range that contains all values greater than or equal to endpoint.

Since:
14.0

downTo

public static <C extends java.lang.Comparable<?>> Range<C> downTo(C endpoint,
                                                                  BoundType boundType)
Returns a range from the given endpoint, which may be either inclusive (closed) or exclusive (open), with no upper bound.

Since:
14.0

all

public static <C extends java.lang.Comparable<?>> Range<C> all()
Returns a range that contains every value of type C.

Since:
14.0

singleton

public static <C extends java.lang.Comparable<?>> Range<C> singleton(C value)
Returns a range that contains only the given value. The returned range is closed on both ends.

Since:
14.0

encloseAll

public static <C extends java.lang.Comparable<?>> Range<C> encloseAll(java.lang.Iterable<C> values)
Returns the minimal range that contains all of the given values. The returned range is closed on both ends.

Throws:
java.lang.ClassCastException - if the parameters are not mutually comparable
java.util.NoSuchElementException - if values is empty
java.lang.NullPointerException - if any of values is null
Since:
14.0

hasLowerBound

public boolean hasLowerBound()
Returns true if this range has a lower endpoint.


lowerEndpoint

public C lowerEndpoint()
Returns the lower endpoint of this range.

Throws:
java.lang.IllegalStateException - if this range is unbounded below (that is, hasLowerBound() returns false)

lowerBoundType

public BoundType lowerBoundType()
Returns the type of this range's lower bound: BoundType.CLOSED if the range includes its lower endpoint, BoundType.OPEN if it does not.

Throws:
java.lang.IllegalStateException - if this range is unbounded below (that is, hasLowerBound() returns false)

hasUpperBound

public boolean hasUpperBound()
Returns true if this range has an upper endpoint.


upperEndpoint

public C upperEndpoint()
Returns the upper endpoint of this range.

Throws:
java.lang.IllegalStateException - if this range is unbounded above (that is, hasUpperBound() returns false)

upperBoundType

public BoundType upperBoundType()
Returns the type of this range's upper bound: BoundType.CLOSED if the range includes its upper endpoint, BoundType.OPEN if it does not.

Throws:
java.lang.IllegalStateException - if this range is unbounded above (that is, hasUpperBound() returns false)

isEmpty

public boolean isEmpty()
Returns true if this range is of the form [v..v) or (v..v]. (This does not encompass ranges of the form (v..v), because such ranges are invalid and can't be constructed at all.)

Note that certain discrete ranges such as the integer range (3..4) are not considered empty, even though they contain no actual values. In these cases, it may be helpful to preprocess ranges with canonical(DiscreteDomain).


contains

public boolean contains(C value)
Returns true if value is within the bounds of this range. For example, on the range [0..2), contains(1) returns true, while contains(2) returns false.


apply

public boolean apply(C input)
Equivalent to contains(C); provided only to satisfy the Predicate interface. When using a reference of type Range, always invoke contains(C) directly instead.

Specified by:
apply in interface Predicate<C extends java.lang.Comparable>

containsAll

public boolean containsAll(java.lang.Iterable<? extends C> values)
Returns true if every element in values is contained in this range.


encloses

public boolean encloses(Range<C> other)
Returns true if the bounds of other do not extend outside the bounds of this range. Examples: Note that if a.encloses(b), then b.contains(v) implies a.contains(v), but as the last two examples illustrate, the converse is not always true.

Being reflexive, antisymmetric and transitive, the encloses relation defines a partial order over ranges. There exists a unique maximal range according to this relation, and also numerous minimal ranges. Enclosure also implies connectedness.


isConnected

public boolean isConnected(Range<C> other)
Returns true if there exists a (possibly empty) range which is enclosed by both this range and other.

For example,

Note that this range and other have a well-defined union and intersection (as a single, possibly-empty range) if and only if this method returns true.

The connectedness relation is both reflexive and symmetric, but does not form an 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, [3, 5] is not considered connected to [6, 10]. In these cases, it may be desirable for both input ranges to be preprocessed with canonical(DiscreteDomain) before testing for connectedness.


intersection

public Range<C> intersection(Range<C> connectedRange)
Returns the maximal range enclosed by both this range and connectedRange, if such a range exists.

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

The intersection exists if and only if the two ranges are connected.

The intersection operation is commutative, associative and idempotent, and its identity element is all()).

Throws:
java.lang.IllegalArgumentException - if isConnected(connectedRange) is false

span

public Range<C> span(Range<C> other)
Returns the minimal range that encloses both this range and other. For example, the span of [1..3] and (5..7) is [1..7).

If the input ranges are 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 intersection, this operation is commutative, associative and idempotent. Unlike it, it is always well-defined for any two input ranges.


asSet

@Beta
@GwtCompatible(serializable=false)
@Deprecated
public ContiguousSet<C> asSet(DiscreteDomain<C> domain)
Deprecated. Use ContiguousSet.create(range, domain) instead.

Returns an ContiguousSet containing the same values in the given domain contained by this range.

Note: a.asSet(d).equals(b.asSet(d)) does not imply a.equals(b)! For example, a and b could be [2..4] and (1..5), or the empty ranges [3..3) and [4..4).

Warning: Be extremely careful what you do with the asSet view of a large range (such as Range.greaterThan(0)). Certain operations on such a set can be performed efficiently, but others (such as Set.hashCode() or Collections.frequency(java.util.Collection, java.lang.Object)) can cause major performance problems.

The returned set's Object.toString() method returns a short-hand form of the set's contents, such as "[1..100]"}.

Throws:
java.lang.IllegalArgumentException - if neither this range nor the domain has a lower bound, or if neither has an upper bound

canonical

public Range<C> canonical(DiscreteDomain<C> domain)
Returns the canonical form of this range in the given domain. The canonical form has the following properties: Furthermore, this method guarantees that the range returned will be one of the following canonical forms:


equals

public boolean equals(@Nullable
                      java.lang.Object object)
Returns true if object is a range having the same endpoints and bound types as this range. Note that discrete ranges such as (1..4) and [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 [3..3), (3..3], (4..4] are all unequal.

Specified by:
equals in interface Predicate<C extends java.lang.Comparable>
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Returns a hash code for this range.

Overrides:
hashCode in class java.lang.Object

toString

public java.lang.String toString()
Returns a string representation of this range, such as "[3..5)" (other examples are listed in the class documentation).

Overrides:
toString in class java.lang.Object