From d291cb7faf2c1856e2cea486b0d935bbb16db2c9 Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Wed, 13 Apr 2022 16:05:00 -0400 Subject: Documentation for Self/Swap --- doc/README.md | 1 + doc/primitive.md | 2 +- doc/swap.md | 30 ++++++++++++++++++ docs/doc/index.html | 1 + docs/doc/primitive.html | 2 +- docs/doc/swap.html | 79 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/help/self_swap.html | 2 ++ help/self_swap.md | 2 ++ 8 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 doc/swap.md create mode 100644 docs/doc/swap.html diff --git a/doc/README.md b/doc/README.md index 4f8c49cf..0560a3a6 100644 --- a/doc/README.md +++ b/doc/README.md @@ -63,6 +63,7 @@ Primitives: - [Scan](scan.md) (`` ` ``) - [Search functions](search.md) (`⊐⊒∊`) - [Select](select.md) (`⊏`) +- [Self and Swap](swap.md) (`˜`) - [Self-search functions](selfcmp.md) (`⊐⊒∊⍷`) - [Shift functions](shift.md) (`»«`) - [Solo, Couple, and Merge](couple.md) (`≍>`) diff --git a/doc/primitive.md b/doc/primitive.md index 03634235..f2b47341 100644 --- a/doc/primitive.md +++ b/doc/primitive.md @@ -68,7 +68,7 @@ Functions that have significant differences from APL equivalents or don't appear Glyph | Name(s) | Definition | Description ------|--------------------|--------------------------------|--------------------------------------- `˙` | Constant | `{𝕩⋄𝕗}` | Return a function that returns the operand -`˜` | Self/Swap | `{𝕩𝔽𝕨⊣𝕩}` | Duplicate one argument or exchange two +`˜` | [Self/Swap](swap.md) | `{𝕩𝔽𝕨⊣𝕩}` | Duplicate one argument or exchange two `∘` | [Atop](compose.md) | `{𝔽𝕨𝔾𝕩}` | Apply `𝔾` to both arguments and `𝔽` to the result `○` | [Over](compose.md) | `{(𝔾𝕨)𝔽𝔾𝕩}` | Apply `𝔾` to each argument and `𝔽` to the results `⊸` | Before/Bind | `{(𝔽𝕨⊣𝕩)𝔾𝕩}` | `𝔾`'s left argument comes from `𝔽` diff --git a/doc/swap.md b/doc/swap.md new file mode 100644 index 00000000..0d9245e3 --- /dev/null +++ b/doc/swap.md @@ -0,0 +1,30 @@ +*View this file with results and syntax highlighting [here](https://mlochbaum.github.io/BQN/doc/swap.html).* + +# Self and Swap + + + +Have the arguments to a function, but not in the right places? Self/Swap (`˜`) will fix it for you. There are only two APL-style 1-modifiers—that is, operands used as functions and applied to arguments—that make sense, and `˜` is both of them. It always calls its operand with two arguments: if there are two arguments to begin with, they are exchanged (Swap), and if there's only one, it's used for both arguments (Self). + +| Name | Call | Definition +|------|--------|:----------: +| Self | ` F˜𝕩` | `𝕩F𝕩` +| Swap | `𝕨F˜𝕩` | `𝕩F𝕨` + +Since `𝕩` is always the left argument, these two definitions can be unified as `{𝕩𝔽𝕨⊣𝕩}`, noting that [Left](identity.md) becomes a plain identity function when the left argument `𝕨` isn't given. + +Swap is arguably less transformative. Some common examples are `-˜` and `÷˜`, since these two functions run the [wrong way](../commentary/problems.md#subtraction-division-and-span-are-backwards) for BQN's evaluation order. This is very often useful in [tacit](tacit.md) programming, and less useful for explicit code. While it sometimes allows for shorter code by making a pair of parentheses unnecessary (say, `(a×b)-c` is `c-˜a×b`), I personally don't think this is always a good idea. My opinion is that it should be used when it makes the semantics a better fit for BQN, but putting the primary argument on the right and a secondary or control argument on the left. + + 'a' ⋈˜ 'b' + + " +" ⊏˜ 0‿1‿1‿0‿0≍1‿0‿1‿0‿1 + +Self re-uses one argument twice. In this way it's a little like [Over](compose.md), which re-uses one *function* twice. A common combination is with Table, `⌜˜`, so that the operand function is called on each combination of elements from the argument to form a square result. For example, `=⌜˜` applied to `↕n` gives the identity matrix of size `n`. + + ט 4 + + =⌜˜ ↕3 + +Note that Self isn't needed with Before (`⊸`) and After (`⟜`), which essentially have a copy built in: for example `F⊸G 𝕩` is the same as `F⊸G˜ 𝕩` by definition. diff --git a/docs/doc/index.html b/docs/doc/index.html index 821de18a..38f7d2cd 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -69,6 +69,7 @@
  • Scan (`)
  • Search functions (⊐⊒∊)
  • Select (⊏)
    • +
  • Self and Swap (˜)
  • Self-search functions (⊐⊒∊⍷)
  • Shift functions (»«)
  • Solo, Couple, and Merge (≍>)
    • diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html index dda31281..c4b48a20 100644 --- a/docs/doc/primitive.html +++ b/docs/doc/primitive.html @@ -431,7 +431,7 @@ ˜ -Self/Swap +Self/Swap {𝕩𝔽𝕨⊣𝕩} Duplicate one argument or exchange two diff --git a/docs/doc/swap.html b/docs/doc/swap.html new file mode 100644 index 00000000..190b0d0a --- /dev/null +++ b/docs/doc/swap.html @@ -0,0 +1,79 @@ + + + + BQN: Self and Swap + +
    (github) / BQN / doc
    +

    Self and Swap

    + + + + Self/Swap + + 𝔽˜ 𝕩 + + + + + 𝔽 + 𝕩 + + + 𝕨 𝔽˜ 𝕩 + + + + + + 𝔽 + 𝕨 + 𝕩 + + + + +

    Have the arguments to a function, but not in the right places? Self/Swap (˜) will fix it for you. There are only two APL-style 1-modifiers—that is, operands used as functions and applied to arguments—that make sense, and ˜ is both of them. It always calls its operand with two arguments: if there are two arguments to begin with, they are exchanged (Swap), and if there's only one, it's used for both arguments (Self).

    + + + + + + + + + + + + + + + + + + + + +
    NameCallDefinition
    Self F˜𝕩𝕩F𝕩
    Swap𝕨F˜𝕩𝕩F𝕨
    +

    Since 𝕩 is always the left argument, these two definitions can be unified as {𝕩𝔽𝕨⊣𝕩}, noting that Left becomes a plain identity function when the left argument 𝕨 isn't given.

    +

    Swap is arguably less transformative. Some common examples are -˜ and ÷˜, since these two functions run the wrong way for BQN's evaluation order. This is very often useful in tacit programming, and less useful for explicit code. While it sometimes allows for shorter code by making a pair of parentheses unnecessary (say, (a×b)-c is c-˜a×b), I personally don't think this is always a good idea. My opinion is that it should be used when it makes the semantics a better fit for BQN, but putting the primary argument on the right and a secondary or control argument on the left.

    +↗️
        'a' ⋈˜ 'b'
