org.feijoas.mango.common.collect

Range

Related Docs: object Range | package collect

final class Range[T, O <: Ordering[T]] extends (T) ⇒ Boolean with Serializable

A range (or "interval") defines the boundaries around a contiguous span of values of some type which an Ordering exists; 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.

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}    Range#open
[a..b]        {x | a <= x <= b}  Range#closed
(a..b]        {x | a < x <= b}   Range#openClosed
[a..b)        {x | a <= x < b}   Range#closedOpen
(a..+inf)     {x | x > a}        Range#greaterThan
[a..+inf)     {x | x >= a}       Range#atLeast
(-inf..b)     {x | x < b}        Range#lessThan
(-inf..b]     {x | x <= b}       Range#atMost
(-inf..+inf)  {x}                Range#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
Pattern matching

Extractors are defined for general ranges with finite and infinite bounds.

Usage example:

val range = Range.atLeast(6) // Range[Int,math.Ordering.Int.type] = [6..inf)
range match {
   case Range(FiniteBound(lower, lowerType),InfiniteBound) =>
   // matches lower = 6
   //         lowerType = Closed
}
Difference between Mango and Guava implementation

Since most Scala classes don't implement Ordered a Range of type T needs a "companion" type class of Ordering[T].

Further reading

See the Guava User Guide article on Range.

Annotations
@SerialVersionUID()
Since

0.8 (copied from Guava-libraries)

Linear Supertypes
Serializable, Serializable, (T) ⇒ Boolean, AnyRef, Any
Ordering
  1. Alphabetic
  2. By inheritance
Inherited
  1. Range
  2. Serializable
  3. Serializable
  4. Function1
  5. AnyRef
  6. Any
  1. Hide All
  2. Show all
Learn more about member selection
Visibility
  1. Public
  2. All

Value Members

  1. final def !=(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any
  2. final def ##(): Int

    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean

    Definition Classes
    AnyRef → Any
  4. def andThen[A](g: (Boolean) ⇒ A): (T) ⇒ A

    Definition Classes
    Function1
    Annotations
    @unspecialized()
  5. final def apply(input: T): Boolean

    Equivalent to #contains; provided only to satisfy the Predicate (T => Boolean) interface.

    Equivalent to #contains; provided only to satisfy the Predicate (T => Boolean) interface. When using a reference of type Range, always invoke #contains directly instead.

    Definition Classes
    Range → Function1
  6. final def asInstanceOf[T0]: T0

    Definition Classes
    Any
  7. def canonical(domain: DiscreteDomain[T]): Range[T, O]

    Returns the canonical form of this range in the given 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, ContiguousSet.create(a.canonical(domain), domain).equals( ContiguousSet.create(a, domain))
    • uniqueness: unless a.isEmpty(), ContiguousSet.create(a, domain).equals(ContiguousSet.create(b, 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)
  8. def clone(): AnyRef

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  9. def compose[A](g: (A) ⇒ T): (A) ⇒ Boolean

    Definition Classes
    Function1
    Annotations
    @unspecialized()
  10. def contains(value: T): Boolean

    Returns true if value is within the bounds of this range.

    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.

  11. def containsAll(values: Iterable[T]): Boolean

    Returns true if every element in values is contained in this range.

    Returns true if every element in values is contained in this range.

  12. def encloses(other: Range[T, O]): Boolean

    Returns true if the bounds of other do not extend outside the bounds of this range.

    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.

    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.

  13. final def eq(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  14. def equals(that: Any): Boolean

    Definition Classes
    Range → AnyRef → Any
  15. def finalize(): Unit

    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  16. final def getClass(): Class[_]

    Definition Classes
    AnyRef → Any
  17. def hasLowerBound(): Boolean

    Returns true if this range has a lower endpoint.

    Returns true if this range has a lower endpoint.

  18. def hasUpperBound(): Boolean

    Returns true if this range has an upper endpoint.

    Returns true if this range has an upper endpoint.

  19. def hashCode(): Int

    Definition Classes
    Range → AnyRef → Any
  20. def intersection(connectedRange: Range[T, O]): Range[T, O]

    Returns the maximal range enclosed by both this range and connectedRange, if such a range exists.

    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 Range#all.

    Annotations
    @throws( ... )
    Exceptions thrown

    IllegalArgumentException if isConnected(connectedRange) is false

  21. def isConnected(other: Range[T, O]): Boolean

    Returns true if there exists a (possibly empty) range which is enclosed by both this range and 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 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.

  22. def isEmpty(): Boolean

    Returns true if this range is of the form [v..v) or (v..v].

    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).

  23. final def isInstanceOf[T0]: Boolean

    Definition Classes
    Any
  24. final def ne(arg0: AnyRef): Boolean

    Definition Classes
    AnyRef
  25. final def notify(): Unit

    Definition Classes
    AnyRef
  26. final def notifyAll(): Unit

    Definition Classes
    AnyRef
  27. def span(other: Range[T, O]): Range[T, O]

    Returns the minimal range that encloses both this range and 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.

  28. final def synchronized[T0](arg0: ⇒ T0): T0

    Definition Classes
    AnyRef
  29. def toString(): String

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

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

    Definition Classes
    Range → Function1 → AnyRef → Any
  30. final def wait(): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  31. final def wait(arg0: Long, arg1: Int): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  32. final def wait(arg0: Long): Unit

    Definition Classes
    AnyRef
    Annotations
    @throws( ... )

Inherited from Serializable

Inherited from Serializable

Inherited from (T) ⇒ Boolean

Inherited from AnyRef

Inherited from Any

Ungrouped