From e9eec52cc74713cfde1314319c2fc6c3b19144cf Mon Sep 17 00:00:00 2001 From: Marshall Lochbaum Date: Fri, 15 Apr 2022 12:27:10 -0400 Subject: Documentation for Choose --- docs/doc/choose.html | 30 ++++++++++++++++++++++++++++++ docs/doc/index.html | 1 + docs/doc/primitive.html | 2 +- docs/help/choose.html | 1 + 4 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 docs/doc/choose.html (limited to 'docs') diff --git a/docs/doc/choose.html b/docs/doc/choose.html new file mode 100644 index 00000000..2bcaa223 --- /dev/null +++ b/docs/doc/choose.html @@ -0,0 +1,30 @@ + + + + BQN: Choose + +
(github) / BQN / doc
+

Choose

+

The 2-modifier Choose (โ—ถ) applies one function from a list ๐•˜, based on a selection function ๐”ฝ that returns an index. It's a combinator form of Pick (โŠ‘), so that {fโ†(๐•จ๐”ฝ๐•ฉ)โŠ‘๐•˜ โ‹„ ๐•จF๐•ฉ} is a complete definition. For example, the function below subtracts 1 from an argument if negative and adds 1 if positive.

+โ†—๏ธ
    0โŠธโ‰คโ—ถโŸจ-โŸœ1, +โŸœ1โŸฉยจ 3โ€ฟยฏ1โ€ฟ5
+โŸจ 4 ยฏ2 6 โŸฉ
+
+

Here the selection function ๐”ฝ is 0โŠธโ‰ค, while ๐•˜ is a list of two functions โŸจ-โŸœ1, +โŸœ1โŸฉ. On the first argument, 3, ๐”ฝ3 is 0โ‰ค3, or 1, so the function +โŸœ1 from ๐•˜ is chosen. The use of array indices means "false" comes first in ๐•˜ and "true" comes second, which is backwards relative to if-else constructs in most programming languages (including BQN's own predicates). When using a comparison for ๐”ฝ I strongly prefer to phrase it as nโŠธ< or nโŠธโ‰ค so that smaller values go through the first one and larger functions go through the second. This doesn't apply so much when comparing two arguments since one is smaller but the other's larger, so I don't have an easy technique for that.

+โ†—๏ธ
    2 >โ—ถโŠฃโ€ฟโŠข 6  # A minimum function (โŒŠ)
+2
+
+

The advantage of using an index is that Choose works with any number of options.

+โ†—๏ธ
    Fn โ† (โŠ‘"rtd"โŠ’โŠ)โ—ถโŸจโŒฝ, 1โŠธโ†‘, 1โŠธโ†“, โŠขโŸฉ  # Reverse, take 1, drop 1
+
+    Fn "r123"
+"321r"
+
+    Fn "d123"
+"123"
+
+    Fn "123"  # Default
+"123"
+
+

The selection function in Fn uses Index of (โŠ’) to find the index of the first character in the list "rtd". An extra value in ๐•˜ serves as a default function if it's none of those, since the result of ๐”ฝ is 3 in that case. A similar function that's often useful is Bins, for grouping inputs into intervals rather than by exact matching.

+

Choose is necessary for tacit programming, but tacit programming is not necessary to be an effective BQN programmer! Consider using block features like predicates when Choose isn't working with your program's flow.

+

Because Choose is based on Pick, it retains the features of negative, multidimensional, and multiple selection. Negative indexing might make sense if there's some special ยฏ1 value, and if the options naturally form an array, multidimensional indexing is pretty neat. Selecting multiple values from ๐•˜, which happens if the result of ๐”ฝ is an array of arrays, is never useful because the array result from ๐”ฝ acts as a constant function. It's much clearer to express it as ๐”ฝโŠ‘๐•˜ห™.

diff --git a/docs/doc/index.html b/docs/doc/index.html index c3d6ea2b..66bdbfec 100644 --- a/docs/doc/index.html +++ b/docs/doc/index.html @@ -48,6 +48,7 @@
  • Array dimensions (โ‰ข=โ‰ )
  • Assert and Catch (! and โŽŠ)
  • Atop and Over (โˆ˜โ—‹)
    • +
  • Choose (โ—ถ)
  • Constant (ห™)
  • Deshape and Reshape (โฅŠ)
  • Enclose (<)
    • diff --git a/docs/doc/primitive.html b/docs/doc/primitive.html index db9140b6..aa3fd087 100644 --- a/docs/doc/primitive.html +++ b/docs/doc/primitive.html @@ -473,7 +473,7 @@ โ—ถ -Choose +Choose {fโ†(๐•จ๐”ฝ๐•ฉ)โŠ‘๐•˜ โ‹„ ๐•จF๐•ฉ} Select one of the functions in list ๐•˜ based on ๐”ฝ diff --git a/docs/help/choose.html b/docs/help/choose.html index f56496f0..5c0562a3 100644 --- a/docs/help/choose.html +++ b/docs/help/choose.html @@ -6,6 +6,7 @@
    (github) / BQN / help

    Circle with Lower Right Quadrant (โ—ถ)

    ๐”ฝโ—ถ๐•˜ ๐•ฉ, ๐•จ ๐”ฝโ—ถ๐•˜ ๐•ฉ: Choose

    +

    โ†’full documentation

    Apply ๐”ฝ to the arguments and use the result to pick (โŠ‘) a function from list ๐•˜. Apply the picked function to the arguments.

    โ†—๏ธ
        F โ† โŠขโ—ถ+โ€ฟ-โ€ฟรทโ€ฟร—
 
-- 
cgit v1.2.3