Built-in Functions

 
APLX
APLX64
News
Version 5 Features
Development
GUI Programming
Language
Learning APL
    Tutorial Contents
    Introduction to APL
    Entering symbols
    QuickSym popup
    Simple Arithmetic
    Variables
    Tables
    Writing a Function
    Overview of APL
    The Workspace
    Data
    Built-in Functions
    System Functions
    Operators
    User Functions
    Component Files
    Error Handling
    Formatting
    Classes
Documentation
Online Help
Downloads
Technical Support
APLX Forum
Community
Buy APLX

APL provides 50 or so built-in functions that do all the conventional operations and some rather sophisticated ones as well. It also provides 5 operators that modify and extend the way the functions work. These functions and operators can be used together very flexibly. Consequently it's possible to do a great deal in APL without ever leaving calculator mode: one APL line can be the equivalent of an entire subroutine in another language.

Arguments

Most APL functions are capable of doing two different but related tasks. The number of 'arguments' the function is given to work on determines which task it will perform. Here's the ⌈ function used first with one argument, then with two:

      ⌈12.625
13
      2 ⌈ 8
8

In the first (monadic or one-argument) form, the function rounded up the number on its right to the next whole number. In the second (dyadic or two-argument) form it selected the bigger of the two numbers.

Here's another example:

      ÷1 2 3 4 5
1 0.5 0.3333333333 0.25 0.2
      100÷1 2 3 4 5
100 50 33.33333333 25 20

In the first example the function ÷ was used with one argument. In this form it yields the reciprocal of the number, or numbers, on the right (i.e. the result of dividing 1 by each number). In the second example it was used with two arguments. In this form it does ordinary division. The left argument, 100, was divided in turn by each number in the right argument.

Execution order

A line of APL may consist of several functions, and arguments. There are therefore two points you must bear in mind:

• Expressions are evaluated from right to left.

• The results of one function become the argument of the next function.

This simple example illustrates both of these points:

      50×2-1
50

The expression is evaluated from right to left so 2-1 is evaluated first, giving 1, and 50×1 is evaluated second, giving a final result of 50. The result produced by the subtract function became the right-hand argument of the multiply function.

Numbers or text

Some functions work on numbers only. The arithmetic functions are in this category. You'll 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.

Shape and size of data

Some functions can be used only on data of a certain shape. Matrix divide (⌹), for example, demands data structured in an appropriate way. Other functions work on data of any shape or size. Arithmetic, for example, can be done on single numbers, vectors of numbers, matrices of numbers, or on numeric arrays of higher rank (up to sixty-three dimensions).

Any two data items involved in arithmetic and certain other operations must, however conform in size and shape, that is, it must be possible for APL to match each element in the left-hand argument with each equivalent element in the right-hand argument. The arguments in this example don't match and an error results:

      29 51 60 27÷3 11
LENGTH ERROR
      29 51 60 27÷3 11
      ^

The reasonable exception to this rule is the case where one argument consists of a single element and the other argument consists of a vector, matrix or multidimensional array:

      39 5 91×2
78 10 182

APL simply applies the single element to each element in the other argument. There's no ambiguity about which element matches which, and no error results.

Groups of functions

In the rest of this chapter we take groups of functions that do related things and discuss briefly what each group does. A few examples are given, partly to illustrate particular functions and partly to 'acclimatise' you to APL.

To find out more about any function, see the APLX Language Manual which provides a definition and examples for each function.

The groupings chosen are:

• Arithmetic functions

• Algebraic functions

• Comparative functions

• Logical functions

• Manipulative functions

• Sorting and coding functions

• Miscellaneous functions and other symbols

• System functions

Arithmetic functions

All the usual arithmetic operations are provided. What makes APL arithmetic interesting is not the functions themselves, but the fact that they can be applied to simple or complicated data.

A multiplication, for example can take place between two numbers. Alternatively every number in one matrix can be multiplied by the corresponding number in a second matrix producing a third matrix of the products. (The scope of operations is extended further by the APL operators, but they are dealt with in the next chapter.)

Remember that each function is capable of two different operations, depending on whether it's used with one or two arguments. The different operations are identified in the table below.

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

Examples of arithmetic functions

1. A vector of numbers is multiplied by a single number.

      2 6 3 19 × 0.5
1 3 1.5 9.5

2. A vector of numbers is divided by a single number:

      3 7 8 11 ÷ 3
1 2.333333333 2.666666667 3.666666667

3. 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

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

5. 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

6. The remainder of dividing 17 into 23 is displayed:

      17 | 23
6

7. 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

These are functions for doing more advanced arithmetic. The ⍟ (Log) function, for example, gives you either natural logarithms or logs to a specified base, while ○ (Circle) gives you access to sine, cosine, tangent and seven other trigonometric functions. Factorials and combinations can be obtained with ! (Factorial) and if you have a simultaneous equation to solve, or want to try a little matrix algebra, ⌹ (Domino) is your function.

Some functions have more everyday uses. The ⍳ (Iota) function will produce a series of numbers from 1 to the number you give it.

The ?(Query, Roll or Deal) function, for its part, 'rolls' you a single random number, or 'deals' you a hand of such numbers.

Examples of algebraic functions

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

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

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

      3?10
2 8 3

