Finish Select documentation

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/doc/select.html b/docs/doc/select.html
index 13589621..48f2af19 100644
--- a/docs/doc/select.html
+++ b/docs/doc/select.html
@@ -161,3 +161,25 @@ ERROR
        ┘
 </pre>
 <h2 id="multi-axis-selection">Multi-axis selection</h2>
+<p>Select also allows <code><span class='Value'>𝕨</span></code> to apply to multiple axes of <code><span class='Value'>𝕩</span></code> simultaneously. For this case, <code><span class='Value'>𝕨</span></code> must be a non-empty list (or unit array) where every element is an array of indices.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMuKAvzEsIDPigL8w4oC/MOKfqSDiio8g4oaVM+KAvzQ=">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Bracket'>⟩</span> <span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
+┌─                         
+╵ ⟨ 2 3 ⟩ ⟨ 2 0 ⟩ ⟨ 2 0 ⟩  
+  ⟨ 1 3 ⟩ ⟨ 1 0 ⟩ ⟨ 1 0 ⟩  
+                          ┘
+</pre>
+<p>Using a <a href="range.html">range</a> for <code><span class='Value'>𝕩</span></code> shows the structure of the selected elements more clearly, because each element is its own index. Each element of <code><span class='Value'>𝕨</span></code> acts independently, giving a structure like the Table modifier.</p>
+<p>While <code><span class='Value'>𝕨</span></code> must have rank one or less, its elements can have any rank. When the elements are units, the corresponding axis of <code><span class='Value'>𝕩</span></code> disappears from the result. We can select a 0-cell of <code><span class='Value'>𝕩</span></code> in this way, although the more common case or selecting an element is handled by Pick.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oPDQsPDUsPDHin6kg4oqPICgz4qWKMTAp4qWK4oaVMWUzCuKfqCA0LCA1LCAx4p+pIOKKkSAoM+KlijEwKeKliuKGlTFlMw==">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Function'>&lt;</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Function'>&lt;</span><span class='Number'>5</span><span class='Separator'>,</span><span class='Function'>&lt;</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'>⊏</span> <span class='Paren'>(</span><span class='Number'>3</span><span class='Function'>⥊</span><span class='Number'>10</span><span class='Paren'>)</span><span class='Function'>⥊↕</span><span class='Number'>1e3</span>
+┌·     
+· 451  
+      ┘
+    <span class='Bracket'>⟨</span> <span class='Number'>4</span><span class='Separator'>,</span> <span class='Number'>5</span><span class='Separator'>,</span> <span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='Paren'>(</span><span class='Number'>3</span><span class='Function'>⥊</span><span class='Number'>10</span><span class='Paren'>)</span><span class='Function'>⥊↕</span><span class='Number'>1e3</span>
+451
+</pre>
+<p>However, the <code><span class='Function'>&lt;</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span></code> construct can select a cell of any rank from <code><span class='Value'>𝕩</span></code>, because <code><span class='Function'>≠</span><span class='Value'>𝕨</span></code> can be smaller than <code><span class='Function'>=</span><span class='Value'>𝕩</span></code> (okay, not quite: an empty list is always interpreted as a list of indices, so it's impossible to select the full-rank cell <code><span class='Value'>𝕩</span></code>). Below, <code><span class='Value'>𝕨</span></code> is missing one axis and the result is a 1-cell, or row, of <code><span class='Value'>𝕩</span></code>.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oNCw14p+pIDzCqOKKuOKKjyAoM+KlijEwKeKliuKGlTFlMw==">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Number'>5</span><span class='Bracket'>⟩</span> <span class='Function'>&lt;</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span> <span class='Paren'>(</span><span class='Number'>3</span><span class='Function'>⥊</span><span class='Number'>10</span><span class='Paren'>)</span><span class='Function'>⥊↕</span><span class='Number'>1e3</span>
+⟨ 450 451 452 453 454 455 456 457 458 459 ⟩
+</pre>
+<p>If an element of <code><span class='Value'>𝕨</span></code> has rank more than 1, it increases the rank of <code><span class='Value'>𝕩</span></code> rather than decreasing it. The general rule is that in the result, one axis of <code><span class='Value'>𝕩</span></code> is replaced by all the axes of the corresponding element of <code><span class='Value'>𝕨</span></code> (trailing axes are unchanged). So the final shape <code><span class='Function'>≢</span><span class='Value'>𝕨</span><span class='Function'>⊏</span><span class='Value'>𝕩</span></code> is <code><span class='Paren'>(</span><span class='Function'>∾≢</span><span class='Modifier'>¨</span><span class='Value'>𝕨</span><span class='Paren'>)</span><span class='Function'>∾</span><span class='Value'>𝕨</span><span class='Function'>≠</span><span class='Modifier2'>⊸</span><span class='Function'>↓≢</span><span class='Value'>𝕩</span></code>. But this shape doesn't affect the elements retrieved from <code><span class='Value'>𝕩</span></code>. In all cases, using <code><span class='Function'>⥊</span><span class='Modifier'>¨</span><span class='Value'>𝕨</span></code> for the left argument and then <a href="reshape.html">reshaping</a> the result would yield the same value.</p>
+<p>Selection only ever applies to leading axes of <code><span class='Value'>𝕩</span></code>. But you can skip some leading axes using <code><span class='Modifier'>˘</span></code> or <code><span class='Modifier2'>⎉</span></code>, to select on any contiguous set of axes. In particular, use the one-axis case <code><span class='Value'>𝕨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span><span class='Modifier2'>⎉</span><span class='Paren'>(</span><span class='Function'>-</span><span class='Value'>k</span><span class='Paren'>)</span> <span class='Value'>𝕩</span></code> to select along axis <code><span class='Value'>k</span></code> of <code><span class='Value'>𝕩</span></code>.</p>