Document IterationBuffer

Author: lizmat

doc/Type/IterationBuffer.rakudoc

@@ -0,0 +1,115 @@
+=begin pod :kind("Type") :subkind("class") :category("composite")
+
+=TITLE class IterationBuffer
+
+=SUBTITLE Lowlevel storage of positional values
+
+=for code
+my class IterationBuffer { }
+
+An C<IterationBuffer> is used when the implementation of an C<Iterator>
+class needs a lightweight way to store/transmit values.  It doesn't make
+C<Scalar> containers, and only supports mutation through the C<BIND-POS>
+method, only supports adding values with the C<push> and C<unshift>
+methods, supports merging of two C<IterationBuffer> objects with the
+C<append> and C<prepend> methods, and supports resetting with the
+C<clear> method.
+
+It can be coerced into a C<List>, C<Slip>, C<List> or C<Seq>.
+
+Values will be stored "as is", which means that L<Junctions|/type/Junction>
+will be stored as such and will B<not> L<autothread|/language/glossary#Autothreading>.
+
+The C<new> method accepts an L<Iterable|/type/Iterable> as an optional
+argument which, when specified, will be used to fill the C<IterationBuffer>.
+
+=head1 Methods
+
+=head2 method push
+
+    method push(IterationBuffer:D: Mu \value)
+
+Adds the given value at the end of the C<IterationBuffer>.
+
+=head2 method unshift
+
+    method unshift(IterationBuffer:D: Mu \value)
+
+Adds the given value at the beginning of the C<IterationBuffer>.
+
+=head2 method append
+
+    method append(IterationBuffer:D: IterationBuffer:D $other)
+
+Adds the contents of the other C<IterationBuffer> at the end of
+the C<IterationBuffer>.
+
+=head2 method prepend
+
+    method prepend(IterationBuffer:D: IterationBuffer:D $other)
+
+Adds the contents of the other C<IterationBuffer> at the beginning
+of the C<IterationBuffer>.
+
+=head2 method clear
+
+    method clear(IterationBuffer:D:)
+
+Resets the number of elements in the C<IterationBuffer> to zero,
+effectively removing all data from it.
+
+=head2 method elems
+
+    method elems(IterationBuffer:D:)
+
+Returns the number of elements in the C<IterationBuffer>.
+
+=head2 method AT-POS
+
+    multi method AT-POS(IterationBuffer:D: int   $pos)
+    multi method AT-POS(IterationBuffer:D: Int:D $pos)
+
+Returns the value at the given element position, or C<Mu> if
+the element position is beyond the length of the C<IterationBuffer>,
+or an error will be thrown indicating the index is out of bounds
+(for negative position values).
+
+=head2 method BIND-POS
+
+    multi method BIND-POS(IterationBuffer:D: int   $pos, Mu \value)
+    multi method BIND-POS(IterationBuffer:D: Int:D $pos, Mu \value)
+
+Binds the given value at the given element position and returns it.
+The C<IterationBuffer> is automatically lengthened if the given
+element position is beyond the length of the C<IterationBuffer>.
+An error indicating the index is out of bounds will be thrown for
+negative position values.
+
+=head2 method Slip
+
+    method Slip(IterationBuffer:D:)
+
+Coerces the C<IterationBuffer> to a L<Slip|/type/Slip>.
+
+=head2 method List
+
+    method List(IterationBuffer:D:)
+
+Coerces the C<IterationBuffer> to a L<List|/type/List>.
+
+=head2 method Seq
+
+    method Seq(IterationBuffer:D:)
+
+Coerces the C<IterationBuffer> to a L<Seq|/type/Seq>.
+
+=head2 method raku
+
+    method raku(IterationBuffer:D:)
+
+Produces a representation of the C<IterationBuffer> as a C<List>
+postfixed with ".IterationBuffer" to make it different from an
+ordinary list.  Does B<not> roundtrip.  Intended for debugging
+uses only, specifically for use with L<dd|/programs/01-debugging#Dumper_function_(dd)>.
+
+=end pod