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. 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]   ⎕PROTOTYPE: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 3<⍴Y, signal a LENGTH ERROR.

Normalize Y by setting it to Y←(-(⍴⍴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]   ⎕PROTOTYPE: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, 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, however, it can't produce the second result 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 (,⍤[⎕IO] 0) R              a.k.a. L,[0.5] R
 a b c d e f
 1 2 3 4 5 6