From 30b5188c23576d5e119bbc8d27cd08a3015a75c9 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Wed, 3 Nov 2021 15:41:10 -0400 Subject: Enlist/Pair documentation --- docs/doc/fill.html | 4 +-- docs/doc/pair.html | 65 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/doc/primitive.html | 5 ++++ 3 files changed, 72 insertions(+), 2 deletions(-) create mode 100644 docs/doc/pair.html (limited to 'docs/doc') diff --git a/docs/doc/fill.html b/docs/doc/fill.html index e350fa6e..ef6e1422 100644 --- a/docs/doc/fill.html +++ b/docs/doc/fill.html @@ -21,7 +21,7 @@ ⟨ ⟨ 0 3 3 3 ⟩ " qrs" ⟩ 3↑⟨⟩ # Fill unknown -ERROR +⟨ 0 0 0 ⟩ »⟨⟩ # Fill not needed ⟨⟩ @@ -77,7 +77,7 @@ -

Besides these, there are a few primitives with special fills. Enclose (<) uses a fill derived directly from 𝕩, with all numbers replaced by 0 and characters by ' ' (if it contains non-data atoms, the fill doesn't exist). Range (↕) does the same, although the reason is less obvious: the result elements don't match 𝕩, but they have the same structure.

+

Besides these, there are a few primitives with special fills. Enclose (<) uses a fill derived directly from 𝕩, with all numbers replaced by 0 and characters by ' ' (if it contains non-data atoms, the fill doesn't exist). Enlist works the same way, while Pair sets the fill this way based on both 𝕨 and 𝕩, if they agree. Range (↕) does the same, although the reason is less obvious: the result elements don't match 𝕩, but they have the same structure.

Prefixes and Suffixes (↑↓) use 0↑𝕩 for the fill, as do Group and Group Indices (⊔) in the single-axis case. Fills for multi-axis ⊔ are more complicated, but follow the rule that variable-length axes are changed to length 0. The elements of the result of ⊔ also have a fill specified: the same as 𝕩 for Group, or 0 for Group Indices.

↗️
    6 ↑ ↑↕3  # Two fills at the end
 ⟨ ⟨⟩ ⟨ 0 ⟩ ⟨ 0 1 ⟩ ⟨ 0 1 2 ⟩ ⟨⟩ ⟨⟩ ⟩
diff --git a/docs/doc/pair.html b/docs/doc/pair.html
new file mode 100644
index 00000000..46f4c82d
--- /dev/null
+++ b/docs/doc/pair.html
@@ -0,0 +1,65 @@
+
+  
+  
+  BQN: Pair
+
+
(github) / BQN / doc

+
Pair

+
The function ⋈ forms a list of all its arguments. When there's one argument, it's called "Enlist", and with two, it's called "Pair".

+↗️
    ⋈ "enlist"    # ⟨𝕩⟩
+⟨ "enlist" ⟩
+
+    "pa" ⋈ "ir"   # ⟨𝕨,𝕩⟩
+⟨ "pa" "ir" ⟩
+

+
It's usually preferable to use list notation directly for such arrays, because it's easy to add or remove any number of elements. Pair is useful when a standalone function is needed, for example to be used as an operand.

+↗️
    2‿4‿1 ⋈⌜ "north"‿"south"  # Cartesian product
+┌─                             
+╵ ⟨ 2 "north" ⟩ ⟨ 2 "south" ⟩  
+  ⟨ 4 "north" ⟩ ⟨ 4 "south" ⟩  
+  ⟨ 1 "north" ⟩ ⟨ 1 "south" ⟩  
+                              ┘
+
+    ⋈¨ "+-×÷"  # Glyphs to strings
+⟨ "+" "-" "×" "÷" ⟩
+

+
Another common pattern is to use Pair in a train, giving the results from applying each of two functions.

+↗️
    'c' (+⋈-)  1‿2
+⟨ "de" "ba" ⟩
+

+
For longer lists, this pattern can be extended with the function <⊸∾, which prepends a single element to a list.

+↗️
    "e0" <⊸∾ "e1" <⊸∾ "e2" ⋈ "e3"
+⟨ "e0" "e1" "e2" "e3" ⟩
+

+
However, before making a long list of this sort, consider that your goal might be more easily accomplished with a list of functions.

+↗️
    6 (+ <⊸∾ - <⊸∾ × ⋈ ÷) 3
+⟨ 9 3 18 2 ⟩
+
+    {6𝕏3}¨ +‿-‿×‿÷
+⟨ 9 3 18 2 ⟩
+

+
Pair versus Couple

+
Enlist and Pair closely related to Solo and Couple, in that ⋈ is equivalent to ≍○< and ≍ is equivalent to >∘⋈. However, the result of ⋈ is always a list (rank 1) while Solo or Couple return an array of rank at least 1.

+↗️
    "abc" ≍ "def"
+┌─     
+╵"abc  
+  def" 
+      ┘
+
+    "abc" ⋈ "def"
+⟨ "abc" "def" ⟩
+

+
And the arguments to Couple must have the same shape, while Enlist takes any two arguments.

+↗️
    "abc" ≍ "defg"
+ERROR
+
+    "abc" ⋈ "defg"
+⟨ "abc" "defg" ⟩
+

+
The difference is that Couple treats the arguments as cells, and adds a dimension, while Pair treats them as elements, adding a layer of depth. Couple is a "flat" version of Pair, much like Cells (˘) is a flat version of Each (¨). Pair is more versatile, but—precisely because of its restrictions—Couple may allow more powerful array operations on the result.

+
Fill element

+
Enlist and Pair set the result's fill element, while list notation doesn't have to. So the following result is guaranteed:

+↗️
    4 ↑ "a"‿5 ⋈ "b"‿7
+⟨ ⟨ "a" 5 ⟩ ⟨ "b" 7 ⟩ ⟨ " " 0 ⟩ ⟨ " " 0 ⟩ ⟩
+

+
This means that ⋈ may always behave the same as the obvious implementation {⟨𝕩⟩;⟨𝕨,𝕩⟩}. However, ≍○< and even >∘{⟨𝕩⟩;⟨𝕨,𝕩⟩}○< compute the result fill as ⋈ does and are identical implementations.

diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index ebb09c09..05cb3dbc 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -145,6 +145,11 @@
 Couple*
 
 
+⋈
+Enlist*
+Pair*
+
+
 ↑
 Prefixes*
 Take
-- 
cgit v1.2.3