Functions and arrays

Generate positions, compare values, sort arrays and select items

Start with Basics. Each glyph below has a monadic form, with one argument, and a dyadic form, with arguments on both sides.

Index generation and lookup

⍳ (iota)

monadic ⍳ (index generator)

A position is also called an index. ⍳ creates the positions of an array with the given shape. Positions start at 0. An exact input gives an exact array: compare ⍳4 with ⍳4ₓ.

For performance-sensitive indexing, use exact integer index arrays. They avoid the whole-number checks and float-to-integer conversions needed for float indices.

⍳4
⍳4ₓ

0 1 2 3

[0 1 2 3]ₓ

A matrix position has a row number and a column number. These are its coordinates. Giving ⍳ a shape vector makes a coordinate vector at each position.

⍳[2 3]

┌→──────────────────┐
↓ ┌→──┐ ┌→──┐ ┌→──┐ │
│ │0 0│ │0 1│ │0 2│ │
│ └~──┘ └~──┘ └~──┘ │
│ ┌→──┐ ┌→──┐ ┌→──┐ │
│ │1 0│ │1 1│ │1 2│ │
│ └~──┘ └~──┘ └~──┘ │
└∊──────────────────┘

Combine ⍳ with ⍴ to arrange the positions in a matrix.

2 3⍴⍳6

┌→────┐
↓0 1 2│
│3 4 5│
└~────┘

Arithmetic on the positions makes other patterns. This gives the first six odd numbers.

1+2×⍳6

1 3 5 7 9 11

A length of 0 gives an empty vector.

⍳0

⍬

⍳⁻¹ gives the generating shape as a vector. A vector of four positions gives [4]; a matrix of row-column coordinates gives its two lengths.

⍳⁻¹⍳4
⍳⁻¹⍳[2 3]

[4]ₓ

[2 3]ₓ

dyadic ⍳ (index of)

For vectors, X⍳Y gives the first position of each item of Y in X. An absent item gets the length of X.

[1 3 6 5 4]⍳3

1ₓ

"ABCDABCDEF"⍳"ACFG"

[0 2 9 10]ₓ

mat←[0 1⋄2 3⋄4 5]
mat

┌→──┐
↓0 1│
│2 3│
│4 5│
└~──┘

A major cell is the part at one position along an array’s first axis, spanning all the remaining axes. A matrix’s major cells are its rows. ⍳ compares these whole cells. The last row of mat is 4 5, at position 2.

mat⍳4 5

2ₓ

With the same search array on the left, ⍳⁻¹ gives the items at the positions. The positions must be valid results of Index Of.

"ABC"⍳⁻¹2 0

┌→─┐
│CA│
└──┘

↦ (Range)

↦N counts from 1 through N. With two arguments it counts between the two ends, including both. It can count down too.

↦4

1 2 3 4

2↦5

2 3 4 5

5↦2

5 4 3 2

Each character has a numeric Unicode code. A character range counts through these codes.

'a'↦'e'

┌→────┐
│abcde│
└─────┘

Comparisons and Boolean values

= (Equal sign)

dyadic = (Equal to)

= compares values and returns a Boolean: true or false. BPL writes true as $t and false as $f.

1=1

$t

= compares each pair of atoms. A single number compares with every item of a vector.

1=1 2

$t $f

1=1 1

$t $t

We can also compare characters.

"Banana"="aaaaaa"

$f $t $f $t $f $t

"Banana"='a'

$f $t $f $t $f $t

["Banana" "Apple" "Candy"]='a'

┌→──────────────────────────────────────────────────────┐
│ ┌→────────────────┐ ┌→─────────────┐ ┌→─────────────┐ │
│ │$f $t $f $t $f $t│ │$f $f $f $f $f│ │$f $t $f $f $f│ │
│ └$────────────────┘ └$─────────────┘ └$─────────────┘ │
└∊──────────────────────────────────────────────────────┘

For Boolean arguments, inverse Equal finds the missing Boolean on the right. True equals false gives false, so $t=⁻¹$f gives $f.

$t=⁻¹$f

$f

monadic = (Classify)

With one argument, = makes a Boolean row for each distinct item, in order of first appearance. The columns correspond to the input items. In "aba", the first row marks the as and the second marks the b.

