Author: lwall
Date: 2010-01-30 00:59:38 +0100 (Sat, 30 Jan 2010)
New Revision: 29599
Modified:
docs/Perl6/Spec/S07-iterators.pod
Log:
[S07] start to work out relationship of item/slice context
(seems they treat parcels similarly, if not identically...)
Modified: docs/Perl6/Spec/S07-iterators.pod
===================================================================
--- docs/Perl6/Spec/S07-iterators.pod 2010-01-29 23:17:27 UTC (rev 29598)
+++ docs/Perl6/Spec/S07-iterators.pod 2010-01-29 23:59:38 UTC (rev 29599)
@@ -14,8 +14,8 @@
Created: 27 Nov 2008
- Last Modified: 23 Jan 2010
- Version: 8
+ Last Modified: 29 Jan 2010
+ Version: 9
=head1 Laziness and Eagerness
@@ -192,13 +192,50 @@
returned in each iteration is visible if this iterator is being used
to build a slice. While building a list, the items will be flattened.
-When it runs out of items, it will return C<Nil>. List context
-always removes C<Nil> values as part of flattening, while slice
-context always promotes parcels to C<Seq>, so it is never possible
-for this method to return C<Nil> as a value. We can use C<Nil> as
-the sentinel because iterators never return C<Parcel>s. and C<Nil>
-is defined as the empty C<Parcel>.
+When it runs out of items, it will fail with the C<EMPTY> exception.
+As with most failures, it is generally returned without throwing it,
+unless the calling lexical scope requests it to be thrown via "use fatal".
+No list should ever contain the C<EMPTY> exception, since iterational
+control flow should always terminate when that value is returned.
+This method provides list context to the iterator.
+
+=head2 method getsome ($max?) {...}
+
+Returns a batch of items in some appropriate C<Positional> type that
+numerifies to the exact number of items returned. (The type may also
+be C<Iterable> in its turn.) Also returns C<EMPTY> if no arguments
+are available; the C<EMPTY> exception should return 0 when numerified
+to facilitate numeric end testing if that is desired.
+
+This method provides list context to the iterator.
+
+=head2 method getitem {...}
+
+Returns the next item for that iteration. The grouping of elements
+returned in each iteration is visible if this iterator is being used
+to build a slice. While building a list, the items will be flattened.
+
+When it runs out of items, it will fail with the C<EMPTY> exception.
+As with most failures, it is generally returned without throwing it,
+unless the calling lexical scope requests it to be thrown via "use fatal".
+No list should ever contain the C<EMPTY> exception, since iterational
+control flow should always terminate when that value is returned.
+
+This method provides item context to the iterator, which is also
+used as slice context in the variadic region.
+
+=head2 method getsomeitems ($max?) {...}
+
+Returns a batch of items in some appropriate C<Positional> type that
+numerifies to the exact number of items returned. (The type may also
+be C<Iterable> in its turn.) Also returns C<EMPTY> if no arguments
+are available; the C<EMPTY> exception should return 0 when numerified
+to facilitate numeric end testing if that is desired.
+
+This method provides item context to the iterator, which is also
+used as slice context in the variadic region.
+
=head1 The List::PushBack Role
This role defines an iterator that knows how to receive values back to
