Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

    java.lang.Object
      com.google.common.collect.Range<C>

All Implemented Interfaces:
  Predicate<C>, Serializable

    @GwtCompatible
    @Beta
    public final class Range<C extends Comparable>

extends Object
implements Predicate<C>, Serializable

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`

(The notation `{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 range-related 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 pre-Java 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)`.

Since:
  10.0
Author:
  Kevin Bourrillion, Gregory Kick
See Also:
  Serialized Form

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

### 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:
    `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:
    `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:
    `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:
    `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.

### 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 Comparable>`

### containsAll

    public boolean containsAll(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:
  - `[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)
  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.

  The encloses relation has the following properties:

  - reflexive: `a.encloses(a)` is always true
  - antisymmetric: `a.encloses(b) && b.encloses(a)` implies `a.equals(b)`
  - transitive: `a.encloses(b) && b.encloses(c)` implies `a.encloses(c)`
  - not a total ordering: `!a.encloses(b)` does not imply `b.encloses(a)`
  - there exists a maximal range, for which `encloses` is always true
  - there also exist minimal ranges, for which `encloses(b)` is always false when `!equals(b)`
  - if `a.encloses(b)`, then `a.isConnected(b)` is `true`.

### intersection

    public Range<C> intersection(Range<C> other)

  Returns the maximal range enclosed by both this range and `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:

  - commutative: `a.intersection(b)` produces the same result as `b.intersection(a)`
  - associative: `a.intersection(b).intersection(c)` produces the same result as `a.intersection(b.intersection(c))`
  - idempotent: `a.intersection(a)` equals `a`
  - identity (`Ranges.all()`): `a.intersection(Ranges.all())` equals `a`

  Throws:
    `IllegalArgumentException` - if no range exists that is enclosed by both these ranges

### 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,

  - `[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 well-defined union and intersection (as a single, possibly-empty range) if and only if this method returns `true`.

  The connectedness relation has the following properties:

  - symmetric: `a.isConnected(b)` produces the same result as `b.isConnected(a)`
  - reflexive: `a.isConnected(a)` returns `true`

### 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)`. Note that the span may contain values that are not contained by either original range.

  The span operation has the following properties:

  - closed: the range `a.span(b)` exists for all ranges `a` and `b`
  - commutative: `a.span(b)` equals `b.span(a)`
  - associative: `a.span(b).span(c)` equals `a.span(b.span(c))`
  - idempotent: `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.

### asSet

    @GwtCompatible(serializable=false)
    public ContiguousSet<C> asSet(DiscreteDomain<C> domain)

  Returns an `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 short-hand form of set's contents such as `"[1..100]`"}.

  Throws:
    `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:
  - equivalence: `a.canonical().contains(v) == a.contains(v)` for all `v` (in other words, `a.canonical(domain).asSet(domain).equals(a.asSet(domain))`
  - uniqueness: unless `a.isEmpty()`, `a.asSet(domain).equals(b.asSet(domain))` implies `a.canonical(domain).equals(b.canonical(domain))`
  - idempotence: `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 `C` is unbounded below)
  - (-∞..+∞) (only if type `C` is unbounded below)

### equals

    public boolean equals(@Nullable
                          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 Comparable>`
  Overrides:
    `equals` in class `Object`

### hashCode

    public int hashCode()

  Returns a hash code for this range.

  Overrides:
    `hashCode` in class `Object`

### toString

    public 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 `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010-2011. All Rights Reserved.