Permalink
Browse files

Iterator, Iterable (very incomplete)

  • Loading branch information...
1 parent a90f472 commit e9f2f73e2d6934d04abf2856e763270fc8f5328d @moritz moritz committed Aug 3, 2012
Showing with 49 additions and 0 deletions.
  1. +14 −0 lib/Iterable.pod
  2. +35 −0 lib/Iterator.pod
View
@@ -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
View
@@ -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

0 comments on commit e9f2f73

Please sign in to comment.