=begin pod :kind("Type") :subkind("role") :category("basic")

=TITLE role PredictiveIterator

=SUBTITLE Iterators that can predict number of values

A C<PredictiveIterator> is a special kind of L<Iterator|/type/Iterator> that can know
how many values it will (still) generate B<without> actually needing to
generate those values.

The main addition to the API of the L<Iterator|/type/Iterator> role, is the C<count-only>
method, which should return the number of values the Iterator is still
able to generate.

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

=head1 Methods

=head2 method count-only

Defined as:

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

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

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

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

=head2 method bool-only

Defaults to the Booleanification of the result of calling the C<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 }

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
