MINLOC(ARRAY, DIM, MASK, KIND, BACK) or MINLOC(ARRAY, MASK, KIND, BACK)

Purpose

Locates the first element, Fortran 2008 begins or the last element if BACK is .TRUE., Fortran 2008 ends of an array along a dimension that has the minimum value of all elements corresponding to the true values of the mask. MINLOC will return the index referable to the position of the element using a positive integer.

Class

Transformational function

Argument type and attributes

ARRAY: An INTEGER, REAL, or CHARACTER array.

DIM: An INTEGER scalar. Its value must be in the range 1≤DIM≤n, where n is the rank of ARRAY.

MASK (optional): An argument of type LOGICAL and conforms to ARRAY in shape. If it is absent, the default mask evaluation is .TRUE.; that is, the entire array is evaluated.

KIND (optional): An INTENT(IN) INTEGER scalar. The actual argument corresponding to KIND must be a constant expression.

BACK (optional): A scalar of type LOGICAL and controls the direction in which ARRAY is searched. If it is .FALSE. or absent, the array is searched from the front. If it is .TRUE., the array is searched from the end.

Result type and attributes

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 integer array of rank one with a size equal to the rank of ARRAY. If DIM is present, the result is an integer array of rank rank(ARRAY)-1, and the shape is (s₁, …, s_DIM-1, s_DIM+1, …, s_n), where n is the rank of ARRAY.
If there is no minimum value, perhaps because the array is zero-sized or the mask array has all .FALSE. values or there is no DIM argument, the return value is a zero-sized one-dimensional entity. If DIM is present, the result shape depends on the rank of ARRAY.

Result value

The result indicates the subscript of the location of the minimum masked element of ARRAY. If ARRAY is of type character, the comparison is done using the ASCII collating sequence. Fortran 2008 begins If more than one element is equal to this minimum value and BACK is absent or has the value .FALSE., the function finds the location of the first element in array element order. If BACK is present with the value .TRUE., the function finds the location of the last element in array element order. Fortran 2008 ends If DIM is specified, the result indicates the location of the minimum masked element along each vector of the dimension.

Because both DIM and MASK are optional, various combinations of arguments are possible. When the -qintlog option is specified with two arguments, the second argument refers to one of the following:

MASK if it is an array of type integer, logical, byte or typeless
DIM if it is a scalar of type integer, byte or typeless
MASK if it is a scalar or type logical

The addition of the DIM argument modifies the behavior from XL Fortran Version 3.

Examples

! A is the array  |  4  9  8 -7 |
!                 |  2  1 -1  5 |
!                 |  9  5 -1  9 |
!                 | -7  5  5 -7 |

To find the first smallest element of A:

RES = MINLOC(A)

The result is | 4 1 | because the minimum value, -7, is located at A(4, 1). Although there are other instances of the minimum value present, A(4, 1) is the first in column-major order.

To find the last smallest element of A:

RES = MINLOC(A, BACK = .TRUE.)

The result is | 4 4 | because the minimum value, -7, is located at A(4, 4). Although there are other instances of the minimum value present, A(4, 4) is the last in column-major order. Fortran 2008 ends

To find the first smallest element that is not equal to -7 in each row of A:

RES = MINLOC(A, DIM = 2, MASK = A .NE. -7)

The result is | 1 3 3 2 | because these are the corresponding column locations of the first smallest value that is not equal to -7 in each row (the values being 4, -1, -1, 5).

To find the last smallest element that is not equal to -7 in each row of A:

RES = MINLOC(A, DIM = 2, MASK = A .NE. -7, BACK = .TRUE.)

The result is | 1 3 3 3 | because these are the corresponding column locations of the last smallest value that is not equal to -7 in each row (the values being 4, -1, -1, 5). Fortran 2008 ends

Regardless of the defined upper and lower bounds of the array, MINLOC will determine the lower bound index as '1'. Both MAXLOC and MINLOC index using positive integers. To find an actual index:

       INTEGER B(-100:100)
! Minloc views the bounds as (1:201)
! If the smallest element is located at index '-49'
       I = MINLOC(B)
! Will return the index '52'
! To return the exact index for the smallest element, insert:
       INDEX = LBOUND(B) - 1 + I
! Which is:  INDEX = (-100) - 1 + 52 = (-49)
       PRINT*, B(INDEX)

Provide feedback