Diagrams for Grade and Ordinals

1 files changed, 108 insertions, 2 deletions

diff --git a/docs/doc/order.html b/docs/doc/order.html
index 1916167d..3d5047ae 100644
--- a/docs/doc/order.html
+++ b/docs/doc/order.html
@@ -23,7 +23,51 @@
 </pre>
 <p>Sort Down always <a href="match.html">matches</a> Sort Up <a href="reverse.html">reversed</a>, <code><span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>∧</span></code>. The reason for this is that BQN's array ordering is a <a href="https://en.wikipedia.org/wiki/Total_order">total order</a>, meaning that if one array doesn't come earlier or later that another array in the ordering then the two arrays match. Since any two non-matching argument cells are strictly ordered, they will have one ordering in <code><span class='Function'>∧</span></code> and the opposite ordering in <code><span class='Function'>∨</span></code>. With the reverse, any pair of non-matching cells are ordered the same way in <code><span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>∧</span></code> and <code><span class='Function'>∨</span></code>. Since these two results have the same major cells in the same order, they match. However, note that the results will not always behave identically because Match doesn't take <a href="fill.html">fill elements</a> into account (if you're curious, take a look at <code><span class='Function'>⊑</span><span class='Modifier'>¨</span><span class='Function'>∨</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>0</span><span class='Separator'>,</span><span class='String'>&quot;&quot;</span><span class='Bracket'>⟩</span></code> versus <code><span class='Function'>⊑</span><span class='Modifier'>¨</span><span class='Function'>⌽</span><span class='Modifier2'>∘</span><span class='Function'>∧</span><span class='Bracket'>⟨</span><span class='Function'>↕</span><span class='Number'>0</span><span class='Separator'>,</span><span class='String'>&quot;&quot;</span><span class='Bracket'>⟩</span></code>).</p>
 <h2 id="grade"><a class="header" href="#grade">Grade</a></h2>
-<p><em>See the <a href="https://aplwiki.com/wiki/Grade">APL Wiki page</a> for a few more examples. BQN only has the monadic form.</em></p>
+<svg viewBox='-186 -13.6 486 193.12'>
+  <g font-family='BQN,monospace' font-size='22px' text-anchor='middle'>
+    <rect class='code' stroke-width='1.5' rx='12' x='-108' y='0' width='330' height='165.92'/>
+    <g class='lilac' stroke-width='2' stroke-linecap='round'>
+      <line x1='55.2' x2='4.8' y1='54.4' y2='95.2'/>
+      <line x1='115.2' x2='64.8' y1='54.4' y2='95.2'/>
+      <line x1='9.6' x2='110.4' y1='54.4' y2='95.2'/>
+      <line x1='180' x2='180' y1='54.4' y2='95.2'/>
+    </g>
+    <g fill='currentColor' font-size='22'>
+      <g class='String'>
+        <text dy='0.32em' x='0' y='40.8'>'s'</text>
+        <text dy='0.32em' x='60' y='40.8'>'o'</text>
+        <text dy='0.32em' x='120' y='40.8'>'r'</text>
+        <text dy='0.32em' x='180' y='40.8'>'t'</text>
+      </g>
+      <g class='Number'>
+        <text dy='0.32em' x='0' y='108.8'>1</text>
+        <text dy='0.32em' x='60' y='108.8'>2</text>
+        <text dy='0.32em' x='120' y='108.8'>0</text>
+        <text dy='0.32em' x='180' y='108.8'>3</text>
+      </g>
+      <g class='String'>
+        <text dy='0.32em' x='0' y='138.72'>'o'</text>
+        <text dy='0.32em' x='60' y='138.72'>'r'</text>
+        <text dy='0.32em' x='120' y='138.72'>'s'</text>
+        <text dy='0.32em' x='180' y='138.72'>'t'</text>
+      </g>
+    </g>
+    <g fill='currentColor' font-size='14' opacity='0.8'>
+      <g class='Number'>
+        <text dy='0.32em' x='0' y='18.36'>0</text>
+        <text dy='0.32em' x='60' y='18.36'>1</text>
+        <text dy='0.32em' x='120' y='18.36'>2</text>
+        <text dy='0.32em' x='180' y='18.36'>3</text>
+      </g>
+    </g>
+    <g font-size='18px' text-anchor='end'>
+      <text dy='0.32em' x='-48' y='40.8'><tspan class='Value'>𝕩</tspan></text>
+      <text dy='0.32em' x='-48' y='108.8'><tspan class='Function'>⍋</tspan><tspan class='Value'>𝕩</tspan></text>
+      <text dy='0.32em' x='-48' y='138.72'><tspan class='Function'>∧</tspan><tspan class='Value'>𝕩</tspan></text>
+    </g>
+  </g>
+</svg>
+
 <p>Grade is more abstract than Sort. Rather than rearranging the argument's cells immediately, it returns a list of indices (more precisely, a permutation) giving the ordering that would sort them.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGwg4oaQICJwbGFuZXQi4oC/Im1vb24i4oC/InN0YXIi4oC/ImFzdGVyb2lkIgoK4oinIGwKCuKNiyBs">↗️</a><pre>    <span class='Function'>⊢</span> <span class='Value'>l</span> <span class='Gets'>←</span> <span class='String'>&quot;planet&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;moon&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;star&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;asteroid&quot;</span>
 ⟨ "planet" "moon" "star" "asteroid" ⟩
