1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
|
<head>
<link href="../favicon.ico" rel="shortcut icon" type="image/x-icon"/>
<link href="../style.css" rel="stylesheet"/>
<title>BQN Tutorial: Working with lists</title>
</head>
<div class="nav">(<a href="https://github.com/mlochbaum/BQN">github</a>) / <a href="../index.html">BQN</a> / <a href="index.html">tutorial</a></div>
<h1 id="tutorial-working-with-lists"><a class="header" href="#tutorial-working-with-lists">Tutorial: Working with lists</a></h1>
<p>Enough with all these preliminaries like learning how to read basic expressions. Let's get into what makes BQN special.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMSwgMiwgM+KfqQ==">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>2</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Bracket'>⟩</span>
⟨ 1 2 3 ⟩
</pre>
<p>This is a list. Wait for it…</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMSwgMiwgM+KfqSArIDE=">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span> <span class='Number'>2</span><span class='Separator'>,</span> <span class='Number'>3</span><span class='Bracket'>⟩</span> <span class='Function'>+</span> <span class='Number'>1</span>
⟨ 2 3 4 ⟩
</pre>
<p>There we go. Now in BQN arrays are not just lists, which are a 1-dimensional data structure, but can have any number of dimensions. In this tutorial we're going to discuss lists only, leaving the 5-dimensional stuff for later. So we're really only seeing the power of <a href="https://aplwiki.com/wiki/K">K</a>, an APL-family language that only uses lists (and dictionaries, which BQN doesn't have). K was powerful enough for Arthur Whitney to found <a href="https://en.wikipedia.org/wiki/Kx_Systems">two</a> <a href="https://shakti.com/">companies</a> and make millions and millions of dollars, and BQN's compiler also runs almost entirely on lists, so this is probably enough power for one webpage.</p>
<h2 id="list-notation"><a class="header" href="#list-notation">List notation</a></h2>
<p>There are three kinds of list notation in BQN. Each of them has a subject role overall, even if expressions used inside it might have other roles. First, a <em>string</em> is a list of characters, and is written by placing those characters in double quotes.</p>
<pre><span class='String'>"Text!"</span>
</pre>
<table class='primitives'>
<tr>
<td><span class='String'>"</span></td>
<td></td>
<td colspan='2'>String</td>
</tr>
<tr>
<td><span class='Bracket'>⟨</span></td>
<td><kbd>\(</kbd></td>
<td colspan='2'>Start list</td>
</tr>
<tr>
<td><span class='Bracket'>⟩</span></td>
<td><kbd>\)</kbd></td>
<td colspan='2'>End list</td>
</tr>
<tr>
<td><span class='Separator'>⋄</span></td>
<td><kbd>\;</kbd></td>
<td colspan='2'>Separator</td>
</tr>
<tr>
<td><span class='Separator'>,</span></td>
<td></td>
<td colspan='2'>Separator</td>
</tr>
</table>
<p>Just one character needs to be escaped to be used a string: the double quote has to be written twice—a lone double quote would end the string, of course. Any other character, including a newline, can be placed directly in a string. For example, <code><span class='String'>"'"""</span></code> is a string with two characters, the single and double quote.</p>
<p>Second, <em>list notation</em> uses angle brackets <code><span class='Bracket'>⟨⟩</span></code>. The <em>elements</em> in the list are kept apart with one of the three <em>separator</em> characters: <code><span class='Separator'>,</span></code>, <code><span class='Separator'>⋄</span></code>, and newline. Anything can be used as an element, even a function, or a modifier like <code><span class='Modifier2'>∘</span></code>. Here's a list containing a number, a 2-modifier, a string, and a non-string list:</p>
<pre><span class='Bracket'>⟨</span> <span class='Number'>π</span><span class='Separator'>,</span> <span class='Modifier2'>∘</span><span class='Separator'>,</span> <span class='String'>"element"</span> <span class='Separator'>⋄</span> <span class='Bracket'>⟨</span><span class='String'>'l'</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>5</span><span class='Separator'>,</span><span class='String'>'t'</span><span class='Bracket'>⟩</span> <span class='Bracket'>⟩</span>
</pre>
<p>The two characters <code><span class='Separator'>,</span></code> and <code><span class='Separator'>⋄</span></code> are completely interchangeable, and newline is nearly the same but has the additional function of ending a comment (I guess now's as good a time as any to officially point out that <em>comments</em> start with <code><span class='Comment'>#</span></code> and end with a newline, and have no effect on the program but may in rare cases have an effect on the reader). You can use extra separators anywhere in a list: leading, trailing, and repeated separators are ignored.</p>
<pre><span class='Bracket'>⟨</span>
<span class='String'>"putting"</span> <span class='Comment'># This is a comment
</span> <span class='String'>"a"</span><span class='Separator'>,</span> <span class='Comment'># That , wasn't needed
</span> <span class='String'>"list"</span>
<span class='Comment'># An extra newline won't hurt anything
</span> <span class='String'>"on"</span><span class='Separator'>,</span><span class='String'>"multiple"</span> <span class='Comment'># Two elements here
</span> <span class='String'>"lines"</span>
<span class='Bracket'>⟩</span>
</pre>
<table class='primitives'>
<tr>
<td><span class='Comment'>#</span></td>
<td></td>
<td colspan='2'>Comment</td>
</tr>
<tr>
<td><span class='Ligature'>‿</span></td>
<td><kbd>\ </kbd></td>
<td colspan='2'>Strand</td>
</tr>
</table>
<p>Finally, <em>strand notation</em> is a shortcut for simple lists, like one that just lists a few numbers. It's written with the <em>ligature</em> <code><span class='Ligature'>‿</span></code>, which has a higher precedence than either functions or operators (and on the BQN keyboard, the ligature is written with a backslash, then a space). A sequence of values joined with ligatures becomes a list, so that for example the following two expressions are equivalent:</p>
<pre><span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Function'>+</span><span class='Separator'>,</span><span class='Function'>-</span><span class='Bracket'>⟩</span>
<span class='Number'>2</span><span class='Ligature'>‿</span><span class='Function'>+</span><span class='Ligature'>‿</span><span class='Function'>-</span>
</pre>
<p>Strand notation is shorter and looks less cluttered in this example. As with lists, anything goes in a strand, but if it's the result of a function or operator, or another strand, then it has to be put in parentheses first. With one set of parentheses, a strand will be just as long as the equivalent bracketed list, and with two you're better off using the list.</p>
<p>An individual ligature part of BQN syntax, not a value, and it doesn't do something specific like a function does. It's the sequence of ligatures that makes whatever they join together into a list. So if we parenthesize either ligature below, we get a different result! Ligatures aren't right-associative or left-associative.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MOKAvzHigL8yCigw4oC/MSnigL8yCjDigL8oMeKAvzIp">↗️</a><pre> <span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span>
⟨ 0 1 2 ⟩
<span class='Paren'>(</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span><span class='Paren'>)</span><span class='Ligature'>‿</span><span class='Number'>2</span>
⟨ ⟨ 0 1 ⟩ 2 ⟩
<span class='Number'>0</span><span class='Ligature'>‿</span><span class='Paren'>(</span><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Paren'>)</span>
⟨ 0 ⟨ 1 2 ⟩ ⟩
</pre>
<h2 id="bqn-types"><a class="header" href="#bqn-types">BQN types</a></h2>
<p>Now that six of the seven BQN types have been introduced, let's make a diagram:</p>
<svg viewBox='-96 -36 600 204'>
<g stroke-width='2'>
<path d='M0 12A12 12 0 0 1 12 0L260 0A12 12 0 0 1 272 12L272 52A12 12 0 0 0 284 64L396 64A12 12 0 0 1 408 76L408 116A12 12 0 0 1 396 128L12 128A12 12 0 0 1 0 116Z' class='yellow'/>
<rect width='392' height='48' x='8' y='8' rx='10px' class='purple'/>
<rect width='392' height='48' x='8' y='72' rx='10px' class='bluegreen'/>
</g>
<g text-anchor='middle' fill='currentColor'>
<g font-size='18px'>
<text x='68' y='32' dy='0.32em'>Number</text>
<text x='68' y='96' dy='0.32em'>Function</text>
<text x='204' y='32' dy='0.32em'>Character</text>
<text x='204' y='96' dy='0.32em'>1-modifier</text>
<text x='340' y='32' dy='0.32em'>Array</text>
<text x='340' y='96' dy='0.32em'>2-modifier</text>
</g>
<g font-size='18px'>
<text class='purple' x='102' y='-12.8' dy='0.32em'>Data</text>
<text class='bluegreen' x='102' y='140.8' dy='0.32em'>Operation</text>
<text class='yellow' x='299.2' y='147.2' dy='0.32em'>Atom</text>
</g>
</g>
</svg>
<p>Lists are just one-dimensional arrays. Types are divided into <em>data types</em>, which tend to have a subject role, and <em>operation types</em>, which tend to have a role matching their type. Also, any value that's not an array, such as everything we used in the last tutorial, is called an <em>atom</em>.</p>
<h2 id="arithmetic-on-lists"><a class="header" href="#arithmetic-on-lists">Arithmetic on lists</a></h2>
<p>Arithmetic functions automatically apply to each element of a list argument. If both arguments are lists, they have to have the same length, and they're matched up one element at a time.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=w7cg4p+oMiwzLDTin6kKCiJBUEwiICsgMQoKIjMxNDE1IiAtICcwJwoKNOKAvzPigL8y4oC/MSDii4YgMeKAvzLigL8z4oC/NA==">↗️</a><pre> <span class='Function'>÷</span> <span class='Bracket'>⟨</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩</span>
⟨ 0.5 0.3333333333333333 0.25 ⟩
<span class='String'>"APL"</span> <span class='Function'>+</span> <span class='Number'>1</span>
"BQM"
<span class='String'>"31415"</span> <span class='Function'>-</span> <span class='String'>'0'</span>
⟨ 3 1 4 1 5 ⟩
<span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>⋆</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
⟨ 4 9 8 1 ⟩
</pre>
<p>This list application works recursively, so that lists of lists (and so on) are handled as well. We say that arithmetic functions are <em>pervasive</em>. They dig into their arguments until reaching the atoms.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiDDlyDin6gw4oC/MiDii4QgMeKAvzPigL814p+pCgrin6ggMTAsIDIw4oC/MzAg4p+pICsg4p+oIDHigL8yLCAzIOKfqQ==">↗️</a><pre> <span class='Number'>2</span> <span class='Function'>×</span> <span class='Bracket'>⟨</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>2</span> <span class='Separator'>⋄</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>5</span><span class='Bracket'>⟩</span>
⟨ ⟨ 0 4 ⟩ ⟨ 2 6 10 ⟩ ⟩
<span class='Bracket'>⟨</span> <span class='Number'>10</span><span class='Separator'>,</span> <span class='Number'>20</span><span class='Ligature'>‿</span><span class='Number'>30</span> <span class='Bracket'>⟩</span> <span class='Function'>+</span> <span class='Bracket'>⟨</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Separator'>,</span> <span class='Number'>3</span> <span class='Bracket'>⟩</span>
⟨ ⟨ 11 12 ⟩ ⟨ 23 33 ⟩ ⟩
</pre>
<h2 id="some-list-functions"><a class="header" href="#some-list-functions">Some list functions</a></h2>
<table class='primitives'>
<tr>
<td><span class='Function'>≍</span></td>
<td><kbd>\.</kbd></td>
<td>Solo</td>
<td>Couple</td>
</tr>
<tr>
<td><span class='Function'>∾</span></td>
<td><kbd>\,</kbd></td>
<td></td>
<td>Join To</td>
</tr>
<tr>
<td><span class='Function'>⌽</span></td>
<td><kbd>\q</kbd></td>
<td>Reverse</td>
<td>Rotate</td>
</tr>
</table>
<p>Let's introduce a few primitives to work with lists.</p>
<p>Make one or two atom arguments into a list with <code><span class='Function'>≍</span></code>, pronounced Solo in the one-argument case and Couple in the two-argument case. This might not seem to merit a symbol but there's more to come. Don't call it on lists and ponder the results, igniting a hunger for ever more dimensions.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4omNIDQKCjIg4omNIDQ=">↗️</a><pre> <span class='Function'>≍</span> <span class='Number'>4</span>
⟨ 4 ⟩
<span class='Number'>2</span> <span class='Function'>≍</span> <span class='Number'>4</span>
⟨ 2 4 ⟩
</pre>
<p>Concatenate lists with Join To (<code><span class='Function'>∾</span></code>). The little chain link symbol—technically "inverted lazy S"—is my favorite in BQN. Hook those lists together!</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4p+oMSwyLDPin6kg4oi+ICJhYmMiCgowIOKIviDin6gxLDIsM+KfqQoKInBsdXJhbCIg4oi+ICdzJw==">↗️</a><pre> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Bracket'>⟩</span> <span class='Function'>∾</span> <span class='String'>"abc"</span>
⟨ 1 2 3 'a' 'b' 'c' ⟩
<span class='Number'>0</span> <span class='Function'>∾</span> <span class='Bracket'>⟨</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Bracket'>⟩</span>
⟨ 0 1 2 3 ⟩
<span class='String'>"plural"</span> <span class='Function'>∾</span> <span class='String'>'s'</span>
"plurals"
</pre>
<p>The last two examples show that you can join a list to an atom, making it the first or last element of the result. This is a little suspect because if you decide the data being stored is more complicated and start using a list instead of an atom, then it will no longer be used as a single element but rather a subsection of the result. So I would only use that shortcut for something like a numeric literal that's clearly an atom and will stay that way, and otherwise wrap those atomic arguments in some <code><span class='Bracket'>⟨⟩</span></code> brackets. Join will even work with two atoms, but in that case I'd say it makes more sense to use Couple instead.</p>
<p>Reverse (<code><span class='Function'>⌽</span></code>) puts the list back to front.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy9ICJkcmF3ZXIi">↗️</a><pre> <span class='Function'>⌽</span> <span class='String'>"drawer"</span>
"reward"
</pre>
<p>With a left argument <code><span class='Function'>⌽</span></code> means Rotate instead, and shifts values over by the specified amount, wrapping those that go off the end to the other side. A positive value rotates to the left, and a negative one rotates right.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiDijL0g4p+oMCwxLDIsMyw04p+pCsKvMSDijL0gImJjZGVhIg==">↗️</a><pre> <span class='Number'>2</span> <span class='Function'>⌽</span> <span class='Bracket'>⟨</span><span class='Number'>0</span><span class='Separator'>,</span><span class='Number'>1</span><span class='Separator'>,</span><span class='Number'>2</span><span class='Separator'>,</span><span class='Number'>3</span><span class='Separator'>,</span><span class='Number'>4</span><span class='Bracket'>⟩</span>
⟨ 2 3 4 0 1 ⟩
<span class='Number'>¯1</span> <span class='Function'>⌽</span> <span class='String'>"bcdea"</span>
"abcde"
</pre>
<h3 id="and-modifiers"><a class="header" href="#and-modifiers">…and modifiers</a></h3>
<table class='primitives'>
<tr>
<td><span class='Modifier'>¨</span></td>
<td><kbd>\2</kbd></td>
<td colspan='2'>Each</td>
</tr>
<tr>
<td><span class='Modifier'>´</span></td>
<td><kbd>\5</kbd></td>
<td colspan='2'>Fold</td>
</tr>
<tr>
<td><span class='Function'>∾</span></td>
<td><kbd>\,</kbd></td>
<td>Join</td>
<td>Join To</td>
</tr>
</table>
<p>The 1-modifier Each (<code><span class='Modifier'>¨</span></code>) applies its operand to every element of a list argument: it's the same as <code><span class='Value'>map</span></code> in a functional programming language. With two list arguments (which have to have the same length), Each pairs the corresponding elements from each, a bit like a <code><span class='Value'>zip</span></code> function. If one argument is a list and one's an atom, the atom is reused every time instead.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oy9wqggImFiY2Qi4oC/IkFCQ0RFRiLigL8iMDEiCgoic3RyaW5nIuKAvyJsaXN0IuKAvyJhcnJheSIg4oi+wqggJ3MnCgoiYWJjIiDiiY3CqCDijL0gImFiYyI=">↗️</a><pre> <span class='Function'>⌽</span><span class='Modifier'>¨</span> <span class='String'>"abcd"</span><span class='Ligature'>‿</span><span class='String'>"ABCDEF"</span><span class='Ligature'>‿</span><span class='String'>"01"</span>
⟨ "dcba" "FEDCBA" "10" ⟩
<span class='String'>"string"</span><span class='Ligature'>‿</span><span class='String'>"list"</span><span class='Ligature'>‿</span><span class='String'>"array"</span> <span class='Function'>∾</span><span class='Modifier'>¨</span> <span class='String'>'s'</span>
⟨ "strings" "lists" "arrays" ⟩
<span class='String'>"abc"</span> <span class='Function'>≍</span><span class='Modifier'>¨</span> <span class='Function'>⌽</span> <span class='String'>"abc"</span>
⟨ "ac" "bb" "ca" ⟩
</pre>
<p>Fold (<code><span class='Modifier'>´</span></code>) is the higher-order function also known as reduce or accumulate. It applies its operand function between each pair of elements in a list argument. For example, <code><span class='Function'>+</span><span class='Modifier'>´</span></code> gives the sum of a list and <code><span class='Function'>×</span><span class='Modifier'>´</span></code> gives its product.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0IDLigL8z4oC/NArDl8K0IDLigL8z4oC/NA==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
9
<span class='Function'>×</span><span class='Modifier'>´</span> <span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span>
24
</pre>
<p>To match the order of BQN evaluation, Fold moves over its argument array from right to left. You'd get the same result by writing the operand function in between each element of the argument list, but you'd also write the function a lot of times.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=LcK0IDHigL8y4oC/M+KAvzTigL81CjEtMi0zLTQtNQ==">↗️</a><pre> <span class='Function'>-</span><span class='Modifier'>´</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>3</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>5</span>
3
<span class='Number'>1</span><span class='Function'>-</span><span class='Number'>2</span><span class='Function'>-</span><span class='Number'>3</span><span class='Function'>-</span><span class='Number'>4</span><span class='Function'>-</span><span class='Number'>5</span>
3
</pre>
<p>With this evaluation order, <code><span class='Function'>-</span><span class='Modifier'>´</span></code> gives the <em>alternating sum</em> of its argument. Think of it this way: the left argument of each <code><span class='Function'>-</span></code> is a single number, while the right argument is made up of all the numbers to the right subtracted together. So each <code><span class='Function'>-</span></code> flips the sign of every number to its right, and every number is negated by all the <code><span class='Function'>-</span></code>s to its left. The first number (<code><span class='Number'>1</span></code> above) never gets negated, the second is negated once, the third is negated twice, returning it to its original value… the signs alternate.</p>
<p><em>Hey, isn't it dissonant that the first, second, and third numbers are negated zero, one, and two times? If they were the zeroth, first, and second it wouldn't be…</em></p>
<p>You can fold with the Join To function to join several lists together:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oi+wrQg4p+oICJjb24iLCAiY2F0IiwgImVuYXQiLCAiZSIg4p+p">↗️</a><pre> <span class='Function'>∾</span><span class='Modifier'>´</span> <span class='Bracket'>⟨</span> <span class='String'>"con"</span><span class='Separator'>,</span> <span class='String'>"cat"</span><span class='Separator'>,</span> <span class='String'>"enat"</span><span class='Separator'>,</span> <span class='String'>"e"</span> <span class='Bracket'>⟩</span>
"concatenate"
</pre>
<p>But you shouldn't! Just <code><span class='Function'>∾</span></code> will do the job for you—with no left argument it's just called "Join" (it's like Javascript's <code><span class='Value'>.join</span><span class='Paren'>()</span></code>, but with no separator and not specific to strings). And it could do more jobs if you had more dimensions. But I'm sure that's the furthest thing from your mind.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oi+IOKfqCAiY29uIiwgImNhdCIsICJlbmF0IiwgImUiIOKfqQ==">↗️</a><pre> <span class='Function'>∾</span> <span class='Bracket'>⟨</span> <span class='String'>"con"</span><span class='Separator'>,</span> <span class='String'>"cat"</span><span class='Separator'>,</span> <span class='String'>"enat"</span><span class='Separator'>,</span> <span class='String'>"e"</span> <span class='Bracket'>⟩</span>
"concatenate"
</pre>
<h2 id="example-base-decoding"><a class="header" href="#example-base-decoding">Example: base decoding</a></h2>
<p>Some people like to imagine that robots or other techno-beings speak entirely in binary-encoded ASCII, like for instance "01001110 01100101 01110010 01100100 00100001". This is dumb for a lot of reasons, and the encoded text probably just says something inane, but you're a slave to curiosity and can't ignore it. Are one and a half tutorials of BQN enough to clear your conscience?</p>
<table class='primitives'>
<tr>
<td><span class='Function'>↕</span></td>
<td><kbd>\d</kbd></td>
<td>Range</td>
<td></td>
</tr>
<tr>
<td><span class='Modifier2'>⊸</span></td>
<td><kbd>\h</kbd></td>
<td>Bind?</td>
<td></td>
</tr>
</table>
<p>Almost. It's really close. There are just two things missing, so I'll cover those and can we agree one and three-quarters is pretty good? First is Range (<code><span class='Function'>↕</span></code>), which is called on a number to give all the natural numbers less than it:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=4oaVIDg=">↗️</a><pre> <span class='Function'>↕</span> <span class='Number'>8</span>
⟨ 0 1 2 3 4 5 6 7 ⟩
</pre>
<p>Natural numbers in BQN start at 0. I'll get to the second function in a moment, but first let's consider how we'd decode just one number in binary. I'll pick a smaller one: 9 is 1001 in binary. Like the first 1 in decimal 1001 counts for one thousand or <code><span class='Number'>10</span><span class='Function'>⋆</span><span class='Number'>3</span></code>, the first one in binary 1001 counts for 8, which is <code><span class='Number'>2</span><span class='Function'>⋆</span><span class='Number'>3</span></code>. We can put each number next to its place value like this:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=OOKAvzTigL8y4oC/MSDiiY3CqCAx4oC/MOKAvzDigL8x">↗️</a><pre> <span class='Number'>8</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>≍</span><span class='Modifier'>¨</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span>
⟨ ⟨ 8 1 ⟩ ⟨ 4 0 ⟩ ⟨ 2 0 ⟩ ⟨ 1 1 ⟩ ⟩
</pre>
<p>To get the value we multiply each number by its place value and then add them up.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0IDjigL804oC/MuKAvzEgw5cgMeKAvzDigL8w4oC/MQ==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´</span> <span class='Number'>8</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span> <span class='Function'>×</span> <span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span>
9
</pre>
<p>Now we'd like to generate that list <code><span class='Number'>8</span><span class='Ligature'>‿</span><span class='Number'>4</span><span class='Ligature'>‿</span><span class='Number'>2</span><span class='Ligature'>‿</span><span class='Number'>1</span></code> instead of writing it out, particularly because it needs to be twice as long to decode eight-bit ASCII characters (where the first bit is always zero come on robots would never use such an inefficient format). It's the first four powers of two, or two to the power of the first four natural numbers, in reverse. While we're at it, let's get <code><span class='Number'>1</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>0</span><span class='Ligature'>‿</span><span class='Number'>1</span></code> from <code><span class='String'>"1001"</span></code> by subtracting <code><span class='String'>'0'</span></code>. Nice.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=MiDii4Yg4oaVNAoK4oy9MuKLhuKGlTQKCijijL0y4ouG4oaVNCkgw5cgIjEwMDEiLScwJwoKK8K0ICjijL0y4ouG4oaVNCkgw5cgIjEwMDEiLScwJw==">↗️</a><pre> <span class='Number'>2</span> <span class='Function'>⋆</span> <span class='Function'>↕</span><span class='Number'>4</span>
⟨ 1 2 4 8 ⟩
<span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>4</span>
⟨ 8 4 2 1 ⟩
<span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>×</span> <span class='String'>"1001"</span><span class='Function'>-</span><span class='String'>'0'</span>
⟨ 8 0 0 1 ⟩
<span class='Function'>+</span><span class='Modifier'>´</span> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>×</span> <span class='String'>"1001"</span><span class='Function'>-</span><span class='String'>'0'</span>
9
</pre>
<p>Lot of functions up there. Notice how I need to use parentheses for the left argument of a function if it's compound, but never for the right argument, and consequently never with a one-argument function.</p>
<svg viewBox='-131.34 -34 512 210'>
<g font-family='BQN,monospace' font-size='18px' class='Paren' fill='currentColor'>
<rect class='code' stroke-width='1' rx='10' x='-2948.48' y='-1536' width='292.68' height='190'/>
<text><tspan class='Function'>+</tspan><tspan class='Modifier'>´</tspan> <tspan class='Paren'>(</tspan><tspan class='Function'>⌽</tspan><tspan class='Number'>2</tspan><tspan class='Function'>⋆</tspan><tspan class='Function'>↕</tspan><tspan class='Number'>4</tspan><tspan class='Paren'>)</tspan> <tspan class='Function'>×</tspan> <tspan class='String'>"1001"</tspan><tspan class='Function'>-</tspan><tspan class='String'>'0'</tspan></text>
<path stroke='currentColor' fill='none' stroke-width='1' d='M233.06 1.9V20.9H211.38'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M173.44 1.9V20.9H211.38'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M211.38 20.9V96.9H124.66'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M92.14 1.9V39.9H81.3'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M81.3 39.9V58.9H70.46'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M59.62 1.9V58.9H70.46'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M70.46 58.9V77.9H48.78'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M48.78 77.9V96.9H124.66'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M124.66 96.9V134.9H16.26'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M5.42 1.9V115.9H16.26'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M16.26 115.9V134.9H16.26'/>
<path stroke='currentColor' fill='none' stroke-width='1' d='M16.26 134.9V153.9H-8.13'/>
<g font-size='15px' text-anchor='middle'>
<g class='codeCover' stroke-width='8' stroke-linejoin='round'>
<text x='31696.16' y='1664'>'0'</text>
<text x='28747.68' y='1664'>-</text>
<text x='23587.84' y='1664'>"1001"</text>
<text x='16953.76' y='6528'>×</text>
<text x='12531.04' y='2880'>4</text>
<text x='11056.8' y='2880'>↕</text>
<text x='9582.56' y='4096'>⋆</text>
<text x='8108.32' y='4096'>2</text>
<text x='6634.08' y='5312'>⌽</text>
<text x='2211.36' y='7744'>´</text>
<text x='737.12' y='7744'>+</text>
</g>
<g opacity='0.9'>
<text x='31696.16' y='1664'><tspan class='String'>'0'</tspan></text>
<text x='28747.68' y='1664'><tspan class='Function'>-</tspan></text>
<text x='23587.84' y='1664'><tspan class='String'>"1001"</tspan></text>
<text x='16953.76' y='6528'><tspan class='Function'>×</tspan></text>
<text x='12531.04' y='2880'><tspan class='Number'>4</tspan></text>
<text x='11056.8' y='2880'><tspan class='Function'>↕</tspan></text>
<text x='9582.56' y='4096'><tspan class='Function'>⋆</tspan></text>
<text x='8108.32' y='4096'><tspan class='Number'>2</tspan></text>
<text x='6634.08' y='5312'><tspan class='Function'>⌽</tspan></text>
<text x='2211.36' y='7744'><tspan class='Modifier'>´</tspan></text>
<text x='737.12' y='7744'><tspan class='Function'>+</tspan></text>
</g>
</g>
</g>
</svg>
<p>Representing our ASCII statement as a list of lists, we convert each digit to a number as before:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=JzAnIC3LnCAiMDEwMDExMTAi4oC/IjAxMTAwMTAxIuKAvyIwMTExMDAxMCLigL8iMDExMDAxMDAi4oC/IjAwMTAwMDAxIg==">↗️</a><pre> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01001110"</span><span class='Ligature'>‿</span><span class='String'>"01100101"</span><span class='Ligature'>‿</span><span class='String'>"01110010"</span><span class='Ligature'>‿</span><span class='String'>"01100100"</span><span class='Ligature'>‿</span><span class='String'>"00100001"</span>
⟨ ⟨ 0 1 0 0 1 1 1 0 ⟩ ⟨ 0 1 1 0 0 1 0 1 ⟩ ⟨ 0 1 1 1 0 0 1 0 ⟩ ⟨ 0 1 1 0 0 1 0 0 ⟩ ⟨ 0 0 1 0 0 0 0 1 ⟩ ⟩
</pre>
<p>Now we need to multiply each digit by the right place value, and add them up. The adding part is easy, just requiring an Each.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0wqggJzAnIC3LnCAiMDEwMDExMTAi4oC/IjAxMTAwMTAxIuKAvyIwMTExMDAxMCLigL8iMDExMDAxMDAi4oC/IjAwMTAwMDAxIg==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´¨</span> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01001110"</span><span class='Ligature'>‿</span><span class='String'>"01100101"</span><span class='Ligature'>‿</span><span class='String'>"01110010"</span><span class='Ligature'>‿</span><span class='String'>"01100100"</span><span class='Ligature'>‿</span><span class='String'>"00100001"</span>
⟨ 4 4 4 3 2 ⟩
</pre>
<p>Multiplication is harder, and if we try to multiply by the place value list directly it doesn't go so well.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=KOKMvTLii4bihpU4KSDDlyAnMCcgLcucICIwMTAwMTExMCLigL8iMDExMDAxMDEi4oC/IjAxMTEwMDEwIuKAvyIwMTEwMDEwMCLigL8iMDAxMDAwMDEi">↗️</a><pre> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>8</span><span class='Paren'>)</span> <span class='Function'>×</span> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01001110"</span><span class='Ligature'>‿</span><span class='String'>"01100101"</span><span class='Ligature'>‿</span><span class='String'>"01110010"</span><span class='Ligature'>‿</span><span class='String'>"01100100"</span><span class='Ligature'>‿</span><span class='String'>"00100001"</span>
ERROR
</pre>
<p>This is because the list on the left has length 8 while the list on the right has length 5. The <em>elements</em> of the list on the right have length 8, but BQN can't be expected to know you want to connect the two arguments in that particular way. Especially considering that if you happen to have 8 characters then the right argument <em>will</em> have length 8!</p>
<p>There are a few ways to handle this. What we'll do is <em>bind</em> the place values to <code><span class='Function'>×</span></code> using the 2-modifier <code><span class='Modifier2'>⊸</span></code>. This modifier attaches a left argument to a function.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=ImFiIiDiiL7CqCDin6ggImNkIiwgInV0IiDin6kKCiJhYiLiirjiiL7CqCDin6ggImNkIiwgInV0IiDin6k=">↗️</a><pre> <span class='String'>"ab"</span> <span class='Function'>∾</span><span class='Modifier'>¨</span> <span class='Bracket'>⟨</span> <span class='String'>"cd"</span><span class='Separator'>,</span> <span class='String'>"ut"</span> <span class='Bracket'>⟩</span>
⟨ "acd" "but" ⟩
<span class='String'>"ab"</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Modifier'>¨</span> <span class='Bracket'>⟨</span> <span class='String'>"cd"</span><span class='Separator'>,</span> <span class='String'>"ut"</span> <span class='Bracket'>⟩</span>
⟨ "abcd" "abut" ⟩
</pre>
<p>In the first bit of code above, <code><span class='Modifier'>¨</span></code> matches up its left and right arguments. In the second, we bind <code><span class='String'>"ab"</span></code> to <code><span class='Function'>∾</span></code> first—remember that modifiers associate from left to right, so that <code><span class='String'>"ab"</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Modifier'>¨</span></code> and <code><span class='Paren'>(</span><span class='String'>"ab"</span><span class='Modifier2'>⊸</span><span class='Function'>∾</span><span class='Paren'>)</span><span class='Modifier'>¨</span></code> are the same—and Each only sees one argument. <code><span class='String'>"ab"</span></code>, packed inside Each's operand, is reused each time. The same principle applies to our binary problem:</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0wqggKOKMvTLii4bihpU4KeKKuMOXwqggJzAnIC3LnCAiMDEwMDExMTAi4oC/IjAxMTAwMTAxIuKAvyIwMTExMDAxMCLigL8iMDExMDAxMDAi4oC/IjAwMTAwMDAxIg==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´¨</span> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>8</span><span class='Paren'>)</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Modifier'>¨</span> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01001110"</span><span class='Ligature'>‿</span><span class='String'>"01100101"</span><span class='Ligature'>‿</span><span class='String'>"01110010"</span><span class='Ligature'>‿</span><span class='String'>"01100100"</span><span class='Ligature'>‿</span><span class='String'>"00100001"</span>
⟨ 78 101 114 100 33 ⟩
</pre>
<p>To wrap things up, we just convert from numbers to characters by adding the null character.</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=QCArICvCtMKoICjijL0y4ouG4oaVOCniirjDl8KoICcwJyAty5wgIjAxMDAxMTEwIuKAvyIwMTEwMDEwMSLigL8iMDExMTAwMTAi4oC/IjAxMTAwMTAwIuKAvyIwMDEwMDAwMSI=">↗️</a><pre> <span class='String'>@</span> <span class='Function'>+</span> <span class='Function'>+</span><span class='Modifier'>´¨</span> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>8</span><span class='Paren'>)</span><span class='Modifier2'>⊸</span><span class='Function'>×</span><span class='Modifier'>¨</span> <span class='String'>'0'</span> <span class='Function'>-</span><span class='Modifier'>˜</span> <span class='String'>"01001110"</span><span class='Ligature'>‿</span><span class='String'>"01100101"</span><span class='Ligature'>‿</span><span class='String'>"01110010"</span><span class='Ligature'>‿</span><span class='String'>"01100100"</span><span class='Ligature'>‿</span><span class='String'>"00100001"</span>
"Nerd!"
</pre>
<p>Was it as anticlimactic as you'd hoped? In fact there's a simpler way to do the base decoding as well, using <code><span class='Modifier2'>⊸</span></code>'s mirror image <code><span class='Modifier2'>⟜</span></code> in a different way. We'll discuss that in the next tutorial!</p>
<a class="replLink" title="Open in the REPL" target="_blank" href="https://mlochbaum.github.io/BQN/try.html#code=K8K0ICjijL0y4ouG4oaVNCkgw5cgIjEwMDEiLScwJwor4p+cKCvLnCnCtCDijL0gIjEwMDEiLScwJw==">↗️</a><pre> <span class='Function'>+</span><span class='Modifier'>´</span> <span class='Paren'>(</span><span class='Function'>⌽</span><span class='Number'>2</span><span class='Function'>⋆↕</span><span class='Number'>4</span><span class='Paren'>)</span> <span class='Function'>×</span> <span class='String'>"1001"</span><span class='Function'>-</span><span class='String'>'0'</span>
9
<span class='Function'>+</span><span class='Modifier2'>⟜</span><span class='Paren'>(</span><span class='Function'>+</span><span class='Modifier'>˜</span><span class='Paren'>)</span><span class='Modifier'>´</span> <span class='Function'>⌽</span> <span class='String'>"1001"</span><span class='Function'>-</span><span class='String'>'0'</span>
9
</pre>
<h2 id="summary"><a class="header" href="#summary">Summary</a></h2>
<p>There are three types of syntax that create lists: the <code><span class='String'>"string literal"</span></code> for lists of characters and either enclosing angle brackets <code><span class='Bracket'>⟨⟩</span></code> with <code><span class='Separator'>,</span></code> or <code><span class='Separator'>⋄</span></code> or newline characters or connecting ligatures <code><span class='Ligature'>‿</span></code> for lists with arbitrary elements. The ligature has a higher precedence than functions or modifiers, so we should add it to our precedence table:</p>
<table>
<thead>
<tr>
<th>Precedence</th>
<th>Role</th>
<th>Associativity</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td><code><span class='Paren'>()</span><span class='Bracket'>⟨⟩</span></code></td>
<td>(none)</td>
</tr>
<tr>
<td>1</td>
<td><code><span class='Ligature'>‿</span></code></td>
<td>Non-binary</td>
</tr>
<tr>
<td>2</td>
<td>Modifier</td>
<td>Left-to-right</td>
</tr>
<tr>
<td>3</td>
<td>Function</td>
<td>Right-to-left</td>
</tr>
</tbody>
</table>
<p>The elements of a list can have any syntactic role; it's ignored and the list as a whole is a subject.</p>
<p>We introduced a few new primitives. The links below go to the full documentation pages for them.</p>
<table>
<thead>
<tr>
<th>Glyph</th>
<th>1 arg</th>
<th>2 args</th>
</tr>
</thead>
<tbody>
<tr>
<td><code><span class='Function'>∾</span></code></td>
<td><a href="../doc/join.html">Join</a></td>
<td><a href="../doc/join.html">Join To</a></td>
</tr>
<tr>
<td><code><span class='Function'>≍</span></code></td>
<td><a href="../doc/couple.html">Solo</a></td>
<td><a href="../doc/couple.html">Couple</a></td>
</tr>
<tr>
<td><code><span class='Function'>⌽</span></code></td>
<td><a href="../doc/reverse.html">Reverse</a></td>
<td><a href="../doc/reverse.html#rotate">Rotate</a></td>
</tr>
<tr>
<td><code><span class='Function'>↕</span></code></td>
<td><a href="../doc/range.html">Range</a></td>
<td></td>
</tr>
<tr>
<td><code><span class='Modifier'>¨</span></code></td>
<td><a href="../doc/map.html">Each</a></td>
<td><a href="../doc/map.html#each">Each</a></td>
</tr>
<tr>
<td><code><span class='Modifier'>´</span></code></td>
<td><a href="../doc/fold.html#fold">Fold</a></td>
<td></td>
</tr>
</tbody>
</table>
<p>Additionally, we saw that the arithmetic functions work naturally on lists, automatically applying to every element of a single list argument or pairing up the elements of two list arguments.</p>
<p>Even this small amount of list functionality is enough to tackle some little problems. We haven't even introduced a function notation yet!</p>
|
