Streams

In stream.cecil:

A stream is like a collection of values, but the values are accessed in sequence. Streams have an implicit position within the stream of values, pointing between two values (or before the first value or after the last value), and operations on streams are relative to this implicit position.

abstract object stream[T];
signature is_at_end(stream[`T]):bool;
method before_end(s@:stream[`T]):bool;
method forward(s@:stream[`T]):void;
signature forward(stream[`T], at_end:&():void):void;
implementation forward(s@:stream_before_end[`T], at_end:&():void):void;
implementation forward(s@:stream_at_end[`T], at_end:&():void):void;
signature next(stream[`T], at_end:&():T):T;
implementation next(s@:stream_before_end[`T], at_end:&():T):T;
implementation next(s@:stream_at_end[`T], at_end:&():void):void;
method next(s@:stream[`T]):T;
method next_N(s@:stream[`T], n:int):sequence[T];
signature peek_next(stream[`T], at_end:&():T):T;
implementation peek_next(s@:stream_at_end[`T], at_end:&():T):T;
method peek_next(s@:stream[`T]):T;
method as_collection(s@:stream[`T]):sequence[T];

The basic stream data type supports forward reading of a stream of values. The at_end and before_end testers check whether the current position is after the last value in the stream. The forward operation advances the position past the next value in the stream. The next operation reads and returns the next value in the stream, advancing the position as a side-effect; the next_N operation reads and returns the next N elements of the stream. The peek_next operation reads and returns the next element of the stream but does not advance the position; a subsequent next or peek_next operation will return the same value.

abstract object m_stream[T] isa stream[T];
signature set_peek_next(m_stream[`T], :T):void;
implementation set_peek_next(@:m_stream_at_end[`T], :T):void;
method set_next(s@:m_stream[`T], x:T):void;
method flush(@:m_stream[`T]):void;

A mutable stream supports changing the value after current position in the stream, and optionally advancing the position past that value. A flush operation makes updates to stream values visible externally, for those implementations of streams such as files that have separate external views.

abstract object removable_stream[T] isa stream[T];
signature remove_next(removable_stream[`T]):void;
implementation remove_next(@:removable_stream_at_end[`T]):void;

A removable_stream supports the remove_next operation, which removes the next element from the stream.

abstract object insertable_stream[T] isa stream[T];
signature insert(insertable_stream[`T], :T):void;
method insert_all(s@:insertable_stream[`T], c@:ordered_collection[T]):void;

An insertable_stream allows an item (or a collection of items) to be inserted immediately behind the current position of the stream, i.e., the position in the stream is right after the inserted value(s).

abstract object extensible_stream[T] isa stream[T];
signature add_last(extensible_stream[`T], x:T):void;
method add_all_last(s@:extensible_stream[`T], c@:ordered_collection[T]):void;

An extensible_stream allows an item (or a collection of items) to be added to the end of the stream; the position of the stream is moved to the end of the stream after the added items.

abstract object reversible_stream[T] isa stream[T];
signature is_at_start(reversible_stream[`T]):bool;
method after_start(s@:reversible_stream[`T]):bool;
signature backward(reversible_stream[`T], at_start:&():void):void;
implementation backward(s@:reversible_stream_after_start[`T],
                        at_start:&():void):void;
implementation backward(s@:reversible_stream_at_start[`T],
                        at_start:&():void):void;
method backward(s@:reversible_stream[`T]):void;
signature prev(reversible_stream[`T], at_start:&():T):T;
implementation prev(s@:reversible_stream_after_start[`T], at_start:&():T):T;
implementation prev(s@:reversible_stream_at_start[`T], at_start:&():T):T;
method prev(s@:reversible_stream[`T]):T;
signature peek_prev(reversible_stream[`T], at_start:&():T):T;
implementation peek_prev(@:reversible_stream_at_start[`T], at_start:&():T):T;
method peek_prev(s@:reversible_stream[`T]):T;
abstract object m_reversible_stream[T] isa reversible_stream[T], m_stream[T];
signature set_peek_prev(m_reversible_stream[`T], :T):void;
implementation set_peek_prev(@:m_reversible_stream_at_start[`T], :T):void;
method set_prev(s@:m_reversible_stream[`T], x:T):void;

A reversible_stream allows backward motion through the stream. It supports backward-looking functions analogous to the forward-looking operations of the generic stream. Similarly, m_reversible_stream supports backwards-looking mutation operations.

abstract object positionable_stream[T] isa reversible_stream[T];
signature position(positionable_stream[`T]):int;
signature set_position(positionable_stream[`T], :int, off_end:&():void):void;
method set_position(s@:positionable_stream[`T], p:int):void;
method forward(s@:positionable_stream[`T], at_end:&():void):void;
method backward(s@:positionable_stream[`T], at_start:&():void):void;
method to_start(s@:positionable_stream[`T]):void;
method to_end(s@:positionable_stream[`T]):void;
method is_at_start(s@:positionable_stream[`T]):bool;
method is_at_end(s@:positionable_stream[`T]):bool;
signature length(positionable_stream[`T]):int;
method is_empty(s@:positionable_stream[`T]):bool;
method non_empty(s@:positionable_stream[`T]):bool;
method view_indexed(@:positionable_stream[`T]):indexed[T];
abstract object m_positionable_stream[T] isa positionable_stream[T],
                                           m_reversible_stream[T];

A positionable_stream supports querying and setting the position in the stream explicitly. The length of the stream can be determined also. Finally, a positionable stream can be viewed as an indexed collection using the view_indexed operation. (view_indexed may not be implemented yet.)