From 0fe07c5912c42fca1f4a9010d240ac0116a671a2 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Mon, 11 Apr 2022 22:32:10 -0400 Subject: Documentation for Atop and Over --- docs/doc/compose.html | 140 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/doc/index.html | 1 + docs/doc/primitive.html | 4 +- docs/help/atop.html | 2 + docs/help/over.html | 2 + 5 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 docs/doc/compose.html (limited to 'docs') diff --git a/docs/doc/compose.html b/docs/doc/compose.html new file mode 100644 index 00000000..4458ea3c --- /dev/null +++ b/docs/doc/compose.html @@ -0,0 +1,140 @@ + + + + BQN: Atop and Over + +
(github) / BQN / doc
+

Atop and Over

+ + + + Atop + + π”½βˆ˜π”Ύ 𝕩 + + + + + + 𝔽 + 𝔾 + 𝕩 + + + 𝕨 π”½βˆ˜π”Ύ 𝕩 + + + + + + + + 𝔽 + 𝔾 + 𝕨 + 𝕩 + + + + + Over + + 𝔽○𝔾 𝕩 + + + + + + 𝔽 + 𝔾 + 𝕩 + + + 𝕨 𝔽○𝔾 𝕩 + + + + + + + + + + 𝔽 + 𝔾 + 𝔾 + 𝕨 + 𝕩 + + + + +

Atop and Over are 2-modifiers that extend the idea of "apply this, then that" in two different ways. They're modelled after the mathematical notation f∘g to compose two functions, and both do the same thing when there's one argument: F∘G x or Fβ—‹G x is F G x.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
CmpCmp 𝕩𝕨 Cmp 𝕩UnifiedOn list
F∘GF G 𝕩F 𝕨 G 𝕩{𝔽𝕨𝔾𝕩}F G´𝕩
Fβ—‹GF G 𝕩(G 𝕨) F G 𝕩{(𝔾𝕨)𝔽𝔾𝕩}FΒ΄G¨𝕩
+

When there are two arguments, we might say Atop treats the right operand 𝔾 as primary and Over treats 𝔽 as primaryβ€”the primary operand becomes dyadic while the other is always monadic. Atop applies 𝔾 directly, making it more like mathematical composition if we suppose that 𝔾 is a function that can take a pair of arguments. Over instead makes two calls to apply 𝔾 separately to both arguments, then passes the results to 𝔽.

+

Atop

+

