Adds push-exactly refs #1395

Author: JJ

doc/Type/IO/Path.pod6

@@ -1010,9 +1010,8 @@ Delete all specified ordinary files, links, or symbolic links for which there
 are privileges to do so. See L<rmdir> to delete directories.
 
 The subroutine form returns the names of the files that were successfully
-deleted. The method form returns C<True> on success, or
-L<fails|/routine/fail> with L<X::IO::Unlink> if the operation could not be
-completed.
+deleted. The method form returns C<True> on success, or L<fails|/routine/fail>
+with L<X::IO::Unlink> if the operation could not be completed.
 
 =head2 method IO
 
@@ -1028,8 +1027,8 @@ Defined as:
 
     method SPEC(IO::Path:D: --> IO::Spec)
 
-Returns the L<IO::Spec|/type/IO::Spec> object that was (implicitly) specified at object
-creation time.
+Returns the L<IO::Spec|/type/IO::Spec> object that was (implicitly) specified at
+object creation time.
 
     my $io = IO::Path.new("/bin/bash");
     say $io.SPEC;                            # OUTPUT: «(Unix)␤»
@@ -1074,12 +1073,12 @@ say "path/to/file".IO.changed.DateTime;  # 2015-02-16T12:18:50Z
 =head2 method mode
 
 Return an L<IntStr> object representing the POSIX permissions of a file.  The
-Str part of the result is the octal representation of the file permission, like
-the form accepted by the chmod(1) utility.
+C<Str> part of the result is the octal representation of the file permission,
+like the form accepted by the C<chmod(1)> utility.
 
 =for code
-say ~"path/to/file".IO.mode;        # e.g. '0644'
-say +"path/to/file".IO.mode;        # e.g. 420, where sprintf('%04o', 420) eq '0644'
+say ~"path/to/file".IO.mode;  # e.g. '0644'
+say +"path/to/file".IO.mode;  # e.g. 420, where sprintf('%04o', 420) eq '0644'
 
 The result of this can be used in the other methods that take a mode as an
 argument.

doc/Type/Iterator.pod6

@@ -123,11 +123,11 @@ a simplistic subroutine re-implementation of the C<for> loop.
 
 It would be more idiomatic to use C<while> or C<until>, and a sigilless variable.
 
-    =begin code :preamble<my $iterator = ().iterator; my &do = &say>
-    until IterationEnd =:= (my \pulled = $iterator.pull-one) {
-        do( pulled );
-    }
-    =end code
+=begin code :preamble<my $iterator = ().iterator; my &do = &say>
+until IterationEnd =:= (my \pulled = $iterator.pull-one) {
+    do( pulled );
+}
+=end code
 
 =head2 method push-exactly
 
@@ -146,7 +146,41 @@ C<$count>.
     say (1 .. ∞).iterator.push-exactly(@array, 3); # OUTPUT: «3␤»
     say @array; # OUTPUT: «[1 2 3]␤»
 
-The Iterator role implements this method in terms of C<pull-one>.
+The Iterator role implements this method in terms of C<pull-one>. In general,
+this is a method that is not intended to be called directly from the end user
+who, instead, should implement it in classes that mix the iterator role. For
+instance, this class implements that role:
+
+=begin code
+class DNA does Iterable does Iterator {
+    has $.chain;
+    has Int $!index = 0;
+
+    method new ($chain where {
+                       $chain ~~ /^^ <[ACGT]>+ $$ / and
+                       $chain.chars %% 3 } ) {
+        self.bless( :$chain );
+    }
+
+    method push-exactly(Iterator:D: $target, int $count --> Mu) {
+        return IterationEnd if $.chain.elems / 3 < $count;
+        for ^($count) {
+            $target.push: $.chain.comb.rotor(3)[ $_ ];
+        }
+    }
+
+};
+
+my $b := DNA.new("AAGCCT");
+for $b -> $a, $b, $c { say "Never mind" }; # Does not enter the loop
+my $þor := DNA.new("CAGCGGAAGCCT");
+for $þor -> $first, $second {
+    say "Coupled codons: $first, $second";
+    # OUTPUT: «Coupled codons: C A G, C G G␤Coupled codons: A A G, C C T␤»
+}
+=end code
+
+This code, which groups DNA chains in triplets (usually called I<codons>) returns those codons when requested in a loop; if too many are requested, like in the first case C«for $b -> $a, $b, $c», it simply does not enter the loop since C<push-exactly> will return C<IterationEnd> since it is not able to serve the request for exactly 3 codons. In the second case, however, it requests exactly two codons in each iteration of the loop; C<push-exactly> is being called with the number of loop variables as the C<$count> variable.
 
 =head2 method push-at-least