1 files changed, 19 insertions, 7 deletions
diff --git a/docs/doc/fill.html b/docs/doc/fill.html
index 3c1a0c27..dc6134b3 100644
--- a/docs/doc/fill.html
+++ b/docs/doc/fill.html
@@ -6,17 +6,17 @@
 <div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">doc</a></div>
 <h1 id="fill-elements"><a class="header" href="#fill-elements">Fill elements</a></h1>
 <p>A few array operations need an array element to use when no existing element applies. BQN tries to maintain a &quot;default&quot; element for every array, known as a fill element, for this purpose. If it's known, the fill element is a nested array structure where each atom is either <code><span class='Number'>0</span></code> or <code><span class='String'>' '</span></code>. If no fill is known, a function that requests it results in an error.</p>
-<p>Fills are used by <a href="take.html">Take</a> (<code><span class='Function'>↑</span></code>) when a value in <code><span class='Value'>𝕨</span></code> is larger than the corresponding length in <code><span class='Value'>𝕩</span></code>, by the two <a href="shift.html">Nudge</a> functions (<code><span class='Function'>»«</span></code>) when <code><span class='Value'>𝕩</span></code> is non-empty, by <a href="couple.html">Merge</a> (<code><span class='Function'>&gt;</span></code>) when <code><span class='Value'>𝕩</span></code> is empty, and by <a href="reshape.html">Reshape</a> (<code><span class='Function'>⥊</span></code>) when <code><span class='Value'>𝕨</span></code> contains <code><span class='Function'>↑</span></code>. Except for these specific cases, the fill value an array has can't affect the program. The result of <a href="match.html">Match</a> (<code><span class='Function'>≡</span></code>) doesn't depend on fills, and any attempt to compute a fill can't cause side effects.</p>
+<p>Fills are used by <a href="take.html">Take</a> (<code><span class='Function'>↑</span></code>) when a value in <code><span class='Value'>𝕨</span></code> is larger than the corresponding length in <code><span class='Value'>𝕩</span></code> and <a href="reshape.html">Reshape</a> (<code><span class='Function'>⥊</span></code>) when <code><span class='Value'>𝕨</span></code> contains <code><span class='Function'>↑</span></code>, by the two <a href="shift.html">Nudge</a> functions (<code><span class='Function'>»«</span></code>) when <code><span class='Value'>𝕩</span></code> is non-empty, by <a href="couple.html">Merge</a> (<code><span class='Function'>&gt;</span></code>) and <a href="join.html">Join</a> when <code><span class='Value'>𝕩</span></code> is empty, and by <a href="rank.html">Cells and Rank</a> when the result has an empty frame. These are the only ways that an array's fill value can affect the program. The result of <a href="match.html">Match</a> (<code><span class='Function'>≡</span></code>) doesn't depend on fills, and any attempt to compute a fill can't cause side effects.</p>
 <h2 id="using-fills"><a class="header" href="#using-fills">Using fills</a></h2>
-<p>For the examples in this section we'll use the fact that an all-number array usually has <code><span class='Number'>0</span></code> as a fill while a string has <code><span class='String'>' '</span></code> (BQN maintains fills alongside array values rather than deriving them from arrays, so it's possible to construct arrays where this isn't true, but this probably wouldn't happen in ordinary code).</p>
-<p><a href="take.html">Take</a> (<code><span class='Function'>↑</span></code>) and <a href="shift.html">Nudge</a> (<code><span class='Function'>»«</span></code>) in either direction use the fill for padding, to extend the array past its boundary. For example, <code><span class='Value'>𝕨</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code> will add elements to one side when a number in <code><span class='Function'>|</span><span class='Value'>𝕨</span></code> is larger than the corresponding length in <code><span class='Function'>≢</span><span class='Value'>𝕩</span></code>.</p>
+<p>For the examples in this section we'll use the fact that an all-number array usually has <code><span class='Number'>0</span></code> as a fill while a string has <code><span class='String'>' '</span></code> (it's not too rare to end up with such an array that has no fill, and possible but very unusual for an array to have a fill that conflicts with those rules).</p>
+<p><a href="take.html">Take</a> (<code><span class='Function'>↑</span></code>) and <a href="shift.html">Nudge</a> (<code><span class='Function'>»«</span></code>) in either direction use the fill for padding, to extend the array past its boundary. For example, <code><span class='Value'>𝕨</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code> adds elements to one side if a number in <code><span class='Function'>|</span><span class='Value'>𝕨</span></code> is larger than the corresponding length in <code><span class='Function'>≢</span><span class='Value'>𝕩</span></code>.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=wq83IOKGkSA04qWKMyAgICAgIyBGaWxsIHdpdGggMAoKwq83IOKGkSAicXJzdCIgICMgRmlsbCB3aXRoIHNwYWNl">↗️</a><pre>    <span class='Number'>¯7</span> <span class='Function'>↑</span> <span class='Number'>4</span><span class='Function'>⥊</span><span class='Number'>3</span>     <span class='Comment'># Fill with 0
 </span>⟨ 0 0 0 3 3 3 3 ⟩
 
     <span class='Number'>¯7</span> <span class='Function'>↑</span> <span class='String'>&quot;qrst&quot;</span>  <span class='Comment'># Fill with space
 </span>"   qrst"
 </pre>
-<p>Nudge Left or Right shifts the array over and places a fill in the vacated space, effectively extending it backwards by one. If <code><span class='Value'>𝕩</span></code> is empty then it shouldn't give an error, but it's safer not to rely on this.</p>
+<p>Nudge Left or Right shifts the array over and places a fill in the vacated space. If <code><span class='Value'>𝕩</span></code> is empty then it doesn't need the fill and can't error.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=wrvCqCDin6g04qWKMywicXJzdCLin6kKCjPihpHin6jin6kgICMgRmlsbCB1bmtub3duCgrCu+KfqOKfqSAgICMgRmlsbCBub3QgbmVlZGVk">↗️</a><pre>    <span class='Function'>»</span><span class='Modifier'>¨</span> <span class='Bracket'>⟨</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='Number'>3</span><span class='Separator'>,</span><span class='String'>&quot;qrst&quot;</span><span class='Bracket'>⟩</span>
 ⟨ ⟨ 0 3 3 3 ⟩ " qrs" ⟩
 
@@ -26,7 +26,6 @@
     <span class='Function'>»</span><span class='Bracket'>⟨⟩</span>   <span class='Comment'># Fill not needed
 </span>⟨⟩
 </pre>
-<p>If the argument to <a href="couple.html">Merge</a> is empty then its result will be as well, since the shape <code><span class='Function'>≢</span><span class='Value'>𝕩</span></code> is a prefix of <code><span class='Function'>≢&gt;</span><span class='Value'>𝕩</span></code>. However, the remainder of the result shape is determined by the elements of <code><span class='Value'>𝕩</span></code>, so if there are none then Merge uses the fill element to decide what the result shape should be.</p>
 <p><a href="reshape.html#computed-lengths">Reshape</a> (<code><span class='Function'>⥊</span></code>) uses the fill when <code><span class='Value'>𝕨</span></code> contains <code><span class='Function'>↑</span></code> and the product of the rest of <code><span class='Value'>𝕨</span></code> doesn't evenly divide the number of elements in <code><span class='Value'>𝕩</span></code>.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaR4oC/OCDipYogImNvbXBsZXRlcGFydCI=">↗️</a><pre>    <span class='Function'>↑</span><span class='Ligature'>‿</span><span class='Number'>8</span> <span class='Function'>⥊</span> <span class='String'>&quot;completepart&quot;</span>
 ┌─          
@@ -38,15 +37,28 @@
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRwrsx4oaR4qWKInN0cmluZyI=">↗️</a><pre>    <span class='Function'>⊑»</span><span class='Number'>1</span><span class='Function'>↑⥊</span><span class='String'>&quot;string&quot;</span>
 ' '
 </pre>
