Basics

Numbers, arrays, grouping and your first functions

Run these examples in the playground, the interactive prompt (REPL), or a BPL notebook. Work through them in order, trying a few changes of your own.

A glyph is a written symbol, such as +. To get help on one at the REPL, type ]help +. The glyph reference has the full definitions.

BPL works with values such as numbers and arrays. Start by entering a few numbers.

Values

Real

Write positive numbers, negative numbers and decimals directly. A negative number starts with the high bar ¯. A value written directly in code, such as 1.5, is called a literal.

1

1

¯1

¯1

1.5

1.5

Exact numbers

Bare numbers use approximate arithmetic. Append ₓ for an exact integer. Write an exact fraction with r between its numerator and denominator, as in 1r3.

3ₓ
1r3

3ₓ

1ᵣ3

Exact fractions display with ᵣ between the numerator and denominator. This spelling also works in input.

1ᵣ3

1ᵣ3

Scientific notation

An e, E or ₑ between two numbers means the first number times 10 raised to the second. A negative exponent moves the decimal point left.

1ₑ3
2e¯3

1000

0.002

Complex

A complex number has a real part and an imaginary part. Write j between them. The imaginary part multiplies i, the square root of −1.

Complex numbers display with ⱼ in place of the input’s j. Either spelling works in input.

0j4

0ⱼ4

3j4

3ⱼ4

3j4 means 3+4i.

4j0

4

4j0 means 4+0i, which is just the real number 4

¯5j¯6

¯5ⱼ¯6

3ⱼ4

3ⱼ4

Float widths

A float is an approximate real number. A bit stores either 0 or 1. Bare floats use 64 bits. The suffixes ₕ, ₛ and ₚ explicitly choose 16, 32 and 64 bits. Fewer bits use less memory and hold fewer significant digits. A narrow literal is rounded when read.

0.1ₕ
0.1ₛ
0.1ₚ

0.099975586ₕ

0.1ₛ

0.1

Complex numbers have two parts, each using 32 or 64 bits. ₛ and ₚ choose those widths. ₕ on a complex number also gives 32-bit parts.

3j4ₛ

3ⱼ4ₛ

Vectors

An array stores values, called items, at numbered positions. A vector has one axis: its positions run in one direction. Positions count from 0. An array’s rank is its number of axes; a vector has rank 1.

Put a vector’s items in brackets, separated by spaces. A list of literals separated by spaces is a shorthand for the same vector.

[2 3 1]

2 3 1

2 3 1

2 3 1

2 ¯3 1

2 ¯3 1

0j4 ¯5j¯6

0ⱼ4 ¯5ⱼ¯6

Append ₓ to a bracketed numeric array to make all its numbers exact:

[1 2 3]ₓ

[1 2 3]ₓ

The width suffixes also apply to bracketed numeric arrays.

[0.1 0.2]ₛ

[0.1 0.2]ₛ

Arrays in arrays

An item of an array can itself be an array. Write nested vectors with nested brackets:

[1 2 3 4 [1 2]]

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

[[1 2] [3 4]]

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

[[1 2] [3 4] 5]

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

⍝ (Comment)

⍝ starts a comment. Everything after it on the same line is ignored.

⍝ This is a comment and doesn't do anything
1 2 3 ⍝ This is a comment after some code

1 2 3

Reading expressions

A function calculates a result from one or two values called arguments. + adds its arguments and × multiplies them. Functions apply from right to left, with no precedence between them. In 3×2+1, the addition happens first.

3×2+1

9

A group in parentheses is calculated as one part. (2×3)+4 multiplies first, then adds 4.

(2×3)+4

10

Spacing can make the same grouping. A run is code with no spaces between its parts. A group in parentheses or brackets counts as one part, even when it contains spaces. Each run is calculated as one part of the surrounding expression.

2×3 + 4 has three runs: 2×3, +, and 4. It gives the same result as (2×3)+4.

2×3 + 4

10

Without the space, addition happens first:

2×3+4

14

A list of literals forms a vector before the functions apply. 1 2 3×2 doubles the vector 1 2 3. You can also write [1 2 3]×2.

