Document .toggle method

zoffixznet · zoffixznet · commit 80c0da677505 · 2018-01-13T17:26:25.000-05:00
This is how it fits into my brain. Feel free to reword/rewrite if the description is confusing. Closes #1716 Rakudo impl: rakudo/rakudo@78caeb6bceb5ab99 Spec: Raku/roast@0bca7906b7
diff --git a/doc/Type/Any.pod6 b/doc/Type/Any.pod6
@@ -729,6 +729,95 @@ Returns an empty List.
 
     say Any.kv; # OUTPUT: «()␤»
 
+=head2 method toggle
+
+Defined as:
+
+    method toggle(Any:D: *@conditions where .all ~~ Callable:D, Bool :$off  --> Seq:D)
+
+L<Iterates|/routine/iterator> over the invocant, producing a L<Seq>, toggling
+whether the received values are propagated to the result on and off, depending
+on the results of calling L<Callables|/type/Callable> in C<@conditions>:
+
+    say ^10 .toggle: * < 4, * %% 2, &is-prime; # OUTPUT: «(0 1 2 3 6 7)␤»
+    say ^10 .toggle: :off, * > 4;              # OUTPUT: «(5 6 7 8 9)␤»
+
+Imagine a switch that's either on or off (C<True> or C<False>), and values are
+produced if it's on. By default, the initial state of that switch is in "on"
+position, unless C<:$off> is set to a true value, in which case the initial
+state will be "off".
+
+A L<Callable> from the L<head> of C<@conditions> is taken (if any are available)
+and it becomes the current tester. Each value from the original sequence is
+tested by calling the tester L<Callable> with that value. The state of our
+imaginary switch is set to the return value from the tester: if it's thruthy,
+set switch to "on",  otherwise set it to "off".
+
+Whenever the switch is I<toggled> (i.e. switched  from "off" to "on" or
+from "on" to "off"), the current tester L<Callable> is replaced by the next
+L<Callable> in C<@conditions>, if available, which will be used to test any
+further values. If no more tester Callables are available, the switch will
+remain in its current state until the end of iteration.
+
+    =begin code
+    # our original sequence of elements:
+    say list ^10; # OUTPUT: «(0 1 2 3 4 5 6 7 8 9)␤»
+    # toggled result:
+    say ^10 .toggle: * < 4, * %% 2, &is-prime; # OUTPUT: «(0 1 2 3 6 7)␤»
+
+    # First tester Callable is `* < 4` and initial state of switch is "on".
+    # As we iterate over our original sequence:
+    # 0 => 0 < 4 === True  switch is on, value gets into result, switch is
+    #                      untoggled, so we keep using the same Callable:
+    # 1 => 1 < 4 === True  same
+    # 2 => 2 < 4 === True  same
+    # 3 => 3 < 4 === True  same
+    # 4 => 4 < 4 === False switch is now off, "4" does not make it into the
+    #                      result. In addition, our switch got toggled, so
+    #                      we're switching to the next tester Callable
+    # 5 => 5 %% 2 === False  switch is still off, keep trying to find a value
+    # 6 => 6 %% 2 === True   switch is now on, take "6" into result. The switch
+    #                        toggled, so we'll use the next tester Callable
+    # 7 => is-prime(7) === True  switch is still on, take value and keep going
+    # 8 => is-prime(8) === False switch is now off, "8" does not make it into
+    #                            the result. The switch got toggled, but we
+    #                            don't have any more tester Callables, so it
+    #                            will remain off for the rest of the sequence.
+    =end code
+
+Since the toggle of the switch's state loads the next tester L<Callable>,
+setting C<:$off> to a C<True> value affects when first tester is discarded:
+
+    =begin code
+    # our original sequence of elements:
+    say <0 1 2>; # OUTPUT: «(0 1 2)␤»
+    # toggled result:
+    say <0 1 2>.toggle: * > 1; # OUTPUT: «()␤»
+
+    # First tester Callable is `* > 1` and initial state of switch is "on".
+    # As we iterate over our original sequence:
+    # 0 => 0 > 1 === False  switch is off, "0" does not make it into result.
+    #                      In addition, switch got toggled, so we change the
+    #                      tester Callable, and since we don't have any more
+    #                      of them, the switch will remain "off" until the end
+    =end code
+
+    =begin code
+    # our original sequence of elements:
+    say <0 1 2>; # OUTPUT: «(0 1 2)␤»
+    # toggled result:
+    say <0 1 2>.toggle: :off, * > 1; # OUTPUT: «(2)␤»
+
+    # First tester Callable is `* > 1` and initial state of switch is "off".
+    # As we iterate over our original sequence:
+    # 0 => 0 > 1 === False  switch is off, "0" does not make it into result.
+    #                       The switch did NOT get toggled this time, so we
+    #                       keep using our current tester Callable
+    # 1 => 1 > 1 === False  same
+    # 2 => 2 > 1 === True   switch is on, "2" makes it into the result
+    =end code
+
+
 =head2 method tree
 
 Defined As:
