groovy.lang

## Class NumberRange

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList<Comparable>
    - - groovy.lang.NumberRange

- All Implemented Interfaces:
    Range<Comparable>, Serializable, Iterable<Comparable>, Collection<Comparable>, List<Comparable>

      public class NumberRange
      extends AbstractList<Comparable>
      implements Range<Comparable>, Serializable

  Represents an immutable list of Numbers from a value to a value with a particular step size. In general, it isn't recommended using a NumberRange as a key to a map. The range 0..3 is deemed to be equal to 0.0..3.0 but they have different hashCode values, so storing a value using one of these ranges couldn't be retrieved using the other.
  Since:
    2.5.0
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class java.util.AbstractList

      `modCount`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NumberRange(T from, U to)` Creates an inclusive `NumberRange` with step size 1.
    `NumberRange(T from, U to, boolean inclusive)` Creates a new `NumberRange` with step size 1.
    `NumberRange(T from, U to, V stepSize)` Creates an inclusive `NumberRange`.
    `NumberRange(T from, U to, V stepSize, boolean inclusive)` Creates a `NumberRange`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T extends Number & Comparable> NumberRange` | `by(T stepSize)` For a NumberRange with step size 1, creates a new NumberRange with the same `from` and `to` as this NumberRange but with a step size of `stepSize`.
    `boolean` | `contains(Object value)` iterates over all values and returns true if one value matches.
    `boolean` | `containsWithinBounds(Object value)` Checks whether a value is between the from and to values of a Range
    `boolean` | `equals(Object that)` An object is deemed equal to this NumberRange if it represents a List of items and those items equal the list of discrete items represented by this NumberRange.
    `boolean` | `fastEquals(NumberRange that)` Compares a `NumberRange` to another `NumberRange` using only a strict comparison of the NumberRange properties.
    `Comparable` | `get(int index)`
    `Comparable` | `getFrom()` The lower value in the range.
    `Comparable` | `getStepSize()`
    `Comparable` | `getTo()` The upper value in the range.
    `int` | `hashCode()` A NumberRange's hashCode is based on hashCode values of the discrete items it represents.
    `String` | `inspect()`
    `boolean` | `isReverse()` Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value
    `Iterator<Comparable>` | `iterator()`
    `int` | `size()`
    `List<Comparable>` | `step(int numSteps)` Forms a list by stepping through the range by the indicated interval.
    `void` | `step(int numSteps, Closure closure)` Steps through the range, calling a closure for each item.
    `List<Comparable>` | `subList(int fromIndex, int toIndex)`
    `RangeInfo` | `subListBorders(int size)` A method for determining from and to information when using this IntRange to index an aggregate object of the specified size.
    `String` | `toString()`

    - ### Methods inherited from class java.util.AbstractList

      `add, add, addAll, clear, indexOf, lastIndexOf, listIterator, listIterator, remove, removeRange, set`

    - ### Methods inherited from class java.util.AbstractCollection

      `addAll, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.util.List

      `add, add, addAll, addAll, clear, containsAll, indexOf, isEmpty, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, sort, spliterator, toArray, toArray`

    - ### Methods inherited from interface java.util.Collection

      `parallelStream, removeIf, stream`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

- - ### Constructor Detail

    - #### NumberRange

          public NumberRange(T from,
                             U to)

      Creates an inclusive `NumberRange` with step size 1. Creates a reversed range if `from` < `to`.
      Parameters:
        `from` - the first value in the range
        `to` - the last value in the range

    - #### NumberRange

          public NumberRange(T from,
                             U to,
                             boolean inclusive)

      Creates a new `NumberRange` with step size 1. Creates a reversed range if `from` < `to`.
      Parameters:
        `from` - start of the range
        `to` - end of the range
        `inclusive` - whether the range is inclusive

    - #### NumberRange

          public NumberRange(T from,
                             U to,
                             V stepSize)

      Creates an inclusive `NumberRange`. Creates a reversed range if `from` < `to`.
      Parameters:
        `from` - start of the range
        `to` - end of the range
        `stepSize` - the gap between discrete elements in the range

    - #### NumberRange

          public NumberRange(T from,
                             U to,
                             V stepSize,
                             boolean inclusive)

      Creates a `NumberRange`. Creates a reversed range if `from` < `to`.
      Parameters:
        `from` - start of the range
        `to` - end of the range
        `stepSize` - the gap between discrete elements in the range
        `inclusive` - whether the range is inclusive

  - ### Method Detail

    - #### subListBorders

          public RangeInfo subListBorders(int size)

      A method for determining from and to information when using this IntRange to index an aggregate object of the specified size. Normally only used internally within Groovy but useful if adding range indexing support for your own aggregates.
      Parameters:
        `size` - the size of the aggregate being indexed
      Returns:
        the calculated range information (with 1 added to the to value, ready for providing to subList

    - #### by

          public <T extends Number & Comparable> NumberRange by(T stepSize)

      For a NumberRange with step size 1, creates a new NumberRange with the same `from` and `to` as this NumberRange but with a step size of `stepSize`.
      Parameters:
        `stepSize` - the desired step size
      Returns:
        a new NumberRange

    - #### equals

          public boolean equals(Object that)

      An object is deemed equal to this NumberRange if it represents a List of items and those items equal the list of discrete items represented by this NumberRange.
      Specified by:
        `equals` in interface `Collection<Comparable>`
      Specified by:
        `equals` in interface `List<Comparable>`
      Overrides:
        `equals` in class `AbstractList<Comparable>`
      Parameters:
        `that` - the object to be compared for equality with this NumberRange
      Returns:
        `true` if the specified object is equal to this NumberRange
      See Also:
        `fastEquals(NumberRange)`

    - #### hashCode

          public int hashCode()

      A NumberRange's hashCode is based on hashCode values of the discrete items it represents.
      Specified by:
        `hashCode` in interface `Collection<Comparable>`
      Specified by:
        `hashCode` in interface `List<Comparable>`
      Overrides:
        `hashCode` in class `AbstractList<Comparable>`
      Returns:
        the hashCode value

    - #### fastEquals

          public boolean fastEquals(NumberRange that)

      Compares a `NumberRange` to another `NumberRange` using only a strict comparison of the NumberRange properties. This won't return true for some ranges which represent the same discrete items, use equals instead for that but will be much faster for large lists.
      Parameters:
        `that` - the NumberRange to check equality with
      Returns:
        `true` if the ranges are equal

    - #### getFrom

          public Comparable getFrom()

      Description copied from interface: `Range`
      The lower value in the range.
      Specified by:
        `getFrom` in interface `Range<Comparable>`
      Returns:
        the lower value in the range.

    - #### getTo

          public Comparable getTo()

      Description copied from interface: `Range`
      The upper value in the range.
      Specified by:
        `getTo` in interface `Range<Comparable>`
      Returns:
        the upper value in the range

    - #### getStepSize

          public Comparable getStepSize()

    - #### isReverse

          public boolean isReverse()

      Description copied from interface: `Range`
      Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value
      Specified by:
        `isReverse` in interface `Range<Comparable>`
      Returns:
        `true` if this is a reverse range

    - #### get

          public Comparable get(int index)

      Specified by:
        `get` in interface `List<Comparable>`
      Specified by:
        `get` in class `AbstractList<Comparable>`

    - #### containsWithinBounds

          public boolean containsWithinBounds(Object value)

      Checks whether a value is between the from and to values of a Range
      Specified by:
        `containsWithinBounds` in interface `Range<Comparable>`
      Parameters:
        `value` - the value of interest
      Returns:
        true if the value is within the bounds

    - #### size

          public int size()

      Specified by:
        `size` in interface `Collection<Comparable>`
      Specified by:
        `size` in interface `List<Comparable>`
      Specified by:
        `size` in class `AbstractCollection<Comparable>`

    - #### subList

          public List<Comparable> subList(int fromIndex,
                                          int toIndex)

      Specified by:
        `subList` in interface `List<Comparable>`
      Overrides:
        `subList` in class `AbstractList<Comparable>`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `AbstractCollection<Comparable>`

    - #### inspect

          public String inspect()

      Specified by:
        `inspect` in interface `Range<Comparable>`
      Returns:
        the verbose `String` representation of this `Range` as would be typed into a console to create the `Range` instance

    - #### contains

          public boolean contains(Object value)

      iterates over all values and returns true if one value matches. Also see containsWithinBounds.
      Specified by:
        `contains` in interface `Collection<Comparable>`
      Specified by:
        `contains` in interface `List<Comparable>`
      Overrides:
        `contains` in class `AbstractCollection<Comparable>`

    - #### step

          public void step(int numSteps,
                           Closure closure)

      Steps through the range, calling a closure for each item.
      Specified by:
        `step` in interface `Range<Comparable>`
      Parameters:
        `numSteps` - the amount by which to step. If negative, steps through the range backwards.
        `closure` - the `Closure` to call

    - #### iterator

          public Iterator<Comparable> iterator()

      Specified by:
        `iterator` in interface `Iterable<Comparable>`
      Specified by:
        `iterator` in interface `Collection<Comparable>`
      Specified by:
        `iterator` in interface `List<Comparable>`
      Overrides:
        `iterator` in class `AbstractList<Comparable>`

    - #### step

          public List<Comparable> step(int numSteps)

      Description copied from interface: `Range`
      Forms a list by stepping through the range by the indicated interval.
      Specified by:
        `step` in interface `Range<Comparable>`
      Parameters:
        `numSteps` - 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.