@@ -39,6 +83,67 @@
 ⟨ "asteroid" "moon" "planet" "star" ⟩
 </pre>
 <h3 id="ordinals"><a class="header" href="#ordinals">Ordinals</a></h3>
+<svg viewBox='-186 -13.6 486 231.2'>
+  <g font-family='BQN,monospace' font-size='22px' text-anchor='middle'>
+    <rect class='code' stroke-width='1.5' rx='12' x='-108' y='0' width='330' height='204'/>
+    <g class='lilac' stroke-width='2' stroke-linecap='round'>
+      <line x1='55.2' x2='4.8' y1='54.4' y2='95.2'/>
+      <line x1='115.2' x2='64.8' y1='54.4' y2='95.2'/>
+      <line x1='9.6' x2='110.4' y1='54.4' y2='95.2'/>
+      <line x1='180' x2='180' y1='54.4' y2='95.2'/>
+      <line x1='110.4' x2='9.6' y1='122.4' y2='163.2'/>
+      <line x1='4.8' x2='55.2' y1='122.4' y2='163.2'/>
+      <line x1='64.8' x2='115.2' y1='122.4' y2='163.2'/>
+      <line x1='180' x2='180' y1='122.4' y2='163.2'/>
+    </g>
+    <g fill='currentColor' font-size='22'>
+      <g class='String'>
+        <text dy='0.32em' x='0' y='40.8'>'s'</text>
+        <text dy='0.32em' x='60' y='40.8'>'o'</text>
+        <text dy='0.32em' x='120' y='40.8'>'r'</text>
+        <text dy='0.32em' x='180' y='40.8'>'t'</text>
+      </g>
+      <g class='Number'>
+        <text dy='0.32em' x='0' y='108.8'>1</text>
+        <text dy='0.32em' x='60' y='108.8'>2</text>
+        <text dy='0.32em' x='120' y='108.8'>0</text>
+        <text dy='0.32em' x='180' y='108.8'>3</text>
+      </g>
+      <g class='String'>
+        <text dy='0.32em' x='0' y='176.8'>2</text>
+        <text dy='0.32em' x='60' y='176.8'>0</text>
+        <text dy='0.32em' x='120' y='176.8'>1</text>
+        <text dy='0.32em' x='180' y='176.8'>3</text>
+      </g>
+    </g>
+    <g fill='currentColor' font-size='14' opacity='0.8'>
+      <g class='Number'>
+        <text dy='0.32em' x='0' y='18.36'>0</text>
+        <text dy='0.32em' x='57.9' y='18.36'>1</text>
+        <text dy='0.32em' x='115.8' y='18.36'>2</text>
+        <text dy='0.32em' x='173.7' y='18.36'>3</text>
+      </g>
+      <g class='String'>
+        <text dy='0.32em' x='0' y='86.36'>0</text>
+        <text dy='0.32em' x='57.9' y='86.36'>1</text>
+        <text dy='0.32em' x='115.8' y='86.36'>2</text>
+        <text dy='0.32em' x='173.7' y='86.36'>3</text>
+      </g>
+      <g class='Number'>
+        <text dy='0.32em' x='0' y='154.36'>0</text>
+        <text dy='0.32em' x='57.9' y='154.36'>1</text>
+        <text dy='0.32em' x='115.8' y='154.36'>2</text>
+        <text dy='0.32em' x='173.7' y='154.36'>3</text>
+      </g>
+    </g>
+    <g font-size='18px' text-anchor='end'>
+      <text dy='0.32em' x='-48' y='40.8'><tspan class='Value'>𝕩</tspan></text>
+      <text dy='0.32em' x='-48' y='108.8'><tspan class='Function'>⍋</tspan><tspan class='Value'>𝕩</tspan></text>
+      <text dy='0.32em' x='-48' y='176.8'><tspan class='Function'>⍋⍋</tspan><tspan class='Value'>𝕩</tspan></text>
+    </g>
+  </g>
+</svg>
+
 <p>So the elements of the Grade of an array correspond to the cells of that array after it's sorted. It's tempting if you don't have the sorted list handy to try to match them up with major cells of the original array, but this never makes sense—there's no relationship. However, applying Grade <em>twice</em> gives us a list that does correspond to the original argument quite usefully: it says, for each major cell of that argument, what rank it has relative to the others (smallest is 0, next is 1, and so on, breaking ties in favor of which cell comes earlier in the argument). Experienced APL programmers call this pattern the &quot;ordinals&quot; idiom.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=bCDiiY0g4o2L4o2LIGw=">↗️</a><pre>    <span class='Value'>l</span> <span class='Function'>≍</span> <span class='Function'>⍋⍋</span> <span class='Value'>l</span>
 ┌─                                   
