diff options
| author | Marshall Lochbaum <mwlochbaum@gmail.com> | 2022-06-06 21:29:06 -0400 |
|---|---|---|
| committer | Marshall Lochbaum <mwlochbaum@gmail.com> | 2022-06-06 21:29:06 -0400 |
| commit | 8342ba5e9392811dbc0514a97e847a44a5b330a2 (patch) | |
| tree | f606422844d6a5df93b5bdd799b9daf4634b3145 /docs/doc | |
| parent | 272464e78e1f44bca037868ce83092856f42995e (diff) | |
When I wrote all these docs did I really understand I'd have to edit them?
Diffstat (limited to 'docs/doc')
| -rw-r--r-- | docs/doc/glossary.html | 1 | ||||
| -rw-r--r-- | docs/doc/prefixes.html | 46 | ||||
| -rw-r--r-- | docs/doc/primitive.html | 34 | ||||
| -rw-r--r-- | docs/doc/range.html | 14 | ||||
| -rw-r--r-- | docs/doc/repeat.html | 8 | ||||
| -rw-r--r-- | docs/doc/replicate.html | 8 | ||||
| -rw-r--r-- | docs/doc/reshape.html | 18 | ||||
| -rw-r--r-- | docs/doc/reverse.html | 16 |
8 files changed, 78 insertions, 67 deletions
diff --git a/docs/doc/glossary.html b/docs/doc/glossary.html index 16a1ade3..1bd32484 100644 --- a/docs/doc/glossary.html +++ b/docs/doc/glossary.html @@ -76,6 +76,7 @@ </ul> <ul> <li><a href="indices.html"><strong>Index</strong></a>: One of a variety of ways to select an element, cell, axis, or position along an axis of an array.</li> +<li><a href="reshape.html"><strong>Index order</strong></a>: The standard ordering of array elements by increasing index.</li> <li><a href="indices.html#element-indices"><strong>Index list</strong></a>: A list of numbers indicating a single element of an array.</li> </ul> <h2 id="operations"><a class="header" href="#operations">Operations</a></h2> diff --git a/docs/doc/prefixes.html b/docs/doc/prefixes.html index dd27b18c..1147dc51 100644 --- a/docs/doc/prefixes.html +++ b/docs/doc/prefixes.html @@ -5,15 +5,16 @@ </head> <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="prefixes-and-suffixes"><a class="header" href="#prefixes-and-suffixes">Prefixes and Suffixes</a></h1> -<p>The Prefixes (<code><span class='Function'>↑</span></code>) function gives a list of all prefixes of its argument array along the <a href="leading.html">first axis</a>, and Suffixes (<code><span class='Function'>↓</span></code>) gives a similar list for suffixes. Because the result can be much larger than the argument, these functions may not be used often in high-performance code, but they are a powerful conceptual tool and can make sense for algorithms that are inherently quadratic.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaRICJhYmNkZSIK4oaTICJhYmNkZSI=">↗️</a><pre> <span class='Function'>↑</span> <span class='String'>"abcde"</span> +<p>The Prefixes (<code><span class='Function'>↑</span></code>) function gives a list of all prefixes of its argument array along the <a href="leading.html">first axis</a>, and Suffixes (<code><span class='Function'>↓</span></code>) gives a similar list for suffixes. Because the result can be much larger than the argument, these functions may not be used often in high-performance code, but they are a good conceptual tool and can make sense for algorithms that are inherently quadratic.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaRICJhYmNkZSIKCuKGkyAiYWJjZGUi">↗️</a><pre> <span class='Function'>↑</span> <span class='String'>"abcde"</span> ⟨ ⟨⟩ "a" "ab" "abc" "abcd" "abcde" ⟩ + <span class='Function'>↓</span> <span class='String'>"abcde"</span> ⟨ "abcde" "bcde" "cde" "de" "e" ⟨⟩ ⟩ </pre> <p>The functions are closely related to <a href="take.html">Take and Drop</a>, as we might expect from their glyphs. Element <code><span class='Value'>i</span><span class='Function'>⊑↑</span><span class='Value'>𝕩</span></code> is <code><span class='Value'>i</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code>, and <code><span class='Value'>i</span><span class='Function'>⊑↓</span><span class='Value'>𝕩</span></code> is <code><span class='Value'>i</span><span class='Function'>↓</span><span class='Value'>𝕩</span></code>.</p> -<p>In both cases, an empty array and the entire argument are included in the result, meaning its length is one more than that of the argument. Using <a href="logic.html">Span</a>, we can say that the result has elements whose lengths go from <code><span class='Number'>0</span></code> to <code><span class='Function'>≠</span><span class='Value'>𝕩</span></code>, inclusive, so there are <code><span class='Paren'>(</span><span class='Function'>≠</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>¬</span><span class='Number'>0</span></code> or <code><span class='Number'>1</span><span class='Function'>+≠</span><span class='Value'>𝕩</span></code> elements. The total number or cells in the result (for example, <code><span class='Function'>≠∾↑</span><span class='Value'>𝕩</span></code> or <code><span class='Function'>+</span><span class='Modifier'>´</span><span class='Function'>≠</span><span class='Modifier'>¨</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code>) scales with the square of the argument length—it is quadratic in <code><span class='Function'>≠</span><span class='Value'>𝕩</span></code>. We can find the exact total by looking at Prefixes and Suffixes together:</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKGkSDiiY3LmCDihpMpICJhYmNkZSIKKOKGkSDiiL7CqCDihpMpICJhYmNkZSI=">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>↑</span> <span class='Function'>≍</span><span class='Modifier'>˘</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abcde"</span> +<p>In both cases, an empty array and the entire argument are included in the result, meaning its length is one more than that of the argument. Using <a href="logic.html">Span</a>, we can say that the result has elements whose <a href="shape.html">lengths</a> go from <code><span class='Number'>0</span></code> to <code><span class='Function'>≠</span><span class='Value'>𝕩</span></code>, inclusive, so there are <code><span class='Paren'>(</span><span class='Function'>≠</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>¬</span><span class='Number'>0</span></code> or <code><span class='Number'>1</span><span class='Function'>+≠</span><span class='Value'>𝕩</span></code> elements. The total number of cells in the result (for example, <code><span class='Function'>≠∾↑</span><span class='Value'>𝕩</span></code> or <code><span class='Function'>+</span><span class='Modifier'>´</span><span class='Function'>≠</span><span class='Modifier'>¨</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code>) scales with the square of the argument length—it's quadratic in <code><span class='Function'>≠</span><span class='Value'>𝕩</span></code>. We can find the exact total by looking at Prefixes and Suffixes together:</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKGkSDiiY3LmCDihpMpICJhYmNkZSIKCijihpEg4oi+wqgg4oaTKSAiYWJjZGUi">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>↑</span> <span class='Function'>≍</span><span class='Modifier'>˘</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abcde"</span> ┌─ ╵ ⟨⟩ "abcde" "a" "bcde" @@ -22,12 +23,14 @@ "abcd" "e" "abcde" ⟨⟩ ┘ + <span class='Paren'>(</span><span class='Function'>↑</span> <span class='Function'>∾</span><span class='Modifier'>¨</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abcde"</span> ⟨ "abcde" "abcde" "abcde" "abcde" "abcde" "abcde" ⟩ </pre> -<p>Joining corresponding elements of <code><span class='Function'>↑</span><span class='Value'>𝕩</span></code> and <code><span class='Function'>↓</span><span class='Value'>𝕩</span></code> gives <code><span class='Value'>𝕩</span></code> again. This is because <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Paren'>(</span><span class='Function'>↑∾</span><span class='Modifier'>¨</span><span class='Function'>↓</span><span class='Paren'>)</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>⊑↑</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>∾</span><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>⊑↓</span><span class='Value'>𝕩</span><span class='Paren'>)</span></code>, or, using the Take and Drop correspondences, <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>↑</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>∾</span><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>↓</span><span class='Value'>𝕩</span><span class='Paren'>)</span></code>, which is <code><span class='Value'>𝕩</span></code>. Element-wise, we are combining the first <code><span class='Value'>i</span></code> cells of <code><span class='Value'>𝕩</span></code> with all but the first <code><span class='Value'>i</span></code>. Looking at the entire result, we now know that <code><span class='Paren'>(</span><span class='Function'>↑∾</span><span class='Modifier'>¨</span><span class='Function'>↓</span><span class='Paren'>)</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>⥊<</span><span class='Value'>𝕩</span></code>. The total number of cells in this combined array is therefore <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>×≠</span><span class='Value'>𝕩</span></code>, or <code><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>+</span><span class='Modifier2'>⊸</span><span class='Function'>×≠</span><span class='Value'>𝕩</span></code>. Each of Prefixes and Suffixes must have the same total number of cells (in fact, <code><span class='Function'>↑</span><span class='Value'>𝕩</span></code> is <code><span class='Function'>⌽</span><span class='Modifier'>¨</span><span class='Modifier2'>∘</span><span class='Function'>↓</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span><span class='Value'>𝕩</span></code>, and Reverse doesn't change an array's shape). So the total number in either one is <code><span class='Number'>2</span><span class='Function'>÷</span><span class='Modifier'>˜</span><span class='Number'>1</span><span class='Modifier2'>⊸</span><span class='Function'>+</span><span class='Modifier2'>⊸</span><span class='Function'>×≠</span><span class='Value'>𝕩</span></code>. With <code><span class='Value'>n</span><span class='Gets'>←</span><span class='Function'>≠</span><span class='Value'>𝕩</span></code>, it is <code><span class='Number'>2</span><span class='Function'>÷</span><span class='Modifier'>˜</span><span class='Value'>n</span><span class='Function'>×</span><span class='Number'>1</span><span class='Function'>+</span><span class='Value'>n</span></code>.</p> +<p>Joining corresponding elements of <code><span class='Function'>↑</span><span class='Value'>𝕩</span></code> and <code><span class='Function'>↓</span><span class='Value'>𝕩</span></code> gives <code><span class='Value'>𝕩</span></code> again. This is because <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Paren'>(</span><span class='Function'>↑∾</span><span class='Modifier'>¨</span><span class='Function'>↓</span><span class='Paren'>)</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>⊑↑</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>∾</span><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>⊑↓</span><span class='Value'>𝕩</span><span class='Paren'>)</span></code>, or, using the Take and Drop correspondences, <code><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>↑</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>∾</span><span class='Paren'>(</span><span class='Value'>i</span><span class='Function'>↓</span><span class='Value'>𝕩</span><span class='Paren'>)</span></code>, which is <code><span class='Value'>𝕩</span></code>. Element-wise, we are combining the first <code><span class='Value'>i</span></code> cells of <code><span class='Value'>𝕩</span></code> with all but the first <code><span class='Value'>i</span></code>.</p> +<p>Looking at the entire result, we now know that <code><span class='Paren'>(</span><span class='Function'>↑∾</span><span class='Modifier'>¨</span><span class='Function'>↓</span><span class='Paren'>)</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>⥊<</span><span class='Value'>𝕩</span></code>. The total number of cells in this combined array is therefore <code><span class='Paren'>(</span><span class='Number'>1</span><span class='Function'>+</span><span class='Value'>n</span><span class='Paren'>)</span><span class='Function'>×</span><span class='Value'>n</span></code>, setting <code><span class='Value'>n</span><span class='Gets'>←</span><span class='Function'>≠</span><span class='Value'>𝕩</span></code>. Each of Prefixes and Suffixes must have the same total number of cells (in code, <code><span class='Function'>↑</span><span class='Value'>𝕩</span></code> is <code><span class='Function'>⌽</span><span class='Modifier'>¨</span><span class='Modifier2'>∘</span><span class='Function'>↓</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span><span class='Value'>𝕩</span></code>, and Reverse doesn't change an array's shape). So the total number in either one is <code><span class='Number'>2</span><span class='Function'>÷</span><span class='Modifier'>˜</span><span class='Value'>n</span><span class='Function'>×</span><span class='Number'>1</span><span class='Function'>+</span><span class='Value'>n</span></code>.</p> <h2 id="definition"><a class="header" href="#definition">Definition</a></h2> -<p>Knowing the <a href="shape.html">length</a> and the elements, it's easy to define functions for Prefixes and Suffixes: <code><span class='Function'>↑</span></code> is equivalent to <code><span class='Paren'>(</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↑</span><span class='Modifier'>¨</span><span class='Function'><</span></code> while <code><span class='Function'>↓</span></code> is <code><span class='Paren'>(</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↓</span><span class='Modifier'>¨</span><span class='Function'><</span></code>. Each primitive is defined only on arrays with at least one axis.</p> +<p>Knowing the length and the elements, it's easy to define functions for Prefixes and Suffixes: <code><span class='Function'>↑</span></code> is equivalent to <code><span class='Paren'>(</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↑</span><span class='Modifier'>¨</span><span class='Function'><</span></code> while <code><span class='Function'>↓</span></code> is <code><span class='Paren'>(</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↓</span><span class='Modifier'>¨</span><span class='Function'><</span></code>. Each primitive is defined only on arrays with at least one axis.</p> <h2 id="working-with-pairs"><a class="header" href="#working-with-pairs">Working with pairs</a></h2> <p>Sometimes it's useful to apply an operation to every unordered pair of elements from a list. For example, consider all possible products of numbers between 1 and 6:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=w5fijJzLnCAxK+KGlTY=">↗️</a><pre> <span class='Function'>×</span><span class='Modifier'>⌜˜</span> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> @@ -41,48 +44,54 @@ ┘ </pre> <p>It's easy enough to use the <a href="map.html#table">Table</a> modifier here, but it also computes most products twice. If we only care about the unique products, we could multiply each number by all the ones after it. "After" sounds like suffixes, so let's look at those:</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MSvihpU2CuKGkyAxK+KGlTY=">↗️</a><pre> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MSvihpU2CgrihpMgMSvihpU2">↗️</a><pre> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> ⟨ 1 2 3 4 5 6 ⟩ + <span class='Function'>↓</span> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> ⟨ ⟨ 1 2 3 4 5 6 ⟩ ⟨ 2 3 4 5 6 ⟩ ⟨ 3 4 5 6 ⟩ ⟨ 4 5 6 ⟩ ⟨ 5 6 ⟩ ⟨ 6 ⟩ ⟨⟩ ⟩ </pre> <p>We want to include the diagonal, so we'll pair each element with the corresponding element of the suffixes, reducing the suffixes to the original array's length by dropping the last element, which is empty. In other cases, we might not want to include it and we should instead drop the first element.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKKoiDDlyDiiaAg4oaRIOKGkykgMSvihpU2CijiiqIgw5cgMSDihpMg4oaTKSAxK+KGlTY=">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>⊢</span> <span class='Function'>×</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKKoiDDlyDiiaAg4oaRIOKGkykgMSvihpU2Cgoo4oqiIMOXIDEg4oaTIOKGkykgMSvihpU2">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>⊢</span> <span class='Function'>×</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> ⟨ ⟨ 1 2 3 4 5 6 ⟩ ⟨ 4 6 8 10 12 ⟩ ⟨ 9 12 15 18 ⟩ ⟨ 16 20 24 ⟩ ⟨ 25 30 ⟩ ⟨ 36 ⟩ ⟩ + <span class='Paren'>(</span><span class='Function'>⊢</span> <span class='Function'>×</span> <span class='Number'>1</span> <span class='Function'>↓</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='Number'>1</span><span class='Function'>+↕</span><span class='Number'>6</span> ⟨ ⟨ 2 3 4 5 6 ⟩ ⟨ 6 8 10 12 ⟩ ⟨ 12 15 18 ⟩ ⟨ 20 24 ⟩ ⟨ 30 ⟩ ⟨⟩ ⟩ </pre> -<p>By using <a href="couple.html">Couple</a> (<code><span class='Function'>≍</span></code>) instead of <code><span class='Function'>×</span></code>, we can see the argument ordering, demonstrating that we are looking at the upper right half of the matrix produced by Table. While in this case we could use <code><span class='Function'>≍</span><span class='Modifier2'>⚇</span><span class='Number'>0</span></code> to mimic the pervasion of <code><span class='Function'>×</span></code>, we'd like this to work even on nested arguments so we should figure out how the mapping structure works to apply Each appropriately.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omN4oycy5wgImFiYyIKKDzLmCDiiY3CqMKoIOKJoCDihpEg4oaTKSAiYWJjIg==">↗️</a><pre> <span class='Function'>≍</span><span class='Modifier'>⌜˜</span> <span class='String'>"abc"</span> +<p>By using <a href="pair.html">Pair</a> (<code><span class='Function'>⋈</span></code>) instead of <code><span class='Function'>×</span></code>, we can see the argument ordering, demonstrating that we are looking at the upper right half of the matrix produced by Table. While in this case we could use <code><span class='Function'>⋈</span><span class='Modifier2'>⚇</span><span class='Number'>0</span></code> to mimic the pervasion of <code><span class='Function'>×</span></code>, we'd like this to work even on nested arguments so we should figure out how the mapping structure works to apply Each appropriately.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4ouI4oycy5wgImFiYyIKCig8y5gg4ouIwqjCqCDiiaAg4oaRIOKGkykgImFiYyI=">↗️</a><pre> <span class='Function'>⋈</span><span class='Modifier'>⌜˜</span> <span class='String'>"abc"</span> ┌─ ╵ "aa" "ab" "ac" "ba" "bb" "bc" "ca" "cb" "cc" ┘ - <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>≍</span><span class='Modifier'>¨¨</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abc"</span> + + <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>⋈</span><span class='Modifier'>¨¨</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abc"</span> ⟨ ⟨ "aa" "ab" "ac" ⟩ ⟨ "bb" "bc" ⟩ ⟨ "cc" ⟩ ⟩ </pre> -<p>As before, we can exclude the diagonal, and using Prefixes instead of Suffixes gives us the lower left half instead of the upper right—in terms of the arguments given to <code><span class='Function'>≍</span></code> it reverses the argument pairs and iterates in a different order.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KDzLmCDiiY3CqMKoIDEg4oaTIOKGkykgImFiYyIKKDzLmCDiiY3CqMKoIDEg4oaTIOKGkSkgImFiYyIKKDzLmCDiiY3CqMKoIOKJoCDihpEg4oaRKSAiYWJjIg==">↗️</a><pre> <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>≍</span><span class='Modifier'>¨¨</span> <span class='Number'>1</span> <span class='Function'>↓</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abc"</span> +<p>As before, we can exclude the diagonal, and using Prefixes instead of Suffixes gives us the lower left half instead of the upper right—in terms of the arguments given to <code><span class='Function'>⋈</span></code> it reverses the argument pairs and iterates in a different order.</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KDzLmCDii4jCqMKoIDEg4oaTIOKGkykgImFiYyIKCig8y5gg4ouIwqjCqCAxIOKGkyDihpEpICJhYmMiCgooPMuYIOKLiMKowqgg4omgIOKGkSDihpEpICJhYmMi">↗️</a><pre> <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>⋈</span><span class='Modifier'>¨¨</span> <span class='Number'>1</span> <span class='Function'>↓</span> <span class='Function'>↓</span><span class='Paren'>)</span> <span class='String'>"abc"</span> ⟨ ⟨ "ab" "ac" ⟩ ⟨ "bc" ⟩ ⟨⟩ ⟩ - <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>≍</span><span class='Modifier'>¨¨</span> <span class='Number'>1</span> <span class='Function'>↓</span> <span class='Function'>↑</span><span class='Paren'>)</span> <span class='String'>"abc"</span> + + <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>⋈</span><span class='Modifier'>¨¨</span> <span class='Number'>1</span> <span class='Function'>↓</span> <span class='Function'>↑</span><span class='Paren'>)</span> <span class='String'>"abc"</span> ⟨ ⟨ "aa" ⟩ ⟨ "ba" "bb" ⟩ ⟨ "ca" "cb" "cc" ⟩ ⟩ - <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>≍</span><span class='Modifier'>¨¨</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↑</span><span class='Paren'>)</span> <span class='String'>"abc"</span> + + <span class='Paren'>(</span><span class='Function'><</span><span class='Modifier'>˘</span> <span class='Function'>⋈</span><span class='Modifier'>¨¨</span> <span class='Function'>≠</span> <span class='Function'>↑</span> <span class='Function'>↑</span><span class='Paren'>)</span> <span class='String'>"abc"</span> ⟨ ⟨⟩ ⟨ "ba" ⟩ ⟨ "ca" "cb" ⟩ ⟩ </pre> <h2 id="slices"><a class="header" href="#slices">Slices</a></h2> -<p>Prefixes and Suffixes give certain restricted slices of the argument array, where a slice is a contiguous selection of cells. If we want all slices along the first axis, we can take the suffixes of each prefix, or vice-versa:</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaTwqjihpEgImFiYyIK4oaRwqjihpMgImFiYyI=">↗️</a><pre> <span class='Function'>↓</span><span class='Modifier'>¨</span><span class='Function'>↑</span> <span class='String'>"abc"</span> +<p>Prefixes and Suffixes give certain restricted slices of the argument array, where a slice is a contiguous selection of major cells. If we want all slices along the first axis, we can take the suffixes of each prefix, or vice-versa:</p> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaTwqjihpEgImFiYyIKCuKGkcKo4oaTICJhYmMi">↗️</a><pre> <span class='Function'>↓</span><span class='Modifier'>¨</span><span class='Function'>↑</span> <span class='String'>"abc"</span> ┌─ · ⟨ ⟨⟩ ⟩ ⟨ "a" ⟨⟩ ⟩ ⟨ "ab" "b" ⟨⟩ ⟩ ⟨ "abc" "bc" "c" ⟨⟩ ⟩ ┘ + <span class='Function'>↑</span><span class='Modifier'>¨</span><span class='Function'>↓</span> <span class='String'>"abc"</span> ┌─ · ⟨ ⟨⟩ "a" "ab" "abc" ⟩ ⟨ ⟨⟩ "b" "bc" ⟩ ⟨ ⟨⟩ "c" ⟩ ⟨ ⟨⟩ ⟩ ┘ </pre> <p>Effectively, this parametrizes the slices either by ending then starting index, or by starting index then length. Four empty slices are included because in a list of length 3 there are 4 places an empty slice can start: all the spaces between or outside elements (these also correspond to all the possible positions for the result of <a href="order.html#bins">Bins</a>). The slices can also be parametrized by length and then starting index using <a href="windows.html">Windows</a>.</p> -<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KCjihpUxK+KJoCnihpXCqDwpICJhYmMiCigo4oaVMSviiaApPMuY4oiY4oaVwqg8KSAiYWJjIiAgIyBTcGxpdCB0aGVtIHRvIG1hdGNoIFByZWZpeGVzL1N1ZmZpeGVz">↗️</a><pre> <span class='Paren'>((</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↕</span><span class='Modifier'>¨</span><span class='Function'><</span><span class='Paren'>)</span> <span class='String'>"abc"</span> +<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KCjihpUxK+KJoCnihpXCqDwpICJhYmMiCgooKOKGlTEr4omgKTzLmOKImOKGlcKoPCkgImFiYyIgICMgU3BsaXQgdGhlbSB0byBtYXRjaCBQcmVmaXhlcy9TdWZmaXhlcw==">↗️</a><pre> <span class='Paren'>((</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'>↕</span><span class='Modifier'>¨</span><span class='Function'><</span><span class='Paren'>)</span> <span class='String'>"abc"</span> ┌─ · ┌┐ ┌─ ┌─ ┌─ ╵ ╵"a ╵"ab ╵"abc" @@ -91,6 +100,7 @@ ┘ ┘ ┘ + <span class='Paren'>((</span><span class='Function'>↕</span><span class='Number'>1</span><span class='Function'>+≠</span><span class='Paren'>)</span><span class='Function'><</span><span class='Modifier'>˘</span><span class='Modifier2'>∘</span><span class='Function'>↕</span><span class='Modifier'>¨</span><span class='Function'><</span><span class='Paren'>)</span> <span class='String'>"abc"</span> <span class='Comment'># Split them to match Prefixes/Suffixes </span>┌─ · ⟨ ⟨⟩ ⟨⟩ ⟨⟩ ⟨⟩ ⟩ ⟨ "a" "b" "c" ⟩ ⟨ "ab" "bc" ⟩ ⟨ "abc" ⟩ diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html index 3da3019b..a981ae81 100644 --- a/docs/doc/primitive.html +++ b/docs/doc/primitive.html @@ -5,8 +5,8 @@ </head> <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="bqn-primitives"><a class="header" href="#bqn-primitives">BQN primitives</a></h1> -<p><em>Primitives</em> are the basic functions and modifiers built into the language, written with individual glyphs (more about the concept <a href="../commentary/primitive.html">here</a>). The role of a primitive when written always matches its type (but you can use its value in other roles by assigning it, or other methods).</p> -<p>Primitives have no side effects other than errors, and can't perform infinite computations, except when a primitive modifier calls an operand function that does one of these things (this can only happen when arguments are passed, as primitive modifiers are always deferred). Side effects here include both writing state such as variables or printed output, and reading any outside state, so that a function without them always returns the same result if passed the same arguments. Since trains and list notation have the same nice properties, tacit code written entirely with primitives, trains, and lists always describes finite, self-contained computations.</p> +<p><em>Primitives</em> are the basic functions and modifiers built into the language, written with individual glyphs (more about the concept <a href="../commentary/primitive.html">here</a>). The <a href="expression.html#syntactic-role">role</a> of a primitive when written always matches its type (but you can use its value in other roles by assigning it, or other methods).</p> +<p>Primitives have no side effects other than errors, and can't perform infinite computations, except when a primitive modifier calls an operand function that does one of these things (and this can only happen when arguments are passed, as primitive modifiers are always deferred). Side effects here include both writing state such as variables or printed output, and reading any outside state, so that a function without them always returns the same result if passed the same arguments. Since trains and list notation have the same nice properties, <a href="tacit.html">tacit</a> code written entirely with primitives, trains, and lists always describes finite, self-contained computations.</p> <p>Recursion is the primary way to perform potentially infinite computations in BQN, and it can be packaged into <a href="control.html">control structures</a> like <code><span class='Function'>While</span></code> for ease of use. A given BQN implementation might also provide <a href="../spec/system.html">system values</a> for "impure" tasks like file access or other I/O.</p> <h2 id="functions"><a class="header" href="#functions">Functions</a></h2> <p>A function call with one argument (prefix) is called "monadic" and one with two arguments (infix) is "dyadic".</p> @@ -412,7 +412,7 @@ </g> </svg> -<p><em>Combinators</em> only control the application of functions. Because a non-function operand applies as a constant function, some combinators have extra meanings when passed a constant. For example, <code><span class='Number'>0</span><span class='Modifier'>˜</span></code> is identical to <code><span class='Number'>0</span><span class='Modifier'>˙</span></code>—a constant function that always returns 0—and <code><span class='Number'>0</span><span class='Modifier2'>⊸</span><span class='Function'><</span></code> is the function that tests whether its right argument is greater than 0.</p> +<p><em>Combinators</em> only control the application of functions, which are passed as operands. A data value such as a number or array can also be an operand and, as always, applies as a constant function.</p> <table> <thead> <tr> @@ -460,12 +460,6 @@ <td><code><span class='Function'>𝔽</span></code>'s right argument comes from <code><span class='Function'>𝔾</span></code></td> </tr> <tr> -<td><code><span class='Modifier2'>⌾</span></code></td> -<td><a href="under.html">Under</a></td> -<td><code><span class='Brace'>{</span><span class='Function'>𝔾</span><span class='Modifier'>⁼</span><span class='Modifier2'>∘</span><span class='Function'>𝔽</span><span class='Modifier2'>○</span><span class='Function'>𝔾</span><span class='Brace'>}</span></code> OR <code><span class='Brace'>{</span><span class='Paren'>(</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Gets'>↩</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Modifier2'>○</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Separator'>⋄</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td> -<td>Apply <code><span class='Function'>𝔽</span></code> over <code><span class='Function'>𝔾</span></code>, then undo <code><span class='Function'>𝔾</span></code></td> -</tr> -<tr> <td><code><span class='Modifier2'>⊘</span></code></td> <td><a href="valences.html">Valences</a></td> <td><code><span class='Brace'>{</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Head'>;</span><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td> @@ -477,10 +471,22 @@ <td><code><span class='Brace'>{</span><span class='Value'>f</span><span class='Gets'>←</span><span class='Paren'>(</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Function'>⊑</span><span class='Value'>𝕘</span> <span class='Separator'>⋄</span> <span class='Value'>𝕨</span><span class='Function'>F</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td> <td>Select one of the functions in list <code><span class='Value'>𝕘</span></code> based on <code><span class='Function'>𝔽</span></code></td> </tr> +<tr> +<td><code><span class='Modifier2'>⌾</span></code></td> +<td><a href="under.html">Under</a></td> +<td><code><span class='Brace'>{</span><span class='Function'>𝔾</span><span class='Modifier'>⁼</span><span class='Modifier2'>∘</span><span class='Function'>𝔽</span><span class='Modifier2'>○</span><span class='Function'>𝔾</span><span class='Brace'>}</span></code> OR <code><span class='Brace'>{</span><span class='Paren'>(</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Paren'>)</span><span class='Gets'>↩</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Modifier2'>○</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Separator'>⋄</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td> +<td>Apply <code><span class='Function'>𝔽</span></code> over <code><span class='Function'>𝔾</span></code>, then undo <code><span class='Function'>𝔾</span></code></td> +</tr> +<tr> +<td><code><span class='Modifier2'>⎊</span></code></td> +<td><a href="assert.html#catch">Catch</a></td> +<td><code><span class='Brace'>{</span><span class='Value'>𝕨</span><span class='Function'>𝔽</span><span class='Value'>𝕩…</span> <span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span><span class='Brace'>}</span></code></td> +<td>Apply <code><span class='Function'>𝔽</span></code>, but if it fails catch the error and apply <code><span class='Function'>𝔾</span></code></td> +</tr> </tbody> </table> -<p>Choose isn't really a combinator since it calls the function <code><span class='Function'>⊑</span></code>, and Under is not a true combinator since it has an "undo" step at the end. This step might be implemented using the left operand's inverse (<em>computational</em> Under) or its structural properties (<em>structural</em> Under).</p> -<p>Other modifiers control array traversal and iteration. In three cases a simpler 1-modifier is paired with a generalized 2-modifier: in each case the 1-modifier happens to be the same as the 2-modifier with a right operand of <code><span class='Number'>¯1</span></code>.</p> +<p>The last three are combinators in spirit but go beyond the actual strict definition: Choose calls the function <code><span class='Function'>⊑</span></code>, Under has an "undo" step at the end, and Catch traps an error. The second definition for Under and the one for Catch are written in pseudo-BQN because they can't be expressed otherwise.</p> +<p>Other modifiers control array traversal and iteration. In three cases a simpler 1-modifier is paired with a generalized 2-modifier: for each of these the 1-modifier happens to be the same as the 2-modifier with a right operand of <code><span class='Number'>¯1</span></code>.</p> <table> <thead> <tr> @@ -533,11 +539,5 @@ <td></td> <td></td> </tr> -<tr> -<td></td> -<td></td> -<td><code><span class='Modifier2'>⎊</span></code></td> -<td><a href="assert.html#catch">Catch</a></td> -</tr> </tbody> </table> diff --git a/docs/doc/range.html b/docs/doc/range.html index 8065a34a..887f9833 100644 --- a/docs/doc/range.html +++ b/docs/doc/range.html @@ -5,7 +5,7 @@ </head> <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="range"><a class="header" href="#range">Range</a></h1> -<p>Range (<code><span class='Function'>↕</span></code>) is a monadic function that creates arrays of <a href="indices.html">indices</a> (like APL's famous <a href="https://aplwiki.com/wiki/Index_Generator">iota</a> function). Each element in the result is its own index.</p> +<p>Range (<code><span class='Function'>↕</span></code>) is a monadic function that creates arrays of indices, like APL's famous <a href="https://aplwiki.com/wiki/Index_Generator">iota</a> function <code><span class='Value'>⍳</span></code>. Each element in the result is its own <a href="indices.html">index</a>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaVIDYKCuKGlSAy4oC/Mw==">↗️</a><pre> <span class='Function'>↕</span> <span class='Number'>6</span> ⟨ 0 1 2 3 4 5 ⟩ @@ -29,7 +29,7 @@ <span class='Paren'>(</span><span class='Function'>↕</span><span class='Bracket'>⟨</span><span class='Number'>6</span><span class='Bracket'>⟩</span><span class='Paren'>)</span> <span class='Function'>⊑</span> <span class='String'>" pick "</span> " pick " </pre> -<p>They also correspond to Length (<code><span class='Function'>≠</span></code>) and <a href="shape.html">Shape</a> (<code><span class='Function'>≢</span></code>): for an array <code><span class='Value'>a</span></code>, <code><span class='Function'>↕≠</span><span class='Value'>a</span></code> gives the indices of major cells, while <code><span class='Function'>↕≢</span><span class='Value'>a</span></code> gives the indices of all elements.</p> +<p>They also correspond to <a href="shape.html">Length</a> (<code><span class='Function'>≠</span></code>) <a href="shape.html">and Shape</a> (<code><span class='Function'>≢</span></code>): for an array <code><span class='Value'>a</span></code>, <code><span class='Function'>↕≠</span><span class='Value'>a</span></code> gives the indices of major cells, while <code><span class='Function'>↕≢</span><span class='Value'>a</span></code> gives the indices of all elements.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=YSDihpAgNOKAvzLipYpACgrihpUg4omgIGEKCuKGlSDiiaIgYQ==">↗️</a><pre> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊</span><span class='String'>@</span> <span class='Function'>↕</span> <span class='Function'>≠</span> <span class='Value'>a</span> @@ -54,11 +54,11 @@ <span class='Number'>2</span> <span class='Function'>↓</span> <span class='Function'>↕</span><span class='Number'>4</span> ⟨ 2 3 ⟩ </pre> -<p>The result of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code> is a list of length <code><span class='Value'>𝕩</span></code>, but doesn't include <code><span class='Value'>𝕩</span></code> itself. That's just how counting starting at 0 works. It does mean we can create a length-0 list easily:</p> +<p>The result of <code><span class='Function'>↕</span><span class='Value'>𝕩</span></code> is a list of length <code><span class='Value'>𝕩</span></code>, but doesn't include <code><span class='Value'>𝕩</span></code> itself. That's just how counting starting at 0 works (but a nice trick if you do want to include <code><span class='Value'>𝕩</span></code> is <code><span class='Function'>↕</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Value'>𝕩</span></code>). It means we can create a length-0 list easily:</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaVIDA=">↗️</a><pre> <span class='Function'>↕</span> <span class='Number'>0</span> ⟨⟩ </pre> -<p>Like all other results of <code><span class='Function'>↕</span></code> on a number, <code><span class='Function'>↕</span><span class='Number'>0</span></code> has a fill of 0.</p> +<p>As with any other number argument, <code><span class='Function'>↕</span><span class='Number'>0</span></code> has a <a href="fill.html">fill</a> of 0.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NCDihpEg4oaVMAoKNCDihpEg4oaVMw==">↗️</a><pre> <span class='Number'>4</span> <span class='Function'>↑</span> <span class='Function'>↕</span><span class='Number'>0</span> ⟨ 0 0 0 0 ⟩ @@ -72,7 +72,7 @@ <span class='Function'>»</span><span class='Modifier2'>⍟</span><span class='Number'>3</span> <span class='String'>'b'</span><span class='Function'>+↕</span><span class='Number'>8</span> " bcdef" </pre> -<p>One interesting use of Range is to find, at each position in a boolean list, the most recent index that has a 1. To do this, first get the array of indices for <code><span class='Value'>b</span></code>, <code><span class='Function'>↕≠</span><span class='Value'>b</span></code>. Then multiply <code><span class='Value'>b</span></code>, reducing indices where a <code><span class='Number'>0</span></code> is found to 0.</p> +<p>One interesting use of Range is to find, at each position in a boolean list, the most recent index that has a 1. To do this, first get the array of indices for <code><span class='Value'>b</span></code>, <code><span class='Function'>↕≠</span><span class='Value'>b</span></code>. Then multiply by <code><span class='Value'>b</span></code>, reducing indices where a <code><span class='Number'>0</span></code> is found to 0.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGIg4oaQIDDigL8x4oC/MeKAvzDigL8w4oC/MOKAvzHigL8wCgpiIOKJjSDihpXiiaBiCgpiIMOXIOKGleKJoGI=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>b</span> <span class='Gets'>←</span> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</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'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span> ⟨ 0 1 1 0 0 0 1 0 ⟩ @@ -97,7 +97,7 @@ ⟨ 0 2 3 3 3 3 7 7 ⟩ </pre> <h2 id="list-range"><a class="header" href="#list-range">List range</a></h2> -<p>When the argument is a list of numbers, the result is an array of lists.</p> +<p>When <code><span class='Value'>𝕩</span></code> is a list of numbers, the result is an array of lists.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaVIDLigL8z4oC/NA==">↗️</a><pre> <span class='Function'>↕</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span> ┌─ ╎ ⟨ 0 0 0 ⟩ ⟨ 0 0 1 ⟩ ⟨ 0 0 2 ⟩ ⟨ 0 0 3 ⟩ @@ -109,7 +109,7 @@ ⟨ 1 2 0 ⟩ ⟨ 1 2 1 ⟩ ⟨ 1 2 2 ⟩ ⟨ 1 2 3 ⟩ ┘ </pre> -<p>This array, which contains all possible choices of one natural number less than each element of <code><span class='Value'>𝕩</span></code>, can also be produced using Range on numbers only, along with <a href="map.html#table">Table</a> (<code><span class='Modifier'>⌜</span></code>).</p> +<p>This array, which contains all possible choices of a natural number below each element of <code><span class='Value'>𝕩</span></code>, can also be produced using Range on numbers only, along with <a href="map.html#table">Table</a> (<code><span class='Modifier'>⌜</span></code>).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KDzin6jin6kpIOKIvuKMnMK0IOKGlcKoIDLigL8z4oC/NA==">↗️</a><pre> <span class='Paren'>(</span><span class='Function'><</span><span class='Bracket'>⟨⟩</span><span class='Paren'>)</span> <span class='Function'>∾</span><span class='Modifier'>⌜´</span> <span class='Function'>↕</span><span class='Modifier'>¨</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span> ┌─ ╎ ⟨ 0 0 0 ⟩ ⟨ 0 0 1 ⟩ ⟨ 0 0 2 ⟩ ⟨ 0 0 3 ⟩ diff --git a/docs/doc/repeat.html b/docs/doc/repeat.html index b5e4ba06..bf097430 100644 --- a/docs/doc/repeat.html +++ b/docs/doc/repeat.html @@ -12,7 +12,7 @@ <span class='Function'>»</span><span class='Modifier2'>⍟</span><span class='Number'>3</span> <span class='String'>"ABCDE"</span> " AB" </pre> -<p>In mathematics (which unsurpisingly tends to use complicated terms to talk about an easy concept), this kind of repetition is called an <a href="https://en.wikipedia.org/wiki/Iterated_function">iterated function</a> and written with exponential notation. It's related to function composition <code><span class='Modifier2'>∘</span></code> in the same way that exponentiation (<code><span class='Function'>⋆</span></code>) relates to multiplication (<code><span class='Function'>×</span></code>): function iteration is repeated composition.</p> +<p>In mathematics (which unsurpisingly tends to use complicated terms to talk about an easy concept), this kind of repetition is called an <a href="https://en.wikipedia.org/wiki/Iterated_function">iterated function</a> and written with exponential notation. It's related to function <a href="compose.html">composition</a> <code><span class='Modifier2'>∘</span></code> in the same way that exponentiation (<code><span class='Function'>⋆</span></code>) relates to multiplication (<code><span class='Function'>×</span></code>): function iteration is repeated composition.</p> <pre><span class='Value'>n</span><span class='Function'>⋆</span><span class='Number'>4</span> <span class='Gets'>←→</span> <span class='Value'>n</span><span class='Function'>×</span><span class='Value'>n</span><span class='Function'>×</span><span class='Value'>n</span><span class='Function'>×</span><span class='Value'>n</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Number'>4</span> <span class='Gets'>←→</span> <span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Function'>F</span><span class='Modifier2'>∘</span><span class='Function'>F</span> </pre> @@ -25,7 +25,7 @@ <span class='Number'>3</span> <span class='Function'>+</span> <span class='Number'>3</span> <span class='Function'>+</span> <span class='Number'>7</span> 13 </pre> -<p>This kind of composition can't be represented by <code><span class='Modifier2'>∘</span></code> anymore (you'd need a <a href="train.html">train</a>), but it's similar in spirit. <code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code> is always equivalent to <code><span class='Value'>𝕨</span><span class='Modifier2'>⊸</span><span class='Function'>𝔽</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code>, provided <code><span class='Value'>n</span></code> is a constant—not a function, as discussed in the next section.</p> +<p>This kind of composition can't be represented by <code><span class='Modifier2'>∘</span></code> anymore (you'd need a <a href="train.html">train</a>), but it's not much of a leap. <code><span class='Value'>𝕨</span> <span class='Function'>𝔽</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code> is always equivalent to <code><span class='Value'>𝕨</span><span class='Modifier2'>⊸</span><span class='Function'>𝔽</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code>, provided <code><span class='Value'>n</span></code> is a constant—not a function, as discussed in the next section.</p> <h2 id="dynamic-repetition-count"><a class="header" href="#dynamic-repetition-count">Dynamic repetition count</a></h2> <p>In the general case, <code><span class='Function'>𝔾</span></code> is a function, which is applied to all arguments to get the repetition count. That is, the <em>actual</em> count is <code><span class='Value'>𝕨</span><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=4oi+4p+cMeKNn+KKoiA0Cgox4oq4K+KNn+KJoCDihpU0">↗️</a><pre> <span class='Function'>∾</span><span class='Modifier2'>⟜</span><span class='Number'>1</span><span class='Modifier2'>⍟</span><span class='Function'>⊢</span> <span class='Number'>4</span> @@ -43,11 +43,11 @@ </span>⟨ 2 3 3 ⟩ </pre> <h2 id="negative-repetition"><a class="header" href="#negative-repetition">Negative repetition</a></h2> -<p>What does it mean to repeat a function a negative number of times? For a negative integer <code><span class='Function'>-</span><span class='Value'>n</span></code>, BQN defines <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span></code> to be <code><span class='Function'>F</span><span class='Modifier'>⁼</span><span class='Modifier2'>⍟</span><span class='Value'>n</span></code>. In particular, <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Number'>¯1</span></code> simply undoes <code><span class='Function'>F</span></code>.</p> +<p>What does it mean to repeat a function a negative number of times? For a negative integer <code><span class='Function'>-</span><span class='Value'>n</span></code>, BQN defines <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span></code> to be <code><span class='Function'>F</span><span class='Modifier'>⁼</span><span class='Modifier2'>⍟</span><span class='Value'>n</span></code>. In particular, <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Number'>¯1</span></code> simply <a href="undo.html">undoes</a> <code><span class='Function'>F</span></code>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MSDijL3ijZ/CrzEgImFiY2RlIiAgIyBSb3RhdGUgYmFja3dhcmRz">↗️</a><pre> <span class='Number'>1</span> <span class='Function'>⌽</span><span class='Modifier2'>⍟</span><span class='Number'>¯1</span> <span class='String'>"abcde"</span> <span class='Comment'># Rotate backwards </span>"eabcd" </pre> -<p>Because BQN's Undo is a little looser than a strict mathematical inverse, this is an extension of the function inverse written f⁻¹ in mathematics. As a result, it doesn't have all the same properties. For natural numbers, Repeat follows the rule that <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>m</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code> is <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Value'>m</span><span class='Function'>+</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code>. For integers, we have <code><span class='Value'>𝕩</span> <span class='Function'>≡</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code>, but not necessarily <code><span class='Value'>𝕩</span> <span class='Function'>≡</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code>.</p> +<p>Because BQN's Undo is a little looser than a strict mathematical inverse, this is an extension of the function inverse written f⁻¹ in mathematics. As a result, it doesn't have all the same properties. For natural numbers, Repeat follows the rule that <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>m</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code> is <code><span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Value'>m</span><span class='Function'>+</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code>. With a negative, we have <code><span class='Value'>𝕩</span> <span class='Function'>≡</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code>, but not necessarily <code><span class='Value'>𝕩</span> <span class='Function'>≡</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>n</span><span class='Paren'>)</span> <span class='Function'>F</span><span class='Modifier2'>⍟</span><span class='Value'>n</span> <span class='Value'>𝕩</span></code>.</p> <h2 id="array-of-repetition-counts"><a class="header" href="#array-of-repetition-counts">Array of repetition counts</a></h2> <p>The value of <code><span class='Value'>𝕨</span><span class='Function'>𝔾</span><span class='Value'>𝕩</span></code> might also be an array, whose elements are any valid repetition values—integers, or other arrays. Each integer in the nested structure is replaced with the result of repeating <code><span class='Function'>𝔽</span></code> that many times.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MuKKuMOX4o2f4p+oMizin6g0LMKvMiwx4p+p4p+pIDE=">↗️</a><pre> <span class='Number'>2</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Modifier2'>⍟</span><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Number'>¯2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Bracket'>⟩⟩</span> <span class='Number'>1</span> diff --git a/docs/doc/replicate.html b/docs/doc/replicate.html index 31e63228..4387373b 100644 --- a/docs/doc/replicate.html +++ b/docs/doc/replicate.html @@ -88,7 +88,7 @@ <p>The functions Indices and Replicate are used to copy or filter data. They might be described as transforming a <a href="https://en.wikipedia.org/wiki/Run-length_encoding">run-length encoding</a> into unencoded form. On the other hand, Indices might be described as giving a sparse representation of <code><span class='Value'>𝕩</span></code>, which is smaller if <code><span class='Value'>𝕩</span></code> mostly consists of zeros.</p> <p>BQN doesn't have any of the various features used in APL to add fills to the result of Replicate, like negative numbers in <code><span class='Value'>𝕨</span></code> or an Expand (<code><span class='Value'>\</span></code>) primitive. An alternative to Expand is to use Replicate with structural <a href="under.html">Under</a> (<code><span class='Modifier2'>⌾</span></code>) to insert values into an array of fills.</p> <h2 id="replicate"><a class="header" href="#replicate">Replicate</a></h2> -<p>Given a list of natural numbers <code><span class='Value'>𝕨</span></code>, Replicate repeats each major cell in <code><span class='Value'>𝕩</span></code> the corresponding number of times. That is, <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code> must have the same length, and the result includes <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>𝕨</span></code> copies of each cell <code><span class='Value'>i</span><span class='Function'>⊏</span><span class='Value'>𝕩</span></code>, in order.</p> +<p>Given a list of natural numbers <code><span class='Value'>𝕨</span></code>, Replicate repeats each <a href="array.html#cells">major cell</a> in <code><span class='Value'>𝕩</span></code> the corresponding number of times. That is, <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code> must have the same length, and the result includes <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>𝕨</span></code> copies of each cell <code><span class='Value'>i</span><span class='Function'>⊏</span><span class='Value'>𝕩</span></code>, in order.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MuKAvzHigL8w4oC/MiAvICJhYmNkIgoK4oqiIGEg4oaQID4iYWEwIuKAvyJiYjEi4oC/ImNjMiLigL8iZGQzIgoKMuKAvzHigL8w4oC/MiAvIGE=">↗️</a><pre> <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='Ligature'>‿</span><span class='Number'>2</span> <span class='Function'>/</span> <span class='String'>"abcd"</span> "aabdd" @@ -124,7 +124,7 @@ "fie" </pre> <p>Here <code><span class='Function'>≤</span><span class='Modifier2'>⟜</span><span class='String'>'i'</span></code> is a pervasive function, so there's no need to add <code><span class='Modifier'>¨</span></code>. Similarly, to filter major cells of an array, <code><span class='Function'>Fn</span><span class='Modifier'>˘</span><span class='Modifier2'>⊸</span><span class='Function'>/</span></code> could be used, applying <code><span class='Function'>Fn</span></code> to one major cell at a time.</p> -<p>A similar pattern applies to Replicate as well. The function below tests which input characters are double quotes, but by adding one it changes the result to 1 for each non-quote character and 2 for quotes (but source code and display also double quotes here, so the input string has only two <code><span class='String'>"</span></code>s and the output has four).</p> +<p>This idea extends to Replicate as well. The function below tests which input characters are double quotes, but by adding one it changes the result to 1 for each non-quote character and 2 for quotes (but source code and display also double quotes here, so the input string has only two <code><span class='String'>"</span></code>s and the output has four).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ezErJyInPfCdlal94oq4LyAiZm9yICIiZXNjYXBpbmciIiBxdW90ZXMi">↗️</a><pre> <span class='Brace'>{</span><span class='Number'>1</span><span class='Function'>+</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'>"for ""escaping"" quotes"</span> "for """"escaping"""" quotes" </pre> @@ -173,7 +173,7 @@ 1 </pre> <h2 id="indices"><a class="header" href="#indices">Indices</a></h2> -<p>The monadic form of <code><span class='Function'>/</span></code> is much simpler than the dyadic one, with no multidimensional case or mismatched argument ranks. <code><span class='Value'>𝕩</span></code> must be a list of natural numbers, and <code><span class='Function'>/</span><span class='Value'>𝕩</span></code> is the list <code><span class='Value'>𝕩</span><span class='Function'>/↕≠</span><span class='Value'>𝕩</span></code>. Its elements are the <a href="indices.html">indices</a> for <code><span class='Value'>𝕩</span></code>, with index <code><span class='Value'>i</span></code> repeated <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>𝕩</span></code> times.</p> +<p>The monadic form of <code><span class='Function'>/</span></code> is much simpler than the dyadic one, with no multidimensional case or mismatched argument ranks. <code><span class='Value'>𝕩</span></code> has to be a list of natural numbers, and <code><span class='Function'>/</span><span class='Value'>𝕩</span></code> is the list <code><span class='Value'>𝕩</span><span class='Function'>/↕≠</span><span class='Value'>𝕩</span></code>. Its elements are the <a href="indices.html">indices</a> for <code><span class='Value'>𝕩</span></code>, with index <code><span class='Value'>i</span></code> repeated <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>𝕩</span></code> times.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=LyAz4oC/MOKAvzHigL8y">↗️</a><pre> <span class='Function'>/</span> <span class='Number'>3</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'>2</span> ⟨ 0 0 0 2 3 3 ⟩ </pre> @@ -211,7 +211,7 @@ 8 2 ┘ </pre> -<p>This means the transitions can be grouped exactly in pairs, the beginning and end of each group. Reshape with a <a href="reshape.html#computed-lengths">computed length</a> <code><span class='Modifier2'>∘</span><span class='Ligature'>‿</span><span class='Number'>2</span></code> groups these pairs, and then a scan <code><span class='Function'>-</span><span class='Modifier'>˜`˘</span></code> can be used to convert the start/end format to start/length if wanted.</p> +<p>This means the transitions can be grouped exactly in pairs, the beginning and end of each group. Reshape with a <a href="reshape.html#computed-lengths">computed length</a> <code><span class='Modifier2'>∘</span><span class='Ligature'>‿</span><span class='Number'>2</span></code> groups these pairs, and then a <a href="scan.html">scan</a> <code><span class='Function'>-</span><span class='Modifier'>˜`˘</span></code> can be used to convert the start/end format to start/length if wanted.</p> <h3 id="inverse"><a class="header" href="#inverse">Inverse</a></h3> <p>The result of Indices <code><span class='Function'>/</span><span class='Value'>n</span></code> is an ordered list of natural numbers, where the number <code><span class='Value'>i</span></code> appears <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>n</span></code> times. Given an ordered list of natural numbers <code><span class='Value'>k</span></code>, the <a href="undo.html"><em>inverse</em></a> of indices returns a corresponding <code><span class='Value'>n</span></code>: one where the value <code><span class='Value'>i</span><span class='Function'>⊑</span><span class='Value'>n</span></code> is the number of times <code><span class='Value'>i</span></code> appears in <code><span class='Value'>k</span></code>.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=LyAz4oC/MuKAvzEKCi/igbwgMOKAvzDigL8w4oC/MeKAvzHigL8y">↗️</a><pre> <span class='Function'>/</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span> diff --git a/docs/doc/reshape.html b/docs/doc/reshape.html index 963d03a3..68537bf0 100644 --- a/docs/doc/reshape.html +++ b/docs/doc/reshape.html @@ -58,8 +58,8 @@ </g> </svg> -<p>The glyph <code><span class='Function'>⥊</span></code> indicates BQN's facilities to reflow the data in an array, giving it a different shape. Its monadic form, Deshape, simply removes all shape information, returning a list of all the elements from the array in reading order. With a left argument, <code><span class='Function'>⥊</span></code> is called Reshape and is a more versatile tool for rearranging the data in an array into the desired shape.</p> -<p>Because of its dependence on the reading order of an array, Reshape is less fundamental than other array operations. Using Reshape in the central computations of a program can be a sign of imperfect usage of arrays. For example, it may be useful to use Reshape to create a constant array or repeat a sequence of values several times, but the same task might also be accomplished more simply with <a href="map.html#table">Table</a> <code><span class='Modifier'>⌜</span></code>, or by taking advantage of <a href="leading.html#leading-axis-agreement">leading axis agreement</a> in arithmetic primitives.</p> +<p>The glyph <code><span class='Function'>⥊</span></code> indicates BQN's facilities to reflow the data in an array, giving it a different shape. Its monadic form, Deshape, simply removes all shape information, returning a list of all the elements from the array in index order. With a left argument, <code><span class='Function'>⥊</span></code> is called Reshape and is a more versatile tool for rearranging the data in an array into the desired shape.</p> +<p>Because of its dependence on the index order of an array, Reshape is less fundamental than other array operations. Using Reshape in the central computations of a program can be a sign of imperfect usage of arrays. For example, it may be useful to use Reshape to create a constant array or repeat a sequence of values several times, but the same task might also be accomplished more simply with <a href="map.html#table">Table</a> <code><span class='Modifier'>⌜</span></code>, or by taking advantage of <a href="leading.html#leading-axis-agreement">leading axis agreement</a> in arithmetic primitives.</p> <h2 id="deshape"><a class="header" href="#deshape">Deshape</a></h2> <p>The result of Deshape is a list containing the same elements as the argument.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICvijJzCtCDin6gxMDDigL8yMDAsIDMw4oC/NDAsIDXigL824oC/N+KfqQoK4qWKIGE=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Function'>+</span><span class='Modifier'>⌜´</span> <span class='Bracket'>⟨</span><span class='Number'>100</span><span class='Ligature'>‿</span><span class='Number'>200</span><span class='Separator'>,</span> <span class='Number'>30</span><span class='Ligature'>‿</span><span class='Number'>40</span><span class='Separator'>,</span> <span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Bracket'>⟩</span> @@ -74,7 +74,7 @@ <span class='Function'>⥊</span> <span class='Value'>a</span> ⟨ 135 136 137 145 146 147 235 236 237 245 246 247 ⟩ </pre> -<p>The elements are ordered in reading order—left to right, then top to bottom. This means that leading axes "matter more" for ordering: if one element comes earlier in the first axis but later in the second than some other element, it will come first in the result. In another view, elements are ordered according to their <a href="indices.html">indices</a>. In other words, deshaping the array of indices for an array will always give a <a href="order.html">sorted</a> array.</p> +<p>The elements are ordered in reading order—left to right, then top to bottom. This means that leading axes "matter more" for ordering: if one element comes earlier in the first axis but later in the second than some other element, it will come first in the result. In another view, elements are ordered according to their <a href="indices.html">indices</a>, leading to the name <em>index order</em> for this ordering. To be precise, deshaping the array of indices for an array always gives a <a href="order.html">sorted</a> array.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaV4omiYQoK4o2LIOKliiDihpXiiaJh">↗️</a><pre> <span class='Function'>↕≢</span><span class='Value'>a</span> ┌─ ╎ ⟨ 0 0 0 ⟩ ⟨ 0 0 1 ⟩ ⟨ 0 0 2 ⟩ @@ -87,8 +87,8 @@ <span class='Function'>⍋</span> <span class='Function'>⥊</span> <span class='Function'>↕≢</span><span class='Value'>a</span> ⟨ 0 1 2 3 4 5 6 7 8 9 10 11 ⟩ </pre> -<p>This ordering is also known as <em>row-major</em> order.</p> -<p>Deshape turns a unit argument into a single-element list, automatically <a href="enclose.html">enclosing</a> it if it's an atom. However, if you know <code><span class='Value'>𝕩</span></code> is a unit, a more principled way to turn it into a list is to apply <a href="couple.html">Solo</a> (<code><span class='Function'>≍</span></code>), which adds a length-1 axis before any other axes. If you ever add axes to the data format, Solo is more likely to continue working after this transition, unless there's a reason the result should always be a list.</p> +<p>This ordering is also known as <em>row-major</em> order in computing.</p> +<p>Deshape turns a unit argument into a single-element list, automatically enclosing it if it's an atom. However, if you know <code><span class='Value'>𝕩</span></code> is a unit, a more principled way to turn it into a list is to apply <a href="couple.html">Solo</a> (<code><span class='Function'>≍</span></code>), which adds a length-1 axis before any other axes. If you ever add axes to the data format, Solo is more likely to continue working after this transition, unless there's a reason the result should always be a list.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4qWKIDIK4omNIDI=">↗️</a><pre> <span class='Function'>⥊</span> <span class='Number'>2</span> ⟨ 2 ⟩ <span class='Function'>≍</span> <span class='Number'>2</span> @@ -121,7 +121,7 @@ <span class='Paren'>(</span><span class='Function'>⥊</span><span class='Value'>a</span><span class='Paren'>)</span> <span class='Function'>≡</span> <span class='Function'>⥊</span> <span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊</span><span class='Value'>a</span> 1 </pre> -<p>One common use is to generate an array with a specified shape that counts up from 0 in reading order, a reshaped <a href="range.html">Range</a>. The idiomatic phrase to do this is <code><span class='Function'>⥊</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Function'>↕×</span><span class='Modifier'>´</span><span class='Paren'>)</span></code>, since it doesn't require writing the shape and its product separately.</p> +<p>One use is to generate an array with a specified shape that counts up from 0 in index order, a reshaped <a href="range.html">Range</a>. The idiomatic phrase to do this is <code><span class='Function'>⥊</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Function'>↕×</span><span class='Modifier'>´</span><span class='Paren'>)</span></code>, since it doesn't require writing the shape and its product separately.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MuKAvzcg4qWKIOKGlTE0CuKliuKfnCjihpXDl8K0KSAy4oC/Nw==">↗️</a><pre> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>7</span> <span class='Function'>⥊</span> <span class='Function'>↕</span><span class='Number'>14</span> ┌─ ╵ 0 1 2 3 4 5 6 @@ -171,12 +171,12 @@ uU" ┘ </pre> -<p>Above, the length given is <code><span class='Modifier2'>∘</span></code>, a special value that indicates that a length that fits the argument should be computed. In fact, Reshape has four different special values that can be used. Every one works the same for a case like the one above, where the rest of the shape divides the argument length evenly. They differ in how they handle uneven cases, where the required length would fall between two whole numbers.</p> +<p>Above, the length given is <code><span class='Modifier2'>∘</span></code>, a special value that indicates that a length fitting the argument should be computed. Reshape has four such special values that can be used. Every one works the same for a case like the one above, where the rest of the shape divides the argument length evenly. They differ in how they handle uneven cases, where the required length falls between two whole numbers.</p> <ul> <li><code><span class='Modifier2'>∘</span></code> says the length must be an exact fit, and gives an error in such a case.</li> <li><code><span class='Function'>⌊</span></code> rounds the length down, so that some elements are discarded.</li> <li><code><span class='Function'>⌽</span></code> rounds the length up, repeating elements to make up the difference.</li> -<li><code><span class='Function'>↑</span></code> rounds the length up, but uses the argument's fill for the needed extra elements.</li> +<li><code><span class='Function'>↑</span></code> rounds the length up, but uses the argument's <a href="fill.html">fill</a> for the needed extra elements.</li> </ul> <p>These values are just BQN primitives of course. They're not called by Reshape or anything like that; the primitives are just chosen to suggest the corresponding functionality.</p> <p>Here's an example of the four cases. If we try to turn five elements into two rows, <code><span class='Modifier2'>∘</span></code> gives an error, <code><span class='Function'>⌊</span></code> drops the last element, <code><span class='Function'>⌽</span></code> uses the first element again, and <code><span class='Function'>↑</span></code> uses a fill element (like <code><span class='Number'>6</span><span class='Function'>↑</span><span class='String'>"abcde"</span></code> would).</p> @@ -201,7 +201,7 @@ de " ┘ </pre> -<p>A computed length can be useful to input an array without using nested notation: for example, if you have a table with rows of three elements, you might write it as one long list, using <code><span class='Modifier2'>∘</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Function'>⥊</span><span class='Bracket'>⟨</span><span class='Value'>…</span><span class='Bracket'>⟩</span></code> to get it back to the appropriate shape. <code><span class='Modifier2'>∘</span></code> is definitely the value to use here, as it will check that you haven't missed an element or something like that.</p> +<p>A computed length can be useful to input an array without using nested <a href="arrayrepr.html#brackets">notation</a>: for example, if you have a table with rows of three elements, you might write it as one long list, using <code><span class='Modifier2'>∘</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Function'>⥊</span><span class='Bracket'>⟨</span><span class='Value'>…</span><span class='Bracket'>⟩</span></code> to get it back to the appropriate shape. <code><span class='Modifier2'>∘</span></code> is definitely the value to use here, as it will check that you haven't missed or added an element.</p> <p>Computed Reshape might also be used in actual data processing: for example, to sum a list in groups of four, you might first reshape it using <code><span class='Function'>↑</span><span class='Ligature'>‿</span><span class='Number'>4</span></code> for the shape, then average the rows. Here the code <code><span class='Function'>↑</span></code> is useful because added fill elements of <code><span class='Number'>0</span></code> won't change the sum, so that if the last group doesn't have four elements (<code><span class='Number'>9</span><span class='Ligature'>‿</span><span class='Number'>7</span></code> below), it will still be summed correctly.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0y5gg4oaR4oC/NCDipYog4p+oMCwyLDEsMSwgNSw5LDYsNCwgMywzLDMsMywgOSw34p+p">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´˘</span> <span class='Function'>↑</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Function'>⥊</span> <span class='Bracket'>⟨</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>5</span><span class='Separator'>,</span><span class='Number'>9</span><span class='Separator'>,</span><span class='Number'>6</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span> <span class='Number'>9</span><span class='Separator'>,</span><span class='Number'>7</span><span class='Bracket'>⟩</span> ⟨ 4 24 12 16 ⟩ diff --git a/docs/doc/reverse.html b/docs/doc/reverse.html index c90f22f2..cd984689 100644 --- a/docs/doc/reverse.html +++ b/docs/doc/reverse.html @@ -5,10 +5,10 @@ </head> <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="reverse-and-rotate"><a class="header" href="#reverse-and-rotate">Reverse and Rotate</a></h1> -<p>The symbol <code><span class='Function'>⌽</span></code> indicates two different array transformations: with no left argument, it reverses the major cells of the array, but with a left argument, it rotates or cycles them around. These two possibilities, first put together in very early versions of APL, can't be considered restrictions or different views of some unifying function, but there are connections between them. Each returns an array with the same <a href="shape.html">shape</a> and all the same elements as <code><span class='Value'>𝕩</span></code>, possibly in a different arrangement. And elements that start out next to each other in <code><span class='Value'>𝕩</span></code> generally stay next to each other—always, if we consider an element on one edge to be next to the one opposite to it. One might think of them as <a href="https://en.wikipedia.org/wiki/Isometry">isometries</a> preserving a discrete subgroup of the torus, if one were inclined to think such things. On major cells, the two functions decompose the <a href="https://en.wikipedia.org/wiki/Dihedral_group">dihedral group</a> okay I'll stop.</p> -<p>Many uses of Rotate in APL are better handled by <a href="shift.html">shift</a> functions in BQN. If there's no reason to treat the data as cyclic or periodic, it's best to avoid Rotate.</p> +<p>The symbol <code><span class='Function'>⌽</span></code> indicates two different array transformations: with no left argument, it reverses the <a href="array.html#cells">major cells</a> of the array, but with a left argument, it rotates or cycles them around. These two possibilities, first put together in very early versions of APL, can't be considered restrictions or different views of some unifying function, but there are connections between them. Each returns an array with the same <a href="shape.html">shape</a> and all the same elements as <code><span class='Value'>𝕩</span></code>, possibly in a different arrangement. And elements that start out next to each other in <code><span class='Value'>𝕩</span></code> generally stay next to each other—always, if we consider an element on one edge to be next to the one opposite to it. One might think of them as <a href="https://en.wikipedia.org/wiki/Isometry">isometries</a> preserving a discrete subgroup of the torus, if one were inclined to think such things. On major cells, the two functions decompose the <a href="https://en.wikipedia.org/wiki/Dihedral_group">dihedral group</a> okay I'll stop.</p> +<p>If there's no reason the data should be seen as cyclic or periodic, it's best to avoid Rotate: <a href="shift.html">shift</a> functions are probably more appropriate.</p> <h2 id="reverse"><a class="header" href="#reverse">Reverse</a></h2> -<p>There's not too much to say about Reverse. It puts the elements of a list the other way around, or more generally the major cells of an array.</p> +<p>Reverse doesn't make things complicated. It puts the elements of a list the other way around, or more generally the major cells of an array.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy9ICJhYmNkZWZnIgoK4oy9ID4iYWIi4oC/ImNkIuKAvyJlZiIKCuKMvSAnYyc=">↗️</a><pre> <span class='Function'>⌽</span> <span class='String'>"abcdefg"</span> "gfedcba" @@ -23,7 +23,7 @@ <span class='Error'>Error: ⌽: Argument cannot be a unit</span> </pre> <p>You can't reverse an atom or rank-0 array because it has no axes to reverse along, or it could be said no ordering to reverse.</p> -<p>To reverse along an axis other than the first, use Cells (<code><span class='Modifier'>˘</span></code>) or Rank (<code><span class='Modifier2'>⎉</span></code>).</p> +<p>To reverse along an axis other than the first, use <a href="rank.html#cells">Cells</a> (<code><span class='Modifier'>˘</span></code>) or <a href="rank.html#rank">Rank</a> (<code><span class='Modifier2'>⎉</span></code>).</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy9y5ggPiJhYiLigL8iY2Qi4oC/ImVmIg==">↗️</a><pre> <span class='Function'>⌽</span><span class='Modifier'>˘</span> <span class='Function'>></span><span class='String'>"ab"</span><span class='Ligature'>‿</span><span class='String'>"cd"</span><span class='Ligature'>‿</span><span class='String'>"ef"</span> ┌─ ╵"ba @@ -38,7 +38,7 @@ <span class='Function'>⋈</span><span class='Modifier'>˜´</span> <span class='Function'>⌽</span> <span class='String'>"abcd"</span> <span class='Comment'># Left to right </span>⟨ ⟨ "ab" 'c' ⟩ 'd' ⟩ </pre> -<p>Reverse is its own <a href="undo.html">inverse</a> <code><span class='Function'>⌽</span><span class='Modifier'>⁼</span></code>. As a result, <code><span class='Function'>𝔽</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span></code> reverses the argument, applies <code><span class='Function'>𝔽</span></code>, and reverses again. It's a particularly useful pattern with <a href="scan.html">Scan</a>, as it allows scanning from the end rather than the beginning of the array. For example, <code><span class='Function'>∨</span><span class='Modifier'>`</span></code> on a list of booleans changes all bits after the first <code><span class='Number'>1</span></code> to <code><span class='Number'>1</span></code>, but <code><span class='Function'>∨</span><span class='Modifier'>`</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span></code> does this to all bits before the last <code><span class='Number'>1</span></code>.</p> +<p>Reverse is its own <a href="undo.html">inverse</a> <code><span class='Function'>⌽</span><span class='Modifier'>⁼</span></code>. So with <a href="under.html">Under</a>, <code><span class='Function'>𝔽</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span></code> reverses the argument, applies <code><span class='Function'>𝔽</span></code>, and reverses again. It's a particularly useful pattern with <a href="scan.html">Scan</a>, as it allows scanning from the end rather than the beginning of the array. For example, <code><span class='Function'>∨</span><span class='Modifier'>`</span></code> on a list of booleans changes all bits after the first <code><span class='Number'>1</span></code> to <code><span class='Number'>1</span></code>, but <code><span class='Function'>∨</span><span class='Modifier'>`</span><span class='Modifier2'>⌾</span><span class='Function'>⌽</span></code> does this to all bits before the last <code><span class='Number'>1</span></code>.</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 ⟩ @@ -74,7 +74,7 @@ "terota" </pre> <h3 id="multiple-axes"><a class="header" href="#multiple-axes">Multiple axes</a></h3> -<p>The easiest way to rotate a later array axis is usually to use the Cells (<code><span class='Modifier'>˘</span></code>) or Rank (<code><span class='Modifier2'>⎉</span></code>) modifier.</p> +<p>The easiest way to rotate along a later array axis is usually to use the <a href="rank.html#cells">Cells</a> (<code><span class='Modifier'>˘</span></code>) or <a href="rank.html#rank">Rank</a> (<code><span class='Modifier2'>⎉</span></code>) modifier.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIHRhYiDihpAgM+KAvzTipYoiYWJjZEFCQ0QwMTIzIgoKMSDijL3LmCB0YWIgICMgUm90YXRlIHRoZSBzZWNvbmQgYXhpcw==">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>tab</span> <span class='Gets'>←</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Function'>⥊</span><span class='String'>"abcdABCD0123"</span> ┌─ ╵"abcd @@ -89,7 +89,7 @@ 1230" ┘ </pre> -<p>Rotate also allows <code><span class='Value'>𝕨</span></code> to be a list (or unit array) of integers, in which case they're matched with <a href="leading.html">leading axes</a> of <code><span class='Value'>𝕩</span></code>. This means the length of <code><span class='Value'>𝕨</span></code> can't be larger than the rank of <code><span class='Value'>𝕩</span></code>, or there wouldn't be enough axes to match. This rule also explains why <code><span class='Value'>𝕩</span></code> has to have rank one or more when <code><span class='Value'>𝕨</span></code> is an atom, because <code><span class='Value'>𝕨</span></code> is treated as the one-element list <code><span class='Function'>⥊</span><span class='Value'>𝕨</span></code> in that case.</p> +<p>Rotate also allows <code><span class='Value'>𝕨</span></code> to be a list (or unit array) of integers, in which case they're matched with <a href="leading.html">leading axes</a> of <code><span class='Value'>𝕩</span></code>. This means the length of <code><span class='Value'>𝕨</span></code> can't be larger than the rank of <code><span class='Value'>𝕩</span></code>, or there wouldn't be enough axes to match. This rule that <code><span class='Value'>𝕩</span></code> has to have rank one or more when <code><span class='Value'>𝕨</span></code> is an atom is a special case, because then <code><span class='Value'>𝕨</span></code> is treated as the one-element list <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=M+KAvzTigL8yIOKMvSAianVzdCBhIGxpc3Qi">↗️</a><pre> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Function'>⌽</span> <span class='String'>"just a list"</span> <span class='Error'>Error: 𝕨⌽𝕩: Length of compound 𝕨 must be at most rank of 𝕩</span> </pre> @@ -101,7 +101,7 @@ cdab" ┘ </pre> -<p>The vertical and horizontal rotations are independent, and could also be done with two <code><span class='Function'>⌽</span></code>s and a <code><span class='Modifier'>˘</span></code>. The multi-axis form is more convenient, and can potentially be evaluated faster that multiple separate rotations in the cases where it shows up.</p> +<p>The vertical and horizontal rotations are independent, and could also be done with two <code><span class='Function'>⌽</span></code>s and a <code><span class='Modifier'>˘</span></code>. The multi-axis form is more convenient, and can potentially be evaluated faster than multiple separate rotations in the cases where it shows up.</p> <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MSDijL0gMiDijL3LmCB0YWI=">↗️</a><pre> <span class='Number'>1</span> <span class='Function'>⌽</span> <span class='Number'>2</span> <span class='Function'>⌽</span><span class='Modifier'>˘</span> <span class='Value'>tab</span> ┌─ ╵"CDAB |