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, using [X], if present.

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

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

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, using [X], if present.

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

    ∇ Z←L (LO #DydRank[X] 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 ⋄ →L1
[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
[9]   L1::if 0=⎕NC 'X' ⋄ Z←⊃Z ⋄ :else ⋄ Z←⊃[X] Z ⋄ :end
    ∇

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.