+<h2 id="edge-cases"><a class="header" href="#edge-cases">Edge cases</a></h2>
+<p>The above functions use the fill as part of their core definition. A few other functions use fills only when they encounter empty arrays. The goal of this behavior is to make programs working on empty arrays more similar to the non-empty case, so if all goes well you don't need to be thinking about these cases.</p>
+<p>If the argument to <a href="couple.html">Merge</a> is empty then its result will be as well, since the shape <code><span class='Function'>≢</span><span class='Value'>𝕩</span></code> is a prefix of <code><span class='Function'>≢&gt;</span><span class='Value'>𝕩</span></code>. However, the remainder of the result shape is determined by the elements of <code><span class='Value'>𝕩</span></code>, so if there are none then Merge uses the fill element to decide what the result shape should be. <a href="join.html">Join</a> is similar, although it multiplies the shape of <code><span class='Value'>𝕩</span></code> by the leading shape of the fill instead of concatenating them.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omiID4gMuKAvzDipYo8M+KAvzTigL8x4qWKMAoK4omiIOKIviAy4oC/MOKlijwz4oC/NOKAvzHipYow">↗️</a><pre>    <span class='Function'>≢</span> <span class='Function'>&gt;</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Function'>⥊&lt;</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Function'>⥊</span><span class='Number'>0</span>
+⟨ 2 0 3 4 1 ⟩
+
+    <span class='Function'>≢</span> <span class='Function'>∾</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Function'>⥊&lt;</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Function'>⥊</span><span class='Number'>0</span>
+⟨ 6 0 1 ⟩
+</pre>
+<p><a href="rank.html">Cells and Rank</a> rely on fills in a slightly more complicated way. If one of the argument frames is empty, that means the result will be empty, but the shape of a result cell still needs to be known to determine its shape (and similarly for the fill, but that's optional). BQN implementations may try to find it by running <code><span class='Function'>𝔽</span></code> using a cell of fills for the argument. As in Each (<code><span class='Modifier'>¨</span></code>) described below, this evaluation is not allowed to produce side effects. If it doesn't work, the result cell shape is assumed to be <code><span class='Bracket'>⟨⟩</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omiIOKMvcuYIOKGlTDigL804oC/MyAgIyBTaGFwZSBpcyBkZXRlcm1pbmVkIGJ5IGZpbGxz">↗️</a><pre>    <span class='Function'>≢</span> <span class='Function'>⌽</span><span class='Modifier'>˘</span> <span class='Function'>↕</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span>  <span class='Comment'># Shape is determined by fills
+</span>⟨ 0 4 3 ⟩
+</pre>
 <h2 id="how-fills-are-computed"><a class="header" href="#how-fills-are-computed">How fills are computed</a></h2>
 <p>For the exact requirements placed on fill, see <a href="../spec/inferred.html#fill-elements">the specification</a> (particularly &quot;required functions&quot;). This section loosely describes behavior in existing BQN implementations, and includes some parts that aren't required in the specification.</p>
 <p>A fill element should encompass something that's necessarily true for all elements of an array. If the way an array is computed implies it's all numbers, the fill should be <code><span class='Number'>0</span></code>. If every element is a list of two numbers, then the fill should be <code><span class='Bracket'>⟨</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Bracket'>⟩</span></code>. If every element is a list but the lengths might vary, <code><span class='Bracket'>⟨⟩</span></code> is probably a reasonable fill element.</p>
-<p>For <a href="arithmetic.html">arithmetic</a> primitives, the fill is found by the rules of pervasion, applying the function to both argument fills. Generally this means it consists of <code><span class='Number'>0</span></code>, but character arithmetic also allows space fills.</p>
+<p>For <a href="arithmetic.html">arithmetic</a> primitives, the fill is found by the rules of pervasion, applying the function to both argument fills. Generally this means it consists of <code><span class='Number'>0</span></code>, but <a href="arithmetic.html#character-arithmetic">character arithmetic</a> can produce space for a fill value.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=wrsgImFiYyIgKyA04oC/M+KAvzI=">↗️</a><pre>    <span class='Function'>»</span> <span class='String'>&quot;abc&quot;</span> <span class='Function'>+</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span>
 " ee"
 </pre>
 <p><a href="map.html">Mapping</a> modifiers Each and Table (<code><span class='Modifier'>¨⌜</span></code>) might try to follow a similar strategy, applying <code><span class='Function'>𝔽</span></code> to argument fills to obtain the result fill. The absolute rule here is that this computation can't cause side effects or an error, so for a complicated <code><span class='Function'>𝔽</span></code> such as a block function this procedure is likely to be aborted to avoid disrupting the rest of the program.</p>
-<p>Most other primitives fit in one of three broad categories as shown in the table below. Structural primitives, indicated by <code><span class='Function'>⊢</span></code>, don't change the fill of <code><span class='Value'>𝕩</span></code>. Combining structural primitives, indicated by <code><span class='Value'>∩</span></code>, only depend on the fill of all combined arrays—elements of <code><span class='Value'>𝕩</span></code> in the one-argument case, or <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code> in the two-argument case. Finally, many functions such as <a href="search.html">search functions</a> return only numbers and have a fill of <code><span class='Number'>0</span></code>.</p>
+<p>Most other primitives fit in one of three broad categories as shown in the table below. Structural primitives, indicated by <code><span class='Function'>⊢</span></code>, don't change the fill of <code><span class='Value'>𝕩</span></code>. Combining structural primitives, indicated by <code><span class='Value'>∩</span></code>, only depend on the fill of all combined arrays—elements of <code><span class='Value'>𝕩</span></code> in the one-argument case, or <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code> in the two-argument case. If these fills are the same value, then that's the fill; otherwise, the result has no fill. Finally, many functions such as <a href="search.html">search functions</a> return only arrays of numbers and have a fill of <code><span class='Number'>0</span></code>.</p>
 <table>
 <thead>
 <tr>