maxloc

Date:: 10-12-2011

NAME

MAXLOC - Returns the location of a maximum value in an array

SYNOPSIS

MAXLOC([ARRAY=]array[, [DIM=]dim][, [MASK=]mask, [KIND=]kind])

IMPLEMENTATION

Cray Linux Environment (CLE)

STANDARDS

Fortran

DESCRIPTION

The MAXLOC intrinsic function returns the location of the first element of array having the maximum value of the elements identified by mask. It accepts the following arguments:

array: Must be of type integer, real, or character. It must not be scalar.
dim: Must be a scalar integer value in the range 1 <= dim <= n, where n is the rank of array. The corresponding actual argument must not be an optional dummy argument.
mask: Must be of type logical and must be conformable with array.
kind: The kind argument determines the kind type of the return result. If this argument is not specified, the return result is of type default integer.

This argument must be a scalar integer initialization expression.

MAXLOC is a transformational function. The name of this intrinsic cannot be passed as an argument.

RETURN VALUES

The result is an integer array of rank one, with size equal to the rank of array.

The result of MAXLOC(array) is a rank one array, whose element values are the values of the subscripts of an element of array, whose value equals the maximum value of all of the elements of array. The ith subscript returned lies in this range:

1 to ei

where the last term 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 0, all elements of the result are zero.

The result of MAXLOC(array,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 equals the maximum value of all such elements of array. The ith subscript returned lies in this range:

1 to ei

where the last term is the extent of the ith dimension of array. If more than one such element has the maximum value, the element whose subscripts are returned is the first such element taken in array element order. If there are no such elements (that is, if array has size 0 or if every element of mask has the value false), all elements of the result are zero.

If array has rank one, the result of MAXLOC(array, DIM=dim[, MASK=mask]) is a scalar with a value that is the same as that of the first element of MAXLOC(array[, MASK=mask]). Otherwise, this element of the result:

(s1, s2, ..., sdim-1, sdim+1, ..., sn)

has a value equal to this:

MAXLOC(array(s1, s2, ..., sdim-1, : , sdim+1, ..., sn), DIM=1

      [, MASK=mask(s1, s2, ..., sdim-1, : , sdim+1, ..., sn)])

An element of the result is undefined if the value cannot be represented as an integer.

EXAMPLES

Example 1:

MAXLOC((/2,6,4,6/)) yields [2]

Example 2:

Assume that array B is declared as follows:

INTEGER, DIMENSION(4:7) :: B = (/ 8,6,3,1/)

MAXLOC(B) yields [1].

Example 3:

Assume that array A is as follows:

| 0 -5  8 -3 |
| 3  4 -1  2 |
| 1  5  6 -4 |

The following are true:

MAXLOC(A) yields [1,3].
MAXLOC(A,MASK=A.LT.6) yields [3,2].

Using array section references, the following are true:

MAXLOC(A(2:3,2:4)) yields [2,2].
MAXLOC(A(2:3,2:4),MASK=A(2:3,2:4).LT.6) yields [2,1].

Example 4:

Assume that B is array [100,2,5,7,1,90,0,20,-1,80].

The following are true of this array:

MAXLOC(B(10:1:-1)) yields [10].
MAXLOC(B(10:1:-2)) yields [3].

Example 5:

MAXLOC((/5,-9,3/)DIM=1) yields 1.

Example 6:

Assume that C is following array:

| 1 3 -9 |
| 2 2  6 |

The following are true of this array:

MAXLOC(C,DIM=1) yields [2,1,2].
MAXLOC(C,DIM=2) yields [2,3].
MAXLOC(C) yields [2,3].