From type/PredictiveIterator

See Original text in context

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.