Top Description Inners Fields Constructors Methods
groovy.lang

public Class NumberRange

extends AbstractList<Comparable<T>>
implements Range<Comparable<T>>, 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.InvokerHelper, .IteratorClosureAdapter, .RangeInfo, org.codehaus.groovy.runtime.typehandling.NumberMath, java.io.Serializable, java.math.BigDecimal, .BigInteger, .RoundingMode, java.util.AbstractList, .Iterator, .List, .NoSuchElementException

Represents an immutable list of Numbers from a value to a value with a particular step size. In general, it isn't recommended using a NumberRange as a key to a map. The range 0..3 is deemed to be equal to 0.0..3.0 but they have different hashCode values, so storing a value using one of these ranges couldn't be retrieved using the other.
Since
2.5.0

Nested and Inner Type Summary

Modifier and TypeClass and Description
private class
NumberRange.StepIterator

convenience class to serve in other methods.

Field Summary

Modifier and TypeField and Description
private final Comparable<T>
from

The first value in the range.

private Integer
hashCodeCache

The cached hashCode (once calculated)

private final boolean
inclusive

true if the range includes the upper bound.

private final boolean
reverse

true if the range counts backwards from to to from.

private static final long
private int
size

The cached size, or -1 if not yet computed

private final Number
stepSize

The step size in the range.

private final Comparable<T>
to

The last value in the range.

Inherited from java.util.AbstractList:
modCount

Constructor Summary

AccessConstructor and Description
public <T extends Number & Comparable<T>, U extends Number & Comparable<T>>
NumberRange(T
the first value in the range
from
,
U
the last value in the range
to
)

Creates an inclusive NumberRange with step size 1.

public <T extends Number & Comparable<T>, U extends Number & Comparable<T>>
NumberRange(T
start of the range
from
,
U
end of the range
to
,
boolean
whether the range is inclusive
inclusive
)

Creates a new NumberRange with step size 1.

public <T extends Number & Comparable<T>, U extends Number & Comparable<T>, V extends Number & Comparable<? super Number>>
NumberRange(T
start of the range
from
,
U
end of the range
to
,
V
the gap between discrete elements in the range
stepSize
)

Creates an inclusive NumberRange.

public <T extends Number & Comparable<T>, U extends Number & Comparable<T>, V extends Number & Comparable<T>>
NumberRange(T
start of the range
from
,
U
end of the range
to
,
V
the gap between discrete elements in the range
stepSize
,
boolean
whether the range is inclusive
inclusive
)

Creates a NumberRange.

Method Summary

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

Returns:

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

For a NumberRange with step size 1, creates a new NumberRange with the same from and to as this NumberRange but with a step size of stepSize.

pack-priv void
calcSize(Comparable<T> from, Comparable<T> to, Number stepSize)

pack-priv static <T extends Number & Comparable<T>> T
pack-priv static <T extends Number & Comparable<T>> T
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.

iterates over all values and returns true if one value matches.
public boolean

Returns:

true if the value is within the bounds
containsWithinBounds
(Object
the value of interest
value
)

Implements groovy.lang.Range.containsWithinBounds.

Checks whether a value is between the from and to values of a Range
private Comparable<T>

Returns:

the decremented value
decrement
(Object
the value to decrement
value
,
Number
the amount to decrement
step
)

Decrements by given step

public boolean

Returns:

true if the specified object is equal to this NumberRange
equals
(Object
the object to be compared for equality with this NumberRange
that
)

Overrides java.util.AbstractList.equals.

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

An object is deemed equal to this NumberRange if it represents a List of items and those items equal the list of discrete items represented by this NumberRange.
public boolean

Returns:

true if the ranges are equal
fastEquals
(NumberRange
the NumberRange to check equality with
that
)

Compares a NumberRange to another NumberRange using only a strict comparison of the NumberRange properties.

public Comparable<T>
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 Comparable<T>
getFrom()

Implements groovy.lang.Range.getFrom.

The lower value in the range.
public Comparable<T>
public Comparable<T>
getTo()

Implements groovy.lang.Range.getTo.

The upper value in the range.
private String
getToString(String toText, String fromText)

public int

Returns:

the hashCode value
hashCode
()

Overrides java.util.AbstractList.hashCode.

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

A NumberRange's hashCode is based on hashCode values of the discrete items it represents.
private Comparable<T>

Returns:

