groovy.lang

## Class IntRange

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractList<java.lang.Integer>
    - - groovy.lang.IntRange

- All Implemented Interfaces:
    Range<java.lang.Integer>, java.lang.Iterable<java.lang.Integer>, java.util.Collection<java.lang.Integer>, java.util.List<java.lang.Integer>

      public class IntRange
      extends java.util.AbstractList<java.lang.Integer>
      implements Range<java.lang.Integer>

  Represents a list of Integer objects starting at a specified `from` value up (or down) to and potentially including a given `to` value.

  Instances of this class may be either inclusive aware or non-inclusive aware. See the relevant constructors for creating each type. Inclusive aware IntRange instances are suitable for use with Groovy's range indexing - in particular if the from or to values might be negative. This normally happens underneath the covers but is worth keeping in mind if creating these ranges yourself explicitly.

  Note: the design of this class might seem a little strange at first. It contains a Boolean field, `inclusive`, which can be `true`, `false` or `null`. This design is for backwards compatibility reasons. Groovy uses this class under the covers to represent range indexing, e.g. `someList[x..y]` and `someString[x..<y]`. In early versions of Groovy the ranges in these expressions were represented under the covers by the `new IntRange(x, y)` and `new IntRange(x, y-1)`. This turns out to be a lossy abstraction when x and/or y are negative values. Now the latter case is represented by `new IntRange(false, x, y)`.

  Note: This class is a copy of `ObjectRange` optimized for `int`. If you make any changes to this class, you might consider making parallel changes to `ObjectRange`.

