

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object com.google.common.collect.Range<C>
@GwtCompatible @Beta public final class Range<C extends Comparable>
A range, sometimes known as an interval, is a convex
(informally, "contiguous" or "unbroken") portion of a particular domain.
Formally, convexity means that for any a <= b <= c
,
range.contains(a) && range.contains(c)
implies that range.contains(b)
.
A range is characterized by its lower and upper bounds (extremes), each of which can open (exclusive of its endpoint), closed (inclusive of its endpoint), or unbounded. This yields nine basic types of ranges:
(a..b) = {x  a < x < b}
[a..b] = {x  a <= x <= b}
[a..b) = {x  a <= x < b}
(a..b] = {x  a < x <= b}
(a..+∞) = {x  x > a}
[a..+∞) = {x  x >= a}
(∞..b) = {x  x < b}
(∞..b] = {x  x <= b}
(∞..+∞) = all values
{x  statement}
is read "the set of all x such
that statement.")
Notice that we use a square bracket ([ ]
) to denote that an range
is closed on that end, and a parenthesis (( )
) when it is open or
unbounded.
The values a
and b
used above are called endpoints.
The upper endpoint may not be less than the lower endpoint. The endpoints may
be equal only if at least one of the bounds is closed:
[a..a]
: singleton range
[a..a); (a..a]
: empty, but valid
(a..a)
: invalid
Instances of this type can be obtained using the static factory methods in
the Ranges
class.
Instances of Range
are immutable. It is strongly encouraged to
use this class only with immutable data types. When creating a range over a
mutable type, take great care not to allow the value objects to mutate after
the range is created.
In this and other rangerelated specifications, concepts like "equal",
"same", "unique" and so on are based on Comparable.compareTo(T)
returning zero, not on Object.equals(java.lang.Object)
returning true
. Of
course, when these methods are kept consistent (as defined in Comparable
), this is not an issue.
A range a
is said to be the maximal range having property
P if, for all ranges b
also having property P, a.encloses(b)
. Likewise, a
is minimal when b.encloses(a)
for all b
having property P. See, for example,
the definition of intersection(com.google.common.collect.Range
.
This class can be used with any type which implements Comparable
;
it does not require Comparable<? super C>
because this would be
incompatible with preJava 5 types. If this class is used with a perverse
Comparable
type (Foo implements Comparable<Bar>
where Bar
is not a supertype of Foo
), any of its methods may throw ClassCastException
. (There is no good reason for such a type to exist.)
When evaluated as a Predicate
, a range yields the same result as
invoking contains(C)
.
Method Summary  

boolean 
apply(C input)
Equivalent to contains(C) ; provided only to satisfy the Predicate interface. 
ContiguousSet<C> 
asSet(DiscreteDomain<C> domain)
Returns an ImmutableSortedSet containing the same values in the
given domain contained by this range. 
Range<C> 
canonical(DiscreteDomain<C> domain)
Returns the canonical form of this range in the given domain. 
boolean 
contains(C value)
Returns true if value is within the bounds of this
range. 
boolean 
containsAll(Iterable<? extends C> values)
Returns true if every element in values is contained in this range. 
boolean 
encloses(Range<C> other)
Returns true if the bounds of other do not extend outside
the bounds of this range. 
boolean 
equals(Object object)
Returns true if object is a range having the same
endpoints and bound types as this range. 
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> other)
Returns the maximal range enclosed by both this range and other , 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] . 
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. 
Range<C> 
span(Range<C> other)
Returns the minimal range that encloses both this range and other . 
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. 
Methods inherited from class java.lang.Object 

clone, finalize, getClass, notify, notifyAll, wait, wait, wait 
Method Detail 

