Top Description Inners Fields Constructors Methods
groovy.lang

public Class IntRange

extends AbstractList<Integer>
implements Range<Integer>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, groovy.lang.Range, java.util.List, java.util.SequencedCollection, java.util.Collection, java.lang.Iterable
Imports
org.codehaus.groovy.runtime.IteratorClosureAdapter, .RangeInfo, java.io.Serializable, java.math.BigInteger, java.util.AbstractList, .Collection, .Iterator, .List, .NoSuchElementException, .Objects
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.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
IntRange.IntRangeIterator

Iterates through each number in an IntRange.

Field Summary

Modifier and TypeField and Description
private final int
from

For non-inclusive aware ranges, the first number in the range; from is always less than or equal to to.

private final Boolean
inclusive

If true or null, to is included in the range.

private final boolean
reverse

If false, counts up from from to to.

private static final long
serialVersionUID

private final int
to

For non-inclusive aware ranges, the last number in the range; to is always greater than or equal to from.

Inherited from java.util.AbstractList:
modCount

Constructor Summary

AccessConstructor and Description
public
IntRange(int
the first number in the range.
from, int
the last number in the range.
to)

Creates a new non-inclusive aware IntRange.

protected
IntRange(int
the first value in the range.
from, int
the last value in the range.
to, boolean
true if the range should count from to to from.
reverse)

Creates a new non-inclusive aware IntRange.

public
IntRange(boolean
true if the to value is included in the range.
inclusive, int
the first value in the range.
from, int
the last value in the range.
to)

Creates a new inclusive aware IntRange.

Method Summary

Modifier and TypeMethod and Description
public <T extends Number & Comparable<T>> NumberRange

Returns:

a new NumberRange
by(T
the desired step size
stepSize)

Creates a new NumberRange with the same from and to as this IntRange but with a step size of stepSize.

private void
checkSize()

public boolean
contains(Object
element whose presence in this list is to be tested
value)

Overrides java.util.AbstractCollection.contains.

Implements java.util.List.contains, java.util.Collection.contains.

Returns true if this list contains the specified element.
public boolean
containsAll(Collection<E>
collection to be checked for containment in this list
other)

Overrides java.util.AbstractCollection.containsAll.

Implements java.util.List.containsAll, java.util.Collection.containsAll.

Returns true if this list contains all of the elements of the specified collection.
public boolean
containsWithinBounds(Object
the object to check against the boundaries of the range
o)

Implements groovy.lang.Range.containsWithinBounds.

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.
public boolean

Returns:

true if the objects are equal
equals(Object
the object to compare
that)

Overrides java.util.AbstractList.equals.

Implements java.util.List.equals, java.util.Collection.equals.

Determines if this object is equal to another object.
public boolean

Returns:

true if the ranges are equal
equals(IntRange
the object to compare for equality
that)

Compares an IntRange to another IntRange.

public Integer
get(int
index of the element to return
index)

Implements abstract java.util.AbstractList.get.

Implements java.util.List.get.

Returns the element at the specified position in this list.
public Integer
getFrom()

Implements groovy.lang.Range.getFrom.

The lower value in the range.
public int

Returns:

the 'from' value as a primitive integer.
getFromInt()

Gets the 'from' value as a primitive integer.

public Boolean
getInclusive()

Returns the inclusive flag.

public Integer
getTo()

Implements groovy.lang.Range.getTo.

The upper value in the range.
public int

Returns:

the 'to' value as a primitive integer.
getToInt()

Gets the 'to' value as a primitive integer.

public int
hashCode()

Overrides java.util.AbstractList.hashCode.

Implements java.util.List.hashCode, java.util.Collection.hashCode.

Returns the hash code value for this list.
public String
inspect()

Implements groovy.lang.Range.inspect.

public boolean
isReverse()

Implements groovy.lang.Range.isReverse.

Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value
public Iterator<Integer>
iterator()

Overrides java.util.AbstractList.iterator.

Implements java.util.List.iterator, java.util.Collection.iterator.

Returns an iterator over the elements in this list in proper sequence.
public int
size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.List.size, java.util.Collection.size.

Returns the number of elements in this list.
public void
step(int
the amount by which to step. If negative, steps through the range backwards.
step, Closure<V>
the Closure to call
closure)

Implements groovy.lang.Range.step.

Steps through the range, calling a closure for each item.
public List<Integer>
step(int
the amount by which to step. If negative, steps through the range backwards.
step)

Implements groovy.lang.Range.step.

Forms a list by stepping through the range by the indicated interval.
public List<Integer>
subList(int
low endpoint (inclusive) of the subList
fromIndex, int
high endpoint (exclusive) of the subList
toIndex)

Overrides java.util.AbstractList.subList.

Implements java.util.List.subList.

Returns a view of the portion of this list between the specified fromIndex, inclusive, and toIndex, exclusive.
public RangeInfo