@@ -87,8 +192,9 @@
 <p><em>There's also an <a href="https://aplwiki.com/wiki/Interval_Index">APL Wiki page</a> on this function, but be careful as the Dyalog version has subtle differences.</em></p>
 <p>The two Bins functions are written with the same symbols <code><span class='Function'>⍋</span></code> and <code><span class='Function'>⍒</span></code> as Grade, but take two arguments instead of one. More complicated? A little, but once you understand Bins you'll find that it's a basic concept that shows up in the real world all the time.</p>
 <p>Bins behaves like a <a href="search.html">search function</a> with respect to rank: it looks up cells from <code><span class='Value'>𝕩</span></code> relative to major cells of <code><span class='Value'>𝕨</span></code>. However, there's an extra requirement: the left argument to Bins is already sorted according to whichever ordering is used. If it isn't, you'll get an error.</p>
-<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NeKAvzbigL8y4oC/NOKAvzEg4o2LIDMKMOKAvzPigL804oC/N+KAvzkg4o2SIDM=">↗️</a><pre>    <span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>⍋</span> <span class='Number'>3</span>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NeKAvzbigL8y4oC/NOKAvzEg4o2LIDMKCjDigL8z4oC/NOKAvzfigL85IOKNkiAz">↗️</a><pre>    <span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>⍋</span> <span class='Number'>3</span>
 <span class='Error'>Error: ⍋: 𝕨 must be sorted</span>
+
     <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>9</span> <span class='Function'>⍒</span> <span class='Number'>3</span>
 <span class='Error'>Error: ⍒: 𝕨 must be sorted in descending order</span>
 </pre>