aboutsummaryrefslogtreecommitdiff
path: root/docs/doc/leading.html
diff options
context:
space:
mode:
authorMarshall Lochbaum <mwlochbaum@gmail.com>2021-08-11 17:21:31 -0400
committerMarshall Lochbaum <mwlochbaum@gmail.com>2021-08-11 17:25:04 -0400
commit2afb23928e1984d475cc460e1672e8f6fa0e4dbe (patch)
treeebd2cc514294d30b6fa4b36c2ee638326f06ef72 /docs/doc/leading.html
parenteac61ca02074c218667754d5f4ef562e780bae85 (diff)
Allow clicking on header to get fragment link
Diffstat (limited to 'docs/doc/leading.html')
-rw-r--r--docs/doc/leading.html18
1 files changed, 9 insertions, 9 deletions
diff --git a/docs/doc/leading.html b/docs/doc/leading.html
index ac7d2d49..55b72a40 100644
--- a/docs/doc/leading.html
+++ b/docs/doc/leading.html
@@ -4,10 +4,10 @@
<title>BQN: The leading axis convention</title>
</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="the-leading-axis-convention">The leading axis convention</h1>
+<h1 id="the-leading-axis-convention"><a class="header" href="#the-leading-axis-convention">The leading axis convention</a></h1>
<p>Several primitive functions manipulate the right argument, or sometimes both arguments, of an <a href="array.html">array</a> along one or more axes. According to the <a href="https://aplwiki.com/wiki/Leading_axis_theory">leading axis model</a>, it's best to make the primitives operate on initial axes, because the Rank modifier then allows it to apply to later axes as well. Here we'll see how this pattern works in BQN.</p>
-<h2 id="monadic-functions">Monadic functions</h2>
-<h3 id="manipulating-cells">Manipulating cells</h3>
+<h2 id="monadic-functions"><a class="header" href="#monadic-functions">Monadic functions</a></h2>
+<h3 id="manipulating-cells"><a class="header" href="#manipulating-cells">Manipulating cells</a></h3>
<p>Most non-arithmetic monadic functions work only on the first axis of the argument—that is, they treat it as a list of its major cells. The function <a href="shape.html">Length</a> (<code><span class='Function'>≠</span></code>) counts these major cells, while <a href="prefixes.html">Prefixes</a> (<code><span class='Function'>↑</span></code>), Suffixes (<code><span class='Function'>↓</span></code>), <a href="reverse.html">Reverse</a> (<code><span class='Function'>⌽</span></code>), and <a href="select.html">First Cell</a> (<code><span class='Function'>⊏</span></code>) move them around. The <a href="fold.html#insert">Insert</a> (<code><span class='Modifier'>˝</span></code>) and <a href="scan.html">Scan</a> (<code><span class='Modifier'>`</span></code>) modifiers also yield functions that work along the first axis; in contrast, <a href="fold.html">Fold</a> (<code><span class='Modifier'>´</span></code>) requires <code><span class='Value'>𝕩</span></code> to be a list, as it works on elements.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQIDPigL8yIOKliiAiYWJjZGVmIiAgIyBBbiBhcnJheSB3aXRoIHRocmVlIG1ham9yIGNlbGxzCuKKjyBhICAgICAgICAgICAgICAgICAgICMgR2V0IHRoZSBmaXJzdCBtYWpvciBjZWxsCuKMvSBhICAgICAgICAgICAgICAgICAgICMgUmV2ZXJzZSB0aGUgY2VsbHMK4oqjYCBhICAgICAgICAgICAgICAgICAgIyBSZXBsaWNhdGUgdGhlIGZpcnN0IGNlbGw=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Function'>⥊</span> <span class='String'>&quot;abcdef&quot;</span> <span class='Comment'># An array with three major cells
</span>┌─
@@ -80,7 +80,7 @@
<span class='Function'>≢</span> <span class='Function'>≍</span><span class='Modifier2'>⎉</span><span class='Number'>0</span> <span class='Value'>a</span> <span class='Comment'># …or deeper still.
</span>⟨ 3 2 1 ⟩
</pre>
-<h3 id="comparing-cells">Comparing cells</h3>
+<h3 id="comparing-cells"><a class="header" href="#comparing-cells">Comparing cells</a></h3>
<p>The functions in the last section manipulate cells in the same way regardless of what data they contain. Other functions compare cells to each other, either testing whether they match or how they are ordered relative to one another. The two <a href="order.html">Grade</a> functions <code><span class='Function'>⍋⍒</span></code>, and the <a href="selfcmp.html">self-search</a> functions Classify (<code><span class='Function'>⊐</span></code>), Mark Firsts (<code><span class='Function'>∊</span></code>), and Occurrence Count (<code><span class='Function'>⊒</span></code>), each give a list result, with one number for each cell. We can see below that Occurrence Count returns the same results even as we make the argument cells more complicated, because the changes made preserve the matching of cells.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=cyDihpAgImFicmFjYWRhYnJhIgriipIgcwriipIg4omNy5ggcwriipIgcyDiiL7ijokw4oC/MSAic3VmZml4Ig==">↗️</a><pre> <span class='Value'>s</span> <span class='Gets'>←</span> <span class='String'>&quot;abracadabra&quot;</span>
<span class='Function'>⊒</span> <span class='Value'>s</span>
@@ -106,13 +106,13 @@
3 3 2 1 0
</pre>
-<h3 id="other-monadic-functions">Other monadic functions</h3>
+<h3 id="other-monadic-functions"><a class="header" href="#other-monadic-functions">Other monadic functions</a></h3>
<p>Not all functions work on the first axis in a straightforward manner. <a href="transpose.html">Transpose</a> <code><span class='Function'>⍉</span></code> moves the first axis to the end, so while it focuses on the first one, it shifts every axis of <code><span class='Value'>𝕩</span></code>. <a href="join.html">Join</a> <code><span class='Function'>∾</span></code> also works on every axis of its argument, and applies to the leading axes of <code><span class='Value'>𝕩</span></code>'s <em>elements</em> instead: these leading inner axes are matched up with the outer axes, and trailing inner axes are allowed but the elements must have rank at least as high as the argument array.</p>
<p>The other two monadic functions that work on high-rank arguments are <a href="reshape.html#deshape">Deshape</a> (<code><span class='Function'>⥊</span></code>) and <a href="pick.html#first">First</a> (<code><span class='Function'>⊑</span></code>). These treat <code><span class='Value'>𝕩</span></code> as one long list, ordered by its element indices. This ordering privileges leading axes (in fact, it is the reason for the choice of leading axes in the leading axis convention), but these functions can't really be said to work on leading axes: they apply to all axes.</p>
<p>The <a href="map.html">Each</a> (<code><span class='Modifier'>¨</span></code>) and <a href="map.html#table">Table</a> (<code><span class='Modifier'>⌜</span></code>) modifiers return functions which are the same in the monadic case. These functions simply go through all elements of the argument array without regard for its multi-dimensional structure (the operand is applied to elements in index order, matching Deshape; this matters if it has side effects). Similarly, monadic arithmetic functions do not have any sort of leading axis dependence.</p>
-<h2 id="dyadic-functions">Dyadic functions</h2>
+<h2 id="dyadic-functions"><a class="header" href="#dyadic-functions">Dyadic functions</a></h2>
<p>For dyadic functions the pattern of working on only one argument axis is not so common. Only two functions can be said to follow it roughly: <a href="join.html">Join to</a> (<code><span class='Function'>∾</span></code>) combines two arrays along one axis, using the first axis of both arguments if they have the same rank and of the higher-rank argument if they differ by one. <a href="couple.html">Couple</a> (<code><span class='Function'>≍</span></code>), like Solo, does not manipulate the argument axes but adds a result axis. There are also some functions that can't be limited to leading axes: <a href="reshape.html">Reshape</a> (<code><span class='Function'>⥊</span></code>) treats <code><span class='Value'>𝕩</span></code> as one long list, and <a href="pick.html">Pick</a> (<code><span class='Function'>⊑</span></code>) requires each index to be as long as <code><span class='Value'>𝕩</span></code>'s rank, because it selects elements and not cells from <code><span class='Value'>𝕩</span></code>.</p>
-<h3 id="multiple-axes">Multiple axes</h3>
+<h3 id="multiple-axes"><a class="header" href="#multiple-axes">Multiple axes</a></h3>
<p>Instead of always working on a single axis, many dyadic functions work on one axis by default, but also allow a left argument with multiple elements corresponding to leading axes of <code><span class='Value'>𝕩</span></code>. To decide which of the two possibilities applies, these functions test the depth of <code><span class='Value'>𝕨</span></code>, a convention that is discussed in the <a href="depth.html#testing-depth-for-multiple-axis-primitives">depth</a> documentation. A left argument that applies to one axis has a particular depth; <code><span class='Value'>𝕨</span></code> can also be a list of such arguments.</p>
<table>
<thead>
@@ -145,7 +145,7 @@
⟨ 4 5 7 7 ⟩
</pre>
<p>Functions with single-axis depth 1 tend to be more complicated; see for example <a href="group.html#multidimensional-grouping">Group</a>.</p>
-<h3 id="leading-axis-agreement">Leading axis agreement</h3>
+<h3 id="leading-axis-agreement"><a class="header" href="#leading-axis-agreement">Leading axis agreement</a></h3>
<p><a href="arithmetic.html">Arithmetic</a> functions, and the <a href="map.html#each">Each</a> (<code><span class='Modifier'>¨</span></code>) and <a href="depth.html#the-depth-modifier">Depth</a> (<code><span class='Modifier2'>⚇</span></code>) modifiers, use leading axis agreement to match their arguments together. All axes of the lower-rank argument are matched with the leading axes of the higher-rank one, and axes matched together must have the same length. After pairing axes in this way, a single element of the lower-rank argument might correspond to any number of elements of the higher-rank one. It's reused for each of those corresponding elements.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIHgg4oaQIDPigL8y4oC/NCDipYog4oaVNjAgICAgICMgQSByYW5rLTMgYXJyYXkKMTAw4oC/MOKAvzIwMCArIHggICAgICAgICAjIDAtY2VsbHMgcGFpcmVkIHdpdGggMi1jZWxscwriiqIgYyDihpAgMTAwIMOXIDMgPeKMnOKXi+KGlSAyICAjIEEgcmFuay0yIGFycmF5IHRvIGFkZApjICsgeCAgICAgICAgICAgICAgICAgIyAwLWNlbGxzIHBhaXJlZCB3aXRoIDEtY2VsbHMKeCArIHggICAgICAgICAgICAgICAgICMgUGFpcndpc2UgYWRkaXRpb24=">↗️</a><pre> <span class='Function'>⊢</span> <span class='Value'>x</span> <span class='Gets'>←</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Function'>⥊</span> <span class='Function'>↕</span><span class='Number'>60</span> <span class='Comment'># A rank-3 array
</span>┌─
@@ -200,7 +200,7 @@
</pre>
<p>If one argument is a unit, that is, it has no axes, then leading axis agreement reduces to APL's &quot;scalar extension&quot; (where &quot;scalar&quot; is equivalent to BQN's &quot;unit&quot;), where a single unit is matched with an entire array by repeating it at every application. A unit always agrees with any other array under leading axis agreement because it has no axes whose lengths would need to be checked.</p>
<p>With leading axis agreement, there are <code><span class='Value'>k</span><span class='Function'>+</span><span class='Number'>1</span></code> shapes for arrays that can be added (or any other function with Each) to a given array <code><span class='Value'>x</span></code> without changing its rank. These are precisely the prefixes of <code><span class='Function'>≢</span><span class='Value'>x</span></code>, with ranks from <code><span class='Number'>0</span></code> to <code><span class='Value'>k</span></code> inclusive. Arrays with larger rank can also be used as the other argument, but then the result shape will match that argument and not <code><span class='Value'>x</span></code>.</p>
-<h3 id="search-functions">Search functions</h3>
+<h3 id="search-functions"><a class="header" href="#search-functions">Search functions</a></h3>
<p>The <a href="search.html">search functions</a>, Index of (<code><span class='Function'>⊐</span></code>), Progressive Index of (<code><span class='Function'>⊒</span></code>), and Member of (<code><span class='Function'>∊</span></code>), and also <a href="order.html#bins">Bins</a> (<code><span class='Function'>⍋⍒</span></code>), look through cells of one argument to find cells of the other. Find (<code><span class='Function'>⍷</span></code>) also does a search, but a slightly different one: it tries to find <em>slices</em> of cells of <code><span class='Value'>𝕩</span></code> that match <code><span class='Value'>𝕨</span></code>.</p>
<table>
<thead>