jaggregate
Class Interval<E extends Number>

java.lang.Object
  jaggregate.AbstractCollection<E>
      jaggregate.Interval<E>

Type Parameters:

E - a restriction on the kinds of numbers that can be in the interval

All Implemented Interfaces:

Collection<E>, ReadOnlySequence<E>, Serializable

public class Interval<E extends Number>
extends AbstractCollection<E>
implements ReadOnlySequence<E>, Serializable

Represents a collection whose elements form an arithmetic progression.

Currently, all the derivatives of Number in JDK 5 that override equals for value equality are supported as type arguments for this class. This excludes the new AtomicInteger and AtomicLong.

This class does nothing to compensate for the inexact representation of primitive floating-point values; keep this in mind when using intervals of float or double.

Version:

$Id: Interval.java,v 1.7 2008/10/03 19:01:23 pholser Exp $

Author:

Paul Holser

See Also:

Serialized Form

Constructor Summary

Interval(E from, E to)
Creates an interval representing an arithmetic progression from one number to another, in increments of 1.

Interval(E from, E to, E by)
Creates an interval representing an arithmetic progression from one number to another, with the given increment.

Method Summary

E	after(E target) Answers the object immediately following the first element which is equivalent to the given target in this sequence.
E	at(int index) Answers the element at the given position in this sequence.
E	before(E target) Answers the object immediately preceding the first element which is equivalent to the given target in this sequence.
<R> ReadOnlySequence<R>	collect(UnaryFunctor<? super E,? extends R> transformer) Evaluates the given transformer for each element of this collection, with the element as the parameter, and answers a new collection containing the results of these evaluations. The elements are traversed in the order specified by forEachDo for this collection. Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection.
ReadOnlySequence<E>	concat(ReadOnlySequence<? extends E> otherSequence) Answers a new sequence containing all of this sequence's elements in their original order followed by all of the elements of the given sequence, in their original order.
ReadOnlySequence<E>	copyRange(int start, int stop) Answers a new sequence containing the specified range of elements of this sequence in their original order.
ReadOnlySequence<E>	copyWith(E newElement) Answers a new sequence with size one greater than the size of this sequence, containing the elements of this sequence and a given new element placed at the end.
ReadOnlySequence<E>	copyWithout(E oldElement) Answers a new sequence with all of the elements of this sequence that are not equivalent to the given element, in their original order.
void	doWithIndex(BinaryFunctor<? super Integer,? super E,?> operation) Evaluates the given operation with the index of each element of this sequence, in order, together with the element itself.
<T> void	doWithOthers(ReadOnlySequence<? extends T> otherSequence, BinaryFunctor<? super E,? super T,?> operation) For each element of this sequence and the corresponding element of the given sequence, evaluates the given operation with this sequence's element as the first parameter, and the element of the other sequence as the second parameter.
boolean	equals(Object that)
int	findFirst(UnaryCondition<? super E> discriminator) Answers the index of the first element which causes the given discriminator to answer true when the element is used as a parameter.
int	findLast(UnaryCondition<? super E> discriminator) Answers the index of the last element which causes the given discriminator to answer true when the element is used as a parameter.
E	first() Answers the element at index 0 in this sequence.
void	forEachDo(UnaryFunctor<? super E,?> operation) For each element of this collection, evaluates the given operation with the element as the parameter.
void	forEachInRangeDo(int start, int stop, UnaryFunctor<? super E,?> operation) For those elements of this sequence between two given positions, inclusive, evaluates the given operation with the element at that index as its argument.
void	forEachInRangeDoWithIndex(int start, int stop, BinaryFunctor<? super Integer,? super E,?> operation) For those elements of this sequence between two given positions, inclusive, evaluates the given operation with an element of this sequence as the first argument and the element's position (index) as the second.
void	forEachInReverseDo(UnaryFunctor<? super E,?> operation) Evaluates the given operation with each element of this sequence in the reverse of this sequence's standard traversal order.
static <T extends Number> Interval<T>	fromTo(T from, T to) Creates an interval representing an arithmetic progression from one number to another, in increments of 1.
static <T extends Number> Interval<T>	fromToBy(T from, T to, T by) Creates an interval representing an arithmetic progression from one number to another, with the given increment.
int	hashCode()
boolean	includes(E target) Answers true if an element of this collection is equivalent to the given one; answers false otherwise.
int	indexOf(E target) Answers the index of the first element which is equivalent to the given target}.
int	indexOf(ReadOnlySequence<? extends E> targetSequence, int start) Answers the index of the first element of this sequence which is the start of a subsequence which matches a given target sequence.
E	last() Answers the last element of this sequence, the element at the index equal to this sequence's size minus 1.
ReadOnlySequence<E>	reject(UnaryCondition<? super E> discriminator) Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer false. For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer false is included in the new collection. The elements are traversed in the order specified by forEachDo for this collection. Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.
ReadOnlySequence<E>	reverse() Answers a sequence with the elements of this sequence arranged in reverse order.
ReadOnlySequence<E>	select(UnaryCondition<? super E> discriminator) Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true. For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer true is included in the new collection. The elements are traversed in order specified by forEachDo for this collection. Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.
int	size() Answers the number of elements in this collection.
String	toString()