Returns:

the calculated range information (with 1 added to the to value, ready for providing to subList
subListBorders(int
the size of the aggregate being indexed
size)

A method for determining from and to information when using this IntRange to index an aggregate object of the specified size.

pack-priv static RangeInfo
subListBorders(int from, int to, boolean inclusive, int size)

public String
toString()

Overrides java.util.AbstractCollection.toString.

Returns a string representation of this collection.
Inherited from java.util.AbstractList:
addaddaddAllclearindexOflastIndexOflistIteratorlistIteratorremoveremoveRangeset

Field Detail

fromback to summary
private final int from

For non-inclusive aware ranges, the first number in the range; from is always less than or equal to to. For inclusive aware ranges, the from argument supplied to the constructor.

inclusiveback to summary
private final Boolean inclusive

If true or null, to is included in the range. If false, the range stops before the to value.

Null for non-inclusive-aware ranges (which are inclusive).

If true or false, the reverse flag is discarded.

reverseback to summary
private final boolean reverse

If false, counts up from from to to. Otherwise, counts down from to to from. Not used for inclusive-aware ranges (inclusive = true|false).

serialVersionUIDback to summary
private static final long serialVersionUID
toback to summary
private final int to

For non-inclusive aware ranges, the last number in the range; to is always greater than or equal to from. For inclusive aware ranges, the from argument supplied to the constructor.

Constructor Detail

IntRangeback to summary
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:int

the first number in the range.

to:int

the last number in the range.

Exceptions
IllegalArgumentException:
if the range would contain more than Integer#MAX_VALUE values.
IntRangeback to summary
protected IntRange(int from, int to, boolean reverse)

Creates a new non-inclusive aware IntRange.

Parameters
from:int

the first value in the range.

to:int

the last value in the range.

reverse:boolean

true if the range should count from to to from.

Exceptions
IllegalArgumentException:
if from is greater than to.
IntRangeback to summary
public IntRange(boolean inclusive, int from, int to)

Creates a new inclusive aware IntRange.

Parameters
inclusive:boolean

true if the to value is included in the range.

from:int

the first value in the range.

to:int

the last value in the range.

Method Detail

byback to summary
public <T extends Number & Comparable<T>> 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:T

the desired step size

Returns:NumberRange

a new NumberRange

Since
2.5.0
checkSizeback to summary
private void checkSize()
containsback to summary
public boolean contains(Object value)

Overrides java.util.AbstractCollection.contains.

Implements java.util.List.contains, java.util.Collection.contains.

Doc from java.util.List.contains.

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

Parameters
value:Object

element whose presence in this list is to be tested

Returns:boolean

true if this list contains the specified element

Annotations
@Override
containsAllback to summary
public boolean containsAll(Collection<E> other)

Overrides java.util.AbstractCollection.containsAll.

Implements java.util.List.containsAll, java.util.Collection.containsAll.

Doc from java.util.List.containsAll.

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

Parameters
other:Collection<E>

collection to be checked for containment in this list

Returns:boolean

true if this list contains all of the elements of the specified collection

Annotations
@Override
containsWithinBoundsback to summary
public boolean containsWithinBounds(Object o)

Implements groovy.lang.Range.containsWithinBounds.

Doc from groovy.lang.Range.containsWithinBounds.

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:Object

the object to check against the boundaries of the range

Returns:boolean

true if the object is between the from and to values

Annotations
@Override
equalsback to summary
public boolean equals(Object that)

Overrides java.util.AbstractList.equals.

Implements java.util.List.equals, java.util.Collection.equals.

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 org.codehaus.groovy.runtime.DefaultGroovyMethods#equals(List, List) instead of this method.

Parameters
that:Object

the object to compare

Returns:boolean

true if the objects are equal

equalsback to summary
public boolean equals(IntRange that)

Compares an IntRange to another IntRange.

Parameters
that:IntRange

the object to compare for equality

Returns:boolean

true if the ranges are equal

getback to summary
public Integer get(int index)

Implements abstract java.util.AbstractList.get.

Implements java.util.List.get.

Doc from java.util.List.get.

Returns the element at the specified position in this list.

Parameters
index:int

index of the element to return

Returns:Integer

the element at the specified position in this list

Annotations
@Override
getFromback to summary
public Integer getFrom()

Implements groovy.lang.Range.getFrom.

Doc from groovy.lang.Range.getFrom.

The lower value in the range.

Returns:Integer

the lower value in the range.

Annotations
@Override
getFromIntback to summary
public int getFromInt()

Gets the 'from' value as a primitive integer.

Returns:int

the 'from' value as a primitive integer.

getInclusiveback to summary
public Boolean getInclusive()

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

getToback to summary
public Integer getTo()

Implements groovy.lang.Range.getTo.

Doc from groovy.lang.Range.getTo.

The upper value in the range.

Returns:Integer

the upper value in the range

Annotations
@Override
getToIntback to summary
public int getToInt()

Gets the 'to' value as a primitive integer.

Returns:int

the 'to' value as a primitive integer.

hashCodeback to summary
public int hashCode()

Overrides java.util.AbstractList.hashCode.

Implements java.util.List.hashCode, java.util.Collection.hashCode.

Doc from java.util.List.hashCode.

Returns the hash code value for this list. The hash code of a list is defined to be the result of the following calculation: 

int hashCode = 1;
    for (E e : list)
        hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
This ensures that list1.equals(list2) implies that list1.hashCode()==list2.hashCode() for any two lists, list1 and list2, as required by the general contract of Object#hashCode.
Returns:int

the hash code value for this list

Annotations
@Override
inspectback to summary
public String inspect()

Implements groovy.lang.Range.inspect.

Returns:String

Doc from groovy.lang.Range.inspect.

the verbose String representation of this Range as would be typed into a console to create the Range instance

Annotations
@Override
isReverseback to summary
public boolean isReverse()

Implements groovy.lang.Range.isReverse.

Doc from groovy.lang.Range.isReverse.

Indicates whether this is a reverse range which iterates backwards starting from the to value and ending on the from value

Returns:boolean

true if this is a reverse range

Annotations
@Override
iteratorback to summary
public Iterator<Integer> iterator()

Overrides java.util.AbstractList.iterator.

Implements java.util.List.iterator, java.util.Collection.iterator.

Doc from java.util.List.iterator.

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

Returns:Iterator<Integer>

an iterator over the elements in this list in proper sequence

Annotations
@Override
sizeback to summary
public int size()

Implements abstract java.util.AbstractCollection.size.

Implements java.util.List.size, java.util.Collection.size.

Doc from java.util.List.size.

Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Returns:int

the number of elements in this list

Annotations
@Override
stepback to summary
public void step(int step, Closure<V> closure)

Implements groovy.lang.Range.step.

Doc from groovy.lang.Range.step.

Steps through the range, calling a closure for each item.

Parameters
step:int

the amount by which to step. If negative, steps through the range backwards.

closure:Closure<V>

the Closure to call

Annotations
@Override
stepback to summary
public List<Integer> step(int step)

Implements groovy.lang.Range.step.

Doc from groovy.lang.Range.step.

Forms a list by stepping through the range by the indicated interval.

Parameters
step:int

the amount by which to step. If negative, steps through the range backwards.

Returns:List<Integer>

the list formed by stepping through the range by the indicated interval.

Annotations
@Override
subListback to summary
public List<Integer> subList(int fromIndex, int toIndex)

Overrides java.util.AbstractList.subList.

Implements java.util.List.subList.

Doc from java.util.List.subList.

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

Parameters
fromIndex:int

low endpoint (inclusive) of the subList

toIndex:int

high endpoint (exclusive) of the subList

Returns:List<Integer>

a view of the specified range within this list

Annotations
@Override
subListBordersback to summary
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:int

the size of the aggregate being indexed

Returns:RangeInfo

the calculated range information (with 1 added to the to value, ready for providing to subList

subListBordersback to summary
pack-priv static RangeInfo subListBorders(int from, int to, boolean inclusive, int size)
toStringback to summary
public String toString()

Overrides java.util.AbstractCollection.toString.

Doc from java.util.AbstractCollection.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(Object).

Returns:String

a string representation of this collection

groovy.lang back to summary

private Class IntRange.IntRangeIterator

extends Object
implements Iterator<Integer>
Class Inheritance
All Implemented Interfaces
java.util.Iterator
Iterates through each number in an IntRange.

Field Summary

Modifier and TypeField and Description
private int
index

Counts from 0 up to size - 1.

private int
size

The number of values in the range.

private int
value

The next value to return.

Constructor Summary

AccessConstructor and Description
private
IntRangeIterator()

Method Summary

Modifier and TypeMethod and Description
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public Integer
next()

Implements java.util.Iterator.next.

Returns the next element in the iteration.
public void
remove()

Overrides default java.util.Iterator.remove.

Not supported.
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

indexback to summary
private int index

Counts from 0 up to size - 1.

sizeback to summary
private int size

The number of values in the range.

valueback to summary
private int value

The next value to return.

Constructor Detail

IntRangeIteratorback to summary
private IntRangeIterator()

Method Detail

hasNextback to summary
public boolean hasNext()

Implements java.util.Iterator.hasNext.

Doc from java.util.Iterator.hasNext.

Returns true if the iteration has more elements. (In other words, returns true if next would return an element rather than throwing an exception.)

Returns:boolean

true if the iteration has more elements

Annotations
@Override
nextback to summary
public Integer next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Integer

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Not supported.

Annotations
@Override
Exceptions
UnsupportedOperationException:
always