- - ### Field Summary

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

      `modCount`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `IntRange(boolean inclusive, int from, int to)` Creates a new inclusive aware `IntRange`.
    `` | `IntRange(int from, int to)` Creates a new non-inclusive aware `IntRange`.
    `protected` | `IntRange(int from, int to, boolean reverse)` Creates a new non-inclusive aware `IntRange`.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T extends java.lang.Number & java.lang.Comparable> NumberRange` | `by(T stepSize)` Creates a new NumberRange with the same `from` and `to` as this IntRange but with a step size of `stepSize`.
    `boolean` | `contains(java.lang.Object value)`
    `boolean` | `containsAll(java.util.Collection other)`
    `boolean` | `containsWithinBounds(java.lang.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.
    `boolean` | `equals(IntRange that)` Compares an `IntRange` to another `IntRange`.
    `boolean` | `equals(java.lang.Object that)` Determines if this object is equal to another object.
    `java.lang.Integer` | `get(int index)`
    `java.lang.Integer` | `getFrom()` The lower value in the range.
    `int` | `getFromInt()` Gets the 'from' value as a primitive integer.
    `java.lang.Boolean` | `getInclusive()` Returns the inclusive flag.
    `java.lang.Integer` | `getTo()` The upper value in the range.
    `int` | `getToInt()` Gets the 'to' value as a primitive integer.
    `int` | `hashCode()`
    `java.lang.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
    `java.util.Iterator<java.lang.Integer>` | `iterator()`
    `int` | `size()`
    `java.util.List<java.lang.Integer>` | `step(int step)` Forms a list by stepping through the range by the indicated interval.
    `void` | `step(int step, Closure closure)` Steps through the range, calling a closure for each item.
    `java.util.List<java.lang.Integer>` | `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.
    `java.lang.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, 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, 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

    - #### IntRange

          public IntRange(int from,
                          int to)

      Creates a new non-inclusive aware `IntRange`. If `from` is greater than `to`, a reverse range is created with `from` and `to` swapped.
      Parameters:
        `from` - the first number in the range.
        `to` - the last number in the range.
      Throws:
        `java.lang.IllegalArgumentException` - if the range would contain more than `Integer.MAX_VALUE` values.

    - #### IntRange

          protected IntRange(int from,
                             int to,
                             boolean reverse)

      Creates a new non-inclusive aware `IntRange`.
      Parameters:
        `from` - the first value in the range.
        `to` - the last value in the range.
        `reverse` - `true` if the range should count from `to` to `from`.
      Throws:
        `java.lang.IllegalArgumentException` - if `from` is greater than `to`.

    - #### IntRange

          public IntRange(boolean inclusive,
                          int from,
                          int to)

      Creates a new inclusive aware `IntRange`.
      Parameters:
        `from` - the first value in the range.
        `to` - the last value in the range.
        `inclusive` - `true` if the to value is included in the range.

  - ### Method Detail

    - #### by

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

      Creates a new NumberRange with the same `from` and `to` as this IntRange but with a step size of `stepSize`.
      Parameters:
        `stepSize` - the desired step size
      Returns:
        a new NumberRange
      Since:
        2.5.0

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

    - #### equals

          public boolean equals(java.lang.Object that)

      Determines if this object is equal to another object. Delegates to `AbstractList.equals(Object)` if `that` is anything other than an `IntRange`.

      It is not necessary to override `hashCode`, as `AbstractList.hashCode()` provides a suitable hash code.

      Note that equals is generally handled by `DefaultGroovyMethods.equals(List, List)` instead of this method.

      Specified by:
        `equals` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `equals` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `equals` in class `java.util.AbstractList<java.lang.Integer>`
      Parameters:
        `that` - the object to compare
      Returns:
        `true` if the objects are equal

    - #### equals

          public boolean equals(IntRange that)

      Compares an `IntRange` to another `IntRange`.
      Parameters:
        `that` - the object to compare for equality
      Returns:
        `true` if the ranges are equal

    - #### getFrom

          public java.lang.Integer getFrom()

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

    - #### getTo

          public java.lang.Integer getTo()

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

    - #### getInclusive

          public java.lang.Boolean getInclusive()

      Returns the inclusive flag. Null for non-inclusive aware ranges or non-null for inclusive aware ranges.

    - #### getFromInt

          public int getFromInt()

      Gets the 'from' value as a primitive integer.
      Returns:
        the 'from' value as a primitive integer.

    - #### getToInt

          public int getToInt()

      Gets the 'to' value as a primitive integer.
      Returns:
        the 'to' value as a primitive integer.

    - #### 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<java.lang.Integer>`
      Returns:
        `true` if this is a reverse range

    - #### containsWithinBounds

          public boolean containsWithinBounds(java.lang.Object o)

      Description copied from interface: `Range`
      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

      Specified by:
        `containsWithinBounds` in interface `Range<java.lang.Integer>`
      Parameters:
        `o` - the object to check against the boundaries of the range
      Returns:
        `true` if the object is between the from and to values

    - #### get

          public java.lang.Integer get(int index)

      Specified by:
        `get` in interface `java.util.List<java.lang.Integer>`
      Specified by:
        `get` in class `java.util.AbstractList<java.lang.Integer>`

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `size` in interface `java.util.List<java.lang.Integer>`
      Specified by:
        `size` in class `java.util.AbstractCollection<java.lang.Integer>`

    - #### iterator

          public java.util.Iterator<java.lang.Integer> iterator()

      Specified by:
        `iterator` in interface `java.lang.Iterable<java.lang.Integer>`
      Specified by:
        `iterator` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `iterator` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `iterator` in class `java.util.AbstractList<java.lang.Integer>`

    - #### subList

          public java.util.List<java.lang.Integer> subList(int fromIndex,
                                                           int toIndex)

      Specified by:
        `subList` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `subList` in class `java.util.AbstractList<java.lang.Integer>`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.util.AbstractCollection<java.lang.Integer>`

    - #### inspect

          public java.lang.String inspect()

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

    - #### contains

          public boolean contains(java.lang.Object value)

      Specified by:
        `contains` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `contains` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `contains` in class `java.util.AbstractCollection<java.lang.Integer>`

    - #### containsAll

          public boolean containsAll(java.util.Collection other)

      Specified by:
        `containsAll` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `containsAll` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `containsAll` in class `java.util.AbstractCollection<java.lang.Integer>`

    - #### step

          public void step(int step,
                           Closure closure)

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

    - #### step

          public java.util.List<java.lang.Integer> step(int step)

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

    - #### hashCode

          public int hashCode()

      Specified by:
        `hashCode` in interface `java.util.Collection<java.lang.Integer>`
      Specified by:
        `hashCode` in interface `java.util.List<java.lang.Integer>`
      Overrides:
        `hashCode` in class `java.util.AbstractList<java.lang.Integer>`