Array Combining Scatter Functions

  The XXX_SCATTER functions are generalized array reduction functions in which an arbitrary subset of the elements of an array can be combined to produce an element of the result; the subset corresponding to the result's elements are nonoverlapping. Each of the eleven reduction operation in the language corresponds to one of the scatter functions, while COPY_SCATTER supports overwriting an existing value with any one of the values in the corresponding subset. The way that elements of the source array are associated with the elements of the result is described in this section; the method of combining their values is described in the specifications of the individual functions in Section 7.7.

These functions have the general form

XXX_SCATTER(ARRAY, BASE, INDX1, ..., INDXn, MASK)

except in the special cases noted below. The allowed values of XXX are ALL, ANY, COPY, COUNT, IALL, IANY, IPARITY, MAXVAL, MINVAL, PARITY, PRODUCT, and SUM. ARRAY, MASK, and all the INDX arrays are conformable. The INDX arrays are integer, and the number of INDX arguments must equal the rank of BASE. The argument MASK is logical, and it is optional. Except for COUNT_SCATTER, ARRAY and BASE are arrays of the same type. For COUNT_SCATTER, ARRAY is of type logical and BASE is of type integer. (For ALL_SCATTER, ANY_SCATTER, COUNT_SCATTER,and PARITY_SCATTER, the ARRAY argument must be logical. These functions do not have an optional MASK argument. To conform with the conventions of the Fortran standard, the required ARRAY argument to these functions is called MASK in their specifications in Section 7.7.) In all cases the result array is an array with the same type, kind type parameter, and shape as BASE.

For every element in ARRAY there is a corresponding element in each of the INDX arrays, since they all have the same shape as ARRAY. For each , where is the rank of BASE, let be the value of the element of INDXj that corresponds to element in ARRAY. These indices determine the element of the result that is affected by element of ARRAY. For each of the indices , let the corresponding index for BASE be given by LBOUND(BASE, j) - 1.

The integers , form a subscript selecting an element of BASE:
BASE(). Because BASE and the result are conformable, for each element of BASE there is a corresponding element of the result.

Thus the INDX arrays establish a mapping from all the elements of ARRAY onto selected elements of the result and BASE. Viewed in the other direction, this mapping associates with each element of BASE a set of elements from ARRAY.

If is empty, then the element of the result corresponding to the element of BASE has the same value as .

If is non-empty, then the elements of will be combined with element to produce an element of the result. The detailed specifications of the scatter functions describe the particular means of combining these values. As an example, for SUM_SCATTER, if the elements of are , then the element of the result corresponding to the element of BASE is the result of evaluating SUM((//)).

Note that the elements of the INDX arrays must be non-negative, and that INDXj may not exceed SIZE(BASE, j). The result computed is not affected by the declared upper or lower bounds on indices of BASE; it depends only on the shape of BASE.

Note that, since a scalar is conformable with any array, a scalar may be used in place of an INDX array, in which case one hyperplane of the result is selected. See the example below.

If the optional, final MASK argument is present, then only the elements of ARRAY in positions for which MASK is true participate in the operation. All other elements of ARRAY and of the INDX arrays are ignored and cannot have any influence on any element of the result.

For example, if

               /       \                            /          \
               | 1 2 3 |                            | -1 -2 -3 |
A is the array | 4 5 6 |;            B is the array | -4 -5 -6 |
               | 7 8 9 |                            | -7 -8 -9 |
               \       /                            \          /

                /       \                             /       \
                | 1 1 1 |                             | 1 2 3 |
I1 is the array | 2 1 1 |;            I2 is the array | 1 1 2 |
                | 3 2 1 |                             | 1 1 1 |
                \       /                             \       /

then

                             /         \
                             | 14 6  0 |
SUM_SCATTER(A, B, I1, I2) is | 8 -5 -6 |;
                             | 0 -8 -9 |
                             \         /

                            /          \
                            | -1 -2 -3 |
SUM_SCATTER(A, B, 2, I2) is | 30  3 -3 |;
                            | -7 -8 -9 |
                            \          /

                            /          \
                            | -1 24 -3 |
SUM_SCATTER(A, B, I1, 2) is | -4  7 -6 |
                            | -7 -1 -9 |
                            \          /

                           /          \
                           | -1 -2 -3 |
SUM_SCATTER(A, B, 2, 2) is | -4 40 -6 |
                           | -7 -8 -9 |
                           \          /

If A is the array [10 20 30 40 -10], B is the array [1 2 3 4], and IND is the array [3 2 2 1 1], then SUM_SCATTER(A, B, IND, MASK=(A .GT. 0)) is [41 52 13 4].