jaggregate
Interface ReadOnlySequence<E>

Type Parameters:

E - a restriction on the types of elements that may be included in the sequence

All Superinterfaces:

Collection<E>

All Known Subinterfaces:

Sequence<E>

All Known Implementing Classes:

Interval, NaturallySortedCollection, OrderedCollection, SortedCollection

public interface ReadOnlySequence<E>
extends Collection<E>

Provides protocol for reading an ordered collection of objects whose elements can be accessed using external integer keys. The keys are between zero (0) and the number of elements in the collection minus one (1), inclusive.

Version:

$Id: ReadOnlySequence.java,v 1.6 2008/05/12 23:49:07 pholser Exp $

Author:

Paul Holser

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.
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.
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. operation is evaluated with each element of this sequence in indexed order starting at 0.
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.
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.
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.

Methods inherited from interface jaggregate.Collection

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

Method Detail

collect

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

Type Parameters:

R - return type of the transformer

Parameters:

transformer - the transformer to evaluate

Returns:

a sequence of transformations

reject

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>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a sequence of rejects

select

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>

Parameters:

discriminator - the discriminator to evaluate

Returns:

a sequence of selections

concat

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.

Parameters:

otherSequence - the sequence to concatenate

Returns:

the result of the concatenation

Throws:

NullPointerException - if otherSequence is null

after

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.

Parameters:

target - the object to lookup

Returns:

the object following target

Throws:

NoSuchElementException - if the first occurrence of target is the last element of this sequence, or if this sequence does not include the given target

at

E at(int index)

Answers the element at the given position in this sequence.

Parameters:

index - the index to lookup

Returns:

the corresponding element

Throws:

IndexOutOfBoundsException - if index < 0, or index >= this sequence's size

before

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.

Parameters:

target - the object to lookup

Returns:

the object preceding target

Throws:

NoSuchElementException - if target is the first element of this sequence, or if this sequence does not include the given target

copyRange

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.

Parameters:

start - the beginning index

stop - the ending index

Returns:

a new sequence containing the specified range of elements

Throws:

IndexOutOfBoundsException - if stop > start and (start < 0 or start >= this sequence's size), or if stop > start and (stop < 0 or stop >= this sequence's size)

copyWith

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.

Parameters:

newElement - element to add to the copy

Returns:

copy of this sequence with newElement appended

copyWithout

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.

Parameters:

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

Returns:

copy of this sequence with oldElement removed

forEachDo

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.

operation is evaluated with each element of this sequence 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:

forEachDo in interface Collection<E>

Parameters:

operation - the operation to perform

Throws:

NullPointerException - if operation is null

findFirst

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.

Parameters:

discriminator - the discriminator to evaluate

Returns:

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

Throws:

NullPointerException - if discriminator is null

findLast

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.

Parameters:

discriminator - the discriminator to evaluate

Returns:

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

Throws:

NullPointerException - if discriminator is null

forEachInReverseDo

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.

Parameters:

operation - the operation to evaluate

Throws:

NullPointerException - if operation is null

first

E first()

Answers the element at index 0 in this sequence.

Returns:

the first element in the sequence

Throws:

NoSuchElementException - if this sequence is empty

forEachInRangeDo

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.

Parameters:

start - beginning index

stop - ending index

operation - the operation to evaluate

Throws:

NullPointerException - if operation is null

IndexOutOfBoundsException - if start < 0 or stop >= this sequence's size

forEachInRangeDoWithIndex

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.

Parameters:

start - beginning index

stop - ending index

operation - the operation to evaluate

Throws:

NullPointerException - if operation is null

IndexOutOfBoundsException - if start < 0 or stop >= this sequence's size

indexOf

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.

Parameters:

target - element to match

Returns:

index of first match, or -1 if no match

indexOf

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.

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

Throws:

NullPointerException - if targetSequence is null

IndexOutOfBoundsException - if start < 0 or start >= this sequence's size

doWithIndex

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.

Parameters:

operation - the operation to perform

Throws:

NullPointerException - if operation is null

last

E last()

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

Returns:

the last element in the sequence

Throws:

NoSuchElementException - if this sequence is empty

reverse

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.

Returns:

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

doWithOthers

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

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

Throws:

NullPointerException - if either otherSequence or operation is null

IllegalArgumentException - if this sequence's size is not equal to the size of the other sequence