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

Purpose

Locates the first element Fortran 2008 begins or the last element Fortran 2008 ends of an array along a dimension that has the maximum value of all elements corresponding to the true values of the mask. MAXLOC 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 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 maximum 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 maximum 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 maximum 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 maximum 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 of 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 largest element of A:

RES = MAXLOC(A)

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

To find the last largest element of A:

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

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

To find the first largest element that is less than 7 in each column of A:

RES = MAXLOC(A, DIM = 1, MASK = A .LT. 7)

The result is | 1 3 4 2 | because these are the corresponding row locations of the first largest value that is less than 7 in each column (the values being 4, 5, 5, 5).

To find the last largest element that is less than 7 in each column of A:

RES = MAXLOC(A, DIM = 1, MASK = A .LT. 7, BACK = .TRUE.)

The result is | 1 4 4 2 | because these are the corresponding row locations of the last largest value that is less than 7 in each column (the values being 4, 5, 5, 5). Fortran 2008 ends

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

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

Provide feedback