jaggregate
Interface GettableStream<E,S extends ReadOnlySequence<E>>

Type Parameters:

E - the type of elements in the stream

S - the type of the backing store

All Known Implementing Classes:

ReadStream

public interface GettableStream<E,S extends ReadOnlySequence<E>>

Provides protocol for a stream that can read objects from its future sequence values.

Version:

$Id: GettableStream.java,v 1.4 2008/05/08 03:49:37 pholser Exp $

Author:

Paul Holser

Method Summary

<R> void	forEachDo(UnaryFunctor<? super E,? extends R> operation) Evaluates the given operation with each of this stream's future sequence values, terminating evaluation when there are no more future sequence values.
boolean	isNextMatchFor(E target) Reads the next object from this stream and tells whether the object is equivalent to the given target.
boolean	isPeekMatchFor(E target) Peeks at the next object in this stream and tells whether it is equivalent to the given target.
E	next() Answers the next object in this stream.
S	next(int amount) Answers a collection of the next given number of objects in this stream.
E	peek() Answers the next object in this stream without advancing this stream's position.
void	skip(int amount) Skips the next given number of objects in this stream's future sequence values.
boolean	skipTo(E target) Sets this stream to read the object just after the next occurrence of the given target and answers true.
S	upTo(E target) Answers a collection of all of the objects in this stream up to, but not including, the next occurrence of the given target.

Method Detail

forEachDo

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

Evaluates the given operation with each of this stream's future sequence values, terminating evaluation when there are no more future sequence values.

Each member of the future sequence values is, in turn, removed from the future sequence values; appended to the past sequence values; and, passed as the argument to an evaluation of operation. The number of evaluations is equal to the initial size of the future sequence values. If initially there are no future sequence values, operation is not evaluated. The future sequence values are used as arguments in their sequence order. The result is undefined if any evaluation of operation changes the future sequence values.

Type Parameters:

R - a constraint on the return type of the operation

Parameters:

operation - the operation to evaluate

Throws:

NullPointerException - if operation is null

next

E next()

Answers the next object in this stream.

The first object is removed from the future sequence values and appended to the end of the past sequence values, and returned as the result of the message.

Returns:

the next object in this stream

Throws:

NoSuchElementException - if this stream has no future sequence values

next

S next(int amount)

Answers a collection of the next given number of objects in this stream.

A number of objects equal to amount are removed from the future sequence values and appended, in order, to the end of the past sequence values. A collection whose elements consist of those objects, in the same order, is returned. If amount == 0, an empty collection is returned.

Parameters:

amount - the number of objects to enumerate

Returns:

a sequence consisting of the enumerated objects

Throws:

IllegalArgumentException - if amount < 0 or amount > the number of objects in this stream's future sequence values

isNextMatchFor

boolean isNextMatchFor(E target)

Reads the next object from this stream and tells whether the object is equivalent to the given target.

The first object is removed from the future sequence values and appended to the past sequence values, regardless of the result of the comparison to target.

Parameters:

target - the object against which to compare the next object from this stream

Returns:

true if the next object is equivalent to target; false otherwise

Throws:

NoSuchElementException - if there are no future sequence values in this stream

peek

E peek()

Answers the next object in this stream without advancing this stream's position.

Answers the first object in the future sequence values without removing it from the future sequence values. Answers null if this stream has no future sequence values. The answer will also be null if the first future sequence value is null.

Returns:

the next object in this stream

isPeekMatchFor

boolean isPeekMatchFor(E target)

Peeks at the next object in this stream and tells whether it is equivalent to the given target.

Parameters:

target - the object to match against

Returns:

true if the first object in this stream's future sequence values is equivalent to target, otherwise false

skip

void skip(int amount)

Skips the next given number of objects in this stream's future sequence values.

A number of objects equal to the lesser of amount and the size of the future sequence values are removed from the future sequence values and appended, in order, to the end of the past sequence values.

Parameters:

amount - the number of objects to skip

Throws:

IllegalArgumentException - if amount < 0

skipTo

boolean skipTo(E target)

Sets this stream to read the object just after the next occurrence of the given target and answers true. If target is not found before the end of this stream is encountered, answers false.

Each object in the future sequence values up to and including the first occurrence of an object that is equivalent to target is removed from the future sequence values and appended to the past sequence values. If an object that is equivalent to target is not found in the future sequence values, all of the objects in the future sequence values are so appended.

Parameters:

target - the object to skip to

Returns:

true if target could be found, otherwise false

upTo

S upTo(E target)

Answers a collection of all of the objects in this stream up to, but not including, the next occurrence of the given target. Sets this stream to read the object just after the next occurrence of target. If target is not found and the end of this stream is encountered, a collection of the objects read is returned.

Each object in the future sequence values up to and including the first occurrence of an object that is equivalent to target is removed from the future sequence values and appended to the past sequence values. A collection, containing, in order, all of the transferred objects except the object (if any) that is equivalent to target is returned. If the future sequence values is initially empty, an empty collection is returned.

Parameters:

target - the object to seek

Returns:

a sequence as specified above