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.]