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 (-⍴⍴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;O
[1]   Y←1↑⌽3⍴⌽Y
[2]   O←⍴⍴R
[3]   Y←(-O)⌈O⌊Y
[4]   Z←LO¨⊂[⍳-Y]R⋄→0
[5]   ⎕PRO:Z←⊃LO¨¨⊂[⍳-Y]¨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 (-(⍴⍴L),⍴⍴R)⌈((⍴⍴L),⍴⍴R)⌊1↓⌽3⍴⌽Y.

The cells from L are of rank |Y[⎕IO]; the cells from R are of rank |Y[⎕IO+1].

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;O
[1]   Y←1↓⌽3⍴⌽Y
[2]   O←(⍴⍴L),⍴⍴R
[3]   Y←(-O)⌈O⌊Y
[4]   Z←(⊂[⍳-1↑Y]L)LO¨⊂[⍳-1↓Y]R⋄→0
[5]   ⎕PRO:Z←⊃(⊂[⍳-1↑Y]¨0⍴⊂L)LO¨¨⊂[⍳-1↓Y]¨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