Topic: `APLX Help` : `Help on APL language` : `APL Fundamentals` : `Primitive Functions`
[ Previous | Next | Contents | Index | APL Home ] # 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

 Function Monadic form Dyadic form `+` Identity (Conjugate) (Scalar function) Add (Scalar function) `-` Negate (Scalar function) Subtract (Scalar function) `×` Sign of (Scalar function) Multiply (Scalar function) `÷` Reciprocal (Scalar function) Divide (Scalar function) `⌈` Ceiling (Scalar function) Greater of (Scalar function) `⌊` Floor (Scalar function) Lesser of (Scalar function) `|` Absolute value (Scalar function) Residue (remainder) of division (Scalar function)

(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

 Function Monadic form Dyadic form `⍳` Index generator (see Comparative functions) `?` Roll (Random number) (Scalar function) Random deal `*` 'e' to power (Scalar function) Power (Scalar function) `⍟` Natural Logarithm (Scalar function) Log to the base (Scalar function) `○` pi times (Scalar function) Circular & Hyperbolic functions (Sine, cosine, etc) (Scalar function) `!` Factorial or Gamma function (Scalar function) Binomial (Scalar function) `⌹` Matrix inversion Matrix division

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

 Function Dyadic form only `<` Less than (Scalar function) `≤` Less than or equal (Scalar function) `=` Equal (Scalar function) `≥` Greater than or equal (Scalar function) `>` Greater than (Scalar function) `≠` Not equal (Scalar function) `≡` Match `≢` Not Match `∊` Membership `⍳` Index of `⍷` Find

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

 Function Monadic form Dyadic form `~` Not (Scalar function) See Selection functions `∨` Or (Scalar function) `^` And (Scalar function) `⍱` Nor (Scalar function) `⍲` Nand (Scalar function)

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

 Function Monadic form Dyadic form `⍴` Shape of Reshape `≡` Depth of an array (see comparative functions) `,` Ravel (Convert array to vector) Catenate (join) data items `∊` Enlist (Make into simple vector) (see comparative functions) `~` See logical functions Without (Removes elements from a vector) `∪` Unique Union `⍥` Intersection `⌽` Reverse elements Rotate elements `⍉` Transpose Transpose as specified `↑` First Take from an array `↓` Drop from an array `⊂` Enclose an array Partition (Creates an array of vectors) `⊃` Disclose an array Pick items from an array `⌷` Index an array `⊣` Stop (replace argument with empty) Left (pass left argument) `⊢` Pass (argument unchanged) Right (pass right argument)

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

 Function Monadic form Dyadic form `⍋` Ascending sorted indices, default sort order Ascending sorted indices, specified sort order `⍒` Descending sorted indices, default sort order Descending sorted indices, specified sort order `⊤` Encode (Convert to a new number system) `⊥` Decode (Convert back to units)

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

 Function Monadic form Dyadic form `⍕` Format Format by specification, Format by example `⍺` Picture format

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

 Function `⎕` Accept numbers from keyboard or Output with newline `⍞` Accept characters from keyboard or Bare output `⋄` Statement separator `⍝` Comment `⍎` Execute an APL expression `⍬` Empty numeric vector (Zilde)

Topic: `APLX Help` : `Help on APL language` : `APL Fundamentals` : `Primitive Functions`
[ Previous | Next | Contents | Index | APL Home ]