# Towards Improvements to Stencil

## Background

The stencil operator `⌺` was introduced in Dyalog version 16.0 in 2017. Recently we received some feedback (OK, complaints) that (a) stencil does padding which is unwanted sometimes and needs to be removed from the result and (b) stencil is too slow when it is not supported by special code.

First, stencil in cases supported by special code is much faster than when it is not. The special cases are as follows, from Dyalog ’17 Workshop SA3.

```   {⍵}      {⊢⍵}      {,⍵}      {⊂⍵}
{+/,⍵}    {∧/,⍵}    {∨/,⍵}    {=/,⍵}    {≠/,⍵}

{  +/,A×⍵}    {  +/⍪A×⍤2⊢⍵}
{C<+/,A×⍵}    {C<+/⍪A×⍤2⊢⍵}
```
`C:  `a single number or variable whose value is a single number
`A:  `a variable whose value is a rank-2 or 3 array
The comparison can be` < ≤ ≥ > = ≠ `
odd window size; movement 1; matrix argument

You can test whether a particular case is supported by using a circumlocution to defeat the special case recognizer.

```   )copy dfns cmpx

cmpx '{⍵}⌺3 5⊢y' '{⊢⊢⍵}⌺3 5⊢y' ⊣ y←?100 200⍴0
{⍵}⌺3 5⊢x   → 4.22E¯4 |      0%
{⊢⊢⍵}⌺3 5⊢x → 5.31E¯2 | +12477% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕

cmpx '{⌽⍵}⌺3 5⊢y' '{⊢⊢⌽⍵}⌺3 5⊢y'
{⌽⍵}⌺3 5⊢y   → 2.17E¯1 |  0% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
{⊢⊢⌽⍵}⌺3 5⊢y → 2.21E¯1 | +1% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
```

If the timings are the same then there is no special code.

Padding and performance improvements will take a lot of work. For example, for padding (i.e. the treatment of cells at the edge of the universe) multiple options are possible: no padding, padding, wrap from opposite edge, etc. While working on these improvements I hit upon the idea of writing a stencil function which produces the stencil cells. It only works with no padding and only for movements of 1 (which I understand are common cases), but turns out to be an interesting study.

## A Stencil Function

`⍺ stencell ⍵` produces the stencil cells of size `⍺` from `⍵` , and is equivalent to `{⍵}⌺⍺⊢⍵` after the padded cells are removed.

```stencell←{
⎕io←0                 ⍝ ⎕io delenda est!
s←(≢⍺)↑⍴⍵
f←1+s-⍺               ⍝ frame AKA outer shape
m←⊖×⍀⊖1↓s,1           ⍝ multiplier for each axis
i←⊃∘.+⌿(m,m)×⍳¨f,⍺    ⍝ indices
(⊂i) ⌷ ⍵ ⍴⍨ (×⌿(≢⍺)↑⍴⍵),(≢⍺)↓⍴⍵
}
```

For example, `stencell` is applied to `x` with cell shape `3 5` .

