Enlist/Pair documentation

6 files changed, 127 insertions, 3 deletions

diff --git a/doc/fill.md b/doc/fill.md
index 6b4bd53c..8c7c626c 100644
--- a/doc/fill.md
+++ b/doc/fill.md
@@ -54,7 +54,7 @@ Most other primitives fit in one of three broad categories as shown in the table
 | `∩`    | `>∾`         | `∾≍»«`
 | `0`    | `≢/⍋⍒∊⊐⊒`    | `⍋⍒⊐⊒∊⍷`
 
-Besides these, there are a few primitives with special fills. [Enclose](enclose.md) (`<`) 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](range.md) (`↕`) 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](enclose.md) (`<`) 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](pair.md) works the same way, while [Pair](pair.md) sets the fill this way based on both `𝕨` and `𝕩`, if they agree. [Range](range.md) (`↕`) does the same, although the reason is less obvious: the result elements don't match `𝕩`, but they have the same structure.
 
 [Prefixes and Suffixes](prefixes.md) (`↑↓`) use `0↑𝕩` for the fill, as do [Group](group.md) 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.
 
diff --git a/doc/pair.md b/doc/pair.md
new file mode 100644
index 00000000..c36e3abd
--- /dev/null
+++ b/doc/pair.md
@@ -0,0 +1,53 @@
+*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/pair.html).*
+
+# 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"    # ⟨𝕩⟩
+
+        "pa" ⋈ "ir"   # ⟨𝕨,𝕩⟩
+
+It's usually preferable to use [list notation](arrayrepr.md#brackets) 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
+
+        ⋈¨ "+-×÷"  # Glyphs to strings
+
+Another common pattern is to use Pair in a [train](train.md), giving the results from applying each of two functions.
+
+        'c' (+⋈-)  1‿2
+
+For longer lists, this pattern can be extended with the function `<⊸∾`, which prepends a single element to a list.
+
+        "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
+
+        {6𝕏3}¨ +‿-‿×‿÷
+
+## Pair versus Couple
+
+Enlist and Pair closely related to [Solo and Couple](couple.md), 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"
+
+And the arguments to Couple must have the same shape, while Enlist takes any two arguments.
+
+        "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](fill.md) element, while list notation doesn't have to. So the following result is guaranteed:
+
+        4 ↑ "a"‿5 ⋈ "b"‿7
+
+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/doc/primitive.md b/doc/primitive.md
index 4cb8f13c..2d5a3b6b 100644
--- a/doc/primitive.md
+++ b/doc/primitive.md
@@ -39,6 +39,7 @@ Functions that have significant differences from APL equivalents or don't appear
 | `⥊`   | [Deshape](reshape.md)                               | [Reshape](reshape.md)*
 | `∾`   | [Join](join.md)*                                    | [Join to](join.md)
 | `≍`   | [Solo](couple.md)*                                  | [Couple](couple.md)*
+| `⋈`   | [Enlist](pair.md)*                                  | [Pair](pair.md)*
 | `↑`   | [Prefixes](prefixes.md)*                            | [Take](take.md)
 | `↓`   | [Suffixes](prefixes.md)*                            | [Drop](take.md)
 | `↕`   | [Range](range.md)                                   | [Windows](windows.md)*
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" ⟩
 
     <span class='Number'>3</span><span class='Function'>↑</span><span class='Bracket'>⟨⟩</span>  <span class='Comment'># Fill unknown
-</span>ERROR
+</span>⟨ 0 0 0 ⟩
 
     <span class='Function'>»</span><span class='Bracket'>⟨⟩</span>   <span class='Comment'># Fill not needed
 </span>⟨⟩
@@ -77,7 +77,7 @@
 </tr>
 </tbody>
 </table>