+"ba"
+
+    " +" ⊏˜ 0‿1‿1‿0‿0≍1‿0‿1‿0‿1
+┌─       
+╵" ++    
+  + + +" 
+        ┘
+
    +

    Self re-uses one argument twice. In this way it's a little like Over, which re-uses one function twice. A common combination is with Table, ⌜˜, so that the operand function is called on each combination of elements from the argument to form a square result. For example, =⌜˜ applied to ↕n gives the identity matrix of size n.

    +↗️
        ט 4
+16
+
+    =⌜˜ ↕3
+┌─       
+╵ 1 0 0  
+  0 1 0  
+  0 0 1  
+        ┘
+
    +

    Note that Self isn't needed with Before (⊸) and After (⟜), which essentially have a copy built in: for example F⊸G 𝕩 is the same as F⊸G˜ 𝕩 by definition.

    diff --git a/docs/help/self_swap.html b/docs/help/self_swap.html index 3cf26801..cd3e0a1c 100644 --- a/docs/help/self_swap.html +++ b/docs/help/self_swap.html @@ -6,6 +6,7 @@
    (github) / BQN / help

    Small Tilde (˜)

    𝔽˜ 𝕩: Self

    +

    →full documentation

    Supplies 𝕩 as a left argument to 𝔽 (𝕩 𝔽 𝕩).

    ↗️
        1 + 1
 2
@@ -14,6 +15,7 @@
 2

    𝕨 𝔽˜ 𝕩: Swap

    +

    →full documentation

    Swaps the arguments of 𝔽 (𝕩 𝔽 𝕨).

    ↗️
        1 - 2
 ¯1
diff --git a/help/self_swap.md b/help/self_swap.md
index c1e66008..23f1372d 100644
--- a/help/self_swap.md
+++ b/help/self_swap.md
@@ -3,6 +3,7 @@
 # Small Tilde (`˜`)
 
 ## `𝔽˜ 𝕩`: Self
+[→full documentation](../doc/swap.md)
 
 Supplies `𝕩` as a left argument to `𝔽` (`𝕩 𝔽 𝕩`).
 
@@ -13,6 +14,7 @@ Supplies `𝕩` as a left argument to `𝔽` (`𝕩 𝔽 𝕩`).
 
 
 ## `𝕨 𝔽˜ 𝕩`: Swap
+[→full documentation](../doc/swap.md)
 
 Swaps the arguments of `𝔽` (`𝕩 𝔽 𝕨`).
 
-- 
cgit v1.2.3