```   ⊢ x←6 10⍴⍳60                    ⍝ (a)
0  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

c←3 5 stencell x                ⍝ (b)
⍴c
4 6 3 5

c ≡ 1 2 ↓ ¯1 ¯2 ↓ {⍵}⌺3 5 ⊢x    ⍝ (c)
1

⊢ e←⊂⍤2 ⊢c                      ⍝ (d)
┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
│ 0  1  2  3  4│ 1  2  3  4  5│ 2  3  4  5  6│ 3  4  5  6  7│ 4  5  6  7  8│ 5  6  7  8  9│
│10 11 12 13 14│11 12 13 14 15│12 13 14 15 16│13 14 15 16 17│14 15 16 17 18│15 16 17 18 19│
│20 21 22 23 24│21 22 23 24 25│22 23 24 25 26│23 24 25 26 27│24 25 26 27 28│25 26 27 28 29│
├──────────────┼──────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│10 11 12 13 14│11 12 13 14 15│12 13 14 15 16│13 14 15 16 17│14 15 16 17 18│15 16 17 18 19│
│20 21 22 23 24│21 22 23 24 25│22 23 24 25 26│23 24 25 26 27│24 25 26 27 28│25 26 27 28 29│
│30 31 32 33 34│31 32 33 34 35│32 33 34 35 36│33 34 35 36 37│34 35 36 37 38│35 36 37 38 39│
├──────────────┼──────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│20 21 22 23 24│21 22 23 24 25│22 23 24 25 26│23 24 25 26 27│24 25 26 27 28│25 26 27 28 29│
│30 31 32 33 34│31 32 33 34 35│32 33 34 35 36│33 34 35 36 37│34 35 36 37 38│35 36 37 38 39│
│40 41 42 43 44│41 42 43 44 45│42 43 44 45 46│43 44 45 46 47│44 45 46 47 48│45 46 47 48 49│
├──────────────┼──────────────┼──────────────┼──────────────┼──────────────┼──────────────┤
│30 31 32 33 34│31 32 33 34 35│32 33 34 35 36│33 34 35 36 37│34 35 36 37 38│35 36 37 38 39│
│40 41 42 43 44│41 42 43 44 45│42 43 44 45 46│43 44 45 46 47│44 45 46 47 48│45 46 47 48 49│
│50 51 52 53 54│51 52 53 54 55│52 53 54 55 56│53 54 55 56 57│54 55 56 57 58│55 56 57 58 59│
└──────────────┴──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘

∪¨ ,¨ e-⍬⍴e                    ⍝ (e)
┌──┬──┬──┬──┬──┬──┐
│0 │1 │2 │3 │4 │5 │
├──┼──┼──┼──┼──┼──┤
│10│11│12│13│14│15│
├──┼──┼──┼──┼──┼──┤
│20│21│22│23│24│25│
├──┼──┼──┼──┼──┼──┤
│30│31│32│33│34│35│
└──┴──┴──┴──┴──┴──┘
```
 (a) The matrix `x` is chosen to make stencil results easier to understand. (b) `stencell` is applied to `x` with cell shape `3 5` . (c) The result of `stencell` is the same as that for `{⍵}⌺` after cells with padding are dropped. (d) Enclose the matrices in `c` (the cells) to make the display more compact and easier to understand. (e) Subsequent discussion is based on the observation that each cell is some scalar integer added to the first cell.

## Indices

The key expression in the computation is

`   ⊃∘.+⌿(m,m)×⍳¨f,⍺ `

where

`   m:  10 1; ` multiplier for each axis
`   f:  4 6; ` multiplier for each axis
`   ⍺:  3 5; ` multiplier for each axis

We discuss a more verbose but equivalent version of this expression,

`   (⊃∘.+⌿m×⍳¨f)∘.+(⊃∘.+⌿m×⍳¨⍺)`

and in particular the right half,` ⊃∘.+⌿m×⍳¨⍺` , which produces the first cell.

```   ⍳⍺               ⍝ ⍳3 5
┌───┬───┬───┬───┬───┐
│0 0│0 1│0 2│0 3│0 4│
├───┼───┼───┼───┼───┤
│1 0│1 1│1 2│1 3│1 4│
├───┼───┼───┼───┼───┤
│2 0│2 1│2 2│2 3│2 4│
└───┴───┴───┴───┴───┘
(⍴⍵)∘⊥¨⍳⍺        ⍝ 6 10∘⊥¨ ⍳3 5
0  1  2  3  4
10 11 12 13 14
20 21 22 23 24
```

Alternatively, this last result obtains by multiplying by `m` the corresponding indices for each axis, where an element of `m` is the increment for a unit in an axis. That is, `m←⊖×⍀⊖1↓s,1` where `s←(≢⍺)↑⍴⍵` is a prefix of the shape of `⍵` . The multipliers are with respect to the argument `⍵` because the indices are required to be with respect to the argument `⍵` .

```   ⍳¨⍺              ⍝ ⍳¨3 5
┌─────┬─────────┐
│0 1 2│0 1 2 3 4│
└─────┴─────────┘
m×⍳¨⍺            ⍝ 10 1×⍳¨3 5
┌───────┬─────────┐
│0 10 20│0 1 2 3 4│
└───────┴─────────┘
∘.+⌿ m×⍳¨⍺       ⍝ ∘.+⌿ 10 1×⍳¨3 5
┌──────────────┐
│ 0  1  2  3  4│
│10 11 12 13 14│
│20 21 22 23 24│
└──────────────┘
((⍴⍵)∘⊥¨⍳⍺) ≡ ⊃∘.+⌿m×⍳¨⍺
1
```