3. The logarithm to the base 2 of 2 4 8.

      2 ⍟ 2 4 8
1 2 3

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

      2 ! 4
6

Comparative functions

Comparative functions naturally take two arguments. The arguments are compared and if the condition specified by the function ('less than', 'equal to' or whatever) is true, the result is 1. Otherwise the result is 0.

Comparative functions are useful for finding items of data that meet certain conditions (e.g. employees whose sex equals 'M', or whose age is less than 55). They are also useful for making decisions about sequence in user-defined functions. For example, if a variable is greater than a certain value, you may want to branch to a particular point in the function.

Examples of comparative functions

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

      10 = 5
0
      12 = 12
1

2. Are the corresponding characters in two strings equal?

      'ABC' = 'CBA'
010

3. Is the first number greater than the second?

      10 > 5
1

4. Is each number in the first vector less than the matching number in the second vector?

      3 9 6 < 9 9 9
101

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

      12 ∊ 6 12 24
1

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

      'B'  ∊  'ABCDE'
1

7. 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

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

      13 7 9 0⍳9
3

9. Are two matrices exact matches?

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

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

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

Logical functions

These are also comparative functions, but they work with data composed exclusively of 1s and 0s. Since the comparative functions you've just looked at produce results composed exclusively of 1s and 0s, you'll appreciate that a logical test is often applied to the result of a comparison.

For example, if you've used the comparative function > (greater than) to produce a vector of employees over the age of 25, you'll have a vector in which such employees are represented by a 1. If you've also applied the = (equals) function to your employee data to find cases where sex equals 'M', you'll have a separate vector in which 1s represent males. Now if you were to apply the logical ^ (and) function to these two vectors, it would compare the vectors, and produce a 1 each time both vectors contained a 1 in the equivalent position. The result would be yet another vector in which employees who were over 25 and male were represented by a 1.

Logical comparisons are also used in user-defined functions to control branching.

Examples of logical comparison functions

1. ~ used to reverse 1's and 0's:

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

2. The same data submitted to various logical functions:

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

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

      1 0 1 ^ 0 0 1
0 0 1

4. 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 functions

These functions do a variety of useful operations on data.

The one argument form of ⍴ (Rho) enables you to find out the size of data. In its two argument form it enables you to specify how data is to be shaped or arranged. (There were many examples of this in the earlier chapter on data.)

≡ (Depth) tells you about the depth (or degree of nesting) of an array.

, Comma, in its one-argument form, can take a multi-dimensional object like a matrix, and unravel it into a single-dimensional vector. In its two-argument form, it can catenate separate data items to form single larger items, so that two matrices, for example can be amalgamated. The two-argument form of , can also join (or laminate) data items in such a way as to give the data an extra dimension. Two laminated vectors, for example, would form a matrix.

∊ (Enlist) turns any array, even nested arrays, into a simple vector.

⌽ (Rotate) and ⍉ (Transpose) can be used to reverse the ordering of data within arrays.

The ↓ and ↑ (Drop and Take) functions are useful for selecting data. You might, for example, wish to examine the first few members of a list with ↑.

~ (Without) can be used to remove items from a vector.

⊂ (Enclose) will turn arrays into nested scalars, useful for making complicated arrays, whilst ⊃ (Disclose) will reverse the process or select elements from nested arrays.

Examples of manipulative functions

1. An enquiry about the size of a character string:

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

2. 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

3. The matrix 'DOZEN' is ravelled into a vector:

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

4. 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

5. 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

6. Even numbers are removed from a vector.

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

7. First 3 characters are selected from a vector:

      3 ↑'AWFULLY'
AWF

8. An array is made into a nested scalar.

      ⊂999 34
 999 34
      ⍴⊂999 34
empty

The two element numeric vector is 'enclosed' into a single nested scalar, with an empty shape.

Sorting and coding functions

The sorting functions enable you to arrange data in ascending or descending order. You can either use the computer's collating sequence to determine sorting order, or you can specify your own collation sequence.

When looking at the examples of ⍋ and ⍒ (Grade up and Grade down), bear in mind that they don't produce a sorted version of the data to which they're applied. Instead they produce what is effectively an index which when applied to the original data will sort it into the required order.

The coding functions ⊤ and ⊥ (encode and decode) enable you to take data represented in one system and convert it to the equivalent value in another system. For example, you could convert numbers from hexadecimal (base 16) to decimal.

Examples of sorting and coding functions

1. 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

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

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

3. 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]
,./;\"

4. To convert the hex number 21 to its decimal equivalent:

      16 16 ⊥ 2 1
33

Miscellaneous functions and other symbols

Many of these involve the input of data from the keyboard, or affect the way data is displayed or printed.

Examples of miscellaneous symbols

1. To carry out more than one APL statement on a single line, then to format the data (turn a number into its character equivalent) and make up a single character vector using the catenate function:

      'TYPE A NUMBER'  ⋄ NUM ← ⎕
      'YOU TYPED', ⍕NUM

2. 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

3. 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

4. To index the third item from a vector:

      3 ⌷ 1 2 3 4 5
3

(The miscellaneous symbols are treated in detail in the APLX Language Manual)

System functions

Another very powerful type of built-in function in the System Function. This is a large topic which is introduced in the next chapter.