docs/doc/pick.html


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
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

<head>
  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
  <link href="../style.css" rel="stylesheet"/>
  <title>BQN: Pick</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="pick"><a class="header" href="#pick">Pick</a></h1>
<p>Pick (<code><span class='Function'>⊑</span></code>) chooses elements from <code><span class='Value'>𝕩</span></code> based on <a href="indices.html">index</a> lists from <code><span class='Value'>𝕨</span></code>. <code><span class='Value'>𝕨</span></code> can be a plain list, or even one number if <code><span class='Value'>𝕩</span></code> is a list, in order to get one element from <code><span class='Value'>𝕩</span></code>. It can also be an array of index lists, or have deeper array structure: each index list will be replaced with the element of <code><span class='Value'>𝕩</span></code> at that index, effectively applying to <code><span class='Value'>𝕨</span></code> at <a href="depth.html#the-depth-modifier">depth</a> 1.</p>
<p>The one-argument form is called First, and <code><span class='Function'>⊑</span><span class='Value'>𝕩</span></code> takes the first element of <code><span class='Value'>𝕩</span></code> in index order, with an error if <code><span class='Value'>𝕩</span></code> is empty.</p>
<p>While sometimes &quot;scatter-point&quot; indexing is necessary, using Pick to select multiple elements from <code><span class='Value'>𝕩</span></code> is less array-oriented than <a href="select.html">Select</a> (<code><span class='Function'>⊏</span></code>), and probably slower. Consider rearranging your data so that you can select along axes instead of picking out elements.</p>
<h2 id="one-element"><a class="header" href="#one-element">One element</a></h2>
<p>When the left argument is a number, Pick gets an element from a list:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiDiipEgMOKAvzHigL8y4oC/M+KAvzQKMiDiipEgImFiYyIKMiDiipEg4p+oQCwgMOKAvzHigL8y4oC/MywgImFiYyLin6k=">↗️</a><pre>    <span class='Number'>2</span> <span class='Function'>⊑</span> <span class='Number'>0</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='Ligature'>‿</span><span class='Number'>4</span>
2
    <span class='Number'>2</span> <span class='Function'>⊑</span> <span class='String'>&quot;abc&quot;</span>
'c'
    <span class='Number'>2</span> <span class='Function'>⊑</span> <span class='Bracket'>⟨</span><span class='String'>@</span><span class='Separator'>,</span> <span class='Number'>0</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='Separator'>,</span> <span class='String'>&quot;abc&quot;</span><span class='Bracket'>⟩</span>
"abc"
</pre>
<p>A negative number <code><span class='Value'>𝕨</span></code> behaves like <code><span class='Value'>𝕨</span><span class='Function'>+≠</span><span class='Value'>𝕩</span></code>, so that <code><span class='Number'>¯1</span></code> will select the last element, and <code><span class='Function'>-≠</span><span class='Value'>𝕩</span></code> the first. A number in <code><span class='Value'>𝕨</span></code> must be an integer less than <code><span class='Function'>≠</span><span class='Value'>𝕩</span></code> but not less than <code><span class='Function'>-≠</span><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=wq8yIOKKkSAw4oC/MeKAvzLigL8z4oC/NArCrzIg4oqRICJhYmMi">↗️</a><pre>    <span class='Number'>¯2</span> <span class='Function'>⊑</span> <span class='Number'>0</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='Ligature'>‿</span><span class='Number'>4</span>
3
    <span class='Number'>¯2</span> <span class='Function'>⊑</span> <span class='String'>&quot;abc&quot;</span>
'b'
</pre>
<p>Making <code><span class='Value'>𝕩</span></code> a list is only a special case. In general <code><span class='Value'>𝕨</span></code> can be a list of numbers whose length is <code><span class='Value'>𝕩</span></code>'s rank. So when <code><span class='Function'>=</span><span class='Value'>𝕩</span></code> is 1, <code><span class='Value'>𝕨</span></code> can be length-1 list. The case above where <code><span class='Value'>𝕨</span></code> is a number is a simplification, but an enclosed number <code><span class='Value'>𝕨</span></code> isn't allowed because it could be confused with the nested case described below.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMiww4p+pIOKKkSDihpU04oC/NQ==">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='Function'>↕</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span>
⟨ 2 0 ⟩
</pre>
<p>Above we see that picking from the result of <a href="range.html">Range</a> gives the index. For something slightly more interesting, here's a character array:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICdhJyArIOKliuKfnCjihpXDl8K0KSA04oC/NQoy4oC/MCDiipEgYQox4oC/wq8xIOKKkSBh">↗️</a><pre>    <span class='Function'>⊢</span> <span class='Value'>a</span> <span class='Gets'>←</span> <span class='String'>'a'</span> <span class='Function'>+</span> <span class='Function'>⥊</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Function'>↕×</span><span class='Modifier'>´</span><span class='Paren'>)</span> <span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span>
┌─       
╵"abcde  
  fghij  
  klmno  
  pqrst" 
        ┘
    <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