="aba"

┌→───────┐
↓$t $f $t│
│$f $t $f│
└$───────┘

≠ (Not equal)

monadic ≠ (Unique Mask)

A Boolean array that marks which items to keep is called a mask. Monadic ≠ marks the first occurrence of each distinct item with $t. Later occurrences get $f.

≠22 10 22 22 21 10 5 10

$t $t $f $f $t $f $t $f

≠"Banana"

$t $t $t $f $f $f

≠"Mississippi"

$t $t $t $f $f $f $f $f $t $f $f

dyadic ≠ (Not Equal To)

Dyadic ≠ gives $t where the atoms differ.

[1 2 3]≠4 2 ¯1

$t $f $t

The number 7 and the character 7 are not equal.

7≠'7'

$t

Inverse Not Equal also solves for a Boolean right argument.

$t≠⁻¹$t

$f

< (Less than sign)

monadic < (Sort up)

With one argument, < sorts the major cells in ascending order.

<30 10 20

10 20 30

<"banana"

┌→─────┐
│aaabnn│
└──────┘

<[3 1⋄1 2⋄2 0]

┌→──┐
↓1 2│
│2 0│
│3 1│
└~──┘

dyadic < (Less than)

[1 2 3]<4 2 ¯1

$t $f $f

[1 2 3]<2

$t $f $f

> (Greater than sign)

monadic > (Sort down)

> sorts in descending order.

>30 10 20

30 20 10

dyadic > (Greater than)

[1 2 3]>4 2 ¯1

$f $f $t

[1 2 3]>2

$f $f $t

≤ (Less than or equal to sign)

monadic ≤ (Decrement)

With one argument, ≤ subtracts 1 from each number.

≤[1 2 3]

0 1 2

The inverse of Decrement adds 1.

≤⁻¹[0 1 2]

1 2 3

dyadic ≤ (Less than or equal to)

[1 2 3]≤4 2 ¯1

$t $t $f

[1 2 3]≤2

$t $t $f

≥ (Greater than or equal to sign)

monadic ≥ (Increment)

With one argument, ≥ adds 1 to each number.

≥[1 2 3]

2 3 4

The inverse of Increment decrements.

≥⁻¹[2 3 4]

1 2 3

dyadic ≥ (Greater than or equal to)

[1 2 3]≥4 2 ¯1

$f $t $t

[1 2 3]≥2

$f $t $t

≡ (Equal underbar)

monadic ≡ (Depth)

An array stored as an item of another array is nested. Depth counts the layers of arrays. An atom has depth 0.

≡7

0ₓ

An array of atoms has depth 1.

≡"abc"

1ₓ

A vector whose items are vectors has depth 2.

[[1 2] [3 4]]

┌→────────────┐
│ ┌→──┐ ┌→──┐ │
│ │1 2│ │3 4│ │
│ └~──┘ └~──┘ │
└∊────────────┘

≡[[1 2] [3 4]]

2ₓ

Uneven nesting takes the depth of the deepest item, plus 1.

[[1 2] [3 4] [5 [6 7]]]

┌→────────────────────────┐
│ ┌→──┐ ┌→──┐ ┌→────────┐ │
│ │1 2│ │3 4│ │ 5 ┌→──┐ │ │
│ └~──┘ └~──┘ │   │6 7│ │ │
│             │   └~──┘ │ │
│             └∊────────┘ │
└∊────────────────────────┘

≡[[1 2] [3 4] [5 [6 7]]]

3ₓ

dyadic ≡ (Match)

Match compares the shape and contents of two whole values. Its result is one Boolean.

1≡1

$t

1≡0

$f

A number and a two-item vector have different shapes, even when every item of the vector equals the number.

1≡1 1

$f

≢ (Equal Underbar Slash)

monadic ≢ (Tally)

Tally counts the major cells of an array. For a vector it gives the length as an exact integer. Shape gives a vector containing that length.

≢1 2 3

3ₓ

⍴1 2 3

[3]ₓ

For a matrix, tally counts the rows.

≢2 3⍴⍳6

2ₓ

≢3 2⍴⍳6

3ₓ

