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

Normalize Y by setting it to Y←(-⍴⍴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⍴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,

      L←'abcdef' ⋄ R←⍳⍴L
      L (,⍤0) R
 a 1
 b 2
 c 3
 d 4
 e 5
 f 6
      L (,⍤[⎕IO] 0) R
 a b c d e f
 1 2 3 4 5 6