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 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 |
| 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).
|
|
public boolean |
containsAll(Collection other)Returns true if this collection contains all of the elements
in the specified collection.
|
|
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 * *
|
|
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.
|
|
public Integer |
getFrom()* 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. * *
|
|
public int |
getToInt()Gets the 'to' value as a primitive integer. |
|
public int |
hashCode()Returns the hash code value for this list.
|
|
public String |
inspect()* |
|
public boolean |
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()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. * *
|
|
public List<Integer> |
step(int step)* Forms a list 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: 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.)
|
|
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.
|
| 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 |
Creates a new non-inclusive aware IntRange. If from is greater than
to, a reverse range is created with from and to swapped.
from - the first number in the range.to - the last number in the range. Creates a new non-inclusive aware IntRange.
from is greater than to.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. Creates a new inclusive aware IntRange.
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. Creates a new inclusive aware IntRange
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. Creates a new NumberRange with the same from and to as this
IntRange but with a step size of stepSize.
stepSize - the desired step size 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).
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).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).o - element whose presence in this collection is to be testedo - element whose presence in this collection is to be testedo - element whose presence in this collection is to be testedtrue if this collection contains the specified
elementtrue if this collection contains the specified
elementtrue if this collection contains the specified
element 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.c - collection to be checked for containment in this collectionc - collection to be checked for containment in this collectionc - collection to be checked for containment in this collectiontrue if this collection contains all of the elements
in the specified collectiontrue if this collection contains all of the elements
in the specified collectiontrue if this collection contains all of the elements
in the specified collectiontrue is returned, otherwise false.
* 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 * *
o - the object to check against the boundaries of the range
*true if the object is between the from and to values 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.
that - the object to comparetrue if the objects are equalCompares an IntRange to another IntRange.
that - the object to compare for equalitytrue if the ranges are equalReturns the element at the specified position in this list.
index < 0 || index >= size())index < 0 || index >= size())index - index of the element to returnindex - index of the element to return* The lower value in the range. * *
Gets the 'from' value as a primitive integer.
Returns the same as getInclusiveRight, kept here for backwards compatibility.
Returns the inclusiveLeft flag. Null for non-inclusive aware ranges or non-null for inclusive aware ranges.
Returns the inclusiveRight flag. Null for non-inclusive aware ranges or non-null for inclusive aware ranges.
* The upper value in the range. * *
Gets the 'to' value as a primitive integer.
Returns the hash code value for this list.
*
* Indicates whether this is a reverse range which iterates backwards * starting from the to value and ending on the from value * *
true if this is a reverse rangeReturns an iterator over the elements in this list in proper sequence.
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.
* Steps through the range, calling a closure for each item. * *
step - the amount by which to step. If negative, steps through the range backwards.
*closure - the Closure to call* Forms a list by stepping through the range by the indicated interval. * *
step - the amount by which to step. If negative, steps through the range backwards.
* 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();
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.)
fromIndex < 0 || toIndex > size ||
fromIndex > toIndex)(fromIndex < 0 || toIndex > size)(fromIndex > toIndex)fromIndex - low endpoint (inclusive) of the subListtoIndex - high endpoint (exclusive) of the subListAbstractList. 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.
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.
size - the size of the aggregate being indexed 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.
Copyright © 2003-2026 The Apache Software Foundation. All rights reserved.