Primitive Functions

Built-in APL functions (or 'primitive' functions) are denoted by symbols (such as + - ÷ ×).

Primitive functions can be either monadic (which means they take a single right argument), or dyadic (in which case they take an argument on the left and an argument on the right). The same symbol may have both monadic and dyadic forms.

Execution order

A line of APL may consist of several functions, and arguments. All primitive and user-defined functions have the same precedence, and simply act on the data on the right. Thus, expressions are evaluated from right to left, and the result of one function becomes the (right) argument of the next function. See the section on Binding strengths for more details.

Scalar and Mixed functions

APL's primitive (i.e. built-in) functions fall into two classes, Scalar and Mixed functions. Scalar functions are defined on scalar arguments, and extend to arrays of any rank on an element-by-element basis. Mixed functions are defined on arrays, and may yield results which are different in shape or rank from their arguments. Most of the arithmetic primitives (such as addition, multiplication, logarithm) are scalar functions.

If one of the arguments to a dyadic function is a scalar, the scalar is applied to each element of the other argument (a property known as scalar extension). The other important property of scalar functions is that they are pervasive, that is they apply at all levels of nesting. Monadic scalar functions are applied independently to every simple scalar in their argument, and the result retains the structure of the argument. Dyadic scalar functions are applied independently to corresponding pairs of simple scalars in the other argument. If one of the arguments is a scalar, it will be applied to all simple elements of the other argument. For example:

      2 3 4 5 + 7 8 9 10
9 11 13 15
      23 + 7 8 9 10
30 31 32 33
      (1 2 3) (2 2⍴4 5 6 7) (7 8) + (10 11 12) (2 2⍴11 22 33 44) (60 70)
 11 13 15   15 27   67 78
            39 51
      (1 2 3) (2 2⍴4 5 6 7) (7 8) + 1
 2 3 4   5 6   8 9
         7 8

Note that you can use the Each operator (¨) to apply a non-scalar function to each element of an array.

Numbers or text

Some functions work on numbers only. The arithmetic functions are in this category. You will get a message saying you've made a DOMAIN ERROR if you try to use any of the arithmetic operators on text data.

