stream

Description:

public virtual Iterator<A> stream<A> (owned StreamFunc<Entry<K,V>,A> f)

Stream function is an abstract function allowing writing many operations.

The stream function accepts three parameter:

state. It is usually the last returned value from function but
it may be Stream.END when Stream.CONTINUE was

returned and there was no more elements.
input. It is valid only if first argument is
Stream.CONTINUE
output. It is valid only if result is Stream.YIELD

It may return one of 3 results:

Stream.YIELD. It means that value was yielded and can
be passed to outgoing iterator.
Stream.CONTINUE. It means that the function needs to be
called with next element or with Stream.END if it is

end of stream). If the state element was Stream.END during the

current iteration function must not return Stream.CONTINUE .
Stream.WAIT. Simply denotes that iterator should skip an element.
Usually the function is called once again with Stream.WAIT as

state however it do affect the initial validity of iterator.
Stream.END. It means that the last argument was yielded.

If the function yields the value immediately then the returning iterator is Iterator.valid and points to this value as well as in case when the parent iterator is Iterator.valid and function yields after consuming 1 input. In other case returned iterator is invalid including when the first value returned is Stream.WAIT.

Note:

In Iterator implementation: if iterator is Iterator.valid the current value should be fed immediately to function if during initial call function returns Stream.CONTINUE. The parent iterator cannot be used before the functions return Stream.END afterwards it points on the last element consumed.