# Rearranging and transforming arrays


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Read [Searching and indexing](05_searching-indexing.ipynb) first.

## Rotate / transpose / flip

### `⌽` (Circle Stile)

#### monadic `⌽` (Reverse)

Reverse puts items in the opposite order along the last axis. On a
matrix, it reverses each row:

``` bpl
⌽"trams"
```

    smart

``` bpl
mat←[0 1 2 3⋄4 5 6 7⋄8 9 10 11]
mat
```

    0 1  2  3
    4 5  6  7
    8 9 10 11

``` bpl
⌽mat
```

     3  2 1 0
     7  6 5 4
    11 10 9 8

Reverse undoes itself: its inverse is Reverse again.

``` bpl
⌽⁻¹"smart"
```

    trams

#### dyadic `⌽` (Rotate)

A positive count rotates left; a negative count rotates right. Items
that leave one end return at the other.

``` bpl
1⌽"HatStand"
```

    atStandH

``` bpl
3⌽"HatStand"
```

    StandHat

``` bpl
¯2⌽1 2 3 4 5 6
```

    5 6 1 2 3 4

``` bpl
mat
```

    0 1  2  3
    4 5  6  7
    8 9 10 11

``` bpl
¯1⌽mat
```

     3 0 1  2
     7 4 5  6
    11 8 9 10

A vector of counts can rotate each row by a different amount:

``` bpl
1 ¯1 2⌽mat
```

     1  2 3 0
     7  4 5 6
    10 11 8 9

The inverse of Rotate turns in the opposite direction, using the same
count:

``` bpl
1⌽⁻¹"atStandH"
```

    HatStand

### `⊖` (Circle Bar)

#### monadic `⊖` (Reverse First)

`⊖` acts along the first axis. A vector has only one axis, so `⌽` and
`⊖` do the same thing there. On a matrix, `⊖` reverses or rotates the
rows.

``` bpl
⊖"trams"
```

    smart

``` bpl
⊖mat
```

    8 9 10 11
    4 5  6  7
    0 1  2  3

Reverse First also undoes itself:

``` bpl
⊖⁻¹⊖mat
```

    0 1  2  3
    4 5  6  7
    8 9 10 11

#### dyadic `⊖` (Rotate First)

``` bpl
3⊖"HatStand"
```

    StandHat

``` bpl
¯1⊖mat
```

    8 9 10 11
    0 1  2  3
    4 5  6  7

Its dyadic inverse reverses the rotation, using the same count:

``` bpl
¯1⊖⁻¹¯1⊖mat
```

    0 1  2  3
    4 5  6  7
    8 9 10 11

### `⍉` (Circle Backslash)

#### monadic `⍉` (Transpose)

Transpose reverses the order of the axes. A matrix’s rows become its
columns:

``` bpl
⍉mat
```

    0 4  8
    1 5  9
    2 6 10
    3 7 11

A `2 3 4` array becomes a `4 3 2` array:

``` bpl
cube←2 3 4⍴⍳24
cube
```

     0  1  2  3
     4  5  6  7
     8  9 10 11

    12 13 14 15
    16 17 18 19
    20 21 22 23

``` bpl
⍉cube
```

     0 12
     4 16
     8 20

     1 13
     5 17
     9 21

     2 14
     6 18
    10 22

     3 15
     7 19
    11 23

``` bpl
⍴⍉cube
```

    [4 3 2]ₓ

Transpose undoes itself too:

``` bpl
⍉⁻¹⍉mat
```

    0 1  2  3
    4 5  6  7
    8 9 10 11

The superscript `ᵀ` writes monadic Transpose after an array. It is for
arrays, not functions. It binds before functions, as the digit
superscripts do. After a space it applies to the whole run on its left:

``` bpl
matᵀ
```

    0 4  8
    1 5  9
    2 6 10
    3 7 11

Without a space, Index reads row 1 of the transpose. With a space before
`ᵀ`, it first reads row 1, then transposes that vector:

``` bpl
1⌷matᵀ
```

    1 5 9

``` bpl
1⌷mat ᵀ
```

    4 5 6 7

#### dyadic `⍉` (Transpose)

Each item on the left gives the destination of the corresponding input
axis. `1 0` sends the rows to axis 1 and the columns to axis 0:

