Iterator, Iterable (very incomplete)

Author: moritz

lib/Iterable.pod

@@ -0,0 +1,14 @@
+=begin pod
+
+=TITLE class Iterable
+
+    class Iterable is Cool { }
+
+C<Iterable> serves as a superclass for objects that can be iterated with the
+C<for> construct and related iteration constructs.
+
+C<Iterable> objects nested in other C<Iterable> objects (but not within scalar
+containers) flatten in certain contexts, for example when iterated with a
+C<for> loop, or on list assignment.
+
+=end pod

lib/Iterator.pod

@@ -0,0 +1,35 @@
+=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