Intel® Fortran Compiler Classic and Intel® Fortran Compiler Developer Guide and Reference

ID 767251
Date 11/07/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

Document Table of Contents

FINDLOC

Transformational Intrinsic Function (Generic): Finds the location of a specified value in an array.

Syntax

result = FINDLOC (array, value, dim [, mask, kind, back])

result = FINDLOC (array, value[, mask, kind, back])

array

(Input) Must be an array of intrinsic type.

value

(Input) Must be scalar and in type conformance with array.

If only one element matches value, that element’s subscripts are returned.

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 element, taken in array element order. If back is present with the value .TRUE., the element whose subscripts are returned is the last element, taken in array element order.

dim

(Input) Must be a scalar integer with a value in the range 1 <= dim <= n, where n is the rank of array.

mask

(Input; optional) Must be of type logical and conformable with array.

kind

(Input; optional) Must be a scalar integer constant expression.

back

(Input; optional) Must be a scalar of type logical.

If both array and value are of type logical, the comparison is performed with the .EQV. operator; otherwise, the comparison is performed with the == operator. If the value of the comparison is true, that element of array matches value.

Results

The result is 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 does not appear, 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.

The result of FINDLOC (array, valuevalue) is a rank-one array whose element values are the values of the subscripts of an element of array whose value matches value. If there is such a value, the ith subscript returned is in the range 1 to ei, where ei is the extent of the ith dimension of array. If no elements match value or if array has size zero, all elements of the result are zero.

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. If there is such a value, the ith subscript returned is in the range 1 to ei, where ei is the extent of the ith dimension of array. If no elements match value, or array has size zero, or every element of mask has the value .FALSE., all elements of the result are zero.

If array has rank one, the result of FINDLOC (array, value, DIM = dim [, MASK = mask]) is a scalar whose value is equal to that of the first element of FINDLOC (array, value [, MASK = mask]). 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 [, MASK = mask (s1, s2,...sdim-1, :, sdim+1,...sn)]).

The setting of compiler options specifying integer size can affect this function.

Examples

The value of FINDLOC ([2, 6, 4, 6], VALUE = 6) is [2].

The value of FINDLOC ([2, 6, 4, 6], VALUE = 6, BACK = .TRUE.) is [4].

If A has the value

  [ 0  −5   7   7 ]
  [ 3   4  −1   2 ]
  [ 1   5   6   7 ]

and M has the value

  [ T   T   F   T ]
  [ T   T   F   T ]
  [ T   T   F   T ]

then FINDLOC (A, 7, MASK = M) is [1, 4] and FINDLOC (A, 7, MASK = M, BACK = .TRUE.) is [3, 4].

This is independent of the declared lower bounds for A.

The value of FINDLOC ([2, 6, 4], VALUE = 6, DIM = 1) is 2.

If B has the value

  [ 1   2   -9 ]
  [ 2   3    6 ]

then FINDLOC (B, VALUE = 2, DIM = 1) is [2, 1, 0] and FINDLOC (B, VALUE = 2, DIM = 2) is [2, 1].

This is independent of the declared lower bounds for B.

See Also