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:

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

  2. input. It is valid only if first argument is

    Stream.CONTINUE

  3. output. It is valid only if result is Stream.YIELD

It may return one of 3 results:

  1. Stream.YIELD. It means that value was yielded and can

    be passed to outgoing iterator.

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

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

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