1 2 3×2

2 4 6

In 1 2 3×2+1, add 2+1 first, then multiply each item of 1 2 3 by the result.

1 2 3×2+1

3 6 9

1 2 3×2+2 4 6

4 12 24

3 ¯5 + 4

7 ¯1

Basic math functions

A function used with one argument, to its right, is monadic. Used with an argument on each side, it is dyadic. The same glyph can name a different function in each form. For example, monadic - negates a number and dyadic - subtracts.

- (Minus sign; Bar)

Monadic - (Negate)

Negate changes the sign of each number. Positive numbers become negative and negative numbers become positive.

- 4

¯4

- ¯4

4

- 4 2 0 ¯3 ¯5

¯4 ¯2 ¯0 3 5

¯4 2 0 ¯3 ¯5

¯4 2 0 ¯3 ¯5

⁻¹ after a function asks for its inverse, a function that undoes it. Negating twice restores the input, so Negate is its own inverse.

-⁻¹¯4

4

After a number, the same ⁻¹ means its reciprocal: one divided by that number.

2⁻¹

0.5

Dyadic - (Minus; subtract)

3-2

1

Subtraction works element by element, pairing the items at each position.

3 2 1 - 4 5 1

¯1 ¯3 0

A single number extends across a vector for element-wise arithmetic.

3 2 1 - 1

2 1 0

1 - 3 2 1

¯2 ¯1 0

With a left argument, an inverse keeps that argument fixed and finds the right argument. 10-⁻¹3 is 7 because 10-7 is 3.

10-⁻¹3

7

+ (Plus sign)

Monadic + (Conjugate)

Conjugate negates the imaginary part of a complex number. It leaves real numbers unchanged.

+ 1.2

1.2

+ ¯5j¯6

¯5ⱼ6

+ 1.2 0j4 ¯5j¯6

1.2 0ⱼ¯4 ¯5ⱼ6

Conjugate is its own inverse too.

+⁻¹2j¯3

2ⱼ3

Dyadic + (Plus)

Plus works element-wise just like minus.

3+2

5

3 2 1 + 4 5 1

7 7 2

3 2 1 + 1

4 3 2

1 + 3 2 1

4 3 2

The inverse of adding 3 subtracts 3.

3+⁻¹10

7

| (Stile;Vertical Bar)

Monadic | (Magnitude)

Magnitude is distance from zero. For a real number it removes the sign. The complex number 3j4 has magnitude 5, the distance from the origin to the point (3, 4).

|3 ¯3 3j4

3 3 5

Dyadic | (Residue;Modulus)

Residue, also called modulus, gives the remainder after division. 2|7 is 1 because 7 divided by 2 is 3 with a remainder of 1.

2 10 2 | 7 13 8

1 3 0

With negative arguments, the nonzero remainder has the same sign as the left argument. For example, 10|¯13 is 7 because ¯13 is ¯2×10 plus 7.

2 10 ¯2.5 | 7 ¯13 8

1 7 ¯2

10 10 ¯10 ¯10 | 13 ¯13 13 ¯13

3 7 ¯7 ¯3

÷ (Divide sign)

Monadic ÷ (Reciprocal)

Reciprocal is division where 1 is the left argument.

• ÷ 3 is equivalent to 1 ÷ 3
• ÷ ¯2 is equivalent to 1 ÷ ¯2
• ÷ 3j4 is equivalent to 1 ÷ 3j4

÷ 3 ¯2 3j4

0.3333333333 ¯0.5 0.12ⱼ¯0.16

Reciprocal is its own inverse.

÷⁻¹0.25

4

Dyadic ÷ (Divided by)

Divided by does element-wise division

3÷2

1.5

3÷2 2.5 ¯1

1.5 1.2 ¯3

3 2 1÷2 2.5 ¯1

1.5 0.8 ¯1

Arithmetic on exact numbers stays exact:

1ₓ÷3ₓ
1r3+1r6

1ᵣ3

1ᵣ2

With a fixed numerator, inverse division finds the denominator.

