=begin pod

=TITLE class Iterator

    class Iterator is Iterable { }

A C<Iterator> is an object that can generate or provide elements of a
sequence. Users usually don't have to care about iterators, their usage
is hidden behind iteration APIs such as C<for @list { }>, L<map>, L<grep>
and list indexing with C<.[$idx]>.

Iterators provide an immutable view of a sequence, though the actual elements
in the sequence can still be mutable.

=head1 Methods

=head2 reify

    method reify(Iterator:D: $n) returns Parcel:D

Returns at least C<$n> elements of the sequence, followed by additional
iterators needed to generate the remaining elements.

Subsequent calls to C<reify> on the same object must return the same
L<Parcel>, even if C<$n> changed between the calls.

=head2 infinite

    method infinite(Iterator:D:)

Returns C<True> if the sequence being iterated is known to be infinite,
C<False> if it is known to be finite, and C<Mu> if the iterator does not know
if the sequence is finite or infinite.

=end pod