Methods inherited from class jaggregate.AbstractCollection

allSatisfy, anySatisfy, detect, inject, isEmpty, occurrencesOf, rehash, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface jaggregate.Collection

allSatisfy, anySatisfy, detect, inject, isEmpty, occurrencesOf, rehash, toArray, toArray, toBag, toIdentityBag, toIdentitySet, toOrderedCollection, toSet, toSortedCollection, toSortedCollection

Constructor Detail

Interval

public Interval(E from,
                E to)

Creates an interval representing an arithmetic progression from one number to another, in increments of 1.

The interval will be empty if from > to.

Parameters:

from - the first element in the interval

to - the last element of the interval

Throws:

NullPointerException - if either from or to is null

Interval

public Interval(E from,
                E to,
                E by)

Creates an interval representing an arithmetic progression from one number to another, with the given increment.

by can be negative.

Note that to is not necessarily an element in the interval. The last element is given by:

( to - from ) / by * by + from

The interval will be empty if from < to and by < 0, or if from > to and by > 0.

Parameters:

from - the first element in the interval

to - the termination of the interval

by - the increment to use to compute successive interval values. If this is null, it will be treated as 1.

Throws:

NullPointerException - if either from or to is null

IllegalArgumentException - if by == 0

Method Detail

fromTo

public static <T extends Number> Interval<T> fromTo(T from,
                                                    T to)

Creates an interval representing an arithmetic progression from one number to another, in increments of 1.

The interval will be empty if from > to.

Type Parameters:

T - the type of numbers in the interval

Parameters:

from - the first element in the interval

to - the last element of the interval

Returns:

the new interval

Throws:

NullPointerException - if either from or to is null

fromToBy

public static <T extends Number> Interval<T> fromToBy(T from,
                                                      T to,
                                                      T by)

Creates an interval representing an arithmetic progression from one number to another, with the given increment.

by can be negative.

Note that to is not necessarily an element in the interval. The last element is given by: ( to - from ) / by * by + from

The interval will be empty if from < to and by < 0, or if from > to and by > 0.

Type Parameters:

T - the type of numbers in the interval

Parameters:

from - the first element in the interval

to - the termination of the interval

by - the increment to use to compute successive interval values. If this is null, it will be treated as 1.

Returns:

the new interval

Throws:

NullPointerException - if from, to, or by is null

IllegalArgumentException - if by == 0

collect

public <R> ReadOnlySequence<R> collect(UnaryFunctor<? super E,? extends R> transformer)

Evaluates the given transformer for each element of this collection, with the element as the parameter, and answers a new collection containing the results of these evaluations.

The elements are traversed in the order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection.

Specified by:

collect in interface Collection<E extends Number>

Specified by:

collect in interface ReadOnlySequence<E extends Number>

Overrides:

collect in class AbstractCollection<E extends Number>

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a collection of the transformations

reject

public ReadOnlySequence<E> reject(UnaryCondition<? super E> discriminator)

Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer false.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer false is included in the new collection.

The elements are traversed in the order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.

Specified by:

reject in interface Collection<E extends Number>

Specified by:

reject in interface ReadOnlySequence<E extends Number>

Overrides:

reject in class AbstractCollection<E extends Number>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the rejected elements of this collection

select

public ReadOnlySequence<E> select(UnaryCondition<? super E> discriminator)

Answers a new collection which contains only the elements in this collection which cause the given discriminator to answer true.

For each element of this collection, discriminator is evaluated with the element as the parameter. Each element which causes discriminator to answer true is included in the new collection.

The elements are traversed in order specified by forEachDo for this collection.

Unless specifically refined, this message is defined to answer an object conforming to the same protocol as this collection. If both this collection and the result maintain an ordering of their elements, the elements of the result will be in the same relative order as the elements of this collection.

Specified by:

select in interface Collection<E extends Number>

Specified by:

select in interface ReadOnlySequence<E extends Number>

Overrides:

select in class AbstractCollection<E extends Number>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a collection of the selected elements of this collection

concat

public ReadOnlySequence<E> concat(ReadOnlySequence<? extends E> otherSequence)

