Skip to main content

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 are displayed 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 are displayed 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 ₚ choose 16, 32 and 64 bits. Floats with fewer bits use less memory but hold fewer significant digits. A literal with ₕ or ₛ is rounded to that width when it is 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 are applied 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 group parts of an expression just as parentheses do. 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 spaces, addition happens first:

2×3+4
14

A list of literals forms a vector before the functions are applied. 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, calculate 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 gives its inverse, a function that undoes it. Negating twice restores the input, so Negate is its own inverse.

-⁻¯4
4

After a number, ⁻¹ raises it to the power ¯1, giving its reciprocal: one divided by that number. This differs from bare ⁻ on a function:

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

For element-wise arithmetic with a number and a vector, the number is used with each item of the vector.

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 fractions 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, Direction returns 1 for positive numbers, ¯1 for negative numbers, and 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 its argument unchanged, which is the number with that direction whose magnitude is 1, or zero. That argument must already be a possible result of Direction.

×⁻¯1 0 1
¯1 0 1

Dyadic × (Times)

Times multiplies element by element.

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. Multiplying by zero 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 exponent for a cube root is the reciprocal of 3:

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, raises its argument to that 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

With a space before it, a superscript is applied 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 are applied 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, written !5, is equal to 5×4×3×2×1.

!5
120

Factorial also extends to arguments that aren’t whole:

!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
2 2 1 1 4
¿0 0
0.8902120197 0.6554078172

Dyadic ¿ (Deal)

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

13¿52
5 49 32 18 33 0 19 12 28 9 46 38 24

π (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. The result’s 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ⱼ0

Dyadic ○ (Circular functions)

The left argument selects a circular function: 1○ is sine and 2○ is 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

With code 0, ○ takes the square root of 1 minus the square of its right 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 is 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 that ends in digits 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. {ω>1?1;ω} returns 1 for an argument greater than 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 the argument minus 1. A function calling itself 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"]
┌→─────────────────┐
│ ┌→──┐ ┌→──┐ "ab" │
│ │1 2│ │3 4│      │
│ └~──┘ └~──┘      │
└∊─────────────────┘

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

$a
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

Next: Functions and arrays.