This alternative computation is more efficient because it avoids creating and working on lots of small nested vectors and because the intermediate results for `∘.+⌿` grows fast from one to the next (i.e., `O(⍟n)` iterations in the main loop).

The left half, `⊃∘.+⌿m×⍳¨f` , is similar, and computes the necessary scalar integers to be added to the result of the right half.

```   ⊃ ∘.+⌿ m×⍳¨f     ⍝ ⊃ ∘.+⌿ 10 1×⍳¨4 6
0  1  2  3  4  5
10 11 12 13 14 15
20 21 22 23 24 25
30 31 32 33 34 35
```

The shorter expression derives from the more verbose one by some simple algebra.

```(⊃∘.+⌿m×⍳¨f)∘.+(⊃∘.+⌿m×⍳¨⍺)    ⍝ verbose version
⊃∘.+⌿(m×⍳¨f),m×⍳¨⍺             ⍝ ∘.+ is associative
⊃∘.+⌿(m,m)×(⍳¨f),⍳¨⍺           ⍝ m× distributes over ,
⊃∘.+⌿(m,m)×⍳¨f,⍺               ⍝ ⍳¨ distributes over ,
```

I am actually disappointed that the shorter expression was found ☺; it would have been amusing to have a non-contrived and short expression with three uses of` ∘.+` .

## Cells

Having the indices `i` in hand, the stencil cells obtain by indexing into an appropriate reshape or ravel of the right argument `⍵` . In general, the expression is

```   (⊂i) ⌷ ⍵ ⍴⍨ (×/(≢⍺)↑⍴⍵),(≢⍺)↓⍴⍵
```

`⍺` specifies the cell shape. If `(≢⍺)=≢⍴⍵` , that is, if a length is specified for each axis of `⍵` , the expression is equivalent to `(⊂i)⌷,⍵` or `(,⍵)[i]` ; if `(≢⍺)<≢⍴⍵` , that is, if there are some trailing unstencilled axes, the expression is equivalent to `(,[⍳≢⍺]⍵)[i;…;]` (the leading `≢⍺` axes are ravelled) or `↑(,⊂⍤((≢⍴⍵)-≢⍺)⊢⍵)[i]` (as if the trailing axes were shielded from indexing). The general expression covers both cases.

Application

`stencell` makes it possible to workaround current shortcomings in `⌺` . The alternative approach is to use `stencell` to get all the stencil cells, all at once, and then work on the cells using `⍤` , `+.×` , and
other efficient primitives.

The following example is from Aaron Hsu. In the original problem the size of `x` is` 512 512 64` .

```   K←?64 3 3 64⍴0
x←?256 256 64⍴0

t←1 1↓¯1 ¯1↓{+/⍪K×⍤3⊢⍵}⌺3 3⊢x
⍴t
256 256 64

cmpx '1 1↓¯1 ¯1↓{+/⍪K×⍤3⊢⍵}⌺3 3⊢x'
6.76E0
```

The computation is slow because the cells are rank-3, not supported by special code. Aaron then devised a significant speed-up using a simpler left operand to create the ravels of the cells (but still no special code):

```   t ≡ (1 1↓¯1 ¯1↓{,⍵}⌺3 3⊢x)+.×⍉⍪K
1
cmpx '(1 1↓¯1 ¯1↓{,⍵}⌺3 3⊢x)+.×⍉⍪K'
1.67E0
```

Use of `stencell` would improve the performance a bit further:

```   t ≡ (,⍤3 ⊢3 3 stencell x)+.×⍉⍪K
1
cmpx '(,⍤3 ⊢3 3 stencell x)+.×⍉⍪K'
1.09E0

cmpx '3 3 stencell x'
6.10E¯2
```

The last timing shows that the `stencell` computation is 6% (`6.10e¯2÷1.09e0`) of the total time.

Materializing all the cells does take more space than if the computation is incorporated in the left operand of `⌺` , and is practicable only if the workspace sufficiently large.

```   )copy dfns wsreq

wsreq '1 1↓¯1 ¯1↓{+/⍪K×⍤3⊢⍵}⌺3 3⊢x'
110649900
wsreq '(1 1↓¯1 ¯1↓{,⍵}⌺3 3⊢x)+.×⍉⍪K'
647815900
wsreq '(,⍤3 ⊢3 3 stencell x)+.×⍉⍪K'
333462260
```

