Package: groovy.lang

## [Java] Class IntRange

- groovy.lang.IntRange

- All Implemented Interfaces and Traits:
    Range, Serializable

      public class IntRange
      extends AbstractList
      implements Range, Serializable

  Represents a list of Integer objects starting at and potentially including 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 Boolean flags, `inclusiveLeft` and `inclusiveRight`, 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.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `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`.
    `IntRange(boolean inclusiveRight, int from, int to)` Creates a new inclusive aware `IntRange`.
    `IntRange(boolean inclusiveLeft, boolean inclusiveRight, int from, int to)` Creates a new inclusive aware `IntRange`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `<T extends Number & Comparable>` | `public NumberRange` | `by(T stepSize)` Creates a new NumberRange with the same `from` and `to` as this IntRange but with a step size of `stepSize`.
    `` | `public boolean` | `contains(Object value)` Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`. throws: ClassCastException if the type of the specified element is incompatible with this collection (optional) throws: NullPointerException if the specified element is null and this collection does not permit null elements (optional) throws: ClassCastException Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`. throws: ClassCastException if the type of the specified element is incompatible with this collection (optional) throws: NullPointerException if the specified element is null and this collection does not permit null elements (optional) throws: NullPointerException Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`. throws: ClassCastException if the type of the specified element is incompatible with this collection (optional) throws: NullPointerException if the specified element is null and this collection does not permit null elements (optional) Parameters: `o` - element whose presence in this collection is to be tested `o` - element whose presence in this collection is to be tested `o` - element whose presence in this collection is to be tested Returns: `true` if this collection contains the specified element `true` if this collection contains the specified element `true` if this collection contains the specified element Implementation Requirements: This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.
    `` | `public boolean` | `containsAll(Collection other)` Returns `true` if this collection contains all of the elements in the specified collection. throws: ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional) throws: NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null. throws: ClassCastException Returns `true` if this collection contains all of the elements in the specified collection. throws: ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional) throws: NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null. throws: NullPointerException Returns `true` if this collection contains all of the elements in the specified collection. throws: ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional) throws: NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null. Parameters: `c` - collection to be checked for containment in this collection `c` - collection to be checked for containment in this collection `c` - collection to be checked for containment in this collection Returns: `true` if this collection contains all of the elements in the specified collection `true` if this collection contains all of the elements in the specified collection `true` if this collection contains all of the elements in the specified collection See Also: contains(Object) contains(Object) contains(Object) contains(Object) Implementation Requirements: This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. If all elements are so contained `true` is returned, otherwise `false`.
    `` | `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 boolean` | `equals(Object that)` Determines if this object is equal to another object.
    `` | `public boolean` | `equals(IntRange that)` Compares an IntRange to another IntRange.
    `` | `public Integer` | `get(int index)` Returns the element at the specified position in this list. throws: IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`) throws: IndexOutOfBoundsException Returns the element at the specified position in this list. throws: IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`) Parameters: `index` - index of the element to return `index` - index of the element to return Returns: the element at the specified position in this list the element at the specified position in this list
    `` | `public Integer` | `getFrom()` * The lower value in the range. * * Returns: the lower value in the range.
    `` | `public int` | `getFromInt()` Gets the 'from' value as a primitive integer.
    `` | `public Boolean` | `getInclusive()` Returns the same as `getInclusiveRight`, kept here for backwards compatibility.
    `` | `public Boolean` | `getInclusiveLeft()` Returns the inclusiveLeft flag.
    `` | `public Boolean` | `getInclusiveRight()` Returns the inclusiveRight flag.
    `` | `public Integer` | `getTo()` * The upper value in the range. * * Returns: the upper value in the range
    `` | `public int` | `getToInt()` Gets the 'to' value as a primitive integer.
    `` | `public int` | `hashCode()` Returns the hash code value for this list. Implementation Requirements: This implementation uses exactly the code that is used to define the list hash function in the documentation for the List.hashCode method. Returns: the hash code value for this list
    `` | `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 Iterator<Integer>` | `iterator()` Returns an iterator over the elements in this list in proper sequence. Implementation Requirements: This implementation returns a straightforward implementation of the iterator interface, relying on the backing list's `size()`, `get(int)`, and `remove(int)` methods. Note that the iterator returned by this method will throw an UnsupportedOperationException in response to its `remove` method unless the list's `remove(int)` method is overridden. This implementation can be made to throw runtime exceptions in the face of concurrent modification, as described in the specification for the (protected) modCount field. Returns: an iterator over the elements in this list in proper sequence
    `` | `public int` | `size()`
    `` | `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<Integer>` | `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.
    `` | `public List<Integer>` | `subList(int fromIndex, int toIndex)` Returns a view of the portion of this list between the specified `fromIndex`, inclusive, and `toIndex`, exclusive. (If `fromIndex` and `toIndex` are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list. This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list:
        list.subList(from, to).clear();
    Similar idioms may be constructed for `indexOf` and `lastIndexOf`, and all of the algorithms in the `Collections` class can be applied to a subList. The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.) throws: IndexOutOfBoundsException for an illegal endpoint index value (`fromIndex < 0 || toIndex > size || fromIndex > toIndex`) throws: IndexOutOfBoundsException if an endpoint index value is out of range `(fromIndex < 0 || toIndex > size)` throws: IllegalArgumentException if the endpoint indices are out of order `(fromIndex > toIndex)` Parameters: `fromIndex` - low endpoint (inclusive) of the subList `toIndex` - high endpoint (exclusive) of the subList Returns: a view of the specified range within this list Implementation Requirements: This implementation returns a list that subclasses `AbstractList`. The subclass stores, in private fields, the size of the subList (which can change over its lifetime), and the expected `modCount` value of the backing list. There are two variants of the subclass, one of which implements `RandomAccess`. If this list implements `RandomAccess` the returned list will be an instance of the subclass that implements `RandomAccess`. The subclass's `set(int, E)`, `get(int)`, `add(int, E)`, `remove(int)`, `addAll(int, Collection)` and `removeRange(int, int)` methods all delegate to the corresponding methods on the backing abstract list, after bounds-checking the index and adjusting for the offset. The `addAll(Collection c)` method merely returns `addAll(size, c)`. The `listIterator(int)` method returns a "wrapper object" over a list iterator on the backing list, which is created with the corresponding method on the backing list. The `iterator` method merely returns `listIterator()`, and the `size` method merely returns the subclass's `size` field. All methods first check to see if the actual `modCount` of the backing list is equal to its expected value, and throw a `ConcurrentModificationException` if it is not.
    `` | `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.
    `` | `public String` | `toString()` Returns a string representation of this collection. The string representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (comma and space). Elements are converted to strings as by String.valueOf. Returns: a string representation of this collection

  - ### Inherited Methods Summary

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

- - ### Constructor Detail

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

      throws:
        IllegalArgumentException if the range would contain more than Integer.MAX_VALUE values.
      Parameters:
        `from` - the first number in the range.
        `to` - the last number in the range.

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

      Creates a new non-inclusive aware `IntRange`.

      throws:
        IllegalArgumentException if `from` is greater than `to`.
      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`.

    - #### public IntRange(boolean inclusiveRight, 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.
        `inclusiveRight` - `true` if the to value is included in the range.

    - #### public IntRange(boolean inclusiveLeft, boolean inclusiveRight, int from, int to)

      Creates a new inclusive aware `IntRange`

      Parameters:
        `inclusiveLeft` - `true` if the from value is included in the range.
        `inclusiveRight` - `true` if the to value is included in the range.
        `from` - the first value in the range.
        `to` - the last value in the range.

  - ### Method Detail

    - #### <T extends Number & Comparable> public 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

    - #### public boolean contains(Object value)

      Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`.

      throws:
        ClassCastException if the type of the specified element is incompatible with this collection (optional)
      throws:
        NullPointerException if the specified element is null and this collection does not permit null elements (optional)
      throws:
        ClassCastException Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`.
      throws:
        ClassCastException if the type of the specified element is incompatible with this collection (optional)
      throws:
        NullPointerException if the specified element is null and this collection does not permit null elements (optional)
      throws:
        NullPointerException Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`.
      throws:
        ClassCastException if the type of the specified element is incompatible with this collection (optional)
      throws:
        NullPointerException if the specified element is null and this collection does not permit null elements (optional)
      Parameters:
        `o` - element whose presence in this collection is to be tested
        `o` - element whose presence in this collection is to be tested
        `o` - element whose presence in this collection is to be tested
      Returns:
        `true` if this collection contains the specified element
        `true` if this collection contains the specified element
        `true` if this collection contains the specified element
      Implementation Requirements:
        This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.

    - #### public boolean containsAll(Collection other)

      Returns `true` if this collection contains all of the elements in the specified collection.

      throws:
        ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional)
      throws:
        NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null.
      throws:
        ClassCastException Returns `true` if this collection contains all of the elements in the specified collection.
      throws:
        ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional)
      throws:
        NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null.
      throws:
        NullPointerException Returns `true` if this collection contains all of the elements in the specified collection.
      throws:
        ClassCastException if the types of one or more elements in the specified collection are incompatible with this collection (optional)
      throws:
        NullPointerException if the specified collection contains one or more null elements and this collection does not permit null elements (optional), or if the specified collection is null.
      Parameters:
        `c` - collection to be checked for containment in this collection
        `c` - collection to be checked for containment in this collection
        `c` - collection to be checked for containment in this collection
      Returns:
        `true` if this collection contains all of the elements in the specified collection
        `true` if this collection contains all of the elements in the specified collection
        `true` if this collection contains all of the elements in the specified collection
      See Also:
        contains(Object)
        contains(Object)
        contains(Object)
        contains(Object)
      Implementation Requirements:
        This implementation iterates over the specified collection, checking each element returned by the iterator in turn to see if it's contained in this collection. If all elements are so contained `true` is returned, otherwise `false`.

    - #### 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 boolean equals(Object that)

      Determines if this object is equal to another object. Delegates to AbstractList.equals 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 instead of this method.

      Parameters:
        `that` - the object to compare
      Returns:
        `true` if the objects are equal

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

    - #### public Integer get(int index)

      Returns the element at the specified position in this list.

      throws:
        IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`)
      throws:
        IndexOutOfBoundsException Returns the element at the specified position in this list.
      throws:
        IndexOutOfBoundsException if the index is out of range (`index < 0 || index >= size()`)
      Parameters:
        `index` - index of the element to return
        `index` - index of the element to return
      Returns:
        the element at the specified position in this list
        the element at the specified position in this list

    - #### public Integer getFrom()

      * The lower value in the range. * *

      Returns:
        the lower value in the range.

    - #### public int getFromInt()

      Gets the 'from' value as a primitive integer.

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

    - #### public Boolean getInclusive()

      Returns the same as `getInclusiveRight`, kept here for backwards compatibility.

    - #### public Boolean getInclusiveLeft()

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

    - #### public Boolean getInclusiveRight()

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

    - #### public Integer getTo()

      * The upper value in the range. * *

      Returns:
        the upper value in the range

    - #### public int getToInt()

      Gets the 'to' value as a primitive integer.

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

    - #### public int hashCode()

      Returns the hash code value for this list.

      Implementation Requirements:
        This implementation uses exactly the code that is used to define the list hash function in the documentation for the List.hashCode method.
      Returns:
        the hash code value for this list

    - #### 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 Iterator<Integer> iterator()

      Returns an iterator over the elements in this list in proper sequence.

      Implementation Requirements:
        This implementation returns a straightforward implementation of the iterator interface, relying on the backing list's `size()`, `get(int)`, and `remove(int)` methods.

        Note that the iterator returned by this method will throw an UnsupportedOperationException in response to its `remove` method unless the list's `remove(int)` method is overridden.

        This implementation can be made to throw runtime exceptions in the face of concurrent modification, as described in the specification for the (protected) modCount field.

      Returns:
        an iterator over the elements in this list in proper sequence

    - #### public int size()

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

    - #### public List<Integer> subList(int fromIndex, int toIndex)

      Returns a view of the portion of this list between the specified `fromIndex`, inclusive, and `toIndex`, exclusive. (If `fromIndex` and `toIndex` are equal, the returned list is empty.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.

      This method eliminates the need for explicit range operations (of the sort that commonly exist for arrays). Any operation that expects a list can be used as a range operation by passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list:

          list.subList(from, to).clear();

      Similar idioms may be constructed for `indexOf` and `lastIndexOf`, and all of the algorithms in the `Collections` class can be applied to a subList.

      The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)

      throws:
        IndexOutOfBoundsException for an illegal endpoint index value (`fromIndex < 0 || toIndex > size || fromIndex > toIndex`)
      throws:
        IndexOutOfBoundsException if an endpoint index value is out of range `(fromIndex < 0 || toIndex > size)`
      throws:
        IllegalArgumentException if the endpoint indices are out of order `(fromIndex > toIndex)`
      Parameters:
        `fromIndex` - low endpoint (inclusive) of the subList
        `toIndex` - high endpoint (exclusive) of the subList
      Returns:
        a view of the specified range within this list
      Implementation Requirements:
        This implementation returns a list that subclasses `AbstractList`. The subclass stores, in private fields, the size of the subList (which can change over its lifetime), and the expected `modCount` value of the backing list. There are two variants of the subclass, one of which implements `RandomAccess`. If this list implements `RandomAccess` the returned list will be an instance of the subclass that implements `RandomAccess`.

        The subclass's `set(int, E)`, `get(int)`, `add(int, E)`, `remove(int)`, `addAll(int, Collection)` and `removeRange(int, int)` methods all delegate to the corresponding methods on the backing abstract list, after bounds-checking the index and adjusting for the offset. The `addAll(Collection c)` method merely returns `addAll(size, c)`.

        The `listIterator(int)` method returns a "wrapper object" over a list iterator on the backing list, which is created with the corresponding method on the backing list. The `iterator` method merely returns `listIterator()`, and the `size` method merely returns the subclass's `size` field.

        All methods first check to see if the actual `modCount` of the backing list is equal to its expected value, and throw a `ConcurrentModificationException` if it is not.

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

    - #### public String toString()

      Returns a string representation of this collection. The string representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets (`"[]"`). Adjacent elements are separated by the characters `", "` (comma and space). Elements are converted to strings as by String.valueOf.

      Returns:
        a string representation of this collection