12÷⁻¹4

3

× (Times sign)

Monadic × (Direction)

For real numbers: 1 for positive numbers, ¯1 for negative numbers, 0 for 0.

For a nonzero complex number, Direction divides the number by its magnitude. The result points in the same direction and has magnitude 1.

× 3.1 ¯2 0 3j4

1 ¯1 0 0.6ⱼ0.8

3j4÷ |3j4

0.6ⱼ0.8

Direction loses the magnitude of its input. Its inverse returns the direction unchanged, choosing a number of magnitude 1, or zero. The argument must already be a possible direction.

×⁻¹¯1 0 1

¯1 0 1

Dyadic × (Times)

Element-wise multiplication

3×2

6

3×2 2.5 ¯1

6 7.5 ¯3

3 2 1×2 2.5 ¯1

6 5 ¯1

The inverse of multiplying by 4 divides by 4. A zero multiplier has no inverse.

4×⁻¹12

3

* (Star)

Monadic * (Exponential)

Exponential raises the constant e (approximately 2.71828) to the power of its argument. *1 gives e.

* 0 1 2

1 2.718281828 7.389056099

The inverse exponential finds the exponent that produced its argument. This is called the natural logarithm.

*⁻¹*2

2

Dyadic * (Power)

Power raises the left argument to the right argument. It works element by element.

49 5 ¯4 * 0.5 2 0.5

7 25 0ⱼ2

The reciprocal of 3 gives the exponent for a cube root:

8*÷3

2

With a fixed base, the inverse finds the exponent. Here 2 to the power of 3 is 8.

2*⁻¹8

3

An integer written above the line, a superscript, gives a power. ² squares its argument and ³ cubes it. Several digits and a leading superscript minus are allowed.

3²
[2 3]³
2¹⁰
2⁻³

9

8 27

1024

0.125

A touching superscript applies to the value just before it. In 2 3², only 3 is squared. Brackets make the whole vector one value.

2 3²
[2 3]²

2 9

4 9

A space before a superscript applies it to the whole run on its left. A spaced superscript also needs a space after it.

2 3 ²
2×3 ² + 1

4 9

37

Superscripts apply before functions. -3² negates the square, whereas (-3)² squares the negated number.

-3²
(-3)²

¯9

9

√ (Root)

Monadic √ takes a square root. Dyadic √ takes the root whose degree is on the left.

√9 ¯4
3√8

3 0ⱼ2

2

Inverse square root squares its argument. With a fixed degree on the left, inverse Root raises its right argument to that degree.

√⁻¹3
3√⁻¹2

9

8

! (Exclamation mark)

Monadic ! (factorial)

5 Factorial, or !5 is equal to 5×4×3×2×1.

!5

120

Factorial also extends to non-integer arguments:

!1.5

1.329340388

Dyadic ! (Binomial)

X!Y counts selections of X things from Y things, ignoring their order. The following counts selections of 0 through 5 things from 5 things.

0 1 2 3 4 5 ! 5

1 5 10 10 5 1

¿ (Inverted question mark)

Monadic ¿ (Roll)

Roll gives a random integer from 0 up to, but not including, its argument. With 0 it gives a random number between 0 and 1.

¿6 6 6 6 6

3 5 3 3 5

¿0 0

0.1356071927 0.8859979024

Dyadic ¿ (Deal)

Deal draws without replacement. 13¿52 gives 13 distinct integers from 0 to 51.

13¿52

4 0 10 38 24 34 51 43 45 44 1 15 17

π (Pi Times)

Monadic π (Pi times)

The constant π is approximately 3.14159. Monadic π multiplies its argument by π.

π0 1 2

0 3.141592654 6.283185307

π⁻¹ divides by π.

π⁻¹π2

2

Dyadic π (Pi ratio)

With two arguments, XπY is X times π divided by Y. Its inverse with fixed X uses the same calculation.

1π2
1π⁻¹π0.5

1.570796327

2

○ (Circle)

Monadic ○ (Cis)