## Performance

`stencell` is competitive with `{⍵}⌺` on matrices, where it is supported by special code written in C, and is faster when there is no special code. The benchmarks are done on a larger argument to reduce the effects of padding/unpadding done in `{⍵}⌺` .

```   y2←?200 300⍴0

cmpx '3 5 stencell y2' '1 2↓¯1 ¯2↓{⍵}⌺3 5⊢y2'
3 5 stencell y      → 1.85E¯3 |   0% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
1 2↓¯1 ¯2↓{⍵}⌺3 5⊢y → 2.91E¯3 | +57% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕

cmpx '3 5 stencell y' '{⍵}⌺3 5⊢y'
3 5 stencell y → 1.85E¯3 |   0% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
* {⍵}⌺3 5⊢y      → 1.04E¯3 | -45% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕

y3←?200 300 64⍴0

cmpx '3 5 stencell y3' '1 2↓¯1 ¯2↓{⍵}⌺3 5⊢y3'
3 5 stencell y3      → 8.90E¯2 |    0% ⎕⎕⎕
1 2↓¯1 ¯2↓{⍵}⌺3 5⊢y3 → 7.78E¯1 | +773% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕

cmpx '3 5 stencell y3' '{⍵}⌺3 5⊢y3'
3 5 stencell y3 → 9.38E¯2 |    0% ⎕⎕⎕⎕⎕⎕⎕⎕
* {⍵}⌺3 5⊢y3      → 3.34E¯1 | +256% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
```

There is an interesting question of whether the shorter version of the key computation (in the Indices section above) is faster than the more verbose version.

```   m←10 1 ⋄ f←4 6 ⋄ a←3 5

cmpx '⊃∘.+⌿(m,m)×⍳¨f,a' '(⊃∘.+⌿m×⍳¨f)∘.+(⊃∘.+⌿m×⍳¨a)'
⊃∘.+⌿(m,m)×⍳¨f,a            → 3.75E¯6 |   0% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
(⊃∘.+⌿m×⍳¨f)∘.+(⊃∘.+⌿m×⍳¨a) → 5.20E¯6 | +38% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
```

In this case, it is faster, and I expect it will be faster for cases which arise in stencil calculations, where the argument size is larger than the cell size. But it is easy to think of arguments where `∘.+⌿` is slower than `∘.+` done with a different grouping:

```   cmpx '((⍳0)∘.+⍳100)∘.+⍳200' '(⍳0)∘.+((⍳100)∘.+⍳200)' '⊃∘.+/⍳¨0 100 200'
((⍳0)∘.+⍳100)∘.+⍳200   → 7.86E¯7 |     0% ⎕⎕
(⍳0)∘.+((⍳100)∘.+⍳200) → 1.05E¯5 | +1234% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
⊃∘.+/⍳¨0 100 200       → 1.11E¯5 | +1310% ⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕⎕
```

This question will be explored further in a later post.

# Enhanced Debugging with Function Keys

Sometimes I want an additional functionality in the IDE. (Are you a RIDE user? We’ll cover that too!) For example, the other day, I was tracing through some very long functions to find an error which was being caught by a trap. Since the error was being caught, I couldn’t just let the function run until it would suspend. Again and again, I would press too many times, causing the error to happen and be trapped, and thus having to start all over again.

I wish I could select a line and run until there, I thought. Sure, I could set a break-point there and then continue execution, but that would drop me into the session upon hitting the break-point, and then I’d have to trace back into the function, and remember to clear the break-point. A repetitive work-flow indeed.

## Make it so!

Luckily, I know someone who loves doing repetitive tasks: `⎕PFKEY`. This is what I needed done:

1. Toggle break-point (to set it)
2. Resume execution
3. Trace
4. Toggle break point (to clear it)

A quick look in Options > Configure… > Keyboard Shortcuts > Code revealed that the command codes for these are `BP`, `RM`, `TC`, and `BP` again, so I tried:

``````      'BP' 'RM' 'TC' 'BP' ⎕PFKEY 10
BP  RM  TC  BP ``````

I defined a simple function to test it with, and traced into that:

``````      ⎕FX 'f',⎕D
⎕VR 'f'
∇f
[1]   0
[2]   1
[3]   2
[4]   3
[5]   4
[6]   5
[7]   6
[8]   7
[9]   8
[10]  9
∇
f``````

