To:        J3                                                J3/15-171
Subject:   FINDALL intrinsic function
From:      Van Snyder
Reference: 15-007r1 15-163
Date: 2015 June 07

1. Proposal
===========

Provide a FINDALL intrinsic function that returns a rank-2 array of all
subscripts of elements of ARRAY that match VALUE.  The extent of the
first dimension of the result is equal to the rank of ARRAY and the
extent of the second dimension is the number of elements of ARRAY that
match VALUE.

2. Draft Edits
==============

[327 Table 13.1] Insert a row in Table 13.1:

"FINDALL   (ARRAY, VALUE [, MASK, KIND ])   T   All locations matching a
                                                specified value
"

[359:11- 13.8:69+] Insert a subclause

"
13.8.70a FINDALL (ARRAY, VALUE [, MASK, KIND])

<<Description.>>  Subscripts of all elements matching a specified value.

<<Class.>> Transformational function.

<<Arguments.>>

ARRRAY   shall be an array. If ARRAY is of derived type, OPERATOR(==)
         shall be bound to the type of ARRAY and shall be accessible.  The
         first operand of OPERATOR(==) shall be a scalar that is type
         compatible with ARRAY; the second shall be a scalar that is type
         compatible with VALUE; the result of OPERATOR(==) shall be a
         scalar of type logical.

VALUE    shall be a scalar and in type conformance with ARRAY, as
         specified in Table 7.2 for the operator == or the operator .EQV.
         if ARRAY is of intrinsic type, or a scalar that is suitable for
         use as a second operand of the OPERATOR(==) bound to the type of
         ARRAY if an element of ARRAY were the first operand.

MASK (optional) shall be of type logical and shall be conformable with
         ARRAY.

KIND (optional) shall be a scalar integer constant expression.

<<Result Characteristics.>>  Integer.  If KIND is present, the type
parameter is that specified by the value of KIND; otherwise the kind type
parameter value is that of default integer type.  The result is an array
of rank two.  The extent of the first dimension of the result is the rank
of ARRAY and the extent of the second dimension is the number of elements
of ARRAY that match VALUE.

<<Result Value.>>  The value of each rank-one section in the first
dimension of the result is a sequence of subscripts of ARRAY for which the
element selected by those subscripts matches VALUE, and if MASK is present
the corresponding element of MASK is true.  The order in which the
subscripts specified by the rank-one sections in the first dimension of
the result specify elements of ARRAY is processor dependent, and need not
be array element order.

{It might be acceptable to use "column(s)" instead of "rank-one section(s)
in the first dimension".}

If both ARRAY and VALUE are of type logical, the comparison is performed
using the .EQV. operator; otherwise, the comparison is performed using the
== operator.  If the value of the comparison is true, the element of ARRAY
matches VALUE.

<<Examples.>>
                   [ 0 -5  7  7 ]                      [ T T F T ]
If A has the value | 7  4 -1  2 |, and M has the value | T T F T |, then
                   [ 1  5  6  7 ]                      [ T T F T ]
                                  [ 2 1 3 ]
FINDALL ( A, 7, M ) has the value [ 1 4 4 ].  Whether the columns appear
in the order illustrated is processor dependent.
"

[505:5+ A.2] Insert an item into the list of processor dependencies:

" o the order in which the subscripts specified by the rank-one sections
    in the first dimension of the result of FINDALL specify elements of
    ARRAY that match VALUE (13.8.70a);"

{It might be acceptable to use "columns" instead of "rank-one sections in
the first dimension".}