diff options
Diffstat (limited to 'docs/doc/depth.html')
| -rw-r--r-- | docs/doc/depth.html | 127 |
1 files changed, 37 insertions, 90 deletions
diff --git a/docs/doc/depth.html b/docs/doc/depth.html index 92e05dd3..e141585c 100644 --- a/docs/doc/depth.html +++ b/docs/doc/depth.html @@ -64,128 +64,75 @@ </table> <p>Functions such as Take and Drop use a single number per axis. When the left argument is a list of numbers, they apply to initial axes. But for convenience, a single number is also accepted, and applied to the first axis only. This is equivalent to ravelling the left argument before applying the function.</p> <pre> <span class='Function'>≢</span><span class='Number'>2</span><span class='Function'>↑</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Function'>⥊</span><span class='String'>"abc"</span> -2‿7‿7‿7 +⟨ 2 7 7 7 ⟩ <span class='Function'>≢</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Function'>↑</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Ligature'>‿</span><span class='Number'>7</span><span class='Function'>⥊</span><span class='String'>"abc"</span> -2‿1‿1‿7 +⟨ 2 1 1 7 ⟩ </pre> <p>In these cases the flexibility seems trivial because the left argument has depth 1 or 0: it is an array or isn't, and it's obvious what a plain number should do. But for the second row in the table, the left argument is always an array. The general case is that the left argument is a vector and its elements correspond to right argument axes:</p> <pre> <span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>7</span> -┌───┬───┬───┐ -│3‿1│3‿4│3‿1│ -├───┼───┼───┤ -│2‿1│2‿4│2‿1│ -└───┴───┴───┘ +┌─ +╵ ⟨ 3 1 ⟩ ⟨ 3 4 ⟩ ⟨ 3 1 ⟩ + ⟨ 2 1 ⟩ ⟨ 2 4 ⟩ ⟨ 2 1 ⟩ + ┘ </pre> <p>This means the left argument is homogeneous of depth 2. What should an argument of depth 1, or an argument that contains non-arrays, do? One option is to continue to require the left argument to be a list, and convert any non-array argument into an array by enclosing it:</p> <pre> <span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'><</span><span class='Modifier2'>⍟</span><span class='Paren'>(</span><span class='Number'>0</span><span class='Function'>=≡</span><span class='Paren'>)</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>6</span><span class='Ligature'>‿</span><span class='Number'>7</span> -┌───┬───┐ -│3‿1│2‿1│ -└───┴───┘ +⟨ ⟨ 3 1 ⟩ ⟨ 2 1 ⟩ ⟩ </pre> <p>While very consistent, this extension represents a small convenience and makes it difficult to act on a single axis, which for Replicate and <a href="group.html">Group</a> is probably the most common way the primitive is used:</p> <pre> <span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span> <span class='Function'>/</span> <span class='String'>"abcde"</span> -aaabbcddeee +"aaabbcddeee" </pre> <p>With the extension above, every case like this would have to use <code><span class='Function'><</span><span class='Modifier2'>⊸</span><span class='Function'>/</span></code> instead of just <code><span class='Function'>/</span></code>. BQN avoids this difficulty by testing the left argument's depth. A depth-1 argument applies to the first axis only, giving the behavior above.</p> <p>For Select, the depth-1 case is still quite useful, but it may also be desirable to choose a single cell using a list of numbers. In this case the left argument depth can be increased from the bottom using <code><span class='Function'><</span><span class='Modifier'>¨</span></code>.</p> <pre> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>4</span> <span class='Function'><</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊏</span> <span class='Function'>↕</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>2</span> -┌───────┬───────┐ -│2‿1‿4‿0│2‿1‿4‿1│ -└───────┴───────┘ +⟨ ⟨ 2 1 4 0 ⟩ ⟨ 2 1 4 1 ⟩ ⟩ </pre> <h2 id="the-depth-modifier">The Depth modifier</h2> <p>The Depth 2-modifier (<code><span class='Modifier2'>⚇</span></code>) is a generalization of Each that allows diving deeper into an array. To illustrate it we'll use a shape <code><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span></code> array of lists of lists.</p> <pre> <span class='Function'>⊢</span> <span class='Value'>n</span> <span class='Gets'>←</span> <span class='Function'><</span><span class='Modifier2'>⎉</span><span class='Number'>1</span><span class='Modifier2'>⍟</span><span class='Number'>2</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Function'>⥊↕</span><span class='Number'>48</span> -┌─────────────┬─────────────┬─────────────┐ -│┌───┬───┐ │┌───┬───┐ │┌───┬─────┐ │ -││0‿1│2‿3│ ││4‿5│6‿7│ ││8‿9│10‿11│ │ -│└───┴───┘ │└───┴───┘ │└───┴─────┘ │ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││12‿13│14‿15│││16‿17│18‿19│││20‿21│22‿23││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││24‿25│26‿27│││28‿29│30‿31│││32‿33│34‿35││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││36‿37│38‿39│││40‿41│42‿43│││44‿45│46‿47││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -└─────────────┴─────────────┴─────────────┘ +┌─ +╵ ⟨ ⟨ 0 1 ⟩ ⟨ 2 3 ⟩ ⟩ ⟨ ⟨ 4 5 ⟩ ⟨ 6 7 ⟩ ⟩ ⟨ ⟨ 8 9 ⟩ ⟨ 10 11 ⟩ ⟩ + ⟨ ⟨ 12 13 ⟩ ⟨ 14 15 ⟩ ⟩ ⟨ ⟨ 16 17 ⟩ ⟨ 18 19 ⟩ ⟩ ⟨ ⟨ 20 21 ⟩ ⟨ 22 23 ⟩ ⟩ + ⟨ ⟨ 24 25 ⟩ ⟨ 26 27 ⟩ ⟩ ⟨ ⟨ 28 29 ⟩ ⟨ 30 31 ⟩ ⟩ ⟨ ⟨ 32 33 ⟩ ⟨ 34 35 ⟩ ⟩ + ⟨ ⟨ 36 37 ⟩ ⟨ 38 39 ⟩ ⟩ ⟨ ⟨ 40 41 ⟩ ⟨ 42 43 ⟩ ⟩ ⟨ ⟨ 44 45 ⟩ ⟨ 46 47 ⟩ ⟩ + ┘ <span class='Function'>≡</span> <span class='Value'>n</span> 3 </pre> <p>Reversing n swaps all the rows:</p> <pre> <span class='Function'>⌽</span> <span class='Value'>n</span> -┌─────────────┬─────────────┬─────────────┐ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││36‿37│38‿39│││40‿41│42‿43│││44‿45│46‿47││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││24‿25│26‿27│││28‿29│30‿31│││32‿33│34‿35││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││12‿13│14‿15│││16‿17│18‿19│││20‿21│22‿23││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌───┬───┐ │┌───┬───┐ │┌───┬─────┐ │ -││0‿1│2‿3│ ││4‿5│6‿7│ ││8‿9│10‿11│ │ -│└───┴───┘ │└───┴───┘ │└───┴─────┘ │ -└─────────────┴─────────────┴─────────────┘ +┌─ +╵ ⟨ ⟨ 36 37 ⟩ ⟨ 38 39 ⟩ ⟩ ⟨ ⟨ 40 41 ⟩ ⟨ 42 43 ⟩ ⟩ ⟨ ⟨ 44 45 ⟩ ⟨ 46 47 ⟩ ⟩ + ⟨ ⟨ 24 25 ⟩ ⟨ 26 27 ⟩ ⟩ ⟨ ⟨ 28 29 ⟩ ⟨ 30 31 ⟩ ⟩ ⟨ ⟨ 32 33 ⟩ ⟨ 34 35 ⟩ ⟩ + ⟨ ⟨ 12 13 ⟩ ⟨ 14 15 ⟩ ⟩ ⟨ ⟨ 16 17 ⟩ ⟨ 18 19 ⟩ ⟩ ⟨ ⟨ 20 21 ⟩ ⟨ 22 23 ⟩ ⟩ + ⟨ ⟨ 0 1 ⟩ ⟨ 2 3 ⟩ ⟩ ⟨ ⟨ 4 5 ⟩ ⟨ 6 7 ⟩ ⟩ ⟨ ⟨ 8 9 ⟩ ⟨ 10 11 ⟩ ⟩ + ┘ </pre> <p>Depth <code><span class='Number'>¯1</span></code> is equivalent to Each, and reverses the larger vectors, while depth <code><span class='Number'>¯2</span></code> applies Each twice to reverse the smaller vectors:</p> <pre> <span class='Function'>⌽</span><span class='Modifier2'>⚇</span><span class='Number'>¯1</span> <span class='Value'>n</span> -┌─────────────┬─────────────┬─────────────┐ -│┌───┬───┐ │┌───┬───┐ │┌─────┬───┐ │ -││2‿3│0‿1│ ││6‿7│4‿5│ ││10‿11│8‿9│ │ -│└───┴───┘ │└───┴───┘ │└─────┴───┘ │ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││14‿15│12‿13│││18‿19│16‿17│││22‿23│20‿21││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││26‿27│24‿25│││30‿31│28‿29│││34‿35│32‿33││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││38‿39│36‿37│││42‿43│40‿41│││46‿47│44‿45││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -└─────────────┴─────────────┴─────────────┘ +┌─ +╵ ⟨ ⟨ 2 3 ⟩ ⟨ 0 1 ⟩ ⟩ ⟨ ⟨ 6 7 ⟩ ⟨ 4 5 ⟩ ⟩ ⟨ ⟨ 10 11 ⟩ ⟨ 8 9 ⟩ ⟩ + ⟨ ⟨ 14 15 ⟩ ⟨ 12 13 ⟩ ⟩ ⟨ ⟨ 18 19 ⟩ ⟨ 16 17 ⟩ ⟩ ⟨ ⟨ 22 23 ⟩ ⟨ 20 21 ⟩ ⟩ + ⟨ ⟨ 26 27 ⟩ ⟨ 24 25 ⟩ ⟩ ⟨ ⟨ 30 31 ⟩ ⟨ 28 29 ⟩ ⟩ ⟨ ⟨ 34 35 ⟩ ⟨ 32 33 ⟩ ⟩ + ⟨ ⟨ 38 39 ⟩ ⟨ 36 37 ⟩ ⟩ ⟨ ⟨ 42 43 ⟩ ⟨ 40 41 ⟩ ⟩ ⟨ ⟨ 46 47 ⟩ ⟨ 44 45 ⟩ ⟩ + ┘ <span class='Function'>⌽</span><span class='Modifier2'>⚇</span><span class='Number'>¯2</span> <span class='Value'>n</span> -┌─────────────┬─────────────┬─────────────┐ -│┌───┬───┐ │┌───┬───┐ │┌───┬─────┐ │ -││1‿0│3‿2│ ││5‿4│7‿6│ ││9‿8│11‿10│ │ -│└───┴───┘ │└───┴───┘ │└───┴─────┘ │ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││13‿12│15‿14│││17‿16│19‿18│││21‿20│23‿22││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││25‿24│27‿26│││29‿28│31‿30│││33‿32│35‿34││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -├─────────────┼─────────────┼─────────────┤ -│┌─────┬─────┐│┌─────┬─────┐│┌─────┬─────┐│ -││37‿36│39‿38│││41‿40│43‿42│││45‿44│47‿46││ -│└─────┴─────┘│└─────┴─────┘│└─────┴─────┘│ -└─────────────┴─────────────┴─────────────┘ +┌─ +╵ ⟨ ⟨ 1 0 ⟩ ⟨ 3 2 ⟩ ⟩ ⟨ ⟨ 5 4 ⟩ ⟨ 7 6 ⟩ ⟩ ⟨ ⟨ 9 8 ⟩ ⟨ 11 10 ⟩ ⟩ + ⟨ ⟨ 13 12 ⟩ ⟨ 15 14 ⟩ ⟩ ⟨ ⟨ 17 16 ⟩ ⟨ 19 18 ⟩ ⟩ ⟨ ⟨ 21 20 ⟩ ⟨ 23 22 ⟩ ⟩ + ⟨ ⟨ 25 24 ⟩ ⟨ 27 26 ⟩ ⟩ ⟨ ⟨ 29 28 ⟩ ⟨ 31 30 ⟩ ⟩ ⟨ ⟨ 33 32 ⟩ ⟨ 35 34 ⟩ ⟩ + ⟨ ⟨ 37 36 ⟩ ⟨ 39 38 ⟩ ⟩ ⟨ ⟨ 41 40 ⟩ ⟨ 43 42 ⟩ ⟩ ⟨ ⟨ 45 44 ⟩ ⟨ 47 46 ⟩ ⟩ + ┘ </pre> <p>While a negative depth tells how many levels to go down, a non-negative depth gives the maximum depth of the argument before applying the left operand. On a depth-3 array like above, depth <code><span class='Number'>2</span></code> is equivalent to <code><span class='Number'>¯1</span></code> and depth <code><span class='Number'>1</span></code> is equivalent to <code><span class='Number'>¯2</span></code>. A depth of <code><span class='Number'>0</span></code> means to loop until non-arrays are reached, that is, apply <a href="https://aplwiki.com/wiki/Pervasion">pervasively</a>, like a scalar function.</p> <pre> <span class='Bracket'>⟨</span><span class='String'>'a'</span><span class='Separator'>,</span><span class='String'>"bc"</span><span class='Bracket'>⟩</span> <span class='Function'>≍</span><span class='Modifier2'>⚇</span><span class='Number'>0</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩</span> -┌─────────────┬─────────────┐ -│┌─────┬─────┐│┌─────┬─────┐│ -││'a'‿2│'a'‿3│││'b'‿4│'c'‿4││ -│└─────┴─────┘│└─────┴─────┘│ -└─────────────┴─────────────┘ +┌─ +· ⟨ ⟨ 'a' 2 ⟩ ⟨ 'a' 3 ⟩ ⟩ ⟨ ⟨ 'b' 4 ⟩ ⟨ 'c' 4 ⟩ ⟩ + ┘ </pre> <p>With a positive operand, Depth doesn't have to use the same depth everywhere. Here, Length is applied as soon as the depth for a particular element is 1 or less, including if the argument has depth 0. For example, it maps over <code><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩⟩</span></code>, but not over <code><span class='Bracket'>⟨</span><span class='Number'>11</span><span class='Separator'>,</span><span class='Number'>12</span><span class='Bracket'>⟩</span></code>, even though these are elements of the same array.</p> <pre> <span class='Function'>≠</span><span class='Modifier2'>⚇</span><span class='Number'>1</span> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>5</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>6</span><span class='Separator'>,</span><span class='Number'>7</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>8</span><span class='Separator'>,</span><span class='Number'>9</span><span class='Separator'>,</span><span class='Number'>10</span><span class='Bracket'>⟩⟩</span><span class='Separator'>,</span><span class='Bracket'>⟨</span><span class='Number'>11</span><span class='Separator'>,</span><span class='Number'>12</span><span class='Bracket'>⟩⟩</span> -┌─┬───┬─────┬─┐ -│1│1‿2│1‿2‿3│2│ -└─┴───┴─────┴─┘ +⟨ 1 ⟨ 1 2 ⟩ ⟨ 1 2 3 ⟩ 2 ⟩ </pre> |