Answers a new sequence containing all of this sequence's elements in their original order followed by all of the elements of the given sequence, in their original order. The size of the new sequence is equal to the sum of the sizes of this sequence and otherSequence.

Sequences that enforce an ordering on their elements are permitted to refine this message to reorder the result.

Specified by:

concat in interface ReadOnlySequence<E extends Number>

Parameters:

otherSequence - the sequence to concatenate

Returns:

the result of the concatenation

after

public E after(E target)

Answers the object immediately following the first element which is equivalent to the given target in this sequence. An element immediately follows another if its index is one greater than that of the other. The order used to determine which of this sequence's elements is the first to be equivalent to target is the traversal order defined by forEachDo for this sequence.

Specified by:

after in interface ReadOnlySequence<E extends Number>

Parameters:

target - the object to lookup

Returns:

the object following target

at

public E at(int index)

Answers the element at the given position in this sequence.

Specified by:

at in interface ReadOnlySequence<E extends Number>

Parameters:

index - the index to lookup

Returns:

the corresponding element

before

public E before(E target)

Answers the object immediately preceding the first element which is equivalent to the given target in this sequence. An element immediately precedes another if its index is one less than that of the other.

Specified by:

before in interface ReadOnlySequence<E extends Number>

Parameters:

target - the object to lookup

Returns:

the object preceding target

copyRange

public ReadOnlySequence<E> copyRange(int start,
                                     int stop)

Answers a new sequence containing the specified range of elements of this sequence in their original order. The element at index start in this sequence is at index 0 in the new sequence; the element at start + 1 is at index 1, etc. If stop < start, then the new sequence is empty. Otherwise, the size of the new sequence is max(0, stop - start).

The given indices must be non-negative.

Specified by:

copyRange in interface ReadOnlySequence<E extends Number>

Parameters:

start - the beginning index

stop - the ending index

Returns:

a new sequence containing the specified range of elements

copyWith

public ReadOnlySequence<E> copyWith(E newElement)

Answers a new sequence with size one greater than the size of this sequence, containing the elements of this sequence and a given new element placed at the end.

Unless specifically refined, this message is defined to answer an instance of the same class as this sequence.

Sequences that enforce an ordering on their elements are permitted to refine this message to reorder the result.

Specified by:

copyWith in interface ReadOnlySequence<E extends Number>

Parameters:

newElement - element to add to the copy

Returns:

copy of this sequence with newElement appended

copyWithout

public ReadOnlySequence<E> copyWithout(E oldElement)

Answers a new sequence with all of the elements of this sequence that are not equivalent to the given element, in their original order.

Specified by:

copyWithout in interface ReadOnlySequence<E extends Number>

Parameters:

oldElement - the element to strip from the copy of this sequence

Returns:

copy of this sequence with oldElement removed

findFirst

public int findFirst(UnaryCondition<? super E> discriminator)

Answers the index of the first element which causes the given discriminator to answer true when the element is used as a parameter. Answers -1 if no such element is found.

The elements are traversed in the order specified by forEachDo for this sequence.

Specified by:

findFirst in interface ReadOnlySequence<E extends Number>

Parameters:

discriminator - the discriminator to evaluate

Returns:

the index of the first match, or -1 if there is no match

findLast

public int findLast(UnaryCondition<? super E> discriminator)

Answers the index of the last element which causes the given discriminator to answer true when the element is used as a parameter. Answers -1 if no such element is found.

The elements are traversed in the order specified by forEachInReverseDo for this sequence.

Specified by:

findLast in interface ReadOnlySequence<E extends Number>

Parameters:

discriminator - the discriminator to evaluate

Returns:

the index of the last match, or -1 if there is no match

forEachInReverseDo

public void forEachInReverseDo(UnaryFunctor<? super E,?> operation)

Evaluates the given operation with each element of this sequence in the reverse of this sequence's standard traversal order. The elements are traversed in the opposite order from forEachDo. Each element is visited exactly once.

Specified by:

forEachInReverseDo in interface ReadOnlySequence<E extends Number>

Parameters:

operation - the operation to evaluate

first

public E first()

Answers the element at index 0 in this sequence.

Specified by:

first in interface ReadOnlySequence<E extends Number>

Returns:

the first element in the sequence

forEachInRangeDo

public void forEachInRangeDo(int start,
                             int stop,
                             UnaryFunctor<? super E,?> operation)

For those elements of this sequence between two given positions, inclusive, evaluates the given operation with the element at that index as its argument.

Specified by:

forEachInRangeDo in interface ReadOnlySequence<E extends Number>

Parameters:

start - beginning index

