jaggregate
Class ReadStream<E>

java.lang.Object
  jaggregate.CollectionStream<E,ReadOnlySequence<E>>
      jaggregate.ReadStream<E>

Type Parameters:

E - a restriction on the types of elements being streamed over

All Implemented Interfaces:

GettableStream<E,ReadOnlySequence<E>>, Stream<E,ReadOnlySequence<E>>

public class ReadStream<E>
extends CollectionStream<E,ReadOnlySequence<E>>
implements GettableStream<E,ReadOnlySequence<E>>

Represents a stream that has a positionable sequence of values that can be read. The sequence values are provided by a sequenced collection that serves as the stream backing store.

Note that there is nothing to stop a caller to continue to manipulate the sequence being streamed over via another reference that allows such manipulations: adding to the sequence, replacing elements in the sequence, and so forth. However, the stream will still stop reading elements when it reaches the end of the sequence as it was set up at the time the stream was created.

Version:

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

Author:

Paul Holser

Constructor Summary

ReadStream(ReadOnlySequence<E> backingStore)
Creates a new stream over the given backing sequence.

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.
OrderedCollection<E>	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.
static <T> ReadStream<T>	readStreamOver(ReadOnlySequence<T> backingStore) Creates a new stream over the given backing sequence.
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.
OrderedCollection<E>	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.

Methods inherited from class jaggregate.CollectionStream

atEnd, close, contents, isEmpty, position, position, reset, setToEnd

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ReadStream

public ReadStream(ReadOnlySequence<E> backingStore)

Creates a new stream over the given backing sequence.

Parameters:

backingStore - the backing sequence to stream over

Throws:

NullPointerException - if backingStore is null

Method Detail

readStreamOver

public static <T> ReadStream<T> readStreamOver(ReadOnlySequence<T> backingStore)

Creates a new stream over the given backing sequence.

Type Parameters:

T - the type of elements in the backing sequence

Parameters:

backingStore - the backing sequence to stream over

Returns:

the new stream

Throws:

NullPointerException - if backingStore is null

forEachDo

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

Specified by:

forEachDo in interface GettableStream<E,ReadOnlySequence<E>>

Type Parameters:

R - a constraint on the return type of the operation

Parameters:

operation - the operation to evaluate

next

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

Specified by:

next in interface GettableStream<E,ReadOnlySequence<E>>

Returns:

the next object in this stream

next

public OrderedCollection<E> 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.

Specified by:

next in interface GettableStream<E,ReadOnlySequence<E>>

Parameters:

amount - the number of objects to enumerate

Returns:

a sequence consisting of the enumerated objects

isNextMatchFor

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

Specified by:

isNextMatchFor in interface GettableStream<E,ReadOnlySequence<E>>

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

peek

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

Specified by:

peek in interface GettableStream<E,ReadOnlySequence<E>>

Returns:

the next object in this stream

isPeekMatchFor

public boolean isPeekMatchFor(E target)

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

Specified by:

isPeekMatchFor in interface GettableStream<E,ReadOnlySequence<E>>

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

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

Specified by:

skip in interface GettableStream<E,ReadOnlySequence<E>>

Parameters:

amount - the number of objects to skip

skipTo

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

Specified by:

skipTo in interface GettableStream<E,ReadOnlySequence<E>>

Parameters:

target - the object to skip to

Returns:

true if target could be found, otherwise false

upTo

public OrderedCollection<E> 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.

Specified by:

upTo in interface GettableStream<E,ReadOnlySequence<E>>

Parameters:

target - the object to seek

Returns:

a sequence as specified above