@GwtCompatible public final class Range<C extends Comparable> extends Object implements Predicate<C>, Serializable
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<C>, com.google.common.collect.DiscreteDomain<C>)
.
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:
[a..a]
: a singleton range
[a..a); (a..a]
: empty ranges; also valid
(a..a)
: invalid; an exception will be thrown
compareTo
returns zero, not whether equals
returns true
.
Comparable<UnrelatedType>
is very broken, and will cause
undefined horrible things to happen in Range
. For now, the Range API does not prevent
its use, because this would also rule out all ungenerified (preJDK1.5) data types. This
may change in the future.
c1 <= c2 <= c3
of type C
, r.contains(c1) && r.contains(c3)
implies r.contains(c2)
). This means that a Range<Integer>
can never be used to represent, say, "all prime numbers from 1 to
100."
Predicate
, a range yields the same result as invoking contains(C)
.
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
.
See the Guava User Guide article on
Range
.
Modifier and Type  Method and Description 

static <C extends Comparable<?>> 
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 Comparable<?>> 
atLeast(C endpoint)
Returns a range that contains all values greater than or equal to
endpoint . 
static <C extends Comparable<?>> 
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 Comparable<?>> 
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 Comparable<?>> 
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(Iterable<? extends C> values)

static <C extends Comparable<?>> 
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 Comparable<?>> 
encloseAll(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(Object object)
Returns
true if object is a range having the same endpoints and bound types as
this range. 
static <C extends Comparable<?>> 
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 Comparable<?>> 
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 Comparable<?>> 
open(C lower,
C upper)
Returns a range that contains all values strictly greater than
lower and strictly less than upper . 
static <C extends Comparable<?>> 
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 Comparable<?>> 
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 Comparable<?>> 
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 . 
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 Comparable<?>> 
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).

public static <C extends Comparable<?>> Range<C> open(C lower, C upper)
lower
and strictly less than upper
.IllegalArgumentException
 if lower
is greater than or
equal to upper
public static <C extends Comparable<?>> Range<C> closed(C lower, C upper)
lower
and less than or equal to upper
.IllegalArgumentException
 if lower
is greater than upper
public static <C extends Comparable<?>> Range<C> closedOpen(C lower, C upper)
lower
and strictly less than upper
.IllegalArgumentException
 if lower
is greater than upper
public static <C extends Comparable<?>> Range<C> openClosed(C lower, C upper)
lower
and less than or equal to upper
.IllegalArgumentException
 if lower
is greater than upper
public static <C extends Comparable<?>> Range<C> range(C lower, BoundType lowerType, C upper, BoundType upperType)
lower
to upper
, where each endpoint may be either inclusive (closed) or exclusive
(open).IllegalArgumentException
 if lower
is greater than upper
public static <C extends Comparable<?>> Range<C> lessThan(C endpoint)
endpoint
.public static <C extends Comparable<?>> Range<C> atMost(C endpoint)
endpoint
.public static <C extends Comparable<?>> Range<C> upTo(C endpoint, BoundType boundType)
public static <C extends Comparable<?>> Range<C> greaterThan(C endpoint)
endpoint
.public static <C extends Comparable<?>> Range<C> atLeast(C endpoint)
endpoint
.public static <C extends Comparable<?>> Range<C> downTo(C endpoint, BoundType boundType)
public static <C extends Comparable<?>> Range<C> all()
C
.public static <C extends Comparable<?>> Range<C> singleton(C value)
public static <C extends Comparable<?>> Range<C> encloseAll(Iterable<C> values)
ClassCastException
 if the parameters are not mutually
comparableNoSuchElementException
 if values
is emptyNullPointerException
 if any of values
is nullpublic 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. In these cases, it may be
helpful to preprocess ranges with canonical(DiscreteDomain)
.
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)
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.
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.
public 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 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.
public Range<C> intersection(Range<C> connectedRange)
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()
).
IllegalArgumentException
 if isConnected(connectedRange)
is false
public Range<C> span(Range<C> other)
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 welldefined for any two input ranges.
@Beta @GwtCompatible(serializable=false) @Deprecated public ContiguousSet<C> asSet(DiscreteDomain<C> domain)
ContiguousSet.create(range, domain)
instead.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 shorthand form of the 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, ContiguousSet.create(a.canonical(domain), domain).equals(
ContiguousSet.create(a, domain))
a.isEmpty()
,
ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, 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.public int hashCode()
Copyright © 20102013. All Rights Reserved.