Then I clicked on the line with a `7` on it, pressed , and lo:

## Keep it so!

Of course, I wouldn’t want to be bothered with setting this up in every session. So here’s a trick to set up F-keys (or anything else for that matter). When Dyalog APL starts up, it will look for MyUCMDs\setup.dyalog in your Documents folder (\$HOME/MyUCMDs/setup.dyalog on non-Windows). If this file contains a function named `Setup`, it will be run whenever APL starts:

``````      ∇Setup
[1]  '<F10> is: ','BP' 'RM' 'TC' 'BP' ⎕PFKEY 10
[2]  ∇
``````

And now, when I start APL:

## Cool, but how about the RIDE?

Right, the RIDE doesn’t support `⎕PFKEY`. However, Edit > Preferences > Shortcuts lets you both find the relevant command codes and assign them to F-keys. Just put `<BP><RM><TC><BP>` (type or paste those sixteen characters, with angle brackets and everything — don’t press the keys they symbolise!) in the `PF10` input field:

The RIDE saves these preferences for you. Note that you can’t assign F-keys in \$HOME/MyUCMDs/setup.dyalog because `⎕PFKEY` has no effect in the RIDE, but you can still use that file to initialise other things.

## Taking it one step further…

After using this for a while, I realised that I often want to “step into” a specific line . That is, I found myself pressing and then (the default keystroke for tracing). So I’ve assigned the same sequence, but with an additional trailing `TC` action:

``````      ∇Setup
[1]  '<F10> is: ','BP' 'RM' 'TC' 'BP' ⎕PFKEY 10
[2]  '<Ctrl>+<F10> is: ','BP' 'RM' 'TC' 'BP' 'TC' ⎕PFKEY 34
[3]  ∇
``````

And for the RIDE, I set `PF34` (which by default is invoked with ) to `<BP><RM><TC><BP><TC>`:

# I-Beam Mnemonics

I-Beam (`⌶`) is an operator that takes as its operand a numeric code and derives a function which isn’t really considered to be part of the APL language – for example: something which could be experimental, which might provide access to parts of the interpreter that should only be accessed with care, or may set up specific conditions within the interpreter to help in testing. Principally, I-Beam functions exist for internal use within Dyalog but as of version 15.0 there are 55 I-Beam functions that are published and available for general use. How on earth are you supposed to remember all the different codes?

To an extent, you are not. It is perhaps no bad thing that they are a little difficult to remember: I-Beam functions are experimental, liable to be changed or even removed and should be used with care. The codes appear to be somewhat random partly because they are somewhat random – mostly selected on the whim of the developer who implemented the function. However, some codes were chosen less randomly than others – quite a few are grouped so that I-Beams that provide related functionality appear consecutively or at least close together but the most interesting ones are “named” – or, at least, given a numeric code that is derived from a name or otherwise memorable value. So here are some of those unofficial mnemonics that may help you better remember them too.

A favourite trick for deriving a code from a meaningful name is to devise a name containing the letters I, V, X, L, C, D and M, and then convert that into a number as if it were a Roman numeral. Thus:

• “Inverted table IndeX of” is abbreviated to IIX, which is I-Beam 8
• “Syntax Colouring” rather awkwardly becomes “Cyntax Colouring”, thence CC and I-Beam 200
• “Called Monadically” is CM, or 900
• “Memory Manager” is MM – I-Beam 2000
• “Line Count” is LC, or rather L,C – 50100

Another favourite is to use numbers that look or sound like something else:

• The compression I-Beam is 219, which looks a bit like “ZIP”
• The case folding I-Beam is 819, or “BIg”
• When support for function trains was in development an I-Beam was used to switch between different implementations – 1060, or “lOCO[motive]” (this I-Beam is no longer in use)
• The number of parallel threads I-Beam is 1111 – four parallel lines
• The fork I-Beam is 4000: 4000 is 4K; “Four K” said very quickly might sound like “Fork”

For others the function is associated, or can be associated, with something already numeric:

• The I-Beam to update function timestamps is 1159 – a memorable time
• The I-Beam to delete the content in unused pockets is 127 – the same as the ASCII code for the delete character
• The draft JSON standard is RFC 7159 and support for it is implemented as `7159⌶`
• The now-deprecated I-Beam to switch between Random Number Generator algorithms is 16807 – the default value used to derive the random seed in a clear workspace