Measure angles in radians: one full turn is 2π radians. Cis turns an angle into the complex point at that angle on a circle of radius 1. Its real part is the cosine of the angle and its imaginary part is the sine.

○0 1

1 0.5403023059ⱼ0.8414709848

The inverse, ○⁻¹, turns a point on that circle back into an angle between −π and π. It cannot recover whole turns.

○⁻¹0j1

1.570796327

Dyadic ○ (Circular functions)

The left argument selects a circular function. Code 1 gives Sine and code 2 gives Cosine.

1○1π2

1

The same code with ⁻¹ selects the inverse function. Inverse sine is called arcsine. It finds an angle whose sine is the given number. For real inputs from ¯1 to 1, it chooses an angle between −π/2 and π/2.

1○⁻¹1

1.570796327

Hyperbolic functions combine exponentials. Code 5 gives hyperbolic sine, or sinh: half the difference between the exponential of the argument and the exponential of its negation.

5○1

1.175201194

Its inverse is called inverse hyperbolic sine, or arcsinh.

5○⁻¹5○1

1

Code 0 takes the square root of 1 minus the square of its argument. Its inverse uses the same calculation.

0○0.6
0○⁻¹0.8

0.8

0.6

The Circle reference lists every code and its inverse.

⍟ (Logarithm; Circle Star)

Monadic ⍟ (Natural Log)

A logarithm gives the power needed to produce a number from a chosen base. The natural logarithm uses e as its base. For example, the natural logarithm of e is 1.

⍟[1 2 3 *1]

0 0.6931471806 1.098612289 1

The inverse of the natural logarithm is Exponential.

⍟⁻¹1

2.718281828

Dyadic ⍟ (Log)

The left argument chooses the base. 2⍟32 is 5 because 2 to the power of 5 is 32.

2 10 ⍟ 32 1000

5 3

With a fixed base, inverse Log raises that base to the given power.

2⍟⁻¹5

32

Names and functions

Assignment

The left arrow ← assigns a value to a name. In a←3, the name a refers to 3. A name whose last character is a digit needs an underscore before the digits: x_1, not x1.

a←3
a

3

Assigning to ⎕ prints a value. Chained assignments still run right to left: first assign 3 to a, then print it.

⎕←a←3

3

b←3 4
b

3 4

Joining numbers

The subscript letters also join values from expressions into one number. aⱼb has real part a and imaginary part b. aₑb is a times 10 raised to b. aᵣb makes the exact fraction a over b, rounding both down first if needed. Each letter must touch the values on both sides.

a←3 ⋄ b←4
aⱼb
aₑb
aᵣb

3ⱼ4

30000

3ᵣ4

A group can supply either part. The joined number is calculated before the surrounding functions.

(a+1)ᵣb
2×aⱼb

1ₓ

6ⱼ8

Functions

A function written in curly braces is called a dfn. Its contents are its body. In a monadic call, the dfn receives its right argument as ⍵.

{⍵×2} 4

8

f ← {⍵×2}
f 4

8

In a dyadic call, the dfn also receives a left argument, ⍺.

g ← {⍵×2+⍺}
3 g 4

20

f ← {⍵×2}
h ← {2 + f ⍵}
h 4

10

⋄ (Statement separator)

A statement is one step of a calculation. Separate statements with a newline or ⋄. A dfn returns the result of its last statement. In this example, first assign ⍵×2 to a, then add 2.

f ← {a ← ⍵×2 ⋄ 2 + a}
f 4

10

f←{a←1 ⋄ 2 ⋄ 3}
f 2

3

Predicates

A predicate chooses whether a dfn body runs. Write the condition followed by ?, then the statements to run when it is true. Separate alternative bodies with ;.

> means greater than. In {⍵>1?1;⍵}, an argument greater than 1 gives the result 1. Otherwise the next body returns the argument unchanged.

cap←{⍵>1?1;⍵}
cap 5
cap 0.5

1

0.5

≤ means less than or equal to. This factorial function returns 1 for arguments at most 1. Otherwise it multiplies the argument by the factorial of one less. Calling the same function again is called recursion.

fact_1←{⍵≤1?1;⍵ × fact_1 ⍵-1}

