IntRange (Groovy 4.0.15)
Description: declaration: package: groovy.lang, class: IntRange

Package groovy.lang

# Class IntRange

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

All Implemented Interfaces:
  `Range<Integer>`, `Serializable`, `Iterable<Integer>`, `Collection<Integer>`, `List<Integer>`

public class IntRange extends AbstractList<Integer> implements Range<Integer>, 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`.

See Also:
  - Serialized Form

- ## Field Summary

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

  `modCount`

- ## Constructor Summary

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

  Modifier and Type
  Method
  Description
  `<T extends Number & 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(Object value)`
  `boolean`
  `containsAll(Collection other)`
  `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.
  `boolean`
  `equals(IntRange that)`
  Compares an `IntRange` to another `IntRange`.
  `boolean`
  `equals(Object that)`
  Determines if this object is equal to another object.
  `Integer`
  `get(int index)`
  `Integer`
  `getFrom()`
  The lower value in the range.
  `int`
  `getFromInt()`
  Gets the 'from' value as a primitive integer.
  `Boolean`
  `getInclusive()`
  Returns the same as `getInclusiveRight`, kept here for backwards compatibility.
  `Boolean`
  `getInclusiveLeft()`
  Returns the inclusiveLeft flag.
  `Boolean`
  `getInclusiveRight()`
  Returns the inclusiveRight flag.
  `Integer`
  `getTo()`
  The upper value in the range.
  `int`
  `getToInt()`
  Gets the 'to' value as a primitive integer.
  `int`
  `hashCode()`
  `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<Integer>`
  `iterator()`
  `int`
  `size()`
  `List<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.
  `List<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.
  `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.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, indexOf, isEmpty, lastIndexOf, listIterator, listIterator, remove, remove, removeAll, replaceAll, retainAll, set, sort, spliterator, toArray, toArray`

- ## Constructor Details

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

  - ### IntRange

    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.

  - ### IntRange

    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 Details

  - ### by

    public <T extends Number & 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(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 `Collection<Integer>`
    Specified by:
      `equals` in interface `List<Integer>`
    Overrides:
      `equals` in class `AbstractList<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 Integer getFrom()
    Description copied from interface: `Range`
    The lower value in the range.
    Specified by:
      `getFrom` in interface `Range<Integer>`
    Returns:
      the lower value in the range.

  - ### getTo

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

  - ### getInclusive

    public Boolean getInclusive()
    Returns the same as `getInclusiveRight`, kept here for backwards compatibility.

  - ### getInclusiveRight

    public Boolean getInclusiveRight()
    Returns the inclusiveRight flag. Null for non-inclusive aware ranges or non-null for inclusive aware ranges.

  - ### getInclusiveLeft

    public Boolean getInclusiveLeft()
    Returns the inclusiveLeft 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<Integer>`
    Returns:
      `true` if this is a reverse range

  - ### containsWithinBounds

    public boolean containsWithinBounds(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<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 Integer get(int index)
    Specified by:
      `get` in interface `List<Integer>`
    Specified by:
      `get` in class `AbstractList<Integer>`

  - ### size

    public int size()
    Specified by:
      `size` in interface `Collection<Integer>`
    Specified by:
      `size` in interface `List<Integer>`
    Specified by:
      `size` in class `AbstractCollection<Integer>`

  - ### iterator

    public Iterator<Integer> iterator()
    Specified by:
      `iterator` in interface `Collection<Integer>`
    Specified by:
      `iterator` in interface `Iterable<Integer>`
    Specified by:
      `iterator` in interface `List<Integer>`
    Overrides:
      `iterator` in class `AbstractList<Integer>`

  - ### subList

    public List<Integer> subList(int fromIndex, int toIndex)
    Specified by:
      `subList` in interface `List<Integer>`
    Overrides:
      `subList` in class `AbstractList<Integer>`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `AbstractCollection<Integer>`

  - ### inspect

    public String inspect()
    Specified by:
      `inspect` in interface `Range<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(Object value)
    Specified by:
      `contains` in interface `Collection<Integer>`
    Specified by:
      `contains` in interface `List<Integer>`
    Overrides:
      `contains` in class `AbstractCollection<Integer>`

  - ### containsAll

    public boolean containsAll(Collection other)
    Specified by:
      `containsAll` in interface `Collection<Integer>`
    Specified by:
      `containsAll` in interface `List<Integer>`
    Overrides:
      `containsAll` in class `AbstractCollection<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<Integer>`
    Parameters:
      `step` - the amount by which to step. If negative, steps through the range backwards.
      `closure` - the `Closure` to call

  - ### step

    public List<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<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 `Collection<Integer>`
    Specified by:
      `hashCode` in interface `List<Integer>`
    Overrides:
      `hashCode` in class `AbstractList<Integer>`