Select

's' 'e' 'l' 'e' 'c' 't' 2 1 1 5 'l' 'e' 'e' 't' 0 1 2 3 4 5 𝕩 𝕨 π•¨βŠπ•©

The function Select (⊏) reorganizes the array 𝕩 along one or more axes based on indices given by 𝕨. The result has the same depth as 𝕩, since its elements are always elements of 𝕩. This means it differs from Pick (βŠ‘), which takes elements from 𝕩 but can arrange them in any nested structure, including returning an element directly.

The monadic form First Cell (⊏) gets the major cell with index 0, so that βŠπ•© is identical to 0βŠπ•©.

Single selection

Each axis of a BQN array is numbered starting at zero. Major cells are arranged along the first axis; in accordance with the leading axis principle, Select returns a major cell of 𝕩 when 𝕨 is an atom.

↗️
    2 ⊏ "abcdef"  # An enclosed element
β”ŒΒ·   
Β·'c' 
    β”˜

    2 βŠ‘ "abcdef"  # Pick gets a non-enclosed element
'c'

    2 ⊏ >"nul"β€Ώ"one"β€Ώ"two"β€Ώ"tre"β€Ώ"for"
"two"

    0 ⊏ <5  # No first axis to select from
ERROR

As a major cell of 𝕩, the result has rank one less than it and its shape is 1↓≒𝕩. 𝕩 must have rank one or more.

The index 𝕨 has to be an integer less than ≠𝕩. It can be negative, in which case it must be greater than or equal to -≠𝕩. Negative indices select from the end of 𝕩, in that Β―1 indicates the last major cell and -≠𝕩 indicates the first. If ≠𝕩 is 0, then no index is valid.

↗️
    ¯2 ⊏ "abcdef"
β”ŒΒ·   
Β·'e' 
    β”˜

    0 ⊏ ""
ERROR

The monadic case First Cell (βŠπ•©) is identical to 0βŠπ•©. It has the same restrictions: 𝕩 must have rank 1 or more, and length 1 or more (this differs from First (βŠ‘), which removes the length requirement to return a fill element).

↗️
    ⊏ "abc"
β”ŒΒ·   
Β·'a' 
    β”˜

    ⊏ "abc"≍"def"
"abc"

    ⊏ ≍ "abc"
"abc"

    ⊏ 'a'
ERROR

First-axis selection

If 𝕨 is an array of numbers (including any empty array), then each number indicates a major cell of 𝕩. In the simplest case, a list of numbers gives a result with the same rank as 𝕩 but maybe not the same length.

↗️
    2β€Ώ3β€Ώ3β€Ώ0β€Ώ4β€Ώ1 ⊏ "OlZEt"
"ZEEOtl"

    ⟨⟩ ⊏ "OlZEt"
⟨⟩

To find the first and last cells of 𝕩, use 0β€ΏΒ―1 for the left argument.

↗️
    ⊒ m ← 3β€Ώ5β€Ώ7β€Ώ11 |⌜ Γ—Λœβ†•7
β”Œβ”€               
β•΅ 0 1 1 0 1 1 0  
  0 1 4 4 1 0 1  
  0 1 4 2 2 4 1  
  0 1 4 9 5 3 3  
                β”˜

    0β€ΏΒ―1 ⊏ m
β”Œβ”€               
β•΅ 0 1 1 0 1 1 0  
  0 1 4 9 5 3 3  
                β”˜

More generally, 𝕨 can be an array of any rank. Each of its 0-cellsβ€”containing a single numberβ€”is replaced with a cell of 𝕩 in the result. The result's shape is then made up of the shape of 𝕨 and the major cell shape of 𝕩: it's (≒𝕨)∾1↓≒𝕩.

When 𝕩 is a list, the result has the same shape as 𝕨. Elements of 𝕨 are replaced one-for-one with elements of 𝕩.

↗️
    2|m
β”Œβ”€               
β•΅ 0 1 1 0 1 1 0  
  0 1 0 0 1 0 1  
  0 1 0 0 0 0 1  
  0 1 0 1 1 1 1  
                β”˜

    (2|m) ⊏ " *"
β”Œβ”€         
β•΅" ** **   
   *  * *  
   *    *  
   * ****" 
          β”˜

Another special case is when 𝕨 is a unit. Now the result shape will be the major cell shape of 𝕩. In fact it's the same as the atom case above, that is, for a number n, (<n)βŠπ•© is the same as nβŠπ•©.

The general case can result in a complicated array. Remember that the initial axes come from 𝕨 while later ones come from 𝕩.

↗️
    "awA0" +⌜ ↕4
β”Œβ”€      
β•΅"abcd  
  wxyz  
  ABCD  
  0123" 
       β”˜

    2 ↕ ↕4
β”Œβ”€     
β•΅ 0 1  
  1 2  
  2 3  
      β”˜

    (2 ↕ ↕4) ⊏ "awA0" +⌜ ↕4
β”Œβ”€      
β•Ž"abcd  
  wxyz  
        
 Β·wxyz  
  ABCD  
        
 Β·ABCD  
  0123" 
       β”˜

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
β”Œβ”€                         
β•΅ ⟨ 2 3 ⟩ ⟨ 2 0 ⟩ ⟨ 2 0 ⟩  
  ⟨ 1 3 ⟩ ⟨ 1 0 ⟩ ⟨ 1 0 ⟩  
                          β”˜

Using a range 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 of selecting an element is handled by Pick.

↗️
    ⟨<4,<5,<1⟩ ⊏ (3β₯Š10)β₯Šβ†•1e3
β”ŒΒ·     
Β· 451  
      β”˜
    ⟨ 4, 5, 1⟩ βŠ‘ (3β₯Š10)β₯Šβ†•1e3
451

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
⟨ 450 451 452 453 454 455 456 457 458 459 ⟩

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 the result would yield the same value.

Selection only ever applies to leading axes of 𝕩. However, 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 𝕩.