'k'
    <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
'j'
</pre>
<p><code><span class='Value'>𝕩</span></code> can even be a <a href="enclose.html#whats-a-unit">unit</a>. By definition it has rank 0, so the only possible value for <code><span class='Value'>𝕨</span></code> is the empty list. This extracts an <a href="enclose.html">enclosed</a> element, and returns an atom unchanged—the atom is promoted to an array by enclosing it, then the action of Pick undoes this. But there's rarely a reason to use this case, because the monadic form First accomplishes the same thing.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+o4p+pIOKKkSA8J2EnCuKfqOKfqSDiipEgJ2En">↗️</a><pre>    <span class='Bracket'>⟨⟩</span> <span class='Function'>⊑</span> <span class='Function'>&lt;</span><span class='String'>'a'</span>
'a'
    <span class='Bracket'>⟨⟩</span> <span class='Function'>⊑</span> <span class='String'>'a'</span>
'a'
</pre>
<h3 id="first"><a class="header" href="#first">First</a></h3>
<p>With no left argument, <code><span class='Function'>⊑</span></code> is called First, and is the same as Pick with a default left argument <code><span class='Number'>0</span><span class='Modifier'>¨</span><span class='Function'>≢</span><span class='Value'>𝕩</span></code>. For a non-empty array it returns the first element in index order.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRIDwnYScK4oqRICJGaXJzdCIK4oqRIOKGlTTigL8y4oC/NeKAvzE=">↗️</a><pre>    <span class='Function'>⊑</span> <span class='Function'>&lt;</span><span class='String'>'a'</span>
'a'
    <span class='Function'>⊑</span> <span class='String'>&quot;First&quot;</span>
'F'
    <span class='Function'>⊑</span> <span class='Function'>↕</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>5</span><span class='Ligature'>‿</span><span class='Number'>1</span>
⟨ 0 0 0 0 ⟩
</pre>
<p>And if <code><span class='Value'>𝕩</span></code> is empty then First results in an error.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqRICIiCgriipEg4omiz4A=">↗️</a><pre>    <span class='Function'>⊑</span> <span class='String'>&quot;&quot;</span>
<span class='Error'>Error: ⊑: Argument cannot be empty</span>

    <span class='Function'>⊑</span> <span class='Function'>≢</span><span class='Number'>π</span>
<span class='Error'>Error: ⊑: Argument cannot be empty</span>
</pre>
<p>In APL it's common to get the last element of a list with an idiom that translates to <code><span class='Function'>⊑⌽</span></code>, or First-<a href="reverse.html">Reverse</a>. In BQN the most straightforward way is to select with index <code><span class='Number'>¯1</span></code> instead. I also sometimes use <a href="fold.html">Fold</a> with the Right <a href="identity.html">identity function</a>.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqR4oy9ICJsYXN0IgrCrzHiipEgImxhc3QiCuKKosK0ICJsYXN0Ig==">↗️</a><pre>    <span class='Function'>⊑⌽</span> <span class='String'>&quot;last&quot;</span>
't'
    <span class='Number'>¯1</span><span class='Function'>⊑</span> <span class='String'>&quot;last&quot;</span>
't'
    <span class='Function'>⊢</span><span class='Modifier'>´</span> <span class='String'>&quot;last&quot;</span>
't'
</pre>
<h2 id="many-elements"><a class="header" href="#many-elements">Many elements</a></h2>
<p>Pick also accepts a list of indices:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICdhJyArIOKliuKfnCjihpXDl8K0KSA04oC/NQphICAjIERlZmluZWQgYWJvdmUKCuKfqDLigL8wLCAx4oC/wq8xLCAz4oC/MSwgwq8x4oC/wq8x4p+pIOKKkSBh">↗️</a><pre>    <span class='Value'>a</span>  <span class='Comment'># Defined above
</span>┌─       
╵"abcde  
  fghij  
  klmno  
  pqrst" 
        ┘

    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Number'>1</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'>1</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
