diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-07-24 22:47:46 -0400 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2021-07-24 22:47:46 -0400 |
| commit | a17782ce2ec31709ce30edb3d96fe2f3a9a6ed1f (patch) | |
| tree | b601681b2282f1a51042f8faf5bfe0e0242c0c31 /docs/doc/fill.html | |
| parent | 436bf368830c828f8008bf55632e2bb4c2a2578f (diff) | |
Documentation on fill elements
Diffstat (limited to 'docs/doc/fill.html')
| -rw-r--r-- | docs/doc/fill.html | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/doc/fill.html b/docs/doc/fill.html new file mode 100644 index 00000000..5ef9baf1 --- /dev/null +++ b/docs/doc/fill.html @@ -0,0 +1,89 @@ +<head> + <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/> + <link href="../style.css" rel="stylesheet"/> + <title>BQN: Fill elements</title> +</head> +<div class="nav"><a href="https://github.com/mlochbaum/BQN">BQN</a> / <a href="../index.html">main</a> / <a href="index.html">doc</a></div> +<h1 id="fill-elements">Fill elements</h1> +<p>A few array operations need an array element to use when no existing element applies. BQN tries to maintain a "default" 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, and by <a href="pick.html">First</a> (<code><span class='Function'>β</span></code>) and <a href="reshape.html">Reshape</a> (<code><span class='Function'>β₯</span></code>) when <code><span class='Value'>π©</span></code> is empty. 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> +<h2 id="using-fills">Using fills</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> +<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'>"qrst"</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> +<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'>"qrst"</span><span class='Bracket'>β©</span> +β¨ β¨ 0 3 3 3 β© " qrs" β© + + <span class='Number'>3</span><span class='Function'>β</span><span class='Bracket'>β¨β©</span> <span class='Comment'># Fill unknown +</span>ERROR + + <span class='Function'>Β»</span><span class='Bracket'>β¨β©</span> <span class='Comment'># Fill not needed +</span>β¨β© +</pre> +<p><a href="pick.html">First</a> (<code><span class='Function'>β</span></code>) and <a href="reshape.html">Reshape</a> (<code><span class='Function'>β₯</span></code>) use the fill when <code><span class='Value'>π©</span></code> is empty, and in the case of Reshape only when the result needs to be non-empty.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRICIiCgo0IOKlisKoIOKfqOKGlTAsICIi4p+pCgow4oC/MyDipYog4p+o4p+pICAjIEZpbGwgbm90IG5lZWRlZA==">βοΈ</a><pre> <span class='Function'>β</span> <span class='String'>""</span> +' ' + + <span class='Number'>4</span> <span class='Function'>β₯</span><span class='Modifier'>Β¨</span> <span class='Bracket'>β¨</span><span class='Function'>β</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='String'>""</span><span class='Bracket'>β©</span> +β¨ β¨ 0 0 0 0 β© " " β© + + <span class='Number'>0</span><span class='Ligature'>βΏ</span><span class='Number'>3</span> <span class='Function'>β₯</span> <span class='Bracket'>β¨β©</span> <span class='Comment'># Fill not needed +</span>β0βΏ3 +</pre> +<p>If for some reason you need to find an array's fill element, the easiest way is <code><span class='Function'>β</span><span class='Number'>0</span><span class='Function'>β₯</span><span class='Value'>a</span></code>.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRMOKliiJzdHJpbmci">βοΈ</a><pre> <span class='Function'>β</span><span class='Number'>0</span><span class='Function'>β₯</span><span class='String'>"string"</span> +' ' +</pre> +<h2 id="how-fills-are-computed">How fills are computed</h2> +<p>For the exact requirements placed on fill, see <a href="../spec/inferred.html#fill-elements">the specification</a> (particularly "required functions"). 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> +<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'>"abc"</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 cannot 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> +<table> +<thead> +<tr> +<th>Fill</th> +<th>Monads</th> +<th>Dyads</th> +<th>Modifiers</th> +</tr> +</thead> +<tbody> +<tr> +<td><code><span class='Function'>β’</span></code></td> +<td><code><span class='Function'>β§β¨β₯β»«β½βββ·</span></code></td> +<td><code><span class='Function'>β₯ββββ½β/β</span></code></td> +<td><code><span class='Function'>π½</span><span class='Modifier'>`</span></code></td> +</tr> +<tr> +<td><code><span class='Value'>β©</span></code></td> +<td><code><span class='Function'>>βΎ</span></code></td> +<td><code><span class='Function'>βΎβ»«</span></code></td> +<td></td> +</tr> +<tr> +<td><code><span class='Number'>0</span></code></td> +<td><code><span class='Function'>β’/βββββ</span></code></td> +<td><code><span class='Function'>ββββββ·</span></code></td> +<td></td> +</tr> +</tbody> +</table> +<p>Besides these, there are a few primitives with special fills. <a href="enclose.html">Enclose</a> (<code><span class='Function'><</span></code>) uses a fill derived directly from <code><span class='Value'>π©</span></code>, with all numbers replaced by <code><span class='Number'>0</span></code> and characters by <code><span class='String'>' '</span></code> (if it contains non-data atoms, the fill doesn't exist). <a href="range.html">Range</a> (<code><span class='Function'>β</span></code>) does the same, although the reason is less obvious: the result elements don't match <code><span class='Value'>π©</span></code>, but they have the same structure.</p> +<p><a href="prefixes.html">Prefixes and Suffixes</a> (<code><span class='Function'>ββ</span></code>) use <code><span class='Number'>0</span><span class='Function'>β</span><span class='Value'>π©</span></code> for the fill, as do <a href="group.html">Group</a> and Group Indices (<code><span class='Function'>β</span></code>) in the single-axis case. Fills for multi-axis <code><span class='Function'>β</span></code> are more complicated, but follow the rule that variable-length axes are changed to length 0. The <em>elements</em> of the result of <code><span class='Function'>β</span></code> also have a fill specified: the same as <code><span class='Value'>π©</span></code> for Group, or <code><span class='Number'>0</span></code> for Group Indices.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NiDihpEg4oaR4oaVMyAgIyBUd28gZmlsbHMgYXQgdGhlIGVuZAoKwrvCqCAz4oC/NOKAvzEgL+KKuOKKlCAiYWJjMDEyM0Ei">βοΈ</a><pre> <span class='Number'>6</span> <span class='Function'>β</span> <span class='Function'>ββ</span><span class='Number'>3</span> <span class='Comment'># Two fills at the end +</span>β¨ β¨β© β¨ 0 β© β¨ 0 1 β© β¨ 0 1 2 β© β¨β© β¨β© β© + + <span class='Function'>Β»</span><span class='Modifier'>Β¨</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='Modifier2'>βΈ</span><span class='Function'>β</span> <span class='String'>"abc0123A"</span> +β¨ " ab" " 012" " " β© +</pre> |