Permalink
Browse files

Document .toggle method

This is how it fits into my brain. Feel free to reword/rewrite if the
description is confusing.

Closes #1716
Rakudo impl: rakudo/rakudo@78caeb6
Spec:        perl6/roast@0bca790
  • Loading branch information...
zoffixznet committed Jan 13, 2018
1 parent ec139cb commit 80c0da677505923a5f6c0a2a9cfb92bd7b93a249
Showing with 89 additions and 0 deletions.
  1. +89 −0 doc/Type/Any.pod6
View
@@ -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:

0 comments on commit 80c0da6

Please sign in to comment.