dyadic ≢ (Not match)

Not Match is the opposite of Match.

1≢1

$f

1≢0

$t

It compares whole values, just as ≡ does.

1≢1 1

$t

∨ (Vee)

monadic ∨ (Real-imag)

∨ separates a complex number into its real and imaginary parts. Each number gives a pair along a new last axis.

∨3j4

3 4

∨3j4 1j2

┌→──┐
↓3 4│
│1 2│
└~──┘

The inverse joins each real-imaginary pair back into a complex number.

∨⁻¹3 4

3ⱼ4

dyadic ∨ (Or / Greatest common divisor)

With Boolean arguments, ∨ gives $t when either input is true.

[$f $t $f $t]∨$f $f $t $t

$f $t $t $t

With numbers, ∨ gives the greatest common divisor. For example, 5 is the largest number that divides both 15 and 35 without a remainder.

[15 1 2 7]ₓ∨[35 1 4 0]ₓ

[5 1 2 7]ₓ

⊽ (Vee bar)

monadic ⊽ (Double)

⊽1 2 3

2 4 6

The inverse of Double halves its argument.

⊽⁻¹2 4 6

1 2 3

dyadic ⊽ (Nor)

Nor gives $t only when neither input is true.

[$f $t $f $t]⊽$f $f $t $t

$t $f $f $f

∧ (Wedge)

monadic ∧ (Polar)

∧ gives each number’s magnitude (distance from zero) and angle from the positive real axis. Angles are in radians, with π1 for a half-turn.

∧3j4

5 0.927295218

The inverse rebuilds a number from its magnitude-angle pair.

∧⁻¹∧3j4

3ⱼ4

dyadic ∧ (And / Least common multiple)

With Boolean arguments, ∧ gives $t only when both inputs are true.

[$f $t $f $t]∧$f $f $t $t

$f $f $f $t

With numbers, ∧ gives the least common multiple. For example, 105 is the smallest positive multiple of both 15 and 35.

[15 1 2 7]ₓ∧[35 1 4 0]ₓ

[105 1 4 0]ₓ

~ (Logical NOT)

monadic ~ (Not)

~$f $t

$t $f

dyadic ~ (Without)

Without keeps the items from the left argument that are absent from the right.

[3 1 4 1 5]~5 1

3 4

It also compares strings as whole items.

["aa" "bb" "cc" "bb"]~["bb" "xx"]

┌→──────────┐
│ ┌→─┐ ┌→─┐ │
│ │aa│ │cc│ │
│ └──┘ └──┘ │
└∊──────────┘

The same rule works for other nested arrays.

[[1 2] 3]~[[1 2] [4 5]]

[3]

⊼ (Wedge bar)

monadic ⊼ (Square)

⊼2 3 4

4 9 16

Inverse Square takes a square root. For a positive real argument it chooses the positive root, even if the original number was negative.

⊼⁻¹4 9 16

2 3 4

dyadic ⊼ (Nand)

Nand gives $f only when both inputs are true.

[$f $t $f $t]⊼$f $f $t $t

$t $t $t $f

Applying Not to the result of And gives the same result.

~[$f $t $f $t]∧$f $f $t $t

$t $t $t $f

# (Hash)

dyadic # (Replicate)

The left argument gives a count for each major cell of the right argument. With a Boolean mask, Replicate keeps the cells marked $t. Here the unique mask keeps the first occurrence of each number.

v←22 10 22 22 21 10 5 10
≠v

$t $t $f $f $t $f $t $f

≠v # v

22 10 21 5

Larger counts repeat each item.

[3 1 3 1 3 1]#"Banana"

┌→───────────┐
│BBBannnannna│
└────────────┘

For a matrix, the major cells are rows. The mask keeps the first row.

[$t $f]#[1 2⋄3 4]

┌→──┐
↓1 2│
└~──┘

With the same counts on the left, #⁻¹ undoes Replicate. It keeps the first copy of each repeated cell. A count of zero gives a fill: the value used where data is absent, zero for numbers and a space for characters.

[$t $f $t]#⁻¹10 20
[2 1]#⁻¹10 10 20

10 0 20

10 20

monadic # (Runs)

