Package 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.io.Serializable, 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>, java.io.Serializable
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.

See Also:
Serialized Form
  • Field Summary

    Fields inherited from class java.util.AbstractList

    modCount
  • Constructor Summary

    Constructors
    Modifier Constructor 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

    Modifier and Type Method 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.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:
      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 Details

    • 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.util.Collection<java.lang.Integer>
      Specified by:
      iterator in interface java.lang.Iterable<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>