Rank/Atop

Monadic Derived Function

Z←(f⍤[X] Y) R Applies the monadic function f to the rank-r cells of R, where r is defined by Y and restores the cells to the result as per X.

R is an arbitrary array, f is an arbitrary monadic function, X is an origin-sensitive integer scalar or vector, and Y is an integer scalar or vector.

If 1<⍴⍴Y, signal a RANK ERROR.

If 1=⍴⍴Y and ~(⍴Y)∊1 2 3, signal a LENGTH ERROR.

Y is a scalar or one-, two-, or three-element integer vector that describes the cell size of the arguments. When it is a three-element vector, the first element specifies the cell size of the right argument when the derived function is called monadically; the second and third elements specify the left and right argument cell sizes when the derived function is called dyadically. When it is a two-element vector, the two values are used for the left and right arguments cell sizes when the derived function is called dyadically; if the derived function is called monadically, the cell size is the second value of the two. When it is a scalar or one-element vector, the single value is used for all three cell sizes. Moreover, the value of Y for the monadic derived function case may be positive or negative with an absolute value no larger than ⍴⍴R. In this case (first element only), the above rules may be summarized by setting Y to the one-element integer vector (-⍴⍴R)⌈(⍴⍴R)⌊1↑⌽3⍴⌽Y.

The cells from R are of rank |Y.

If Y is positive, the cells from R are taken from the right end of the shape vector; if negative, the cells are taken from the left end of the shape vector. In particular, CR←(-Y)↑⍴R is the shape of the righthand cells, and FR←(-Y)↓⍴R is the shape of the righthand frame.

Loop through the frame applying f to the shape CR cells from R.

The result Z is the conforming disclose of the above (see below).

The monadic derived function of this dyadic operator is partially implemented by calling the following internal magic function:

    ∇ Z←(LO #MonRank Y) R;YR
[1]   YR←(1↑⌽3⍴⌽Y)⌊⍴⍴R
[2]   :if 0>YR ⋄ YR←0⌈YR+⍴⍴R ⋄ :end
[3]   Z←LO¨⊂[(-YR)↑⍳⍴⍴R] R ⋄ →0
[4]   ⎕PRO:YR←(1↑⌽3⍴⌽Y)⌊⍴⍴R
[5]   :if 0>YR ⋄ YR←0⌈YR+⍴⍴R ⋄ :end
[6]   Z←⊃LO¨¨⊂[(-YR)↑⍳⍴⍴R]¨0⍴⊂R
    ∇

See the discussion below for details on the final processing of the result of this magic function.

Dyadic Derived Function

Z←L (f⍤[X] Y) R Applies the dyadic function f between the rank-l cells of L and the rank-r cells of R and restores the cells to the result as per X, where l and r are defined by Y.

L and R are arbitrary arrays, f is an arbitrary dyadic function, X is an origin-sensitive integer scalar or vector, and Y is an integer scalar or vector.

If 1<⍴⍴Y, signal a RANK ERROR.

If 1=⍴⍴Y and ~(⍴Y)∊1 2 3, signal a LENGTH ERROR.

Y is a scalar or one-, two-, or three-element integer vector that describes the cell size of the arguments. When it is a three-element vector, the first element specifies the cell size of the right argument when the derived function is called monadically; the second and third elements specify the left and right argument cell sizes when the derived function is called dyadically. When it is a two-element vector, the two values are used for the left and right arguments cell sizes when the derived function is called dyadically; if the derived function is called monadically, the cell size is the second value of the two. When it is a scalar or one-element vector, the single value is used for all three cell sizes. Moreover, the values of Y for the dyadic derived function case may be positive or negative with an absolute value no larger than (⍴⍴L),⍴⍴R. In this case (second and third elements only), the above rules may be summarized by setting Y to the two-element integer vector (-(⍴⍴L),⍴⍴R)⌈((⍴⍴L),⍴⍴R)⌊1↓⌽3⍴⌽Y.

The cells from L are of rank |1↑Y; the cells from R are of rank |1↓Y.

If 1↑Y is positive, the cells from L are taken from the right end of the shape vector; if negative, the cells are taken from the left end of the shape vector. In particular, CL←(-1↑Y)↑⍴L is the shape of the lefthand cells, and FL←(-1↑Y)↓⍴L is the shape of the lefthand frame.

If 1↓Y is positive, the cells from R are taken from the right end of the shape vector; if negative, the cells are taken from the left end of the shape vector. In particular, CR←(-1↓Y)↑⍴R is the shape of the righthand cells, and FR←(-1↓Y)↓⍴R is the shape of the righthand frame.

If FL and FR are both non-empty and (⍴FL)≠⍴FR, signal a RANK ERROR; if the shapes of FL and FR are the same, but their values differ, signal a LENGTH ERROR.

Loop through the frames (scalar extending as necessary) applying f between the shape CL cells from L and the shape CR cells from R.

The result Z is the conforming disclose of the above (see below).

The dyadic derived function of this dyadic operator is partially implemented by calling the following internal magic function:

    ∇ Z←L (LO #DydRank Y) R;YL;YR
[1]   (YL YR)←(1↓⌽3⍴⌽Y)⌊(⍴⍴L),⍴⍴R
[2]   :if 0>YL ⋄ YL←0⌈YL+⍴⍴L ⋄ :end
[3]   :if 0>YR ⋄ YR←0⌈YR+⍴⍴R ⋄ :end
[4]   Z←(⊂[(-YL)↑⍳⍴⍴L] L) LO¨⊂[(-YR)↑⍳⍴⍴R] R ⋄ →0
[5]   ⎕PRO:(YL YR)←(1↓⌽3⍴⌽Y)⌊(⍴⍴L),⍴⍴R
[6]   :if 0>YL ⋄ YL←0⌈YL+⍴⍴L ⋄ :end
[7]   :if 0>YR ⋄ YR←0⌈YR+⍴⍴R ⋄ :end
[8]   Z←⊃(⊂[(-YL)↑⍳⍴⍴L]¨0⍴⊂L) LO¨¨⊂[(-YR)↑⍳⍴⍴R]¨0⍴⊂R
    ∇

Conforming Disclose

Both of the above magic functions implement their respective derived function except for some final processing which is essentially a disclose but one which allows for mismatched ranks. That part is implemented by the following function where L has already been calculated as the maximum rank across all items:

    ∇ Z←L #Conform R
[1]   Z←(((L-∊⍴∘⍴¨R)⍴¨1),¨⍴¨R)⍴¨R
    ∇

If the axis operator [X] is present on the rank operator, it is used in the final stage to disclose with axis (⊃[X]) the #Conform result to produce the final result Z. If the axis operator is not present, the final result Z is the disclose without axis (⊃) of the #Conform result.

For example, the rank operator can emulate laminate between the following two vectors to produce the first result, but not the second without help from the axis operator:

      L←'abcdef' ⋄ R←⍳⍴L
      L ,⍤0 R                             a.k.a. L,[1.5] R
 a 1
 b 2
 c 3
 d 4
 e 5
 f 6
      L ,⍤[1] 0 R                   a.k.a. L,[0.5] R
 a b c d e f
 1 2 3 4 5 6

Acknowledgments

The APL functions shown above were originally based upon those found in the paper J. Philip Benkhard, "Extending structure, type, and expression in APL2", ACM SIGAPL APL Quote Quad, v.21 n.4, p.20-38, Aug. 1991, but later was modified to reflect the definition of the Rank operator in the ISO-IEC 13751 Extended APL Standard.