J3/06-181
To: J3
From: Dick Hendrickson
Date: 10 May 2006
Subject: Edits for FINDLOC intrinsic
Reference: Repository J3-032
This paper has the edits for repository item J3-032, the FINDLOC
intrinsic.
Based on meeting 176 straw votes, the following changes are made to
the specs and syntax.
1) A MASK argument is added to FINDLOC.
2) A BACK argument is added to MAXLOC and MINLOC. Actual edits to the
intrinsics are left as an integration issue.
3) /HPC may want to add a CO_FINDLOC subroutine to the collective
routines, and possible a BACK argument to the *LOC collective routines,
but that is not proposed in this paper.
______________________________________________
EDITS:
1) Add FINDLOC to 13.5.14 list, change MAXLOC and MINLOC
[297:23+] Add
FINDLOC (ARRAY, VALUE, DIM, [,MASK, KIND, BACK]) Location of value in an
array
Or FINDLOC (ARRAY, VALUE, [,MASK, KIND, BACK])
[297:24:25] Change [, MASK, KIND] to [MASK, KIND, BACK] in 4 places
2) Add FINDLOC in the intrinsic function descriptions
[316:23-] insert in alphabetical order
13.7.38A FINDLOC (ARRAY, VALUE, DIM, [,MASK, KIND, BACK]) or
FINDLOC (ARRAY, VALUE, [,MASK, KIND, BACK])
Description. Determine the location of the first element of ARRAY identified
by MASK along dimension DIM having a value equal to VALUE.
Class. Transformational function.
Arguments.
ARRAY shall be of intrinsic type. It shall be an array.
[Note to editor: Other intrinsics are inconsistent, some say "not be scalar",
others say "be array". Please make consistent globally]
VALUE shall be in type conformance with ARRAY, as specified in Table 7.8.
DIM shall be scalar and of type integer with a value in the range
1 <= DIM <= n, where n is the rank of ARRAY. The corresponding
actual argument shall not be an optional dummy argument.
MASK (optional) shall be of type logical and shall be conformable with ARRAY.
KIND (optional) shall be a scalar integer initialization expression.
BACK (optional) shall be of type logical
[Note to editor, type set the d1, ei, sDIM+1, etc. as in MAXLOC]
Result Characteristics. Integer. If KIND is present, the kind type parameter is
that specified by the value of KIND; otherwise the kind type parameter is that
of default integer type. If DIM is absent, the result is an array of rank one
and of size equal to the rank of ARRAY; otherwise, the result is of rank n - 1
and shape (d1, d2, ..., dDIM , dDIM+1, ..., dn), where (d1, d2, ..., dn) is the
shape of ARRAY.
Result Value.
Case (i): The result of FINDLOC (ARRAY, VALUE) is a rank-one array
whose element values are the values of the subscripts of an element of ARRAY
whose value matches VALUE. The ith subscript returned lies in the range 1 to ei,
where ei is the extent of the ith dimension of ARRAY. If no elements match VALUE
or ARRAY as size zero, all elements of the result are zero.
Case (ii): The result of FINDLOC (ARRAY, VALUE, MASK = MASK) is a
rank-one array whose element values are the values of the subscripts of an element
of ARRAY, corresponding to a true element of MASK, whose value matches VALUE. The ith
subscript returned lies in the range 1 to ei, where ei is the extent of the ith
dimension of ARRAY. If no elements match VALUE, ARRAY has size zero, or every
element of MASK has the value false, all elements of the result are zero.
Case (iii): If ARRAY has rank one,
FINDLOC (ARRAY, VALUE, DIM=DIM, [, MASK = MASK]) is a scalar whose value is equal
to that of the first element of FINDLOC (ARRAY [, MASK = MASK]). Otherwise, the
value of element (s1, s2, ..., sDIM , sDIM+1, ..., sn ) of the result is equal to
FINDLOC (ARRAY (s1, s2, ..., sDIM , :, sDIM+1, ..., sn), DIM=1,
[, MASK = MASK (s1, s2, ..., sDIM , :, sDIM+1, ..., sn) ] ).
If both ARRAY and VALUE are of type logical, the comparison is performed as
array-element .EQV. VALUE, otherwise, the comparison is performed as
array-element == VALUE. If the value of the comparison is true, array-element
matches VALUE.
If more than one element matches VALUE and BACK is absent or present with the
value false, the element whose subscripts are returned is the first such element,
taken in array element order. If BACK is present with the value true, the element
whose subscripts are returned is the last such element, taken in array element order.
Examples.
Case (i): The value of FINDLOC ((/ 2, 6, 4, 6 /), 6) is [2].
0 -5 7 7
Case (ii): If A has the value 3 4 -1 2
1 5 6 7
T T F T
and M has the value T T F T
T T F T
FINDLOC (A, 7, MASK = M) has the value [1,4] and FINDLOC( A, 7, MASK =A, BACK = .TRUE.)
has the value [3,4]. Note that this is independent of the declared lower bounds for A.
[Another example is needed here.]
[3) Add BACK= to MAXLOC and MINLOC, similar to FINDLOC above, after the edits
have been accepted.]