stop - ending index

operation - the operation to evaluate

forEachInRangeDoWithIndex

public void forEachInRangeDoWithIndex(int start,
                                      int stop,
                                      BinaryFunctor<? super Integer,? super E,?> operation)

For those elements of this sequence between two given positions, inclusive, evaluates the given operation with an element of this sequence as the first argument and the element's position (index) as the second.

Specified by:

forEachInRangeDoWithIndex in interface ReadOnlySequence<E extends Number>

Parameters:

start - beginning index

stop - ending index

operation - the operation to evaluate

indexOf

public int indexOf(E target)

Answers the index of the first element which is equivalent to the given target}. Answers -1 if no such element is found.

The elements are traversed in the order specified by forEachDo for this sequence.

Specified by:

indexOf in interface ReadOnlySequence<E extends Number>

Parameters:

target - element to match

Returns:

index of first match, or -1 if no match

indexOf

public int indexOf(ReadOnlySequence<? extends E> targetSequence,
                   int start)

Answers the index of the first element of this sequence which is the start of a subsequence which matches a given target sequence.

Each subsequence of this sequence starting at index start is checked for a match with targetSequence. To match, each element of a subsequence of this sequence must be equivalent to the corresponding element of\ targetSequence. Answers the index of the first element which begins a matching subsequence; no further subsequences are considered. Answers -1 if no such subsequence is found in this sequence, or if targetSequence is empty.

The elements are traversed in the order specified by forEachDo message for this sequence.

Specified by:

indexOf in interface ReadOnlySequence<E extends Number>

Parameters:

targetSequence - sequence to match

start - index at which to begin the search

Returns:

index of the beginning of the first match, or -1 if none

doWithIndex

public void doWithIndex(BinaryFunctor<? super Integer,? super E,?> operation)

Evaluates the given operation with the index of each element of this sequence, in order, together with the element itself.

operation is evaluated with the index of each element of this sequence as the first argument and the element itself as the second argument. Evaluation is in indexed order starting at 0. The first element is at index 0, the second at index 1, etc. The index of the last element is equal to this sequence's size minus 1.

Specified by:

doWithIndex in interface ReadOnlySequence<E extends Number>

Parameters:

operation - the operation to perform

last

public E last()

Answers the last element of this sequence, the element at the index equal to this sequence's size minus 1.

Specified by:

last in interface ReadOnlySequence<E extends Number>

Returns:

the last element in the sequence

reverse

public ReadOnlySequence<E> reverse()

Answers a sequence with the elements of this sequence arranged in reverse order.

This operation is equivalent to:

1. Create a new sequence which conforms to the same protocols as this sequence.
2. Traverse the elements of this sequence in the order specified by forEachInReverseDo message, adding each element of this sequence to the new sequence.
3. Answer the new sequence.

Specified by:

reverse in interface ReadOnlySequence<E extends Number>

Returns:

a new sequence with the elements of this sequence in reverse order

equals

public boolean equals(Object that)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object

doWithOthers

public <T> void doWithOthers(ReadOnlySequence<? extends T> otherSequence,
                             BinaryFunctor<? super E,? super T,?> operation)

For each element of this sequence and the corresponding element of the given sequence, evaluates the given operation with this sequence's element as the first parameter, and the element of the other sequence as the second parameter. This sequence and otherSequence must have the same size.

The elements of this sequence and otherSequence are traversed in indexed order starting at 0. The operation is evaluated with the elements at index 0 in the two sequences, then index 1, etc.

Specified by:

doWithOthers in interface ReadOnlySequence<E extends Number>

Type Parameters:

T - a constraint on the types of elements in the given sequence

Parameters:

otherSequence - the other elements to use in the evaluation

operation - the operation to perform

forEachDo

public void forEachDo(UnaryFunctor<? super E,?> operation)

For each element of this collection, evaluates the given operation with the element as the parameter.

Unless specifically refined, the elements are not traversed in a particular order. Each element is visited exactly once. Conformant protocols may refine this message to specify a particular ordering.

Specified by:

forEachDo in interface Collection<E extends Number>

Specified by:

forEachDo in interface ReadOnlySequence<E extends Number>

Parameters:

operation - the operation to perform

includes

public boolean includes(E target)

Answers true if an element of this collection is equivalent to the given one; answers false otherwise.

Specified by:

includes in interface Collection<E extends Number>

Overrides:

includes in class AbstractCollection<E extends Number>

Parameters:

target - the object to compare against

Returns:

whether an equivalent object is in the collection

size

public int size()

Answers the number of elements in this collection.

Specified by:

size in interface Collection<E extends Number>

Returns:

the number of elements in this collection