diff options
| -rw-r--r-- | doc/select.md | 19 | ||||
| -rw-r--r-- | docs/doc/select.html | 22 |
2 files changed, 41 insertions, 0 deletions
diff --git a/doc/select.md b/doc/select.md index 69f6595e..c9da2304 100644 --- a/doc/select.md +++ b/doc/select.md @@ -97,3 +97,22 @@ The general case can result in a complicated array. Remember that the initial ax (2 ↕ ↕4) ⊏ "awA0" +⌜ ↕4 ## Multi-axis selection + +Select also allows `𝕨` to apply to multiple axes of `𝕩` simultaneously. For this case, `𝕨` must be a non-empty list (or unit array) where every element is an array of indices. + + ⟨2‿1, 3‿0‿0⟩ ⊏ ↕3‿4 + +Using a [range](range.md) for `𝕩` shows the structure of the selected elements more clearly, because each element is its own index. Each element of `𝕨` acts independently, giving a structure like the Table modifier. + +While `𝕨` must have rank one or less, its elements can have any rank. When the elements are units, the corresponding axis of `𝕩` disappears from the result. We can select a 0-cell of `𝕩` in this way, although the more common case or selecting an element is handled by Pick. + + ⟨<4,<5,<1⟩ ⊏ (3⥊10)⥊↕1e3 + ⟨ 4, 5, 1⟩ ⊑ (3⥊10)⥊↕1e3 + +However, the `<¨⊸⊏` construct can select a cell of any rank from `𝕩`, because `≠𝕨` can be smaller than `=𝕩` (okay, not quite: an empty list is always interpreted as a list of indices, so it's impossible to select the full-rank cell `𝕩`). Below, `𝕨` is missing one axis and the result is a 1-cell, or row, of `𝕩`. + + ⟨4,5⟩ <¨⊸⊏ (3⥊10)⥊↕1e3 + +If an element of `𝕨` has rank more than 1, it increases the rank of `𝕩` rather than decreasing it. The general rule is that in the result, one axis of `𝕩` is replaced by all the axes of the corresponding element of `𝕨` (trailing axes are unchanged). So the final shape `≢𝕨⊏𝕩` is `(∾≢¨𝕨)∾𝕨≠⊸↓≢𝕩`. But this shape doesn't affect the elements retrieved from `𝕩`. In all cases, using `⥊¨𝕨` for the left argument and then [reshaping](reshape.md) the result would yield the same value. + +Selection only ever applies to leading axes of `𝕩`. But you can skip some leading axes using `˘` or `⎉`, to select on any contiguous set of axes. In particular, use the one-axis case `𝕨⊸⊏⎉(-k) 𝕩` to select along axis `k` of `𝕩`. 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'><</span><span class='Number'>4</span><span class='Separator'>,</span><span class='Function'><</span><span class='Number'>5</span><span class='Separator'>,</span><span class='Function'><</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'><</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'><</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> |