javadoc.com.google.common.collect.Range.html Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of guava-osgi

Repackaging of Google Guava libraries as OSGi bundle

The newest version!








Range (Guava: Google Core Libraries for Java 11.0.1 API)























  
      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-2012. All Rights Reserved.

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.

javadoc.com.google.common.collect.Range.html Maven / Gradle / Ivy

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

hasLowerBound

lowerEndpoint

lowerBoundType

hasUpperBound

upperEndpoint

upperBoundType

isEmpty

contains

apply

containsAll

encloses

intersection

isConnected

span

asSet

canonical

equals

hashCode

toString

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