From af3ea02fe40f75b6d13cb18294b1679aa244107a Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Mon, 4 Jan 2021 20:33:49 -0500 Subject: Join Join To to Join document --- doc/README.md | 2 +- doc/join.md | 34 ++++++++++++++++++++++++++++++-- doc/primitive.md | 2 +- docs/doc/index.html | 2 +- docs/doc/join.html | 52 ++++++++++++++++++++++++++++++++++++++++++++++--- docs/doc/primitive.html | 2 +- docs/tutorial/list.html | 2 +- tutorial/list.md | 2 +- 8 files changed, 87 insertions(+), 11 deletions(-) diff --git a/doc/README.md b/doc/README.md index 4b71be11..046651b4 100644 --- a/doc/README.md +++ b/doc/README.md @@ -23,7 +23,7 @@ Primitives: - [Array depth](depth.md) (`≡` and `⚇`) - [Deshape and Reshape](reshape.md) (`⥊`) - [Group](group.md) (`⊔`) -- [Join](join.md) (`∾`) +- [Join and Join To](join.md) (`∾`) - [Logical functions](logic.md) (`∧∨¬`) - [Prefixes and Suffixes](prefixes.md) (`↑↓`) - [Shift functions](shift.md) (`»«`) diff --git a/doc/join.md b/doc/join.md index 04fa8a0e..7a0523dd 100644 --- a/doc/join.md +++ b/doc/join.md @@ -1,8 +1,38 @@ *View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/join.html).* -# Join +# Join and Join To -Join (`∾`) is an extension of the monadic function [Raze](https://aplwiki.com/wiki/Raze) from A+ and J to arbitrary argument ranks. It has the same relationship to Join to, the dyadic function sharing the same glyph, as [Merge](couple.md) (`>`) does to Couple (`≍`): `a≍b` is `>a‿b` and `a∾b` is `∾a‿b`. While Merge and Couple combine arrays (the elements of Merge's argument, or the arguments themselves for Couple) along a new leading axis, Join and Join to combine them along the existing leading axis. Both Merge and Join can also be called on a higher-rank array, causing Merge to add multiple leading axes while Join combines elements along multiple existing axes. +The glyph `∾` combines arrays along an existing axis, a concept that other languages might call "concatenation" or "catenation" but BQN names "Join". The one-argument form Join and two-argument form Join To are parallel to the [functions that combine arrays along a new axis](couple.md), Merge (`>`) and Couple (`≍`). + +## Join To + +Join To connects its two arguments together, for example to join two strings: + + "abcd" ∾ "EFG" + +If the arguments have the same rank, then they are combined along the first axis: the result is an array whose major cells are the major cells of `𝕨` followed by the major cells of `𝕩`. For arrays with rank two or more, this means they will be joined "vertically" according to BQN's display. + + ⊢ a ← 3 +⌜○↕ 4 + ⊢ b ← 2‿4 ⥊ ↕8 + a ∾ b + +For this definition to work, major cells of `𝕨` and `𝕩` have to have the same shape. That means that `𝕨≡○(1↓≢)𝕩`, and the shape of the result is the sum of the lengths of `𝕨` and `𝕩` followed by their shared major cell shape: to use a self-referential definition, the final shape is given by `+○≠ ∾ ⊣⁼○(1↓≢)` for arguments of equal rank. + + a ∾ 2‿5⥊b + +Join To will also allow arguments with ranks that are one apart. In this case, the smaller-rank argument is treated as a major cell in its entirety. If for example `𝕨<○=𝕩`, then we must have `(≢𝕨)≡1↓≢𝕩`, and the result shape is `1⊸+⌾⊑≢𝕩`. + + 4‿2‿3‿0 ∾ a + +An edge case for Join To is that it can also be applied to two units to make a list: + + 3 ∾ 'c' + +This case is unusual because the rank of the result is higher than that of either argument. It's also identical to Couple (`≍`); Couple should be preferred because it doesn't require a special case for this situation. See [coupling units](couple.md#coupling-units). + +## Join + +The monadic form of `∾`, called simply Join, is more complicated than Join To because it really takes not just one argument but an entire array of them. Join is an extension of the monadic function [Raze](https://aplwiki.com/wiki/Raze) from A+ and J to arbitrary argument ranks. It has the same relationship to Join to, the dyadic function sharing the same glyph, as [Merge](couple.md) (`>`) does to Couple (`≍`): `a≍b` is `>a‿b` and `a∾b` is `∾a‿b`. While Merge and Couple combine arrays (the elements of Merge's argument, or the arguments themselves for Couple) along a new leading axis, Join and Join to combine them along the existing leading axis. Both Merge and Join can also be called on a higher-rank array, causing Merge to add multiple leading axes while Join combines elements along multiple existing axes. Join can be used to combine several strings into a single string, like `array.join()` in Javascript (but it doesn't force the result to be a string). diff --git a/doc/primitive.md b/doc/primitive.md index 98ff2fa0..dfc03f01 100644 --- a/doc/primitive.md +++ b/doc/primitive.md @@ -33,7 +33,7 @@ Functions that have significant differences from APL functions are marked with a | `⊣` | [Identity](https://aplwiki.com/wiki/Identity) | [Left](https://aplwiki.com/wiki/Identity) | `⊢` | [Identity](https://aplwiki.com/wiki/Identity) | [Right](https://aplwiki.com/wiki/Identity) | `⥊` | [Deshape](reshape.md) | [Reshape](reshape.md)* -| `∾` | [Join](join.md)* | [Join to](https://aplwiki.com/wiki/Catenate) +| `∾` | [Join](join.md)* | [Join to](join.md) | `≍` | [Solo](couple.md)* | [Couple](couple.md)* | `↑` | [Prefixes](prefixes.md)* | [Take](https://aplwiki.com/wiki/Take) | `↓` | [Suffixes](prefixes.md)* | [Drop](https://aplwiki.com/wiki/Drop) diff --git a/docs/doc/index.html b/docs/doc/index.html index 2c05a49c..72e9568a 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -28,7 +28,7 @@
  • Array depth (≡ and ⚇)
  • Deshape and Reshape (⥊)
  • Group (⊔)
    • -
  • Join (∾)
    • +
  • Join and Join To (∾)
  • Logical functions (∧∨¬)
  • Prefixes and Suffixes (↑↓)
  • Shift functions (»«)
    • diff --git a/docs/doc/join.html b/docs/doc/join.html index c324a706..62f478ee 100644 --- a/docs/doc/join.html +++ b/docs/doc/join.html @@ -1,11 +1,57 @@ - BQN: Join + BQN: Join and Join To
    BQN / main / doc
    -

    Join

    -

    Join (∾) is an extension of the monadic function Raze from A+ and J to arbitrary argument ranks. It has the same relationship to Join to, the dyadic function sharing the same glyph, as Merge (>) does to Couple (≍): a≍b is >a‿b and a∾b is ∾a‿b. While Merge and Couple combine arrays (the elements of Merge's argument, or the arguments themselves for Couple) along a new leading axis, Join and Join to combine them along the existing leading axis. Both Merge and Join can also be called on a higher-rank array, causing Merge to add multiple leading axes while Join combines elements along multiple existing axes.

    +

    Join and Join To

    +

    The glyph ∾ combines arrays along an existing axis, a concept that other languages might call "concatenation" or "catenation" but BQN names "Join". The one-argument form Join and two-argument form Join To are parallel to the functions that combine arrays along a new axis, Merge (>) and Couple (≍).

    +

    Join To

    +

    Join To connects its two arguments together, for example to join two strings:

    +↗️
        "abcd" ∾ "EFG"
+"abcdEFG"
+
    +

    If the arguments have the same rank, then they are combined along the first axis: the result is an array whose major cells are the major cells of 𝕨 followed by the major cells of 𝕩. For arrays with rank two or more, this means they will be joined "vertically" according to BQN's display.

    +↗️
        ⊢ a ← 3 +⌜○↕ 4
+┌─         
+╵ 0 1 2 3  
+  1 2 3 4  
+  2 3 4 5  
+          ┘
+    ⊢ b ← 2‿4 ⥊ ↕8
+┌─         
+╵ 0 1 2 3  
+  4 5 6 7  
+          ┘
+    a ∾ b
+┌─         
+╵ 0 1 2 3  
+  1 2 3 4  
+  2 3 4 5  
+  0 1 2 3  
+  4 5 6 7  
+          ┘
+
    +

    For this definition to work, major cells of 𝕨 and 𝕩 have to have the same shape. That means that 𝕨≡○(1↓≢)𝕩, and the shape of the result is the sum of the lengths of 𝕨 and 𝕩 followed by their shared major cell shape: to use a self-referential definition, the final shape is given by +○≠ ∾ ⊣⁼○(1↓≢) for arguments of equal rank.

    +↗️
        a ∾ 2‿5⥊b
+ERROR
+
    +

    Join To will also allow arguments with ranks that are one apart. In this case, the smaller-rank argument is treated as a major cell in its entirety. If for example 𝕨<○=𝕩, then we must have (≢𝕨)≡1↓≢𝕩, and the result shape is 1⊸+⌾⊑≢𝕩.

    +↗️
        4‿2‿3‿0 ∾ a
+┌─         
+╵ 4 2 3 0  
+  0 1 2 3  
+  1 2 3 4  
+  2 3 4 5  
+          ┘
+
    +

    An edge case for Join To is that it can also be applied to two units to make a list:

    +↗️
        3 ∾ 'c'
+⟨ 3 'c' ⟩
+
    +

    This case is unusual because the rank of the result is higher than that of either argument. It's also identical to Couple (≍); Couple should be preferred because it doesn't require a special case for this situation. See coupling units.

    +

    Join

    +

    The monadic form of ∾, called simply Join, is more complicated than Join To because it really takes not just one argument but an entire array of them. Join is an extension of the monadic function Raze from A+ and J to arbitrary argument ranks. It has the same relationship to Join to, the dyadic function sharing the same glyph, as Merge (>) does to Couple (≍): a≍b is >a‿b and a∾b is ∾a‿b. While Merge and Couple combine arrays (the elements of Merge's argument, or the arguments themselves for Couple) along a new leading axis, Join and Join to combine them along the existing leading axis. Both Merge and Join can also be called on a higher-rank array, causing Merge to add multiple leading axes while Join combines elements along multiple existing axes.

    Join can be used to combine several strings into a single string, like array.join() in Javascript (but it doesn't force the result to be a string).

    ↗️
        ∾"time"‿"to"‿"join"‿"some"‿"words"
 "timetojoinsomewords"
diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html
index 755697ec..e943a23c 100644
--- a/docs/doc/primitive.html
+++ b/docs/doc/primitive.html
@@ -135,7 +135,7 @@
 
 ∾
 Join*
-Join to
+Join to
 
 
 ≍
diff --git a/docs/tutorial/list.html b/docs/tutorial/list.html
index 05e4b9c5..b8d8ffba 100644
--- a/docs/tutorial/list.html
+++ b/docs/tutorial/list.html
@@ -406,7 +406,7 @@ ERROR
 
 ∾
 Join
-Join To
+Join To
 
 
 ≍
diff --git a/tutorial/list.md b/tutorial/list.md
index 36933b91..c1811eea 100644
--- a/tutorial/list.md
+++ b/tutorial/list.md
@@ -237,7 +237,7 @@ We introduced a few new primitives. The links below go to the full documentation
 
 Glyph | 1 arg                    | 2 args
 ------|--------------------------|--------
-`∾`   | [Join](../doc/join.md)   | Join To
+`∾`   | [Join](../doc/join.md)   | [Join To](../doc/join.md)
 `≍`   | [Solo](../doc/couple.md) | [Couple](../doc/couple.md)
 `⌽`   | Reverse                  | Rotate
 `↕`   |                          | Range
-- 
cgit v1.2.3