-<p>Besides these, there are a few primitives with special fills. <a href="enclose.html">Enclose</a> (<code><span class='Function'>&lt;</span></code>) uses a fill derived directly from <code><span class='Value'>𝕩</span></code>, with all numbers replaced by <code><span class='Number'>0</span></code> and characters by <code><span class='String'>' '</span></code> (if it contains non-data atoms, the fill doesn't exist). <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>) does the same, although the reason is less obvious: the result elements don't match <code><span class='Value'>𝕩</span></code>, but they have the same structure.</p>
+<p>Besides these, there are a few primitives with special fills. <a href="enclose.html">Enclose</a> (<code><span class='Function'>&lt;</span></code>) uses a fill derived directly from <code><span class='Value'>𝕩</span></code>, with all numbers replaced by <code><span class='Number'>0</span></code> and characters by <code><span class='String'>' '</span></code> (if it contains non-data atoms, the fill doesn't exist). <a href="pair.html">Enlist</a> works the same way, while <a href="pair.html">Pair</a> sets the fill this way based on both <code><span class='Value'>𝕨</span></code> and <code><span class='Value'>𝕩</span></code>, if they agree. <a href="range.html">Range</a> (<code><span class='Function'>↕</span></code>) does the same, although the reason is less obvious: the result elements don't match <code><span class='Value'>𝕩</span></code>, but they have the same structure.</p>
 <p><a href="prefixes.html">Prefixes and Suffixes</a> (<code><span class='Function'>↑↓</span></code>) use <code><span class='Number'>0</span><span class='Function'>↑</span><span class='Value'>𝕩</span></code> for the fill, as do <a href="group.html">Group</a> and Group Indices (<code><span class='Function'>⊔</span></code>) in the single-axis case. Fills for multi-axis <code><span class='Function'>⊔</span></code> are more complicated, but follow the rule that variable-length axes are changed to length 0. The <em>elements</em> of the result of <code><span class='Function'>⊔</span></code> also have a fill specified: the same as <code><span class='Value'>𝕩</span></code> for Group, or <code><span class='Number'>0</span></code> for Group Indices.</p>
 <a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NiDihpEg4oaR4oaVMyAgIyBUd28gZmlsbHMgYXQgdGhlIGVuZAoKwrvCqCAz4oC/NOKAvzEgL+KKuOKKlCAiYWJjMDEyM0Ei">↗️</a><pre>    <span class='Number'>6</span> <span class='Function'>↑</span> <span class='Function'>↑↕</span><span class='Number'>3</span>  <span class='Comment'># Two fills at the end
 </span>⟨ ⟨⟩ ⟨ 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 @@
+<head>
+  <link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
+  <link href="../style.css" rel="stylesheet"/>
+  <title>BQN: Pair</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="pair"><a class="header" href="#pair">Pair</a></h1>
+<p>The function <code><span class='Function'>⋈</span></code> forms a list of all its arguments. When there's one argument, it's called &quot;Enlist&quot;, and with two, it's called &quot;Pair&quot;.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4ouIICJlbmxpc3QiICAgICMg4p+o8J2VqeKfqQoKInBhIiDii4ggImlyIiAgICMg4p+o8J2VqCzwnZWp4p+p">↗️</a><pre>    <span class='Function'>⋈</span> <span class='String'>&quot;enlist&quot;</span>    <span class='Comment'># ⟨𝕩⟩
+</span>⟨ "enlist" ⟩
+
+    <span class='String'>&quot;pa&quot;</span> <span class='Function'>⋈</span> <span class='String'>&quot;ir&quot;</span>   <span class='Comment'># ⟨𝕨,𝕩⟩
+</span>⟨ "pa" "ir" ⟩
+</pre>
+<p>It's usually preferable to use <a href="arrayrepr.html#brackets">list notation</a> 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.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MuKAvzTigL8xIOKLiOKMnCAibm9ydGgi4oC/InNvdXRoIiAgIyBDYXJ0ZXNpYW4gcHJvZHVjdAoK4ouIwqggIistw5fDtyIgICMgR2x5cGhzIHRvIHN0cmluZ3M=">↗️</a><pre>    <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>⋈</span><span class='Modifier'>⌜</span> <span class='String'>&quot;north&quot;</span><span class='Ligature'>‿</span><span class='String'>&quot;south&quot;</span>  <span class='Comment'># Cartesian product
+</span>┌─                             
+╵ ⟨ 2 "north" ⟩ ⟨ 2 "south" ⟩  
+  ⟨ 4 "north" ⟩ ⟨ 4 "south" ⟩  
+  ⟨ 1 "north" ⟩ ⟨ 1 "south" ⟩  
+                              ┘
+
+    <span class='Function'>⋈</span><span class='Modifier'>¨</span> <span class='String'>&quot;+-×÷&quot;</span>  <span class='Comment'># Glyphs to strings
+</span>⟨ "+" "-" "×" "÷" ⟩
+</pre>
+<p>Another common pattern is to use Pair in a <a href="train.html">train</a>, giving the results from applying each of two functions.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=J2MnICgr4ouILSkgIDHigL8y">↗️</a><pre>    <span class='String'>'c'</span> <span class='Paren'>(</span><span class='Function'>+⋈-</span><span class='Paren'>)</span>  <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span>
+⟨ "de" "ba" ⟩
+</pre>
+<p>For longer lists, this pattern can be extended with the function <code><span class='Function'>&lt;</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span></code>, which prepends a single element to a list.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImUwIiA84oq44oi+ICJlMSIgPOKKuOKIviAiZTIiIOKLiCAiZTMi">↗️</a><pre>    <span class='String'>&quot;e0&quot;</span> <span class='Function'>&lt;</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span> <span class='String'>&quot;e1&quot;</span> <span class='Function'>&lt;</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span> <span class='String'>&quot;e2&quot;</span> <span class='Function'>⋈</span> <span class='String'>&quot;e3&quot;</span>
+⟨ "e0" "e1" "e2" "e3" ⟩
+</pre>
+<p>However, before making a long list of this sort, consider that your goal might be more easily accomplished with a list of functions.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NiAoKyA84oq44oi+IC0gPOKKuOKIviDDlyDii4ggw7cpIDMKCns28J2VjzN9wqggK+KAvy3igL/Dl+KAv8O3">↗️</a><pre>    <span class='Number'>6</span> <span class='Paren'>(</span><span class='Function'>+</span> <span class='Function'>&lt;</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span> <span class='Function'>-</span> <span class='Function'>&lt;</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span> <span class='Function'>×</span> <span class='Function'>⋈</span> <span class='Function'>÷</span><span class='Paren'>)</span> <span class='Number'>3</span>
+⟨ 9 3 18 2 ⟩
+
+    <span class='Brace'>{</span><span class='Number'>6</span><span class='Function'>𝕏</span><span class='Number'>3</span><span class='Brace'>}</span><span class='Modifier'>¨</span> <span class='Function'>+</span><span class='Ligature'>‿</span><span class='Function'>-</span><span class='Ligature'>‿</span><span class='Function'>×</span><span class='Ligature'>‿</span><span class='Function'>÷</span>
+⟨ 9 3 18 2 ⟩
+</pre>
+<h2 id="pair-versus-couple"><a class="header" href="#pair-versus-couple">Pair versus Couple</a></h2>
+<p>Enlist and Pair closely related to <a href="couple.html">Solo and Couple</a>, in that <code><span class='Function'>⋈</span></code> is equivalent to <code><span class='Function'>≍</span><span class='Modifier2'>○</span><span class='Function'>&lt;</span></code> and <code><span class='Function'>≍</span></code> is equivalent to <code><span class='Function'>&gt;</span><span class='Modifier2'>∘</span><span class='Function'>⋈</span></code>. However, the result of <code><span class='Function'>⋈</span></code> is always a list (rank 1) while Solo or Couple return an array of rank at least 1.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImFiYyIg4omNICJkZWYiCgoiYWJjIiDii4ggImRlZiI=">↗️</a><pre>    <span class='String'>&quot;abc&quot;</span> <span class='Function'>≍</span> <span class='String'>&quot;def&quot;</span>
+┌─     
+╵"abc  
+  def" 
+      ┘
+
+    <span class='String'>&quot;abc&quot;</span> <span class='Function'>⋈</span> <span class='String'>&quot;def&quot;</span>
+⟨ "abc" "def" ⟩
+</pre>
+<p>And the arguments to Couple must have the same shape, while Enlist takes any two arguments.</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImFiYyIg4omNICJkZWZnIgoKImFiYyIg4ouIICJkZWZnIg==">↗️</a><pre>    <span class='String'>&quot;abc&quot;</span> <span class='Function'>≍</span> <span class='String'>&quot;defg&quot;</span>
+ERROR
+
+    <span class='String'>&quot;abc&quot;</span> <span class='Function'>⋈</span> <span class='String'>&quot;defg&quot;</span>
+⟨ "abc" "defg" ⟩
+</pre>
+<p>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 &quot;flat&quot; version of Pair, much like Cells (<code><span class='Modifier'>˘</span></code>) is a flat version of Each (<code><span class='Modifier'>¨</span></code>). Pair is more versatile, but—precisely because of its restrictions—Couple may allow more powerful array operations on the result.</p>
+<h2 id="fill-element"><a class="header" href="#fill-element">Fill element</a></h2>
+<p>Enlist and Pair set the result's <a href="fill.html">fill</a> element, while list notation doesn't have to. So the following result is guaranteed:</p>
+<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=NCDihpEgImEi4oC/NSDii4ggImIi4oC/Nw==">↗️</a><pre>    <span class='Number'>4</span> <span class='Function'>↑</span> <span class='String'>&quot;a&quot;</span><span class='Ligature'>‿</span><span class='Number'>5</span> <span class='Function'>⋈</span> <span class='String'>&quot;b&quot;</span><span class='Ligature'>‿</span><span class='Number'>7</span>
+⟨ ⟨ "a" 5 ⟩ ⟨ "b" 7 ⟩ ⟨ " " 0 ⟩ ⟨ " " 0 ⟩ ⟩
+</pre>
+<p>This means that <code><span class='Function'>⋈</span></code> may always behave the same as the obvious implementation <code><span class='Brace'>{</span><span class='Bracket'>⟨</span><span class='Value'>𝕩</span><span class='Bracket'>⟩</span><span class='Value'>;</span><span class='Bracket'>⟨</span><span class='Value'>𝕨</span><span class='Separator'>,</span><span class='Value'>𝕩</span><span class='Bracket'>⟩</span><span class='Brace'>}</span></code>. However, <code><span class='Function'>≍</span><span class='Modifier2'>○</span><span class='Function'>&lt;</span></code> and even <code><span class='Function'>&gt;</span><span class='Modifier2'>∘</span><span class='Brace'>{</span><span class='Bracket'>⟨</span><span class='Value'>𝕩</span><span class='Bracket'>⟩</span><span class='Value'>;</span><span class='Bracket'>⟨</span><span class='Value'>𝕨</span><span class='Separator'>,</span><span class='Value'>𝕩</span><span class='Bracket'>⟩</span><span class='Brace'>}</span><span class='Modifier2'>○</span><span class='Function'>&lt;</span></code> compute the result fill as <code><span class='Function'>⋈</span></code> does and are identical implementations.</p>
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 @@
 <td><a href="couple.html">Couple</a>*</td>
 </tr>
 <tr>
+<td><code><span class='Function'>⋈</span></code></td>
+<td><a href="pair.html">Enlist</a>*</td>
+<td><a href="pair.html">Pair</a>*</td>
+</tr>
+<tr>
 <td><code><span class='Function'>↑</span></code></td>
 <td><a href="prefixes.html">Prefixes</a>*</td>
 <td><a href="take.html">Take</a></td>