role PredictiveIterator

Iterators that can predict number of values

A PredictiveIterator is a special kind of Iterator that can know how many values it will (still) generate without actually needing to generate those values.

The main addition to the API of the Iterator role, is the count-only method, which should return the number of values the Iterator is still able to generate.

The other addition is the bool-only method, that should return a Bool indicating whether the Iterator is stil capable of producing values (aka, is not exhausted yet). By default, this is the Booleanification of the result of the call to the count-only method.

Methods

method count-only

Defined as:

method count-only(--> Int:D{ ... }

It is expected to return the number of values the iterator can still produce without actually producing them. The returned number must adjust itself for items already pulled, so that the method can be called on a partially consumed Iterator.

It will be used in situations where only the number of values of an iterator is needed, e.g. when the .elems method is called.

Important: it's expected the Iterators that implement this method can return that number without producing any values. In other words, it's expected the user of the class will be able to still pull-one after calling this method, and eventually receive as many values as the return value of this method indicated.

method bool-only

Defaults to the Booleanification of the result of calling the count-only method. If it is possible to have a faster way of finding out whether the iterator is capable of producing any value, it should be implemented.

Defined as:

method bool-only(--> Bool:D{ self.count-only.Bool }