## Tips for the use of I-Beam functions

• Do not use I-Beam functions directly in application code – always encapsulate their use in cover-functions that can quickly be modified to protect your application in the event that Dyalog should change the behaviour of, or withdraw, an I-Beam function.
• Do not use I-Beam functions that are not documented by Dyalog in the Language Reference or elsewhere – those designed to test the interpreter may have undesirable side effects.
• Do let Dyalog know if you find an I-Beam function particularly useful and/or have suggestions for its development. Some new features are initially implemented as I-Beam functions to allow such feedback to shape their final design.

# Loops, Folds and Tuples

For-loops
Given an initial state defined by a number of variables, a for-loop iterates through its argument array modifying the state.

``````    A←... ⋄ B←... ⋄ C←...       ⍝ initial state
:For item :In items         ⍝ iterating through array "items"
A←A ... item            ⍝ new value for A depending on item
C←C ... A ... item      ⍝ new value for C depending on A and item
...                     ⍝ state updated
:EndFor
A B C                       ⍝ final state
``````

In the above example the state comprises just three variables. In general, it may be arbitrarily complex, as can the interactions between its various components within the body of the loop.

Dfns
Dfns don’t have for-loops. Instead, we can use reduction (or “fold”) with an accumulating vector “tuple” of values representing the state. Here is the D-equivalent of the above code:

``````    ⊃{                      ⍝ next item is ⍺
(A B C)←⍵           ⍝ named items of tuple ⍵
A∆←A ... ⍺          ⍝ new value for A depending on item ⍺
C∆←C ... A∆ ... ⍺   ⍝ new value for C depending on A∆ and item ⍺
...                 ⍝ ...
A∆ B C∆             ⍝ "successor" tuple (A and C changed)
}/(⌽items),⊂A B C       ⍝ for each item and initial state tuple A B C``````

In this coding, the accumulating tuple arrives as the right argument (⍵) of the operand function, with the next “loop item” on the left (⍺). Notice how the items vector is reversed (`⌽items`) so that the items arrive in index-order in the right-to-left reduction.

If you prefer your accumulator to be on the left, you can replace the primitive reduction operator (/) with Phil Last’s foldl operator, which also presents its loop items in index-order:

``    foldl←{⊃⍺⍺⍨/(⌽⍵),⊂⍺}    ⍝ fold left``

then:

``````    A B C {                 ⍝ final state from initial state (left argument)
(A B C)←⍺           ⍝ named items of tuple ⍺
A∆←A ... ⍵          ⍝ new value for A depending on item ⍵
C∆←C ... A∆ ... ⍵   ⍝ new value for C depending on A∆ and item ⍵
A∆ B C∆             ⍝ successor tuple (A and C changed)
} foldl items``````

If the number of elements in the state tuple is large, it can become unwieldy to name each on entry and exit to the operand function. In this case it simplifies the code to name the indices of the tuple vector, together with an at operator to denote the items of its successor:

``````    T ← (...) (...) ...         ⍝ intitial state tuple T
A B C D ... ← ⍳⍴T           ⍝ A B C D ... are tuple item "names"

T {                         ⍝ final state from initial state (left argument)
A∆←(A⊃⍺) ... ⍵          ⍝ new value for A depending on item ⍵
C∆←(C⊃⍺) ... A∆ ... ⍵   ⍝ new value for C depending on A∆ and item ⍵
A∆ C∆(⊣at A C)⍺         ⍝ successor tuple (A and C changed)
} foldl items``````

where:

``    at←{A⊣A[⍵⍵]←⍺ ⍺⍺(A←⍵)[⍵⍵]}   ⍝ (⍺ ⍺⍺ ⍵) at ⍵⍵ in ⍵``

There is some discussion about providing a primitive operator @ for at in Dyalog V16.

Examples
Function kk illustrates naming tuple elements (S E K Q) at the start of the operand function.
Function scc accesses tuple elements using named indices (C L X x S) and an at operator.

Tuples: a postscript
We might define a “tuple” in APL as a vector in which we think of each item as having a name, rather than an index position.

``````    bob         ⍝ Tuple: name gender age
┌───┬─┬──┐
│Bob│M│39│
└───┴─┴──┘

