on master help sign in
Merge pull request #1099 from urbit/roll-reel-revise

roll/reel revision and clarification

commitd3d3aa691c2a9aef03d57cb198bf49d7c1267fa0 authorpoprox <51337059+drbeefsupreme@users.noreply.github.com> dateWed 16 Jun 2021, 11:32 (5 years ago) parent416937de7adaa3
1 file changed+60−9
hoon/reference/stdlib/2b.md+60−9
hoon/reference/stdlib/2b.md+60−9
@@ -564,6 +564,11 @@ the final value of the accumulator.
564564(To "slam" means to call a gate and give it a sample/samples. In this instance,
565565`a` is the list of samples that are given to the gate b.)
566566
567+The initial value of the accumulator is the bunt of `b`'s second argument (`+<+`). This can occasionally produce
568+undesired behavior (see examples). If you need more control over the initial
569+value, try making use of `$_` and `|:`, or perhaps [`+spin`](#spin) or
570+[`+spun`](#spun).
571+
567572#### Accepts
568573
569574`a` is a list.
@@ -600,6 +605,27 @@ The accumulator, which is a noun.
600605 ! exit
601606```
602607
608+`+mul`'s default sample is 1, so calling `+reel` with `+mul` yields the expected behavior:
609+```
610+> *mul
611+1
612+
613+> (reel `(list @)`~[1 2 3 4] mul)
614+24
615+```
616+However, if you build a gate that uses `+mul` like so, the sample defaults to 0
617+since that is the bunt of `@`:
618+```
619+> (reel `(list @)`~[1 2 3 4] |=([a=@ b=@] (mul a b)))
620+0
621+```
622+We can fix this with `|:`:
623+```
624+> (reel `(list @)`~[1 2 3 4] |:([a=1 b=1] (mul a b)))
625+24
626+```
627+
628+
603629
604630---
605631### `++roll`
@@ -613,6 +639,11 @@ producing the final value of the accumulator.
613639(To "slam" means to call a gate and give it a sample/samples. In this instance,
614640`a` is the list of samples that are given to the gate b.)
615641
642+The initial value of the accumulator is `b`'s second argument (`+<+`). This can
643+occasionally produce undesired behavior (see examples). If you need more control
644+over the initial value, try making use of `$_` and `|:`, or perhaps
645+[`+spin`](#spin) or [`+spun`](#spun).
646+
616647#### Accepts
617648
618649`a` is a list.
@@ -638,15 +669,35 @@ The accumulator, which is a noun.
638669#### Examples
639670
640671```
641− > (roll `(list @)`[1 2 3 4 5 ~] add)
642− q=15
672+> (roll `(list @)`[1 2 3 4 5 ~] add)
673+q=15
643674
644− > (roll `(list @)`[6 3 1 ~] sub)
645− ! subtract-underflow
646− ! exit
675+> (roll `(list @)`[6 3 1 ~] sub)
676+! subtract-underflow
677+! exit
678+
679+> (roll `(list @)`[1 3 6 ~] sub)
680+q=4
681+```
682+
683+`+mul`'s default sample is 1, so calling `+roll` with `+mul` yields the expected behavior:
684+```
685+> *mul
686+1
647687
648− > (roll `(list @)`[1 3 6 ~] sub)
649− q=4
688+> (roll `(list @)`~[1 2 3 4] mul)
689+24
690+```
691+However, if you build a gate that uses `+mul` like so, the sample defaults to 0
692+since that is the bunt of `@`:
693+```
694+> (roll `(list @)`~[1 2 3 4] |=([a=@ b=@] (mul a b)))
695+0
696+```
697+We can fix this with `|:`:
698+```
699+> (roll `(list @)`~[1 2 3 4] |:([a=1 b=1] (mul a b)))
700+24
650701```
651702
652703
@@ -1042,7 +1093,7 @@ A list
10421093
10431094
10441095---
1045−### `++spin`
1096+### `++spin` {#spin}
10461097
10471098Gate to list, with state
10481099
@@ -1107,7 +1158,7 @@ is the continuation of the RNG.
11071158
11081159
11091160---
1110−### `++spun`
1161+### `++spun` {#spun}
11111162
11121163Gate to list, with state
11131164