diff options
Diffstat (limited to 'docs/doc')
| -rw-r--r-- | docs/doc/fill.html | 21 | ||||
| -rw-r--r-- | docs/doc/find.html | 6 | ||||
| -rw-r--r-- | docs/doc/pick.html | 13 | ||||
| -rw-r--r-- | docs/doc/reshape.html | 8 | ||||
| -rw-r--r-- | docs/doc/types.html | 2 |
5 files changed, 22 insertions, 28 deletions
diff --git a/docs/doc/fill.html b/docs/doc/fill.html index 5ef9baf1..843e80e8 100644 --- a/docs/doc/fill.html +++ b/docs/doc/fill.html @@ -6,7 +6,7 @@ <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> +<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="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> <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> @@ -26,18 +26,15 @@ <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 +<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'>"completepart"</span> +ββ +β΅"complete + part " + β </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> +<p>If for some reason you need to find an array's fill element, the easiest general way is probably <code><span class='Function'>βΒ»</span><span class='Number'>1</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=4oqRwrsx4oaR4qWKInN0cmluZyI=">βοΈ</a><pre> <span class='Function'>βΒ»</span><span class='Number'>1</span><span class='Function'>ββ₯</span><span class='String'>"string"</span> ' ' </pre> <h2 id="how-fills-are-computed">How fills are computed</h2> diff --git a/docs/doc/find.html b/docs/doc/find.html index bc883db2..1421500e 100644 --- a/docs/doc/find.html +++ b/docs/doc/find.html @@ -32,14 +32,14 @@ <span class='String'>"string"</span> <span class='Paren'>(</span><span class='Function'>β’</span><span class='Modifier2'>β</span><span class='Function'>β’ββ·</span><span class='Paren'>)</span> <span class='String'>"substring"</span> <span class='Comment'># APL style </span>β¨ 0 0 0 1 0 0 0 0 0 β© </pre> -<p>If <code><span class='Value'>π¨</span></code> is larger than <code><span class='Value'>π©</span></code>, the result is empty, and there's no error even in cases where Windows would fail. One place this tends to come up is when applying <a href="pick.html">First</a> (<code><span class='Function'>β</span></code>) the result: <code><span class='Function'>ββ·</span></code> tests whether <code><span class='Value'>π¨</span></code> appears in <code><span class='Value'>π©</span></code> at the first position, that is, whether it's a prefix of <code><span class='Value'>π©</span></code>. If <code><span class='Value'>π¨</span></code> is longer than <code><span class='Value'>π©</span></code> it shouldn't be a prefix, so 0 is appropriate.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Imxvb29vb29uZyIg4o23ICJzaG9ydCIKCjkg4oaVICJzaG9ydCIKCuKKkSAibG9vb29vb25nIiDijbcgInNob3J0Ig==">βοΈ</a><pre> <span class='String'>"loooooong"</span> <span class='Function'>β·</span> <span class='String'>"short"</span> +<p>If <code><span class='Value'>π¨</span></code> is larger than <code><span class='Value'>π©</span></code>, the result is empty, and there's no error even in cases where Windows would fail. One place this tends to come up is when applying <a href="pick.html#first">First</a> (<code><span class='Function'>β</span></code>) the result: <code><span class='Function'>ββ·</span></code> tests whether <code><span class='Value'>π¨</span></code> appears in <code><span class='Value'>π©</span></code> at the first position, that is, whether it's a prefix of <code><span class='Value'>π©</span></code>. If <code><span class='Value'>π¨</span></code> is longer than <code><span class='Value'>π©</span></code> it shouldn't be a prefix. First will fail but using a <a href="fold.html">fold</a> <code><span class='Number'>0</span><span class='Function'>β£</span><span class='Modifier'>Β΄</span><span class='Function'>β₯</span><span class='Modifier2'>β</span><span class='Function'>β·</span></code> instead gives a 0 in this case.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=Imxvb29vb29uZyIg4o23ICJzaG9ydCIKCjkg4oaVICJzaG9ydCIKCjAg4oqjwrQgImxvb29vb29uZyIg4o23ICJzaG9ydCI=">βοΈ</a><pre> <span class='String'>"loooooong"</span> <span class='Function'>β·</span> <span class='String'>"short"</span> β¨β© <span class='Number'>9</span> <span class='Function'>β</span> <span class='String'>"short"</span> ERROR - <span class='Function'>β</span> <span class='String'>"loooooong"</span> <span class='Function'>β·</span> <span class='String'>"short"</span> + <span class='Number'>0</span> <span class='Function'>β£</span><span class='Modifier'>Β΄</span> <span class='String'>"loooooong"</span> <span class='Function'>β·</span> <span class='String'>"short"</span> 0 </pre> <p>This pattern also works in the high-rank case discussed below, testing whether <code><span class='Value'>π¨</span></code> is a multi-dimensional prefix starting at the lowest-index corner of <code><span class='Value'>π©</span></code>.</p> diff --git a/docs/doc/pick.html b/docs/doc/pick.html index b0e99195..a296d6c0 100644 --- a/docs/doc/pick.html +++ b/docs/doc/pick.html @@ -6,7 +6,7 @@ <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="pick">Pick</h1> <p>Pick (<code><span class='Function'>β</span></code>) chooses elements from <code><span class='Value'>π©</span></code> based on <a href="indices.html">index</a> lists from <code><span class='Value'>π¨</span></code>. <code><span class='Value'>π¨</span></code> can be a plain list, or even one number if <code><span class='Value'>π©</span></code> is a list, in order to get one element from <code><span class='Value'>π©</span></code>. It can also be an array of index lists, or have deeper array structure: each index list will be replaced with the element of <code><span class='Value'>π©</span></code> at that index, effectively applying to <code><span class='Value'>π¨</span></code> at <a href="depth.html#the-depth-modifier">depth</a> 1.</p> -<p>With no <code><span class='Value'>π¨</span></code>, monadic <code><span class='Function'>β</span><span class='Value'>π©</span></code> takes the first element of <code><span class='Value'>π©</span></code> in index order, or its <a href="fill.html">fill element</a> if <code><span class='Value'>π©</span></code> is empty (causing an error if no fill is known).</p> +<p>With no <code><span class='Value'>π¨</span></code>, monadic <code><span class='Function'>β</span><span class='Value'>π©</span></code> takes the first element of <code><span class='Value'>π©</span></code> in index order, with an error if <code><span class='Value'>π©</span></code> is empty.</p> <p>While sometimes "scatter-point" indexing is necessary, using Pick to select multiple elements from <code><span class='Value'>π©</span></code> is less array-oriented than <a href="select.html">Select</a> (<code><span class='Function'>β</span></code>), and probably slower. Consider rearranging your data so that you can select along axes instead of picking out elements.</p> <h2 id="one-element">One element</h2> <p>When the left argument is a number, Pick gets an element from a list:</p> @@ -55,15 +55,12 @@ <span class='Function'>β</span> <span class='Function'>β</span><span class='Number'>4</span><span class='Ligature'>βΏ</span><span class='Number'>2</span><span class='Ligature'>βΏ</span><span class='Number'>5</span><span class='Ligature'>βΏ</span><span class='Number'>1</span> β¨ 0 0 0 0 β© </pre> -<p>If <code><span class='Value'>π©</span></code> is empty then Pick always results in an error. First never gives an error: instead it returns the <a href="fill.html">fill element</a> for <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=4oqRICIiCuKKkSDiiaLPgAriipEgMOKGkTzin6giICAiLOKGlTTin6k=">βοΈ</a><pre> <span class='Function'>β</span> <span class='String'>""</span> -' ' +<p>If <code><span class='Value'>π©</span></code> is empty then First results in an error, like Pick.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRICIiCuKKkSDiiaLPgA==">βοΈ</a><pre> <span class='Function'>β</span> <span class='String'>""</span> +ERROR <span class='Function'>β</span> <span class='Function'>β’</span><span class='Number'>Ο</span> -0 - <span class='Function'>β</span> <span class='Number'>0</span><span class='Function'>β<</span><span class='Bracket'>β¨</span><span class='String'>" "</span><span class='Separator'>,</span><span class='Function'>β</span><span class='Number'>4</span><span class='Bracket'>β©</span> -β¨ " " β¨ 0 0 0 0 β© β© +ERROR </pre> -<p>So one way to find the fill element for an array <code><span class='Value'>π©</span></code> of any shape is <code><span class='Function'>β</span><span class='Number'>0</span><span class='Function'>β₯</span><span class='Value'>π©</span></code>.</p> <p>In APL it's common to get the last element of a list with an idiom that translates to <code><span class='Function'>ββ½</span></code>, or First-<a href="reverse.html">Reverse</a>. In BQN the most straightforward way is to select with index <code><span class='Number'>Β―1</span></code> instead. I also sometimes use <a href="fold.html">Fold</a> with the Right <a href="identity.html">identity function</a>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqR4oy9ICJsYXN0IgrCrzHiipEgImxhc3QiCuKKosK0ICJsYXN0Ig==">βοΈ</a><pre> <span class='Function'>ββ½</span> <span class='String'>"last"</span> 't' diff --git a/docs/doc/reshape.html b/docs/doc/reshape.html index 23e77e9c..b9d16cc5 100644 --- a/docs/doc/reshape.html +++ b/docs/doc/reshape.html @@ -142,12 +142,12 @@ 235 236 237 β </pre> -<p>If the left argument implies a larger number of elements, then the argument elements are reused cyclically. Below, we reach the last element <code><span class='Number'>247</span></code> and start over at <code><span class='Number'>135</span></code>. If the array doesn't have any elements to start with, its <a href="fill.html">fill element</a> is used instead, but it's probably best not to invoke this case!</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MTUg4qWKIGEKCjQg4qWKIOKGlTAgICMgRmlsbCBmb3Ig4oaVMCBpcyAw">βοΈ</a><pre> <span class='Number'>15</span> <span class='Function'>β₯</span> <span class='Value'>a</span> +<p>If the left argument implies a larger number of elements, then the argument elements are reused cyclically. Below, we reach the last element <code><span class='Number'>247</span></code> and start over at <code><span class='Number'>135</span></code>. If the array doesn't have any elements to start with, you'll get an error as there aren't any elements available.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MTUg4qWKIGEKCjQg4qWKIOKGlTA=">βοΈ</a><pre> <span class='Number'>15</span> <span class='Function'>β₯</span> <span class='Value'>a</span> β¨ 135 136 137 145 146 147 235 236 237 245 246 247 135 136 137 β© - <span class='Number'>4</span> <span class='Function'>β₯</span> <span class='Function'>β</span><span class='Number'>0</span> <span class='Comment'># Fill for β0 is 0 -</span>β¨ 0 0 0 0 β© + <span class='Number'>4</span> <span class='Function'>β₯</span> <span class='Function'>β</span><span class='Number'>0</span> +ERROR </pre> <p>Reshape is the idiomatic way to make an array filled with a constant value (that is, where all elements are the same). For an atom element, just reshape it directly; for an arbitrary element, first enclose it to create a unit, and then reshape it.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=M+KAvzQg4qWKIDAKCjUg4qWKIDwgInN0cmluZyI=">βοΈ</a><pre> <span class='Number'>3</span><span class='Ligature'>βΏ</span><span class='Number'>4</span> <span class='Function'>β₯</span> <span class='Number'>0</span> diff --git a/docs/doc/types.html b/docs/doc/types.html index 46356766..bcc119f6 100644 --- a/docs/doc/types.html +++ b/docs/doc/types.html @@ -59,7 +59,7 @@ <h3 id="arrays">Arrays</h3> <p><em>Full documentation <a href="array.html">here</a>.</em></p> <p>A BQN array is a multidimensional arrangement of data. This means it has a certain <a href="shape.html"><em>shape</em></a>, which is a finite list of natural numbers giving the length along each axis, and it contains an <em>element</em> for each possible <a href="indices.html"><em>index</em></a>, which is a choice of one natural number that's less than each axis length in the shape. The total number of elements, or <em>bound</em>, is then the product of all the lengths in the shape. The shape may have any length including zero, and this shape is known as the array's <em>rank</em>. An array of rank 0, which always contains exactly one element, is called a <em>unit</em>, while an array of rank 1 is called a <em>list</em> and an array of rank 2 is called a <em>table</em>.</p> -<p>Each arrayβempty or nonemptyβhas an inferred property called a <em>fill</em>. The fill either indicates what element should be used to pad an array, or that such an element is not known and an error should result. Fills can be used by <a href="take.html">Take</a> (<code><span class='Function'>β</span></code>), the two <a href="shift.html">Nudge</a> functions (<code><span class='Function'>»«</span></code>), <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>).</p> +<p>Each arrayβempty or nonemptyβhas an inferred property called a <a href="fill.html"><em>fill</em></a>. The fill either indicates what element should be used to pad an array, or that such an element is not known and an error should result. Fills can be used by <a href="take.html">Take</a> (<code><span class='Function'>β</span></code>), the two <a href="shift.html">Nudge</a> functions (<code><span class='Function'>»«</span></code>), and <a href="reshape.html">Reshape</a> (<code><span class='Function'>β₯</span></code>).</p> <p>Arrays are value types (or immutable), so that there is no way to "change" the shape or elements of an array. An array with different properties is a different array. As a consequence, arrays are an inductive type, and it's not possible for an array to contain itself, or contain an array that contains itself, and so on. However, it is possible for an array to contain a function or other operation that has access to the array through a variable, and in this sense an array can "know about" itself.</p> <p>Different elements of an array should not influence each other. While some APLs force numbers placed in the same array to a common representation, which may have different precision properties, BQN values must not change behavior when placed in an array. However, this doesn't preclude changing the storage type of an array for better performance: for example, in a BQN implementation using 64-bit floats, an array whose elements are all integers that fit in 32-bit int range might be represented as an array of 32-bit ints.</p> <h2 id="operation-types">Operation types</h2> |