Some functions work on either. The ⍴ function, for example, can be used (with one argument) to find how many characters are in a text item, or how many numbers are in a numeric item. Its two-argument form (which you've seen used to shape data into a specified number of rows and columns) also works on either numbers or characters.

The logical functions (logical ^, ∨ and the rest of that family) work on a subset of the number domain. They recognise two states only, true or false as represented by the numbers 1 and 0. If any other numbers or characters are submitted to them, a DOMAIN ERROR results.

Arithmetic functions

(Note: the - minus sign represents the negate and subtract functions, the ¯ sign is used to identify negative numbers.)

Examples of arithmetic functions

A vector of numbers is multiplied by a single number.

      2 6 3 19 × 0.5
1 3 1.5 9.5

A vector of numbers is divided by a single number:

      3 7 8 11 ÷ 3
1 2.333333333 2.666666667 3.666666667

A vector of numbers is divided by a single number. The results are rounded up to the next whole number and are then displayed:

      ⌈ 3 7 8 11 ÷3
1 3 3 4

The same operation as the last example, except that 0.5 is subtracted from each number before it's rounded up in order to give 'true' rounding:

      ⌈ ¯0.5 + 3 7 8 11 ÷3
1 2 3 4

Two vectors containing some negative values are added. × is applied to the resulting vector to establish the sign of each number. The final result is a vector in which each positive number is represented by a 1, each negative number by a ¯1 and each zero by a 0.

      ×12 ¯1 3¯5 + 2 ¯6 ¯4 5
1 ¯1 ¯1 0

The remainder of dividing 17 into 23 is displayed:

      17 | 23
6

The remainders of two division operations are compared and the smaller of the two is displayed as final result:

      (3 |7 ) ⌊ 4 | 11
1

Algebraic functions

Examples of algebraic functions

The numbers 1 to 10 are put in a variable called X.

      X ← ⍳10
1 2 3 4 5 6 7 8 9 10

3 random numbers between 1 and 10, with no repetitions.

      3?10
2 8 3

The logarithm to the base 2 of 2 4 8.

      2 ⍟ 2 4 8
1 2 3

The number of combinations of 2 items which can be made from a population of 4 items.

      2 ! 4
6

Comparative functions

Examples of comparative functions

Are two given numbers equal? (1 = yes 0 = no)

      10 = 5
0
      12 = 12
1

Are the corresponding characters in two strings equal?

      'ABC' = 'CBA'
0 1 0

Is the first number greater than the second?

      10 > 5
1

Is each number in the first vector less than the corresponding number in the second vector?

      3 9 6 < 9 9 9
1 0 1

Is the number on the left in the vector on the right?

      12 ∊ 6 12 24
1

Is the character on the left in the string on the right?

      'B'  ∊  'ABCDE'
1

Which numbers in a matrix are negative? (The contents of TABLE are shown first so that you can see what's going on.)

      TABLE
12 54  1
¯3 90 23
16 ¯9  2
      TABLE < 0
0 0 0
1 0 0
0 1 0

Find the number on the right in the vector on the left and show its position.

      13 7 9 0⍳9
3

Are two matrices exact matches?

      (2 2⍴⍳4) ≡  (2 2⍴⍳4)
1

Find the pattern 'CAT' within the characters 'THATCAT'

      'CAT ' ⍷ 'THATCAT '
0 0 0 0 1 0 0

Logical functions

Examples of logical functions

Logical NOT:

      ~1 1 1 0 0 0 1
0 0 0 1 1 1 0

The same data submitted to various logical functions:

      1 ∨ 0
1
      1 ^ 0
0
      1 ⍱ 0
0
      1 ⍲ 0
1

Each element in one vector is compared (^) with the corresponding element in another.

      1 0 1 ^ 0 0 1
0 0 1

Two expressions are evaluated. If both are true (i.e. both return a value of 1) then the whole statement is true (i.e. returns a value of 1):

      (5 > 4) ^ 1 < 3
1

Manipulative and selection functions

Examples of manipulative functions

An enquiry about the size of a character string:

      ⍴ 'ARLINGTON A.J, 22 BOND RD SPE 32E'
33

A three-row four-column matrix is formed from the numbers 1 to 12 and is assigned to DOZEN:

      DOZEN ← 3 4 ⍴ ⍳ 12
      DOZEN
1  2  3  4
5  6  7  8
9 10 11 12

The matrix DOZEN is ravelled into a vector:

      ,DOZEN
1 2 3 4 5 6 7 8 9 10 11 12

The matrix DOZEN is first converted to vector form and is then catenated (joined) with the vector 13 14 15):

      (,DOZEN), 13 14 15
      DOZEN
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

The matrix DOZEN is re-formed from the original data in reverse order:

      +DOZEN ← 3 4⍴⌽,DOZEN
12 11 10 9
 8  7  6 5
 4  3  2 1

Numbers are removed from a vector:

      1 2 3 4 5 6 ~ 2 4 6
1 3 5

First 3 characters are selected from a vector:

      3 ↑'AWFULLY'
AWF

Data array enclosed into a nested scalar, with an empty shape:

      ⊂999 34
 999 34
      ⍴⊂999 34
empty

Index the third item from a vector:

      3 ⌷ 1 2 3 4 5
3

Sorting and coding functions

Examples of sorting and coding functions

To put a vector of numbers into ascending order:

      LIST ← 200 54 13 9 55 100 14 82
      ⍋LIST
4 3 7 2 5 8 6 1
      LIST[4 3 7 2 5 8 6 1)
9 13 14 54 55 82 100 200

To sort the same vector as in example 1 with less typing:

      LIST[⍋LIST]
9 13 14 54 55 82 100 200

To find how certain symbols rank in the collating order (i.e. the order in which APL holds characters internally):

      SYMBS ← '⌹\≠(/'
      ORDER ← ⍋SYMBS
      SYMBS[ORDER]
⌹≠/(\

To convert the hex number 21 to its decimal equivalent:

      16 16 ⊥ 2 1
33

Formatting functions

Examples of formatting functions

To display each number in a vector in a 6-character field with two decimal places:

      6 2 ⍕ 60.333333 19 2 52.78
60.33 19.00 2.00 52.78

To display each number in a vector preceded by a dollar sign and with up to three leading zeroes suppressed:

      '$$Z,ZZ9' ⍺ 3899 66 2
$3,899    $66     $2

Miscellaneous functions and other symbols