J3/05-124 Date: 2005 Jan 07 To: J3 From: Dan Nagle Subject: FINDLOC A Public Comment for f03 requested a FIRSTLOC and a LASTLOC pair of intrinsics to return the first or last elements evaluating to true. Paper 04-113 replaced that suggestion with FINDLOC, and included a BACK= argument, similarly to the string search intrinsics. The 167 Hate .. Love vote was 0 - 1 - 9 - 0. This paper is a proposed "doneness" paper for FINDLOC. Number: Title: FINDLOC Submitted By: J3 Status: For Consideration References: 03-106, Public Comment by Jean Vizena Basic Functionality: Intrinsic returns location of first true encountered, searching from the first or last element of an array. Rationale: Considered in response to a public comment, this formulation is modeled on the MINLOC/MAXLOC procedures. Rather than propose two procedures, a BACK= is proposed modeled after similar argument to the character search routines index, scan, and verify. The BACK= is used to distinguish forward and backward searches, this may result is coding convience or in more compact code. Estimated Impact: The impact score was 3 on the John Reid scale at 167. Detailed Specification: FINDLOC( [, DIM=s-i-e, BACK= s-l-e, KIND=i-i-e]) Returns the indices of the first true, starting with the first element of mask. If BACK= is present and the s-l-e evaluates to true, returns the index of the first true element starting with the last element and searching backwards. Proposed Edits follow: [316:22+] (after the Note) Add: "13.7.38+ FINDLOC( ARRAY, DIM [, BACK, KIND]) FINDLOC( ARRAY [, BACK, KIND]) *Description.* Determine the location of the first or last element of a logical array having the value of true. *Class.* Transformational function. *Arguments.* ARRAY shall be of type logical. It shall not be a scalar. DIM (optional) shall be 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. BACK (optional) shall be of type logical. It shall be a scalar. KIND (optional) shall be a scalar integer initialization expression. *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-1, dDIM+1, ... dn), where (d1, d2, ..., dn) is the shape of ARRAY. *Result Value.* Case (i): The result of FINDLOC( ARRAY) or FINDLOC( ARRAY, BACK=.false.) is a rank-one array whose element values are the values of the subscripts of the first element of ARRAY, taken in array element order, having the value true. The ith subscript lies in the range 1 to ei, where ei is the extent of the ith dimension of ARRAY. If ARRAY has no true elements, all elements of the result are zero. Case (ii): The result of FINDLOC( ARRAY, BACK=.true.) is a rank-one array whose element values are the values of the subscripts of the first element of ARRAY, taken in reverse array element order, having the value true. The ith subscript lies in the range 1 to ei, where ei is the extent of the ith dimension of ARRAY. If ARRAY has no true elements, all elements of the result are zero. Case (iii): If ARRAY has rank one, FINDLOC( ARRAY, DIM=DIM) or FINDLOC( ARRAY, DIM=DIM, BACK= .false.) is a scalar whose value is equal to that of the first element of FINDLOC( ARRAY [,BACK=.false.]). Otherwise, the value of element (s1, s2, ..., sDIM-1, sDIM+1, ..., sn) of the result is equal to FINDLOC( ARRAY( s1, s2, ..., sDIM-1, :, sDIM+1, ..., sn), DIM=1 [, BACK=.false.]) Case (iv): If ARRAY has rank one, FINDLOC( ARRAY, DIM=DIM, BACK= .true.) is a scalar whose value is equal to that of the first element of FINDLOC( ARRAY, BACK=.true.). Otherwise, the value of element (s1, s2, ..., sDIM-1, sDIM+1, ..., sn) of the result is equal to FINDLOC( ARRAY( s1, s2, ..., sDIM-1, :, sDIM+1, ..., sn), DIM=1, BACK=.true.) An example might be helpful, but this paper does not contain one. Since ARRAY cannot be of type character, there is no need to discuss a character case (as is discussed in the MINLOC/MAXLOC definitions). For symmetry, it may be desirable to add a BACK= to MAXLOC and MINLOC, however, this paper does not propose to do so. History: 04-113 at 167