``` bpl
1 0⍉mat
```

    0 4  8
    1 5  9
    2 6 10
    3 7 11

A diagonal takes matching positions along two axes: row 0 with column 0,
row 1 with column 1, and so on. Sending two axes to the same destination
selects their diagonal. The shorter axis determines its length:

``` bpl
0 0⍉mat
```

    0 5 10

With three axes, `1 0 2` swaps the first two. Repeated destinations
again select diagonals:

``` bpl
⍴cube
```

    [2 3 4]ₓ

``` bpl
⍴1 0 2⍉cube
```

    [3 2 4]ₓ

``` bpl
0 0 0⍉cube
```

    0 17

``` bpl
1 0 0⍉cube
```

     0 12
     5 17
    10 22

When each axis has a different destination, the inverse undoes the
routing. Repeated destinations discard items, so a diagonal has no
standalone inverse:

``` bpl
(2 0 1⍉⁻¹2 0 1⍉cube)≡cube
```

    $t

#### Splitting, naming and merging axes

A nested item splits one input axis into several axes. Here the last
axis of length 8 becomes two axes of lengths 2 and 4, named `"group"`
and `"offset"`. Each pair gives a destination and length. `∞` computes
the length needed to keep the number of items unchanged. The key on the
group, `"packed"`, names the axis when it is merged back:

``` bpl
packed←["batch":2 "row":3 "packed":8]⍴⍳48
split←["batch":0 "row":2 "packed":["group":1 2;"offset":3 ∞]]⍉
⍴split packed
```

    ["batch":2 "group":2 "row":3 "offset":4]ₓ

The inverse form, `⍉⁻¹`, lists input axes in output order. A nested
group merges its axes into one. This puts the group and offset axes
together again:

``` bpl
merged←["batch" "row" "packed":["group" "offset"]]⍉⁻¹split packed
merged≡packed
```

    $t

The inverse of a split merges the factors back into their original axis.
This bound function remembers the numeric routing:

``` bpl
(split⁻¹split packed)≡packed
```

    $t

A named output pattern in `⍉⁻¹` does not record the previous axis order,
so it has no standalone inverse.

## Other operators

### `⌺` (Quad Diamond)

#### Dyadic operator `⌺` (Stencil)

A window is a section of an array around one position. Stencil applies
its left operand to each window, with that position at the centre. Its
right operand gives the window’s size. At the edges, missing items use
fill: zero for these numeric arrays. Enclosing each window shows what
the operand receives:

``` bpl
⊂⌺3[1 2 3 4]
```

    (0 1 2⋄1 2 3⋄2 3 4⋄3 4 0)

Replace enclosure with summation to add the neighbours:

``` bpl
+/⌺3[1 2 3 4]
```

    3 6 9 7

Two sizes make a rectangular window. Here we sum each three-by-three
window:

``` bpl
{+/,⍵}⌺[3 3] [1 2 3⋄4 5 6⋄7 8 9]
```

    12 21 16
    27 45 33
    24 39 28

A two-row specification gives the sizes above the movements. This uses
three-item windows centred two positions apart:

``` bpl
+/⌺[[3]⋄[2]]⍳8
```

    1 6 12 18

### `⊘` (Valences)

A function’s valence is the number of arguments it takes. Valences
supplies separate functions for calls with one and two arguments. This
function negates with one argument and adds with two:

``` bpl
f←-⊘+
f3
```

    ¯3

``` bpl
10 f 3
```

    13

The inverse uses the inverse of whichever function that valence selects.
Here it negates with one argument and subtracts the fixed left argument
with two:

``` bpl
f⁻¹¯3
```

    3

``` bpl
10 f⁻¹ 13
```

    3

### `@` (Under)

`f@g` applies `f` to the selection that `g` makes, and writes it back.
The other items stay unchanged. A list of positions selects along the
first axis. A value in the function position replaces the selection:

``` bpl
0@[1 3] ⍳6
```

    0 0 2 0 4 5

``` bpl
[30 10]@[1 3] ⍳6
```

    0 30 2 10 4 5

Exact input keeps the reciprocals rational. Positions 1 and 3 hold 2 and
4, whose reciprocals are `1ᵣ2` and `1ᵣ4`:

``` bpl
÷@[1 3] ↦6ₓ
```

    1ₓ 1ᵣ2 3ₓ 1ᵣ4 5ₓ 6ₓ

``` bpl
10 ×@[1 3] ⍳5
```

    0 10 2 30 4

A function inside a one-item list selects where its result is true. Here
`2|` marks the odd numbers:

``` bpl
0@[2|] ⍳6
```

    0 0 2 0 4 0

``` bpl
⌽@[2|] ⍳6
```

    0 5 2 3 4 1

A selecting function can also supply the right operand. Drop skips the
first item; Under changes only the rest:

``` bpl
-@ 1↓ 1 2 3
```

    1 ¯2 ¯3

With an invertible transformation, Under transforms, applies its left
operand, then reverses the transformation. To round down to tenths,
multiply by ten, floor, then divide by ten:

``` bpl
⌊@ 10× 1.25 2.78
```

    1.2 2.7

Dot selections after Same can supply Under’s selector without a dfn.
Here the selected positions are multiplied by ten; a field selector
changes just that field:

``` bpl
v←10 20 30 40
{⍵×10}@ ⊢.[[1 3]] v
```

    10 200 30 400

``` bpl
order←["price":10 "qty":2]
≥@ ⊢.qty order
```

    ["price":10 "qty":3]

Under’s inverse keeps the selection and inverts its left function. This
decrements the selected items:

``` bpl
(≥@[1 3])⁻¹10 20 30 40
```

    10 19 30 39

### `⍚` (Agenda)

Agenda chooses a function from a list. Each function is a case. Its left
operand supplies the case’s position, or a function that computes that
position. A false Boolean chooses case 0, and a true Boolean chooses
case 1:

``` bpl
abs←(0≤)⍚[- ⊢]
abs¯3
```

    3

``` bpl
abs3
```

    3

A vector of choices picks one case for each cell. Here negative numbers
become zero, while nonnegative numbers take their square roots:

``` bpl
(0≤)⍚[0 √] ¯4 9 16
```

    0 3 4

## Execute and Format

### `⍎` (Hydrant)

#### Monadic `⍎` (Execute expression)

Execute reads a string as code and returns its last result. The string
can refer to names already defined here.

``` bpl
⍎"1+1"
```

    2

``` bpl
v←1 2 3
⍎"v"
```

    1 2 3

Intermediate statements still display their results, even when the last
result is assigned. This prints 2 and stores 4 in `answer`:

``` bpl
answer←⍎"1+1 ⋄ 2+2"
```

    2

``` bpl
answer
```

    4

Execute’s inverse writes a value as BPL source text that Execute can
read back. Exact numbers keep their marks:

``` bpl
source←⍎⁻¹[1 2 3]ₓ
[source]
```

    ["[1 2 3]ₓ"]

``` bpl
⍎source
```

    [1 2 3]ₓ

#### dyadic `⍎` (Execute in)

A keyed left argument supplies names for the expression:

``` bpl
["price":10.5 "qty":2]⍎"price×qty"
```

    21

### `⍕` (Thorn)

#### Monadic `⍕` (Format)

Format turns values into text. The numeric vector and its character
representation display alike:

``` bpl
4 5 6
```

    4 5 6

``` bpl
⍕4 5 6
```

    4 5 6

The vector has three numbers; the text has five characters, including
its two spaces:

``` bpl
[≢4 5 6;≢⍕4 5 6]
```

    [3 5]ₓ

A single number on the left sets the decimal places, the number of
digits after the decimal point:

``` bpl
2⍕3.125 0.002
```

    3.13 0.00

#### Dyadic `⍕` (Format By Specification)

A two-item vector gives the field width and decimal places. The width is
the number of characters for each number, padded with spaces:

``` bpl
6 2⍕3.125 0.002
```

      3.13  0.00

[Indexing](../indexing.ipynb) covers more selections, and each entry in
the [glyph reference](../glyphs.qmd) links to its full definitions.

[Previous: Searching and indexing](05_searching-indexing.ipynb) · [Study
guide](../glyphs-study.qmd) · [Next: Numerical
tools](07_numerical-tools.ipynb)