With one argument, # counts groups of adjacent equal major cells. It returns the group lengths and their values as two vectors.

#"aaabcc"

┌→──────────────┐
│ ┌→────┐ ┌→──┐ │
│ │3 1 2│ │abc│ │
│ └ₓ────┘ └───┘ │
└∊──────────────┘

With one argument, #⁻¹ rebuilds the array from the group lengths and values.

#⁻¹[[3 1 2] "abc"]

┌→─────┐
│aaabcc│
└──────┘

Intervals, min and max

⍸ (iota underbar)

monadic ⍸ (Where)

On a Boolean array, Where gives the positions of the true items.

⍸$t $f $f $t $t

[0 3 4]ₓ

Nonnegative integer counts repeat the positions. The result contains position 0 once, position 1 twice and position 2 three times.

⍸[1 2 3]

[0 1 1 2 2 2]ₓ

⍸[2 0 0 2 1]

[0 0 3 3 4]ₓ

On a matrix, each position is a row-column coordinate pair.

bmat←[$f $t $f⋄$t $f $t]
⍸bmat

┌→──────────────────┐
│ ┌→──┐ ┌→──┐ ┌→──┐ │
│ │0 1│ │1 0│ │1 2│ │
│ └ₓ──┘ └ₓ──┘ └ₓ──┘ │
└∊──────────────────┘

bmat←[0 2 0⋄2 0 2]
⍸bmat

┌→────────────────────────────────────┐
│ ┌→──┐ ┌→──┐ ┌→──┐ ┌→──┐ ┌→──┐ ┌→──┐ │
│ │0 1│ │0 1│ │1 0│ │1 0│ │1 2│ │1 2│ │
│ └ₓ──┘ └ₓ──┘ └ₓ──┘ └ₓ──┘ └ₓ──┘ └ₓ──┘ │
└∊────────────────────────────────────┘

dyadic ⍸ (Interval Index)

X⍸Y counts how many boundaries in sorted X are less than or equal to each value of Y.

The boundaries 2 4 6 define four intervals, numbered from 0:

• 0: less than 2
• 1: from 2 up to 4, excluding 4
• 2: from 4 up to 6, excluding 6
• 3: greater than or equal to 6

The values 2 and 3 both fall in interval 1. The value 4 falls in interval 2.

[2 4 6]⍸1 2 3 4 5 6 7

[0 1 1 2 2 3 3]ₓ

Character boundaries work in the same way. A and C are in interval 1, before the next boundary E. Y is beyond all five boundaries.

"AEIOU"⍸"CANDY"

[1 1 3 1 5]ₓ

Interval index also compares major cells. Rows compare from left to right, at the first item that differs.

mat←[1 2⋄3 4⋄5 6]
mat

┌→──┐
↓1 2│
│3 4│
│5 6│
└~──┘

mat⍸3 3

1ₓ

mat⍸3 5

2ₓ

mat⍸[3 3⋄3 5]

[1 2]ₓ

⌈ (Upstile)

monadic ⌈ (Ceiling)

Rounds up to an exact integer.

⌈3.4 ¯3.4 3 0

[4 ¯3 3 0]ₓ

dyadic ⌈ (Maximum)

Takes the greater of each pair of numbers.

3⌈2

3

[3 2]⌈2 3

3 3

4⌈6⌈2

6

a←¯4 6 2
0⌈a

0 6 2

⌊ (Downstile)

monadic ⌊ (Floor)

Rounds down to an exact integer.

⌊3.4 ¯3.4 3 0

[3 ¯4 3 0]ₓ

After a name or a computed expression, the suffix ₓ also means Floor. On a list of literals it marks exact numbers instead, as in Basics.

x←3.7 ¯2.5
xₓ
(3.7-1)ₓ

[3 ¯3]ₓ

2ₓ

dyadic ⌊ (Minimum)

Takes the lesser of each pair of numbers.

4⌊6⌊2.5

2.5

Continue with Operators to combine these functions.

Not is its own inverse.

~⁻¹$t $f

$f $t

For a vector of positions, ⍸⁻¹ gives the count at each position through the last one present. It cannot recover trailing zero counts.

⍸⁻¹0 2 2

[1 0 2]ₓ