the incremented value
increment
(Object
the value to increment
value
,
Number
the amount to increment
step
)

Increments by given step

public String
private boolean
isIntegral(Number stepSize)

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<Comparable<T>>
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.
private void
setSize(int size)

protection against calls from Groovy

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.
numSteps
,
Closure<V>
the Closure to call
closure
)

Implements groovy.lang.Range.step.

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

Implements groovy.lang.Range.step.

Forms a list by stepping through the range by the indicated interval.
public List<Comparable<T>>
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.

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 Comparable<T> from

The first value in the range.

hashCodeCacheback to summary
private Integer hashCodeCache

The cached hashCode (once calculated)

inclusiveback to summary
private final boolean inclusive

true if the range includes the upper bound.

reverseback to summary
private final boolean reverse

true if the range counts backwards from to to from.

serialVersionUIDback to summary
private static final long serialVersionUID
sizeback to summary
private int size

The cached size, or -1 if not yet computed

stepSizeback to summary
private final Number stepSize

The step size in the range.

toback to summary
private final Comparable<T> to

The last value in the range.

Constructor Detail

NumberRangeback to summary
public <T extends Number & Comparable<T>, U extends Number & Comparable<T>> NumberRange(T from, U to)

Creates an inclusive NumberRange with step size 1. Creates a reversed range if from < to.

Parameters
from:T

the first value in the range

to:U

the last value in the range

NumberRangeback to summary
public <T extends Number & Comparable<T>, U extends Number & Comparable<T>> NumberRange(T from, U to, boolean inclusive)

Creates a new NumberRange with step size 1. Creates a reversed range if from < to.

Parameters
from:T

start of the range

to:U

end of the range

inclusive:boolean

whether the range is inclusive

NumberRangeback to summary
public <T extends Number & Comparable<T>, U extends Number & Comparable<T>, V extends Number & Comparable<? super Number>> NumberRange(T from, U to, V stepSize)

Creates an inclusive NumberRange. Creates a reversed range if from < to.

Parameters
from:T

start of the range

to:U

end of the range

stepSize:V

the gap between discrete elements in the range

NumberRangeback to summary
public <T extends Number & Comparable<T>, U extends Number & Comparable<T>, V extends Number & Comparable<T>> NumberRange(T from, U to, V stepSize, boolean inclusive)

Creates a NumberRange. Creates a reversed range if from < to.

Parameters
from:T

start of the range

to:U

end of the range

stepSize:V

the gap between discrete elements in the range

inclusive:boolean

whether the range is inclusive

Method Detail

areReversedback to summary
private static boolean areReversed(Number from, Number to)
byback to summary
public <T extends Number & Comparable<T>> NumberRange by(T stepSize)

For a NumberRange with step size 1, creates a new NumberRange with the same from and to as this NumberRange but with a step size of stepSize.

Parameters
stepSize:T

the desired step size

Returns:NumberRange

a new NumberRange

calcSizeback to summary
pack-priv void calcSize(Comparable<T> from, Comparable<T> to, Number stepSize)
comparableNumberback to summary
pack-priv static <T extends Number & Comparable<T>> T comparableNumber(Comparable<T> c)
Annotations
@SuppressWarnings:unchecked
comparableNumberback to summary
pack-priv static <T extends Number & Comparable<T>> T comparableNumber(Number n)
Annotations
@SuppressWarnings:unchecked
containsback to summary
public boolean contains(Object value)

Overrides java.util.AbstractCollection.contains.

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

iterates over all values and returns true if one value matches. Also see containsWithinBounds.

Parameters
value:Object

Doc from java.util.List.contains.

element whose presence in this list is to be tested

Returns:boolean

Doc from java.util.List.contains.

true if this list contains the specified element

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

Implements groovy.lang.Range.containsWithinBounds.

Checks whether a value is between the from and to values of a Range

Parameters
value:Object

the value of interest

Returns:boolean

true if the value is within the bounds

Annotations
@Override
decrementback to summary
private Comparable<T> decrement(Object value, Number step)

Decrements by given step

Parameters
value:Object

the value to decrement

step:Number

the amount to decrement

Returns:Comparable<T>

the decremented value

Annotations
@SuppressWarnings:unchecked
equalsback to summary
public boolean equals(Object that)

Overrides java.util.AbstractList.equals.

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

An object is deemed equal to this NumberRange if it represents a List of items and those items equal the list of discrete items represented by this NumberRange.