folk        ⍝ Vector of tuples
┌──────────┬────────────┬──────────┬────────────┬─
│┌───┬─┬──┐│┌─────┬─┬──┐│┌───┬─┬──┐│┌─────┬─┬──┐│
││Bob│M│39│││Carol│F│31│││Ted│M│31│││Alice│F│32││ ...
│└───┴─┴──┘│└─────┴─┴──┘│└───┴─┴──┘│└─────┴─┴──┘│
└──────────┴────────────┴──────────┴────────────┴─

↓⍉↑ folk    ⍝ Tuple of vectors
┌─────────────────────────┬────────┬───────────────┐
│┌───┬─────┬───┬─────┬─   │MFMF ...│39 31 31 32 ...│
││Bob│Carol│Ted│Alice│ ...│        │               │
│└───┴─────┴───┴─────┴─   │        │               │
└─────────────────────────┴────────┴───────────────┘

⍪∘↑¨ ↓⍉↑ folk   ⍝ Tuple of matrices
┌─────┬─┬──┐
│Bob  │M│39│
│Carol│F│31│
│Ted  │M│31│
│Alice│F│32│
...   . ..
└─────┴─┴──┘``````

APLers sometimes talk about “inverted files”. In this sense, a “regular” file is a vector-of-tuples and an inverted file (or more recently: “column store”) is a tuple-of-vectors (or matrices).

# Quicksort in APL Revisited

A message in the Forum inquired on sorting strings in APL with a custom comparison function.

First, sorting strings without a custom comparison function obtains with a terse expression:

``````      {⍵[⍋↑⍵]} 'syzygy' 'boustrophedon' 'kakistocracy' 'chthonic'
┌─────────────┬────────┬────────────┬──────┐
│boustrophedon│chthonic│kakistocracy│syzygy│
└─────────────┴────────┴────────────┴──────┘
``````

Sorting strings with a custom comparison function can also be accomplished succinctly by simple modifications to the Quicksort function

``````Q←{1≥≢⍵:⍵ ⋄ S←{⍺⌿⍨⍺ ⍺⍺ ⍵} ⋄ ⍵((∇<S)⍪=S⍪(∇>S))⍵⌷⍨?≢⍵}
``````

in a Dyalog blog post in 2014. A version that accepts a comparison function operand is:

``````QS←{1≥≢⍵:⍵ ⋄ (∇ ⍵⌿⍨0>s),(⍵⌿⍨0=s),∇ ⍵⌿⍨0<s←⍵ ⍺⍺¨ ⍵⌷⍨?≢⍵}
``````

The operand function `⍺ ⍺⍺ ⍵` is required to return `¯1`, `0`, or `1`, according to whether `⍺` is less than, equal to, or greater than `⍵`. In `QS`, the phrase `s←⍵ ⍺⍺¨ ⍵⌷⍨?≢⍵` compares each element of `⍵` against a randomly chosen pivot `⍵⌷⍨?≢⍵`; the function then applies recursively to the elements of `⍵` which are less than the pivot `(0>s)` and those which are greater than the pivot `(0<s)`.

Example with numbers:

``````      (×-)QS 3 1 4 1 5 9 2 6 5 3 5 8 97 9
1 1 2 3 3 4 5 5 5 6 8 9 9 97

3(×-)4
¯1
3(×-)3
0
3(×-)¯17
1
``````

Example with strings:

``````      strcmp←{⍺≡⍵:0 ⋄ ¯1*</⍋↑⍺ ⍵}

'syzygy' strcmp 'syzygy'
0
'syzygy' strcmp 'eleemosynary'
1
'syzygy' strcmp 'zumba'
¯1

strcmp QS 'syzygy' 'boustrophedon' 'kakistocracy' 'chthonic'
┌─────────────┬────────┬────────────┬──────┐
│boustrophedon│chthonic│kakistocracy│syzygy│
└─────────────┴────────┴────────────┴──────┘
``````

A more efficient string comparison function is left as an exercise for the reader. 🙂

# Zero-length Regular Expression Matches Considered Harmful

I was asked by a colleague why `⎕S` reports two matches in the following example:

``````      ('\d*'⎕S 0 1)'321'
┌───┬───┐
│0 3│3 0│
└───┴───┘
``````

