J3/05-247
To: J3
From: Dan Nagle
Subject: findloc intrinsic
Date: 2005 August 4
This paper attempts to provide edits for the findloc intrinsic.
It is added to section 13 in alphabetical order.
FINDLOC is specified in 05-124r3.
In Section 13.5.8, page 298, add to the list:
[297:23+] Add:
"FINDLOC find a specified value"
In Section 13.7, add to the list of procedures:
[316:22+] Add: (after the Note)
"13.7.38+ FINDLOC( ARRAY, VALUE [, DIM, BACK, KIND])
<> Find the indices of the first or last array element
containing a specified scalar value.
<> Transformational function.
<>
ARRAY is INTENT(IN) and shall be of any intrinsic type.
It shall not be scalar.
VALUE is INTENT(IN) and shall be of the same type and kind as ARRAY.
It shall be a scalar.
DIM is INTENT(IN) and shall be scalar and of type integer
(optional) 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 is INTENT(IN) and shall be of type logical.
(optional)
KIND is INTENT(IN) and shall be
(optional) a scalar integer initialization expression.
<> 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.
<>
Case (i): The result of FINDLOC( ARRAY, VALUE [, BACK= .false.]) is a rank-one array
whose element values are the values of the subscripts of an element
of ARRAY whose value equals the value VALUE. The ith subscript
returned lies in the range 1 to ei, where ei is the extent
of the ith dimension of ARRAY. If more than one element
has the maximum value, the element whose subscripts are returned
is the first such element, taken in array element order. If ARRAY has
size zero, all elements of the result are zero.
Case (ii): The result of FINDLOC( ARRAY, VALUE , BACK= .true.) is a rank-one array
whose element values are the values of the subscripts of an element
of ARRAY whose value equals the value VALUE. The ith subscript
returned lies in the range 1 to ei, where ei is the extent
of the ith dimension of ARRAY. If more than one element
has the maximum value, the element whose subscripts are returned
is the last such element, taken in array element order. If ARRAY has
size zero, all elements of the result are zero.
Case (iii): If ARRAY has rank one, FINDLOC (ARRAY, VALUE, DIM = DIM)
is a scalar whose value is equal to that of the first element
of FINDLOC (ARRAY, VALUE). 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), VALUE, DIM=1 ).
If ARRAY has type character, the result is the value that would be
selected by application of intrinsic relational operators; that is,
the collating sequence for characters with the kind type parameter
of the arguments is applied.
<>
integer, dimension( 3) :: i = [ 3, 5, 5]
integer, dimension( 1) :: idx
idx = findloc( i, value= 5)
assigns [2] to idx.