Package 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
  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, boolean inclusiveLeft, boolean inclusiveRight)`
  Creates a `NumberRange`.
  `NumberRange(T from, U to, V stepSize)`
  Creates an inclusive `NumberRange`.
  `NumberRange(T from, U to, V stepSize, boolean inclusive)`
  Creates a `NumberRange`.
  `NumberRange(T from, U to, V stepSize, boolean inclusiveLeft, boolean inclusiveRight)`
  Creates a `NumberRange`.

- ## Method Summary

  Modifier and Type
  Method
  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()`
  Returns the increment used when traversing this range.
  `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.Collection

  `parallelStream, removeIf, stream, toArray`

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

  `forEach`

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

- ## Constructor Details

  - ### 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 (upper bound)

  - ### NumberRange

    public NumberRange(T from, U to, boolean inclusiveLeft, boolean inclusiveRight)
    Creates a `NumberRange`. Creates a reversed range if `from` < `to`.
    Parameters:
      `from` - start of the range
      `to` - end of the range
      `inclusiveLeft` - whether the range is includes the lower bound
      `inclusiveRight` - whether the range is includes the upper bound

  - ### NumberRange

    public NumberRange(T from, U to, V stepSize, boolean inclusiveLeft, boolean inclusiveRight)
    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
      `inclusiveLeft` - whether the range is includes the lower bound
      `inclusiveRight` - whether the range is includes the upper bound

- ## Method Details

  - ### 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()
    The lower value in the range.
    Specified by:
      `getFrom` in interface `Range<Comparable>`
    Returns:
      the lower value in the range.

  - ### getTo

    public Comparable getTo()
    The upper value in the range.
    Specified by:
      `getTo` in interface `Range<Comparable>`
    Returns:
      the upper value in the range

  - ### getStepSize

    public Comparable getStepSize()
    Returns the increment used when traversing this range.
    Returns:
      the step size between successive values

  - ### isReverse

    public boolean isReverse()
    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 `Collection<Comparable>`
    Specified by:
      `iterator` in interface `Iterable<Comparable>`
    Specified by:
      `iterator` in interface `List<Comparable>`
    Overrides:
      `iterator` in class `AbstractList<Comparable>`

  - ### step

    public List<Comparable> step(int numSteps)
    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.