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

www.microapl.co.uk

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

FunctionMonadic formDyadic 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

FunctionMonadic formDyadic 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 inversionMatrix 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

FunctionDyadic 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

FunctionMonadic formDyadic 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

FunctionMonadic formDyadic 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)
UniqueUnion
Intersection
Reverse elementsRotate elements
Transpose Transpose as specified
FirstTake from an array
Drop from an array
Enclose an array Partition (Creates an array of vectors)
Disclose an arrayPick 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 orderAscending sorted indices, specified sort order
Descending sorted indices, default sort orderDescending 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

FunctionMonadic formDyadic form
FormatFormat 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 ]