fact_1 1

1

fact_1 5

120

∇ Del/Nabla (Recursion)

Inside a dfn, ∇ refers to that same dfn. It lets you write a recursive call without using the function’s name.

{⍵≤1?1;⍵ × ∇ ⍵-1}5

120

The two definitions give the same results:

fact_2←{⍵≤1?1;⍵ × ∇ ⍵-1}
fact_1 1
fact_2 1
fact_1 5
fact_2 5

1

1

120

120

{⍵≤1?1;⍵ × ∇ ⍵-1}5

120

fact←{⍵≤1?1;⍵ × ∇ ⍵-1}

fact 1

1

fact 5

120

Destructuring assignment

Destructuring assigns the items of an array to separate names. Put the names in brackets on the left of ←.

[a b]←3 4
a
b

3

4

Array rank

⍴ (rho)

Dyadic ⍴ (reshape)

A vector has one axis. A matrix has two, with items arranged in rows and columns. Its shape is the length of each axis, written as a vector. A matrix with 2 rows and 3 columns has shape 2 3.

⎕ ← 1 2 3 4 5 6

1 2 3 4 5 6

Dyadic ⍴ reshapes its right argument to the shape given on the left.

a ← 1 2 3 4 5 6
⎕←mat←2 3 ⍴ a

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

a ← 1 2 3 4 5 6
3 2 ⍴ a

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

a ← 1 2 3 4 5 6
1 6 ⍴ a

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

Reshape cycles through the original vector as needed to fill the desired shape.

a ← 1 2 3 4 5 6
⎕←c←2 2 3 ⍴ a

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

2 3 ⍴ 1

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

2 2 ⍴ 1 2 3

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

With a shape on the left, ⍴⁻¹ reads the items back into a vector in row order. Its right argument must have the given shape. It cannot restore items discarded by an earlier reshape.

[2 3]⍴⁻¹[1 2 3⋄4 5 6]

1 2 3 4 5 6

Monadic ⍴ (shape of)

Monadic ⍴ gives an array’s shape.

a ← 1 2 3 4 5 6
⍴a

[6]ₓ

mat←2 3 ⍴ a
⍴mat

[2 3]ₓ

A number is an atom: a value that isn’t an array. It has no axes and its shape is the empty vector, written ⍬.

⍴3

⍬ₓ

⍬

⍬

Suffixes work on the empty vector too. ⍬ₓ is an empty vector of exact numbers; ⍬ₕ, ⍬ₛ and ⍬ₚ choose a float width.

⍬ₓ
⍬ₛ

⍬ₓ

⍬ₛ

The empty vector still has one axis, of length 0:

⍴⍬

[0]ₓ

The shape is itself a vector. Taking its shape gives a one-item vector containing the rank of the original array.

mat←2 3 ⍴ a
⍴⍴mat

[2]ₓ

mat←2 3 ⍴ a
⍴⍴⍴mat

[1]ₓ

c←2 2 3 ⍴ a
⍴c

[2 2 3]ₓ

c←2 2 3 ⍴ a
⍴⍴⍴c

[1]ₓ

Strings

A character is an atom written in single quotes, such as 'A'. A string is a vector of characters written in double quotes, such as "ACF". Its length is its number of characters.

"ACF"

┌→──┐
│ACF│
└───┘

⍴"ACF"

[3]ₓ

'A' 'C' 'F'

┌→──┐
│ACF│
└───┘

A character has no axes. The string "y" is a vector of length 1.

⍴'y'

⍬ₓ

⍴"y"

[1]ₓ

⍴"your boat"

[9]ₓ

[1 2 3 4 'a']

1 2 3 4 'a'

A string inside another vector is a nested array, like the numeric vectors earlier.

[1 2 3 4 "ab"]

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

[[1 2] [3 4] "ab"]

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

The constant $a contains the uppercase letters A to Z.

$a

┌→─────────────────────────┐
│ABCDEFGHIJKLMNOPQRSTUVWXYZ│
└──────────────────────────┘

Next: Functions and arrays.