Selective specification

A number of APL functions can be used to select elements or portions of an array. These selection operations can also be used as specifications when enclosed in parentheses and used as the left argument to the assignment symbol. The array being selected must appear as the rightmost name within the parentheses. The following functions can be used to make the selection, either singly or in combinations.

Monadic ∊ ↑ , ⌽ ⍉ ⊖
Dyadic ↑ ↓ ⊃ ⍴ ⌽ ⍉ ⊖ ⌷


and the functions \ ('expand') and / ('compress', 'replicate').

Bracket indexing can also be used as the left argument to the assignment arrow although in this case it is not necessary to enclose the indexing expression in parentheses.

Some examples will illustrate.

First, bracket indexing:

             TAB←2 3⍴⍳6              (Simple matrix)
             TAB[2;1]←8              (Row 2 column 1 assigned the value 8)

Nearly all the selection functions listed above operate on the outermost structure of a nested array. The shape of the right argument to the assignment arrow must either match that of the selected elements or be a scalar in which case scalar extension applies.

             VEC←⍳5
             (3↑VEC)←'ABC'           (First three elements become 'ABC')
             VEC
       ABC 4 5
             (3↑VEC)←'A'             (A scalar right argument is extended to
             VEC                      all items specified)
       AAA 4 5
             MAT←3 4⍴'ABCDEFGHIJKL'   (Simple character matrix)
             (,MAT)←'NEW DATAHERE'   (Ravel used for selection, so vector
             MAT                      used as right argument to ←)
       NEW
       DATA
       HERE
             (('A'=,MAT)/,MAT)←'*'   (Combination of compression and ravel
             MAT                      used for selection)
       NEW
       D*T*
       HERE
             (,2 2↑MAT)←'⎕⎕⎕⎕'       (Combination of ↑ and , used for
             MAT                      selection)
       ⎕⎕W
       ⎕⎕T*
       HERE
             TABLE←3 4⍴⍳12
             TABLE
       1  2  3  4
       5  6  7  8
       9 10 11 12
             (1 0 1 0/TABLE)←3 2⍴100 (Compression used for selection)
             TABLE
       100  2 100  4
       100  6 100  8
       100 10 100 12
             DATA←⍳13
             X←10 20 30              (Other APL functions may be used within
             ((⍴X)↑DATA)←X            the parentheses - here ⍴ is used to supply
             DATA                     the left argument to ↑)
       10 20 30 4 5 6 7 8 9 10 11 12 13
             Y←⍳10
             X←3
             ((2+X)↑Y)←⌽⍳X+2         (Left argument to ↑ includes the + function)
             Y
       5 4 3 2 1 6 7 8 9 10

The function enlist (∊) removes all nesting from an array. When used with selective specification, it can be used to replace elements at the deepest level of nesting, whilst retaining the structure of the array.

             NEST←(2 2⍴⍳4) 'TEXT' (3 1⍴⍳3)
             NEST
        1 2   TEXT   1
        3 4          2
                     3
             (∊NEST)←0               (Entire array set to 0, but original
             NEST                     structure retained)
        0 0   0 0 0 0   0
        0 0             0
                        0
      (6⌷∊NEST)←999                  (Single element at bottom of nested array
      NEST                            array altered)
 0 0   0 999 0 0   0
 0 0               0
                   0
      (7⌷∊NEST)←⊂'TEXT'              (Further nesting introduced)
      NEST
 0 0    0 999 TEXT 0    0
 0 0                    0
                        0

The function first (↑), selects the whole array which is the first element in an array. If first is used purely to select the first array within a nested array, then the array which is the right argument to the assignment arrow will replace the selected array.

             (↑NEST)←'ABC'           (First element of NEST is a matrix of
             NEST                     shape 2 by 2. This is replaced by
        ABC  0 999 TEXT 0    0        a length 3 vector)
                             0
                             0
             (2⌷↑NEST)←'⎕'           (One element within the first element of
             NEST                     NEST is replaced)
        A⎕C  0 999 TEXT 0    0
                             0
                             0

Pick (⊃) will select an entire array at an arbitrary depth in a nested array, and will also replace that entire array by the right argument to the specification symbol.

             2 2⊃NEST
       999
             (2 2⊃NEST)←⍳10          (New array placed in 2 2⊃ of NEST)
             NEST
        A⎕C  0  1 2 3 4 5 6 7 8 9 10  TEXT 0    0
                                                0
                                                0
             (2⊃NEST)←'DATA'         (Nested vector at element 2 replaced by
             NEST                     length 4 vector)
        A⎕C DATA   0
                   0
                   0
             (3 (2 1)⊃NEST)←1000     (Row 2 column 1 of element 3
             NEST                     specified)
        A⎕C DATA      0
                   1000
                      0

There are some exceptions and restrictions to the rules for selective specification:

- User-defined functions and operators cannot be used within selective specification

- Execute (⍎) is not allowed within selective specification

- System functions are allowed within selective specification with the exception of those which use execute (⎕EA and ⎕EC)

- The selection expression must select elements from the variable and not insert fill items (as, for example, can be done by expand and replicate).

- No arithmetic operations can be carried out on the array being specified or on the elements selected

- Assignments are not allowed within the parentheses used for selective specification.

- Selective and multiple specification operations cannot be mixed.

Thus, if

             X←3 4 5

then the following expressions are not allowed:

             (AVERAGE X)←6           (Use of user-defined function)

             ((⍎'1+2')↑X)←'ABC'      (Use of execute)

             ((Y←2)↓X)←'A'           (Assignment within the selection expression)

             ((2↓X) Y Z)←'ABC'       (Mixture of multiple and selective
                                      specifications)
             (10↑X)←⍳10              (Fill items inserted by the selection
                                      expression)

As stated above, arithmetic may not be carried out on the elements of an array that are selected:

             X←⍳5
             (2+1↑X)←5
       DOMAIN ERROR
       (2+1↑X)←5
            ^

but other expressions within the specification parentheses may use arithmetic operations, even on another instance of the name being specified:

             ((2+1↑X)↑X)←100
             X
       100 100 100 4 5