FINDLOC(ARRAY, VALUE, DIM, MASK, KIND, BACK) or FINDLOC(ARRAY, VALUE, MASK, KIND, BACK) (Fortran 2008)

Purpose

Locates the first or the last element of an array along a dimension that equals the target value corresponding to the true values of the mask. FINDLOC returns the subscript of the element using positive integers.

Class

Transformational function

Argument type and attributes

ARRAY
An array of type integer, real, complex, logical, character, or byte.
VALUE
A scalar of the same type as ARRAY.
DIM (optional)
An integer scalar. Its value must be in the range 1 ≤ DIMn, where n is the rank of ARRAY. The corresponding actual argument cannot be an optional dummy argument.
MASK (optional)
An array of type logical and of the same shape as ARRAY. If it is absent, the default mask evaluation is .TRUE., which means that the entire array is evaluated.
KIND (optional)
An integer scalar. The actual argument corresponding to KIND must be a constant expression.
BACK (optional)
A logical scalar. It controls the direction in which ARRAY is searched. If it is .FALSE. or absent, the array is searched from the beginning. If it is .TRUE., the array is searched from the end.

Result type and attributes

Restriction: FINDLOC cannot be passed as an actual argument.

Result value

The result indicates the subscript of the location of the masked element of ARRAY whose value matches VALUE. If ARRAY is of type character, the comparison is done using the ASCII collating sequence.

If more than one element equals VALUE, and BACK is absent or has the value .FALSE., the result indicates the location of the first element in array element order. If BACK is present with the value .TRUE., the result indicates the location of the last element in array element order.

If DIM is specified, the result indicates the location of the masked element of ARRAY whose value matches VALUE along each vector of the dimension. Example 3 demonstrates the results according to different value of DIM in a 2-rank array.

Examples

Example 1:
PRINT *, FINDLOC([4,9,-2,9], VALUE=9)
It prints | 2 | because the array is searched from the beginning and the second element is the first one that is of target value.
PRINT *, FINDLOC([4,9,-2,9], VALUE=9, BACK=.TRUE.)
It prints | 4 | because BACK has the value .TRUE. and the fourth element is the last one that is of target value.
Example 2:
INTEGER :: A(-2:0,5:8)     ! The lower bound of A does not affect the result.
LOGICAL :: M(-5:-3,-1:2)   ! A and M can have different lower bounds.
A = RESHAPE((/3,2,7,8,5,1,-4,1,0,5,3,5/), (/3,4/))
M = RESHAPE((/.FALSE., .TRUE., .FALSE., .TRUE., .FALSE., .TRUE., .TRUE., 
             .TRUE., .TRUE., .TRUE., .TRUE., .TRUE./), (/3,4/))
!A has the value |3  8 -4  5|, and M has the value |.FALSE. .TRUE.  .TRUE. .TRUE.|.
!                |2  5  1  3|                      |.TRUE.  .FALSE. .TRUE. .TRUE.|
!                |7  1  0  5|                      |.FALSE. .TRUE.  .TRUE. .TRUE.|
To find the first element of value 5 using mask M:
PRINT *, FINDLOC(A, 5, MASK=M)
It prints | 1 4 | because the target value, 5, is at A(1, 4). A(2, 2), which also has target value, is not evaluated because of mask M. Although A(3,4) is also of target value, it is not the first in column-major order.
To find the last element of value 5 using mask M:
PRINT *, FINDLOC(A, 5, MASK=M, BACK=.TRUE.)
It prints | 3 4 | because the target value, 5, is at A(3, 4). Although there are other instances of target value, A(3, 4) is the last in column-major order.
Example 3:
INTEGER  :: B(2,3)
B = RESHAPE((/6,4,-2,3,4,5/),(/2,3/))  
!B has the value |6 -2  4|.
!                |4  3  5|
To find the first element of value 4 in each column of B, specify DIM = 1:
PRINT *, FINDLOC(B, VALUE=4, DIM=1)
It prints | 2 0 1|. These numbers are the corresponding row locations of the first element that is of the target value, 4, in each column. The found elements are at B(2, 1) and B(1, 3). There is no matching value in the second column, so 0 is in the second place.
To find the first element of value 4 in each row of B, specify DIM = 2:
PRINT *, FINDLOC(B, VALUE=4, DIM=2)
It prints | 3 1|. These numbers are the corresponding column locations of the first element that is of target value in each row. The found elements are at B(1, 3) and B(2, 1).