GRADE_DOWN(ARRAY,DIM)

Optional Argument. DIM

Description. Produces a permutation of the indices of an array, expressed as one-based coordinates, and sorted by descending array element values.

Class. Transformational function.

Arguments.

ARRAY must be of type integer, real, or character. It must not be scalar.

DIM (optional) must be scalar and of type integer with a value in the range , where is the rank of ARRAY. The corresponding actual argument must not be an optional dummy argument.

Result Type, Type Parameter, and Shape. The result is of type default integer. If DIM is present, the result has the same shape as ARRAY. If DIM is absent, the result has shape (/ SIZE(SHAPE(ARRAY)), SIZE(ARRAY) /).

Result Value.
*

Case (i): The result of
S = GRADE_DOWN(ARRAY)
+ SPREAD(LBOUND(ARRAY),DIM=2, NCOPIES=SIZE(ARRAY))-1
is such that if one computes the rank-one array B of size SIZE(ARRAY) by
FORALL (K=1:SIZE(B)) B(K)=ARRAY(S(1,K),S(2,K),...,S(N,K))
where N has the value SIZE(SHAPE(ARRAY)), then B is sorted in descending order; moreover, all of the columns of S are distinct, that is, if j does not equal m then ALL(S(:,) .EQ. S(:,))j < m will be false. The sort is stable; if and B(j) = B(m), then ARRAY(S(1,j),S(2,j),...,S(n,j)) precedes ARRAY(S(1,m),S(2,m),...,S(n,m)) in the array element ordering of ARRAY. The collating sequence for an array of type CHARACTER is that used by the Fortran intrinsic functions, namely ASCII.

Case (ii): The result of
R = GRADE_DOWN(ARRAY, DIM=K) + LBOUND(ARRAY, DIM=K) -1
has the property that if one computes the array
B(i₁, i₂,..., i_k,..., i_n) =
ARRAY(i₁, i₂,..., R(i₁, i₂,..., i_k,..., i_n),..., i_n)
then for all i₁, i₂,..., (omit i_k),..., i_n, the vector B(i₁, i₂,..., :,..., i_n) is sorted in descending order; moreover, R(i₁, i₂,..., :,..., i_n) is a permutation of all the integers between and SIZE(ARRAY, DIM=K), inclusive. The sort is stable; that is, if j < m and
B(i₁, i₂,..., j,..., i_n) = B(i₁, i₂,..., m,..., i_n), then
R(i₁, i₂,..., j,..., i_n) = R(i₁, i₂,..., m,..., i_n). The collating sequence for an array of type CHARACTER is that used by the Fortran intrinsic functions, namely ASCII.

Examples.
*

Case (i): GRADE_DOWN( (/30, 20, 30, 40, -10/) ) is a rank two array of shape [1 5] with the value [4 1 3 2 5]. (To produce a rank-one result, the optional DIM = 1 argument must be used.)

                  /       \
                  | 1 9 2 |
If A is the array | 4 5 2 |
                  | 1 2 4 |
                  \       /

                                 /                   \
then GRADE_DOWN(A) has the value | 1 2 3 4 4 1 2 1 3 |
                                 | 2 2 1 3 2 3 3 1 1 |
                                 \                   /

Case(ii):

                  /       \
                  | 1 9 2 |
If A is the array | 4 5 2 |
                  | 1 2 4 |
                  \       /

                                          /       \
                                          | 2 1 3 |
then GRADE_DOWN(A, DIM = 1) has the value | 1 2 1 |,
                                          | 3 3 2 |
                                          \       /

                                          /       \
                                          | 2 3 1 |
and GRADE_DOWN(A, DIM = 2) has the value | 2 1 3 |.
                                          | 3 2 1 |
                                          \       /