Of the two modifiers on this page, Atop is more common but less impactful. The composition F∘G is equivalent to the 2-train F G (the trains page has hints on when you'd choose one or the other). Its definition {F𝕨G𝕩} means that G is applied to one or two arguments and F is applied monadically to the result. It could be considered a "default way" to compose two functions. Keeps tacit programming syntax running smoothly, without making noise about it. Not like that busybody ⊸. Some examples:

+

β†•βˆ˜β‰  is useful with one argument: ↕≠l is a list of indices for l.

+

⌊∘÷ is useful with two arguments: ⌊a÷b is the integer part when dividing a by b, often paired with the remainder b|a.

+

βŠ”βˆ˜βŠ is useful with one or two arguments. From right to left, we have Classify/Index-of (⊐) to convert values to indices, and Group Indices to group the indices. Er, that sounds good but what it actually does is to group indices of Group's argument, which correspond to indices of the original 𝕩, according to their values as returned by ⊐. Without a left argument, this means indices of 𝕩 are grouped corresponding to ⍷𝕩, and if 𝕨 is provided the groups correspond to 𝕨 instead.

+↗️
    βŠ”βˆ˜βŠ "bbeabee"
+⟨ ⟨ 0 1 4 ⟩ ⟨ 2 5 6 ⟩ ⟨ 3 ⟩ ⟩
+
+    "abcde" βŠ”βˆ˜βŠ "bbeabee"
+⟨ ⟨ 3 ⟩ ⟨ 0 1 4 ⟩ ⟨⟩ ⟨⟩ ⟨ 2 5 6 ⟩ ⟩
+
+

Over

+

Once you get used to Over, it's painful to go without it. I'd use it all the time in C if I could.

+

Usually Over is used just for the dyadic meaning. If you have a composition that only works with one argument it's typical to write it with Atop (∘). And cases that work with one or two arguments do come up from time to time, but they're fairly rare, so the examples below are just for two arguments.

+

A classic is the function β‰‘β—‹βˆ§, which tests whether 𝕨 is a reordering of 𝕩. The idea is to sort both arrays with ∧ to remove the ordering information

+↗️
    "BQN" β‰‘β—‹βˆ§ "QNB"
+1
+    "BQN" β‰‘β—‹βˆ§ "BBQ"
+0
+
+

Another example is /β—‹β₯Š, used to filter elements in a high-rank array. Alone, / won't do this because there's no automatic choice of ordering for the results. Applying Deshape (β₯Š) to both chooses index order.

+↗️
    ⊒ a ← "qBrs"≍"QtuN"
+β”Œβ”€      
+β•΅"qBrs  
+  QtuN" 
+       β”˜
+
+    a < 'a'  # Capital letters
+β”Œβ”€         
+β•΅ 0 1 0 0  
+  1 0 0 1  
+          β”˜
+
+    (a<'a') / a  # Not allowed
+Error: 𝕨/𝕩: Components of 𝕨 must have rank 0 or 1
+
+    (a<'a') /β—‹β₯Š a
+"BQN"
+
+

Over is closely connected with the Under modifier, which performs all the same steps but then undoes 𝔾 afterwards.

diff --git a/docs/doc/index.html b/docs/doc/index.html index 49567105..821de18a 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -47,6 +47,7 @@
  • Array depth (≑ and βš‡)
  • Array dimensions (β‰’=β‰ )
  • Assert and Catch (! and ⎊)
    • +
  • Atop and Over (βˆ˜β—‹)
  • Deshape and Reshape (β₯Š)
  • Enclose (<)
  • Find (⍷)
    • diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html index 4def02cf..dda31281 100644 --- a/docs/doc/primitive.html +++ b/docs/doc/primitive.html @@ -437,13 +437,13 @@ ∘ -Atop +Atop {𝔽𝕨𝔾𝕩} Apply 𝔾 to both arguments and 𝔽 to the result β—‹ -Over +Over {(𝔾𝕨)𝔽𝔾𝕩} Apply 𝔾 to each argument and 𝔽 to the results diff --git a/docs/help/atop.html b/docs/help/atop.html index 02764808..04827555 100644 --- a/docs/help/atop.html +++ b/docs/help/atop.html @@ -6,6 +6,7 @@
    (github) / BQN / help

    Ring Operator (∘)

    π”½βˆ˜π”Ύ 𝕩: Atop

    +

    β†’full documentation

    Apply 𝔾 to 𝕩, then apply 𝔽 (𝔽 𝔾 𝕩).

    𝔽 and 𝔾 must be monadic.

    ↗️
        -∘- 5
@@ -15,6 +16,7 @@
 5

    𝕨 π”½βˆ˜π”Ύ 𝕩: Dyadic Atop

    +

    β†’full documentation

    Apply 𝔾 to 𝕨 and 𝕩, then apply 𝔽 (𝔽 (𝕨 𝔾 𝕩)).

    𝔽 must be monadic, and 𝔾 must be dyadic.

    ↗️
        1 -∘+ 2
diff --git a/docs/help/over.html b/docs/help/over.html
index 8fe4c1eb..f7c86560 100644
--- a/docs/help/over.html
+++ b/docs/help/over.html
@@ -6,6 +6,7 @@
 
    (github) / BQN / help
    
 
    Circle (β—‹)
    
 
    𝔽○𝔾 𝕩: Atop
    
+
    β†’full documentation
    
 
    Apply 𝔾 to 𝕩, then apply 𝔽 (𝔽 𝔾 𝕩).
    
 
    𝔽 and 𝔾 must be monadic.
    
 ↗️
        -β—‹- 5
@@ -15,6 +16,7 @@
 5
 
    
 
    𝕨 𝔽○𝔾 𝕩: Over
    
+
    β†’full documentation
    
 
    Apply 𝔾 to 𝕨 and 𝕩, then apply 𝔽 to them ((𝔾 𝕨) 𝔽 (𝔾 𝕩)).
    
 
    𝔽 must be dyadic, 𝔾 must be monadic.
    
 ↗️
        1 +β—‹- 2
-- 
cgit v1.2.3