Range (groovy 2.5.0 API)
Date: 2018-05-27

Package: groovy.lang

## [Java] Interface Range<T extends Comparable>

- java.lang.Iterable

- All Superinterfaces:
    Collection, Iterable

  A Range represents the list of discrete items between some starting (or `from`) value and working up towards some ending (or `to`) value. For a reverse range, the list is obtained by starting at the `to` value and working down towards the `from` value. The concept of working up and working down is dependent on the range implementation. In the general case, working up involves successive calls to the first item's `next()` method while working down involves calling the `previous()` method. Optimized numerical ranges may apply numeric addition or subtraction of some numerical step size. Particular range implementations may also support the notion of inclusivity and exclusivity with respect to the ending value in the range. E.g. `1..3 == [1, 2, 3]`; but `1..<3 == [1, 2]`. In general, the second boundary may not be contained in the range, and `a..b` may produce a different set of elements than `(b..a).reversed()`. E.g. `1..2.5 == [1, 2]`; but `2.5..1 == [2.5, 1.5]`. Implementations can be memory efficient by storing just the `from` and `to` boundary values rather than eagerly creating all discrete items in the conceptual list. The actual discrete items can be lazily calculated on an as needed basis (e.g. when calling methods from the `java.util.List` interface or the additional `step` methods in the `Range` interface). In addition to the methods related to a Range's "discrete items" abstraction, there is a method, `containsWithinBounds` which, for numerical ranges, allows checking within the continuous interval between the Range's boundary values.

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `boolean` | `containsWithinBounds(Object o)` Indicates whether an object is greater than or equal to the `from` value for the range and less than or equal to the `to` value.
    `` | `T` | `getFrom()` The lower value in the range.
    `` | `T` | `getTo()` The upper value in the range.
    `` | `String` | `inspect()` @return the verbose String representation of this Range as would be typed into a console to create the Range instance
    `` | `boolean` | `isReverse()` Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value
    `` | `void` | `step(int step, Closure closure)` Steps through the range, calling a closure for each item.
    `` | `List<T>` | `step(int step)` Forms a list by stepping through the range by the indicated interval.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `interface List` | `add, add, remove, remove, get, equals, hashCode, indexOf, clear, contains, isEmpty, iterator, lastIndexOf, replaceAll, size, subList, toArray, toArray, spliterator, addAll, addAll, set, containsAll, listIterator, listIterator, removeAll, retainAll, sort, stream, removeIf, parallelStream, forEach`
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Method Detail

    - #### public boolean containsWithinBounds(Object o)

      Indicates whether an object is greater than or equal to the `from` value for the range and less than or equal to the `to` value.

      This may be true even for values not contained in the range. Example: from = 1.5, to = 3, next() increments by 1 containsWithinBounds(2) == true contains(2) == false

      Parameters:
        `o` - the object to check against the boundaries of the range
      Returns:
        `true` if the object is between the from and to values

    - #### public T getFrom()

      The lower value in the range.

      Returns:
        the lower value in the range.

    - #### public T getTo()

      The upper value in the range.

      Returns:
        the upper value in the range

    - #### public String inspect()

      Returns:
        the verbose String representation of this Range as would be typed into a console to create the Range instance

    - #### public boolean isReverse()

      Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value

      Returns:
        `true` if this is a reverse range

    - #### public void step(int step, Closure closure)

      Steps through the range, calling a closure for each item.

      Parameters:
        `step` - the amount by which to step. If negative, steps through the range backwards.
        `closure` - the Closure to call

    - #### public List<T> step(int step)

      Forms a list by stepping through the range by the indicated interval.

      Parameters:
        `step` - the amount by which to step. If negative, steps through the range backwards.
      Returns:
        the list formed by stepping through the range by the indicated interval.