diff options
| -rw-r--r-- | doc/couple.md | 2 | ||||
| -rw-r--r-- | doc/fill.md | 4 | ||||
| -rw-r--r-- | doc/types.md | 2 | ||||
| -rw-r--r-- | docs/doc/couple.html | 2 | ||||
| -rw-r--r-- | docs/doc/fill.html | 3 | ||||
| -rw-r--r-- | docs/doc/types.html | 2 |
6 files changed, 9 insertions, 6 deletions
diff --git a/doc/couple.md b/doc/couple.md index 4603b22b..95806d8f 100644 --- a/doc/couple.md +++ b/doc/couple.md @@ -30,7 +30,7 @@ In all cases what these functions do is more like reinterpreting existing data t ⥊ ⥊¨ a ∾ ⥊ ⥊¨ a -The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like [Table](map.md#table) `⌜`, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or [unit](enclose.md#whats-a-unit) arrays are somewhat special. They are the [identity value](fold.md#identity-values) of a function with Table, and can be produced by Merge [inverse](undo.md), `>⁼` **on a list**, which forces either the outer or inner shape to be empty (BQN chooses `>⁼` to be `<`, but only on an array, as `>` cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a `0` in the shape, except at the end, unless fills can be specified. +The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like [Table](map.md#table) `⌜`, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or [unit](enclose.md#whats-a-unit) arrays are somewhat special. They are the [identity value](fold.md#identity-values) of a function with Table, and can be produced by Merge [inverse](undo.md), `>⁼` **on a list**, which forces either the outer or inner shape to be empty (BQN chooses `>⁼` to be `<`, but only on an array, as `>` cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a `0` in the shape, except at the end, without relying on a [fill](fill.md) element. ⊢ e ← ⟨⟩¨ ↕3 ≢ > e diff --git a/doc/fill.md b/doc/fill.md index ed93b02c..6b4bd53c 100644 --- a/doc/fill.md +++ b/doc/fill.md @@ -4,7 +4,7 @@ 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 `0` or `' '`. If no fill is known, a function that requests it results in an error. -Fills are used by [Take](take.md) (`↑`) when a value in `𝕨` is larger than the corresponding length in `𝕩`, by the two [Nudge](shift.md) functions (`»«`) when `𝕩` is non-empty, and by [Reshape](reshape.md) (`⥊`) when `𝕨` contains `↑`. Except for these specific cases, the fill value an array has can't affect the program. The result of [Match](match.md) (`≡`) doesn't depend on fills, and any attempt to compute a fill can't cause side effects. +Fills are used by [Take](take.md) (`↑`) when a value in `𝕨` is larger than the corresponding length in `𝕩`, by the two [Nudge](shift.md) functions (`»«`) when `𝕩` is non-empty, by [Merge](couple.md) (`>`) when `𝕩` is empty, and by [Reshape](reshape.md) (`⥊`) when `𝕨` contains `↑`. Except for these specific cases, the fill value an array has can't affect the program. The result of [Match](match.md) (`≡`) doesn't depend on fills, and any attempt to compute a fill can't cause side effects. ## Using fills @@ -24,6 +24,8 @@ Nudge Left or Right shifts the array over and places a fill in the vacated space »⟨⟩ # Fill not needed +If the argument to [Merge](couple.md) is empty then its result will be as well, since the shape `≢𝕩` is a prefix of `≢>𝕩`. However, the remainder of the result shape is determined by the elements of `𝕩`, so if there are none then Merge uses the fill element to decide what the result shape should be. + [Reshape](reshape.md#computed-lengths) (`⥊`) uses the fill when `𝕨` contains `↑` and the product of the rest of `𝕨` doesn't evenly divide the number of elements in `𝕩`. ↑‿8 ⥊ "completepart" diff --git a/doc/types.md b/doc/types.md index f3b7f414..96870844 100644 --- a/doc/types.md +++ b/doc/types.md @@ -71,7 +71,7 @@ Other linear combinations such as adding two characters or negating a character A BQN array is a multidimensional arrangement of data. This means it has a certain [*shape*](shape.md), which is a finite list of natural numbers giving the length along each axis, and it contains an *element* for each possible [*index*](indices.md), which is a choice of one natural number that's less than each axis length in the shape. The total number of elements, or *bound*, 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 *rank*. An array of rank 0, which always contains exactly one element, is called a *unit*, while an array of rank 1 is called a *list* and an array of rank 2 is called a *table*. -Each array—empty or nonempty—has an inferred property called a [*fill*](fill.md). 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 [Take](take.md) (`↑`), the two [Nudge](shift.md) functions (`»«`), and [Reshape](reshape.md) (`⥊`). +Each array—empty or nonempty—has an inferred property called a [*fill*](fill.md). 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 [Take](take.md) (`↑`), the two [Nudge](shift.md) functions (`»«`), [Merge](couple.md) (`>`), and [Reshape](reshape.md) (`⥊`). 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. diff --git a/docs/doc/couple.html b/docs/doc/couple.html index 164c0fd5..1923e9d1 100644 --- a/docs/doc/couple.html +++ b/docs/doc/couple.html @@ -65,7 +65,7 @@ <span class='Function'>∾</span> <span class='Function'>⥊</span> <span class='Function'>⥊</span><span class='Modifier'>¨</span> <span class='Value'>a</span> "ABrstABuvwABxyzCDrstCDuvwCDxyz" </pre> -<p>The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like <a href="map.html#table">Table</a> <code><span class='Modifier'>⌜</span></code>, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or <a href="enclose.html#whats-a-unit">unit</a> arrays are somewhat special. They are the <a href="fold.html#identity-values">identity value</a> of a function with Table, and can be produced by Merge <a href="undo.html">inverse</a>, <code><span class='Function'>></span><span class='Modifier'>⁼</span></code> <strong>on a list</strong>, which forces either the outer or inner shape to be empty (BQN chooses <code><span class='Function'>></span><span class='Modifier'>⁼</span></code> to be <code><span class='Function'><</span></code>, but only on an array, as <code><span class='Function'>></span></code> cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a <code><span class='Number'>0</span></code> in the shape, except at the end, unless fills can be specified.</p> +<p>The way this happens, and the constraint that all inner arrays have the same shape, is closely connected to the concept of an array, and like <a href="map.html#table">Table</a> <code><span class='Modifier'>⌜</span></code>, Merge might be considered a fundamental way to build up multidimensional arrays from lists. In both cases rank-0 or <a href="enclose.html#whats-a-unit">unit</a> arrays are somewhat special. They are the <a href="fold.html#identity-values">identity value</a> of a function with Table, and can be produced by Merge <a href="undo.html">inverse</a>, <code><span class='Function'>></span><span class='Modifier'>⁼</span></code> <strong>on a list</strong>, which forces either the outer or inner shape to be empty (BQN chooses <code><span class='Function'>></span><span class='Modifier'>⁼</span></code> to be <code><span class='Function'><</span></code>, but only on an array, as <code><span class='Function'>></span></code> cannot produce non-arrays). Merge has another catch as well: it cannot produce arrays with a <code><span class='Number'>0</span></code> in the shape, except at the end, without relying on a <a href="fill.html">fill</a> element.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGUg4oaQIOKfqOKfqcKoIOKGlTMK4omiID4gZQriiaIgPiA+IGU=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>e</span> <span class='Gets'>←</span> <span class='Bracket'>⟨⟩</span><span class='Modifier'>¨</span> <span class='Function'>↕</span><span class='Number'>3</span> ⟨ ⟨⟩ ⟨⟩ ⟨⟩ ⟩ <span class='Function'>≢</span> <span class='Function'>></span> <span class='Value'>e</span> diff --git a/docs/doc/fill.html b/docs/doc/fill.html index 843e80e8..e77872c4 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="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>, 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'>></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> <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,6 +26,7 @@ <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'>≢></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'>"completepart"</span> ┌─ diff --git a/docs/doc/types.html b/docs/doc/types.html index bcc119f6..8d3c4e39 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 <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>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>), <a href="couple.html">Merge</a> (<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> |