method push-at-least

Documentation for method push-at-least assembled from the following types:

role Iterator

From Iterator

(Iterator) method push-at-least

Defined as:

method push-at-least(Iterator:D: $targetint $count --> Mu)

Should produce at least $count elements, and for each of them, call $target.push($value).

If fewer than $count elements are available from the iterator, it should return the sentinel value IterationEnd. Otherwise it should return $count.

Iterators with side effects should produce exactly $count elements; iterators without side effects (such as Range iterators) can produce more elements to achieve better performance.

my @array;
say (1 .. ∞).iterator.push-at-least(@array10); # OUTPUT: «10␤» 
say @array# OUTPUT: «[1 2 3 4 5 6 7 8 9 10]␤» 

The Iterator role implements this method in terms of pull-one. In general, it is also not intended to be called directly as in the example above. It can be implemented, if unhappy with this default implementation, by those using this role. See the documentation for push-exactly for an example implementation.