Initial Seq documentation

Author: moritz

lib/Type/Seq.pod

@@ -0,0 +1,41 @@
+=begin pod
+
+=TITLE class Seq
+
+=SUBTITLE An iterable, lazy sequence of values
+
+    class Seq is Cool does Iterable does PositionalBindFailover { }
+
+A C<Seq> represents anything that can lazily produce a sequence of values. A
+C<Seq> is born in a state where iterating it will consume the values. However,
+calling .list on a Seq will return a List that is still lazy, but stores the
+generated values for later access. The same is true when assigning a Seq to an
+array.
+
+A typical use case is L<method C<lines> in C<IO::Handles>|/type/IO::Handles#method lines>,
+which could use quite much memory if it stored all the lines read from the
+file. So
+
+    for open('README').lines -> $line {
+        say $line;
+    }
+
+won't keep all lines from the file in memory.
+
+This implies that you cannot iterate the same C<Seq> object twice (otherwise
+it couldn't throw away old values), so this dies:
+
+=begin code :allow<L>
+my \lines := open('README').lines;
+for lines { .say };
+for lines { .say }; # dies with "This Seq has already been iterated [...]"
+                    # of type L<X::Seq::Consumed>
+=end code
+
+A high-level construct to generate a C<Seq> is C<gather/take>, as well as many
+built-in methods like C<map> and C<grep>, low-level constructors to create a
+Seq from an iterator or from looping constrcuts are available too.
+
+=head1 Methods
+
+=end pod