Finish Scan documentation

2 files changed, 33 insertions, 8 deletions

diff --git a/doc/scan.md b/doc/scan.md
index ab4b6669..c4e3a3ad 100644
--- a/doc/scan.md
+++ b/doc/scan.md
@@ -50,7 +50,7 @@ BQN's Scan is ordered differently from Scan in APL. Both include one result for
 
 Scan also differs from Fold or Insert in that it never depends on `𝔽`'s identity element, because scanning over an empty array simply returns that array.
 
-## Examples
+## Lists
 
 The best-known use of Scan is the [prefix sum](https://en.wikipedia.org/wiki/Prefix_sum) of a list, in which each element of the result is the sum of that element and all the ones before it. With a [shift](shift.md) this can be modified to sum the previous elements only.
 
@@ -92,7 +92,7 @@ A more complicated boolean scan, which depends on the left-to-right ordering, is
 
         {¬<`'\'=𝕩}⊸/ "ab\\\rs\\\\"
 
-### Reverse scan
+## Reverse scan
 
 We've discussed how the scan moves forward along `𝕩`, so that each time `𝔽` takes an old result as `𝕨` and a new value as `𝕩`. This means that results correspond to prefixes and go left to right on each one. Since the most important scans have associative, commutative operands, the left-to-right ordering often doesn't make a difference. But sometimes a suffix rather than prefix scan is wanted. For these cases, Scan Under [Reverse](reverse.md) (`` `⌾⌽ ``) does the trick.
 
@@ -109,10 +109,22 @@ The new value is still the right argument to `𝔽`, even though with the revers
         {"("∾𝕨∾")𝔽"∾𝕩}˜`⌾⌽ "a"‿"b"‿"c"‿"d"
 
 
-### Higher ranks
+## Higher ranks
 
-Scan moves along the [leading axis](leading.md) of `𝕩`. Results are produced in index order.
+Scan moves along the [leading axis](leading.md) of `𝕩`: vertically, for a table. To apply a scan to later axes, use `˘` or `⎉`. Since a scan returns an array with the same shape as its argument, this can't cause an error from differing result cell shapes, unlike Fold or Insert.
 
         ⊢ a ← ¯2‿0.25‿'a'‿∞ ∾ 3‿4⥊¯1‿0‿1
 
         +` a
+
+If `𝕨` is given, it must have the same shape as a major cell of `𝕩` (this is why `𝕨` needs to be enclosed when `𝕩` is a list: in general it's an array). Then the first result cell is found by applying `𝔽` to elements of `𝕨` and `⊏𝕩`, and the computation continues as in the one-argument case for remaining cells.
+
+        3‿2‿1‿0 +` a
+
+Results are produced in index order. This means that instead of moving along each column in turn, a scan produces the first result cell one element at a time, then the next, and so on. Something like a breadth-first as opposed to depth-first ordering.
+
+## Definition
+
+Scan admits a simple recursive definition. `𝕩` is an array of rank one or more and `𝕨`, if given, is an atom or array with shape `1↓≢𝕩`. The result ``z←𝕨𝔽`𝕩`` is an array with the same shape as `𝕩`. If it has length at least one, `⊏z` is `⊏𝕩` if `𝕨` isn't given and `𝕨𝔽¨⊏𝕩` if it is. For `0≤i`, `(i+1)⊏z` is `(i⊏z)𝔽¨(i+1)⊏𝕩`.
+
+The ordering of `𝔽` application is the natural one for this definition: cells are computed in turn, and each instance of `𝔽¨` goes in index order.
diff --git a/docs/doc/scan.html b/docs/doc/scan.html
index 64deae85..1f572239 100644
--- a/docs/doc/scan.html
+++ b/docs/doc/scan.html
@@ -61,7 +61,7 @@
 <p>The 1-modifier Scan (<code><span class='Modifier'>`</span></code>) moves along the first axis of the array <code><span class='Value'>𝕩</span></code>, building up an array of results by applying <code><span class='Function'>𝔽</span></code> repeatedly beginning with <code><span class='Value'>𝕨</span></code> or <code><span class='Function'>⊏</span><span class='Value'>𝕩</span></code>. It's related to the fold modifiers, and most closely resembles the <a href="fold.html#apl2-reduction">APL2-style reduction</a> <code><span class='Modifier'>¨˝</span></code>, but it traverses the array in forward rather than reverse index order, and includes all intermediate results of <code><span class='Function'>𝔽</span></code> in its output instead of just the final one.</p>
 <p>BQN's Scan is ordered differently from Scan in APL. Both include one result for each non-empty prefix of <code><span class='Value'>𝕩</span></code>. In BQN this is a left-to-right fold, so that each new result requires one application of <code><span class='Function'>𝔽</span></code>. APL uses a right-to-left ordering, which matches with reduction, but requires starting over at the end for each new prefix, except in special cases. If needed, this definition can be obtained with a fold on each <a href="prefixes.html">prefix</a> except the first (which is empty). In the particular case of <code><span class='Function'>-</span><span class='Value'>⍀</span></code>, that nested solution isn't needed: negate odd-indexed elements and then apply <code><span class='Function'>+</span><span class='Modifier'>`</span></code>.</p>
 <p>Scan also differs from Fold or Insert in that it never depends on <code><span class='Function'>𝔽</span></code>'s identity element, because scanning over an empty array simply returns that array.</p>
-<h2 id="examples">Examples</h2>
+<h2 id="lists">Lists</h2>
 <p>The best-known use of Scan is the <a href="https://en.wikipedia.org/wiki/Prefix_sum">prefix sum</a> of a list, in which each element of the result is the sum of that element and all the ones before it. With a <a href="shift.html">shift</a> this can be modified to sum the previous elements only.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K2AgMuKAvzTigL8z4oC/MQoKK2DCuzLigL804oC/M+KAvzEgICMgRXhjbHVzaXZlIHByZWZpeCBzdW0=">↗️</a><pre>    <span class='Function'>+</span><span class='Modifier'>`</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>1</span>
 ⟨ 2 6 9 10 ⟩
@@ -108,7 +108,7 @@
     <span class='Brace'>{</span><span class='Function'>¬&lt;</span><span class='Modifier'>`</span><span class='String'>'\'</span><span class='Function'>=</span><span class='Value'>𝕩</span><span class='Brace'>}</span><span class='Modifier2'>⊸</span><span class='Function'>/</span> <span class='String'>&quot;ab\\\rs\\\\&quot;</span>
 "ab\rs\\"
 </pre>
-<h3 id="reverse-scan">Reverse scan</h3>
+<h2 id="reverse-scan">Reverse scan</h2>
 <p>We've discussed how the scan moves forward along <code><span class='Value'>𝕩</span></code>, so that each time <code><span class='Function'>𝔽</span></code> takes an old result as <code><span class='Value'>𝕨</span></code> and a new value as <code><span class='Value'>𝕩</span></code>. This means that results correspond to prefixes and go left to right on each one. Since the most important scans have associative, commutative operands, the left-to-right ordering often doesn't make a difference. But sometimes a suffix rather than prefix scan is wanted. For these cases, Scan Under <a href="reverse.html">Reverse</a> (<code><span class='Modifier'>`</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span></code>) does the trick.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oioYCAgIDDigL8w4oC/MeKAvzDigL8w4oC/MeKAvzAKCuKIqGDijL7ijL0gMOKAvzDigL8x4oC/MOKAvzDigL8x4oC/MA==">↗️</a><pre>    <span class='Function'>∨</span><span class='Modifier'>`</span>   <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span>
 ⟨ 0 0 1 1 1 1 1 ⟩
@@ -124,8 +124,8 @@
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=eyIoIuKIvvCdlajiiL4iKfCdlL0i4oi+8J2VqX3LnGDijL7ijL0gImEi4oC/ImIi4oC/ImMi4oC/ImQi">↗️</a><pre>    <span class='Brace'>{</span><span class='String'>&quot;(&quot;</span><span class='Function'>∾</span><span class='Value'>𝕨</span><span class='Function'>∾</span><span class='String'>&quot;)𝔽&quot;</span><span class='Function'>∾</span><span class='Value'>𝕩</span><span class='Brace'>}</span><span class='Modifier'>˜`</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span> <span class='String'>&quot;a&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;b&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;c&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;d&quot;</span>
 ⟨ "(a)𝔽(b)𝔽(c)𝔽d" "(b)𝔽(c)𝔽d" "(c)𝔽d" "d" ⟩
 </pre>
-<h3 id="higher-ranks">Higher ranks</h3>
-<p>Scan moves along the <a href="leading.html">leading axis</a> of <code><span class='Value'>𝕩</span></code>. Results are produced in index order.</p>
+<h2 id="higher-ranks">Higher ranks</h2>
+<p>Scan moves along the <a href="leading.html">leading axis</a> of <code><span class='Value'>𝕩</span></code>: vertically, for a table. To apply a scan to later axes, use <code><span class='Modifier'>˘</span></code> or <code><span class='Modifier2'>⎉</span></code>. Since a scan returns an array with the same shape as its argument, this can't cause an error from differing result cell shapes, unlike Fold or Insert.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQIMKvMuKAvzAuMjXigL8nYSfigL/iiJ4g4oi+IDPigL804qWKwq8x4oC/MOKAvzEKCitgIGE=">↗️</a><pre>    <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>¯2</span><span class='Ligature'>‿</span><span class='Number'>0.25</span><span class='Ligature'>‿</span><span class='String'>'a'</span><span class='Ligature'>‿</span><span class='Number'>∞</span> <span class='Function'>∾</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span>
 ┌─                
 ╵ ¯2 0.25 'a' ∞   
@@ -142,3 +142,16 @@
   ¯2 0.25 'a' ∞  
                 ┘
 </pre>
+<p>If <code><span class='Value'>𝕨</span></code> is given, it must have the same shape as a major cell of <code><span class='Value'>𝕩</span></code> (this is why <code><span class='Value'>𝕨</span></code> needs to be enclosed when <code><span class='Value'>𝕩</span></code> is a list: in general it's an array). Then the first result cell is found by applying <code><span class='Function'>𝔽</span></code> to elements of <code><span class='Value'>𝕨</span></code> and <code><span class='Function'>⊏</span><span class='Value'>𝕩</span></code>, and the computation continues as in the one-argument case for remaining cells.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=M+KAvzLigL8x4oC/MCArYCBh">↗️</a><pre>    <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span> <span class='Function'>+</span><span class='Modifier'>`</span> <span class='Value'>a</span>
+┌─              
+╵ 1 2.25 'b' ∞  
+  0 2.25 'c' ∞  
+  0 3.25 'b' ∞  
+  1 2.25 'b' ∞  
+               ┘
+</pre>
+<p>Results are produced in index order. This means that instead of moving along each column in turn, a scan produces the first result cell one element at a time, then the next, and so on. Something like a breadth-first as opposed to depth-first ordering.</p>
+<h2 id="definition">Definition</h2>
+<p>Scan admits a simple recursive definition. <code><span class='Value'>𝕩</span></code> is an array of rank one or more and <code><span class='Value'>𝕨</span></code>, if given, is an atom or array with shape <code><span class='Number'>1</span><span class='Function'>↓≢</span><span class='Value'>𝕩</span></code>. The result <code><span class='Value'>z</span><span class='Gets'>←</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Modifier'>`</span><span class='Value'>𝕩</span></code> is an array with the same shape as <code><span class='Value'>𝕩</span></code>. If it has length at least one, <code><span class='Function'>⊏</span><span class='Value'>z</span></code> is <code><span class='Function'>⊏</span><span class='Value'>𝕩</span></code> if <code><span class='Value'>𝕨</span></code> isn't given and <code><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Modifier'>¨</span><span class='Function'>⊏</span><span class='Value'>𝕩</span></code> if it is. For <code><span class='Number'>0</span><span class='Function'>≤</span><span class='Value'>i</span></code>, <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>+</span><span class='Number'>1</span><span class='Paren'>)</span><span class='Function'>⊏</span><span class='Value'>z</span></code> is <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>⊏</span><span class='Value'>z</span><span class='Paren'>)</span><span class='Function'>𝔽</span><span class='Modifier'>¨</span><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>+</span><span class='Number'>1</span><span class='Paren'>)</span><span class='Function'>⊏</span><span class='Value'>𝕩</span></code>.</p>
+<p>The ordering of <code><span class='Function'>𝔽</span></code> application is the natural one for this definition: cells are computed in turn, and each instance of <code><span class='Function'>𝔽</span><span class='Modifier'>¨</span></code> goes in index order.</p>