Here we are asking for the position and length of sequences of zero or more digits in an input document containing three numeric characters. Intuitively there is just one match of all three characters from the start of the sequence, but `⎕S` reports an additional match of zero characters at the end.

The short explanation is this: when there is a match in the input, the matching characters are “consumed” and searching continues from after them. In this example the first match consumes all three characters in the input, leaving it empty. Searching then resumes and, as the pattern matches the zero remaining characters, there is a second match.

If it seems odd that we search when the input is empty then consider the case where the input is empty to start with:

``````      ('\d*'⎕S 0 1)''
┌───┐
│0 0│
└───┘
``````

In this case we should not be surprised there is a match – the pattern explicitly allows it and, indeed, we would have coded the search pattern differently, perhaps as `'\d+'`, if that was not wanted. It is therefore correct and consistent that the first example matches zero characters as well.

My colleague was not yet convinced. In this case, he asked, why are there not an infinite number of matches at the end?

It’s a good question. Zero-length matches have to be treated specially by the search engine to prevent exactly that, wherever they appear. The rule used by the PCRE search engine, which Dyalog uses, is that any pattern that results in a zero-length match is prohibited from generating another zero-length match until more characters are consumed from the input. PCRE is widely used so this behaviour is commonplace, but other search engine implementations take a different view and simply consume a single character following a zero-length match to prevent the repetition.

That difference in the rules would not have affected our example but consider a slightly more complex search pattern containing alternatives – here, zero or more digits, or one word character:

``````      ('\d*|\w'⎕S 0 1)'x321'
┌───┬───┬───┬───┐
│0 0│0 1│1 3│4 0│
└───┴───┴───┴───┘
``````

In this example the first match is of zero digits at the start of the input – that is, at offset zero and zero characters long. PCRE then resumes searching at offset zero but without allowing further zero-length matches. Consequently the first alternative pattern cannot match this time but the second can. The next match is therefore a single word character (the `'x'`), also at the start of the input. The `'x'` is consumed and searching resumes with `'321'` as the input where, as explained above, there are two further matches making four in total.

Search engines which simply consume a character after a zero-length match would give a different result. After the same initial match of zero characters at the start of the input they would consume the `'x'` and resume searching at `'321'` to give two further matches and a total of only three.

So, patterns which allow zero-length matches appear to be counter-intuitive and the cause of incompatibilities with other search engines. Should we avoid `'*'` and other qualifiers which allow zero repetitions of a pattern? Of course not – used carefully they can be very effective.

Firstly, a pattern which allows a sequence of zero characters within it can still be constructed so that the overall match can never have a length of zero. For example, `'colou?r'` allows zero or one `'u'` characters after the second `'o'` so that it matches both the British English spelling `'colour'` and the American English spelling `'color'` – but it never results in a zero-length match, and should never surprise anyone in the way it works.

Secondly, anchors can often be used to prevent those unintuitive extra matches. Anchors in search patterns don’t match actual characters – rather, they allow the match to succeed only at specific locations in the input. `'^'` and `'\$'` mean the start and end of a line respectively which, used in our very first example, prevent anything from preceding or following a match within a line and exclude the zero-length sequence because it does not satisfy that requirement:

``````      ('^\d*\$'⎕S 0 1)'321'
┌───┐
│0 3│
└───┘
``````

Thirdly – it often doesn’t matter that zero-length matches occur. In this example the search pattern matches any character except newline zero or more times and we are asking for it to be folded to upper-case:

``````      ('.*' ⎕R '\u&') 'Hello there'
HELLO THERE
``````

The first match is of all 11 characters which are folded to upper-case and replaced. Then is there a second match of zero characters at the end and this too is folded and replaced, having no further effect. You can see this is so by using a different replacement pattern:

``````      ('.*' ⎕R '[\u&]') 'Hello there'
[HELLO THERE][]
``````

As an aside, a `⎕R` search pattern constructed so that it has no visible effect at all can be very useful for doing a quick and simple read of a text file into the workspace. In this example:

``````      tieno←⎕NTIE 'input.txt'
''⎕R''⊢tieno
``````

text is read from the file without modification into a vector of character vectors, one line per element. There are many search and replace patterns that could be used to do this but this is the shortest, and it makes use of zero-length matches and replacements.

Perhaps, after all, the title of this blog should have been “zero-length regex matches considered helpful“?