From 15281037815c136b70d1410e4000e570d6ec019a Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Wed, 30 Jun 2021 22:44:44 -0400 Subject: Select documentation, single-axis case only --- docs/doc/select.html | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 docs/doc/select.html (limited to 'docs/doc/select.html') diff --git a/docs/doc/select.html b/docs/doc/select.html new file mode 100644 index 00000000..13589621 --- /dev/null +++ b/docs/doc/select.html @@ -0,0 +1,163 @@ + + + + BQN: Select + +
BQN / main / doc
+

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

-- cgit v1.2.3