"kjqt"
</pre>
<p>These indices have to be lists, since if they're numbers it just looks like <code><span class='Value'>𝕨</span></code> is an index list for one element.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMiwxLDAswq8x4p+pIOKKkSAiYWJjIiAgIyDwnZWpIGRvZXNuJ3QgaGF2ZSByYW5rIDQhCgrin6gyLDEsMCzCrzHin6kg4qWKwqjiirjiipEgImFiYyIKCuKfqDIsMSwwLMKvMeKfqSDiio8gImFiYyIgICMgQmV0dGVyIHdheQ==">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='String'>&quot;abc&quot;</span>  <span class='Comment'># 𝕩 doesn't have rank 4!
</span><span class='Error'>Error: ⊑: Picking item at wrong rank (index 2‿1‿0‿¯1 in array of shape ⟨3⟩)</span>

    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⥊</span><span class='Modifier'>¨</span><span class='Modifier2'>⊸</span><span class='Function'>⊑</span> <span class='String'>&quot;abc&quot;</span>
"cbac"

    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span> <span class='Function'>⊏</span> <span class='String'>&quot;abc&quot;</span>  <span class='Comment'># Better way
</span>"cbac"
</pre>
<p>It's much more general than just a list of indices though. As long as your indices are lists, you can arrange them in any array structure with arbitrary nesting.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICdhJyArIOKliuKfnCjihpXDl8K0KSA04oC/NQrin6gy4oC/MCwg4p+o4p+oMeKAv8KvMSwgM+KAvzHin6ksIMKvMeKAv8KvMeKfqeKfqSDiipEgYQoKKOKfqDLigL8wLCAx4oC/wq8x4p+p4omN4p+oM+KAvzEsIMKvMeKAv8KvMeKfqSkg4oqRIGEKCijin6gy4oC/MCwgPDHigL/CrzHin6niiY3in6g8M+KAvzEsIMKvMeKAv8KvMeKfqSkg4oqRIGE=">↗️</a><pre>    <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Bracket'>⟨⟨</span><span class='Number'>1</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'>1</span><span class='Bracket'>⟩</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩⟩</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
⟨ 'k' ⟨ "jq" 't' ⟩ ⟩

    <span class='Paren'>(</span><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Function'>≍</span><span class='Bracket'>⟨</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Paren'>)</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
┌─    
╵"kj  
  qt" 
     ┘

    <span class='Paren'>(</span><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Function'>&lt;</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Function'>≍</span><span class='Bracket'>⟨</span><span class='Function'>&lt;</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Paren'>)</span> <span class='Function'>⊑</span> <span class='Value'>a</span>
┌─             
╵ 'k'   ┌·     
        ·'j'   
            ┘  
  ┌·    't'    
  ·'q'         
      ┘        
              ┘
</pre>
<p>This option is easily described using the <a href="depth.html#the-depth-modifier">Depth modifier</a>. Pick applies to depth-1 components of the left argument and the entire right argument, which corresponds to a depth operand of <code><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>∞</span></code>. The left argument components have to be lists of numbers, or Pick gives an error.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oqiIGEg4oaQICdhJyArIOKliuKfnCjihpXDl8K0KSA04oC/NQoo4p+oMuKAvzAsIDwx4oC/wq8x4p+p4omN4p+oPDPigL8xLCDCrzHigL/CrzHin6kpIOKKkeKahzHigL/iiJ4gYQoK4p+o4p+oMiwz4p+pLDHin6kg4oqRIGEgICMgMSBpc24ndCBhIHZhbGlkIGluZGV4">↗️</a><pre>    <span class='Paren'>(</span><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Separator'>,</span> <span class='Function'>&lt;</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Function'>≍</span><span class='Bracket'>⟨</span><span class='Function'>&lt;</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>¯1</span><span class='Ligature'>‿</span><span class='Number'>¯1</span><span class='Bracket'>⟩</span><span class='Paren'>)</span> <span class='Function'>⊑</span><span class='Modifier2'>⚇</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>∞</span> <span class='Value'>a</span>
┌─             
╵ 'k'   ┌·     
        ·'j'   
            ┘  
  ┌·    't'    
  ·'q'         
      ┘        
              ┘

    <span class='Bracket'>⟨⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Bracket'>⟩</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Bracket'>⟩</span> <span class='Function'>⊑</span> <span class='Value'>a</span>  <span class='Comment'># 1 isn't a valid index
</span><span class='Error'>Error: ⊑: 𝕨 contained list with mixed-type elements</span>
</pre>