Parameters
that:Object

the object to be compared for equality with this NumberRange

Returns:boolean

true if the specified object is equal to this NumberRange

Annotations
@Override
See Also
fastEquals(NumberRange)
fastEqualsback to summary
public boolean fastEquals(NumberRange that)

Compares a NumberRange to another NumberRange using only a strict comparison of the NumberRange properties. This won't return true for some ranges which represent the same discrete items, use equals instead for that but will be much faster for large lists.

Parameters
that:NumberRange

the NumberRange to check equality with

Returns:boolean

true if the ranges are equal

getback to summary
public Comparable<T> 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:Comparable<T>

the element at the specified position in this list

Annotations
@Override
getFromback to summary
public Comparable<T> getFrom()

Implements groovy.lang.Range.getFrom.

Doc from groovy.lang.Range.getFrom.

The lower value in the range.

Returns:Comparable<T>

the lower value in the range.

Annotations
@Override
getStepSizeback to summary
public Comparable<T> getStepSize()
getToback to summary
public Comparable<T> getTo()

Implements groovy.lang.Range.getTo.

Doc from groovy.lang.Range.getTo.

The upper value in the range.

Returns:Comparable<T>

the upper value in the range

Annotations
@Override
getToStringback to summary
private String getToString(String toText, String fromText)
hashCodeback to summary
public int hashCode()

Overrides java.util.AbstractList.hashCode.

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

A NumberRange's hashCode is based on hashCode values of the discrete items it represents.

Returns:int

the hashCode value

Annotations
@Override
incrementback to summary
private Comparable<T> increment(Object value, Number step)

Increments by given step

Parameters
value:Object

the value to increment

step:Number

the amount to increment

Returns:Comparable<T>

the incremented value

Annotations
@SuppressWarnings:unchecked
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
isIntegralback to summary
private boolean isIntegral(Number stepSize)
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<Comparable<T>> 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<Comparable<T>>

an iterator over the elements in this list in proper sequence

Annotations
@Override
setSizeback to summary
private void setSize(int size)

protection against calls from Groovy

Annotations
@SuppressWarnings:unused
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 numSteps, 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
numSteps: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<Comparable<T>> step(int numSteps)

Implements groovy.lang.Range.step.

Doc from groovy.lang.Range.step.

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

Parameters
numSteps:int

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

Returns:List<Comparable<T>>

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

Annotations
@Override
subListback to summary
public List<Comparable<T>> 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<Comparable<T>>

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

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

Annotations
@Override
groovy.lang back to summary

private Class NumberRange.StepIterator

extends Object
implements Iterator<Comparable<T>>
Class Inheritance
All Implemented Interfaces
java.util.Iterator

convenience class to serve in other methods. It's not thread-safe, and lazily produces the next element only on calls of hasNext() or next()

Field Summary

Modifier and TypeField and Description
private final boolean
private boolean
private Comparable<T>
private final NumberRange
private final Number

Constructor Summary

AccessConstructor and Description
pack-priv

Method Summary

Modifier and TypeMethod and Description
private void
public boolean
hasNext()

Implements java.util.Iterator.hasNext.

Returns true if the iteration has more elements.
public Comparable<T>
next()

Implements java.util.Iterator.next.

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

Overrides default java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation).
Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

isAscendingback to summary
private final boolean isAscending
isNextFetchedback to summary
private boolean isNextFetched
nextback to summary
private Comparable<T> next
rangeback to summary
private final NumberRange range
stepback to summary
private final Number step

Constructor Detail

StepIteratorback to summary
pack-priv StepIterator(NumberRange range, Number step)

Method Detail

fetchNextIfNeededback to summary
private void fetchNextIfNeeded()
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 Comparable<T> next()

Implements java.util.Iterator.next.

Doc from java.util.Iterator.next.

Returns the next element in the iteration.

Returns:Comparable<T>

the next element in the iteration

Annotations
@Override
removeback to summary
public void remove()

Overrides default java.util.Iterator.remove.

Doc from java.util.Iterator.remove.

Removes from the underlying collection the last element returned by this iterator (optional operation). This method can be called only once per call to next.

The behavior of an iterator is unspecified if the underlying collection is modified while the iteration is in progress in any way other than by calling this method, unless an overriding class has specified a concurrent modification policy.

The behavior of an iterator is unspecified if this method is called after a call to the forEachRemaining method.

Annotations
@Override