public boolean hasLowerBound()
true
if this range has a lower endpoint.
public C lowerEndpoint()
IllegalStateException
 if this range is unbounded below (that is,
hasLowerBound()
returns false
)public BoundType lowerBoundType()
BoundType.CLOSED
if
the range includes its lower endpoint, BoundType.OPEN
if it does
not.
IllegalStateException
 if this range is unbounded below (that is,
hasLowerBound()
returns false
)public boolean hasUpperBound()
true
if this range has an upper endpoint.
public C upperEndpoint()
IllegalStateException
 if this range is unbounded above (that is,
hasUpperBound()
returns false
)public BoundType upperBoundType()
BoundType.CLOSED
if
the range includes its upper endpoint, BoundType.OPEN
if it does
not.
IllegalStateException
 if this range is unbounded above (that is,
hasUpperBound()
returns false
)public boolean isEmpty()
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.
public boolean contains(C value)
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
.
public boolean apply(C input)
contains(C)
; provided only to satisfy the Predicate
interface. When using a reference of type Range
, always
invoke contains(C)
directly instead.
apply
in interface Predicate<C extends Comparable>
public boolean containsAll(Iterable<? extends C> values)
true
if every element in values
is contained in this range.
public boolean encloses(Range<C> other)
true
if the bounds of other
do not extend outside
the bounds of this range. Examples:
[3..6]
encloses [4..5]
(3..6)
encloses (3..6)
[3..6]
encloses [4..4)
(even though the latter is
empty)
(3..6]
does not enclose [3..6]
[4..5]
does not enclose (3..6)
(even though it contains
every value contained by the latter range)
[3..6]
does not enclose (1..1]
(even though it contains
every value contained by the latter range)
a.encloses(b)
, then b.contains(v)
implies
a.contains(v)
, but as the last two examples illustrate, the
converse is not always true.
The encloses relation has the following properties:
a.encloses(a)
is always true
a.encloses(b) && b.encloses(a)
implies a.equals(b)
a.encloses(b) && b.encloses(c)
implies a.encloses(c)
!a.encloses(b)
does not imply b.encloses(a)
encloses
is always true
encloses(b)
is always false when !equals(b)
a.encloses(b)
, then a.isConnected(b)
is true
.
public Range<C> intersection(Range<C> other)
other
, 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)
.
Generally, the intersection exists if and only if this range and
other
are connected.
The intersection operation has the following properties:
a.intersection(b)
produces the same result as
b.intersection(a)
a.intersection(b).intersection(c)
produces the
same result as a.intersection(b.intersection(c))
a.intersection(a)
equals a
Ranges.all()
): a.intersection(Ranges.all())
equals a
IllegalArgumentException
 if no range exists that is enclosed by
both these rangespublic boolean isConnected(Range<C> other)
true
if there exists a (possibly empty) range which is
enclosed by both this range and other
.
For example,
[2, 4)
and [5, 7)
are not connected
[2, 4)
and [3, 5)
are connected, because both enclose
[3, 4)
[2, 4)
and [4, 6)
are connected, because both enclose
the empty range [4, 4)
Note that this range and other
have a welldefined union and intersection (as a single,
possiblyempty range) if and only if this method returns true
.
The connectedness relation has the following properties:
a.isConnected(b)
produces the same result as
b.isConnected(a)
a.isConnected(a)
returns true
public Range<C> span(Range<C> other)
other
. For example, the span of [1..3]
and
(5..7)
is [1..7)
. Note that the span may contain values
that are not contained by either original range.
The span operation has the following properties:
a.span(b)
exists for all ranges a
and
b
a.span(b)
equals b.span(a)
a.span(b).span(c)
equals a.span(b.span(c))
a.span(a)
equals a
Note that the returned range is also called the union of this
range and other
if and only if the ranges are
connected.
@GwtCompatible(serializable=false) public ContiguousSet<C> asSet(DiscreteDomain<C> domain)
ImmutableSortedSet
containing the same values in the
given domain contained by this range.
Note: a.asSet().equals(b.asSet())
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 Ranges.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 shorthand
form of set's contents such as "[1..100]
"}.
IllegalArgumentException
 if neither this range nor the domain has a
lower bound, or if neither has an upper boundpublic Range<C> canonical(DiscreteDomain<C> domain)
a.canonical().contains(v) == a.contains(v)
for
all v
(in other words, a.canonical(domain).asSet(domain).equals(a.asSet(domain))
a.isEmpty()
,
a.asSet(domain).equals(b.asSet(domain))
implies
a.canonical(domain).equals(b.canonical(domain))
a.canonical(domain).canonical(domain).equals(a.canonical(domain))
C
is unbounded below)
C
is unbounded below)
public boolean equals(@Nullable Object object)
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.
equals
in interface Predicate<C extends Comparable>
equals
in class Object
public int hashCode()
hashCode
in class Object
public String toString()
"[3..5)"
(other examples are listed in the class documentation).
toString
in class Object


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 