J3/05-124
Date: 2005 Jan 07
To: J3
From: Dan Nagle
Subject: FINDLOC
A Public Comment for f03 requested a FIRSTLOC and a LASTLOC
pair of intrinsics to return the first or last elements evaluating
to true.
Paper 04-113 replaced that suggestion with FINDLOC, and included
a BACK= argument, similarly to the string search intrinsics.
The 167 Hate .. Love vote was 0 - 1 - 9 - 0.
This paper is a proposed "doneness" paper for FINDLOC.
Number:
Title: FINDLOC
Submitted By: J3
Status: For Consideration
References: 03-106, Public Comment by Jean Vizena
Basic Functionality: Intrinsic returns location of first true encountered,
searching from the first or last element of an array.
Rationale: Considered in response to a public comment, this formulation
is modeled on the MINLOC/MAXLOC procedures. Rather than
propose two procedures, a BACK= is proposed modeled after
similar argument to the character search routines index, scan,
and verify. The BACK= is used to distinguish forward and
backward searches, this may result is coding convience
or in more compact code.
Estimated Impact: The impact score was 3 on the John Reid scale at 167.
Detailed Specification: FINDLOC( [, DIM=s-i-e, BACK= s-l-e,
KIND=i-i-e])
Returns the indices of the first true,
starting with the first element of mask.
If BACK= is present and the s-l-e evaluates to true,
returns the index of the first true element
starting with the last element and searching
backwards.
Proposed Edits follow:
[316:22+] (after the Note) Add:
"13.7.38+ FINDLOC( ARRAY, DIM [, BACK, KIND])
FINDLOC( ARRAY [, BACK, KIND])
*Description.* Determine the location of the first
or last element of a logical array having the value
of true.
*Class.* Transformational function.
*Arguments.*
ARRAY shall be of type logical. It shall
not be a scalar.
DIM (optional) shall be of type integer with a value
in the range 1 <= DIM <= n, where
n is the rank of ARRAY. The
corresponding actual argument shall
not be an optional dummy argument.
BACK (optional) shall be of type logical. It shall
be a scalar.
KIND (optional) shall be a scalar integer
initialization expression.
*Result Characteristics.* 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 is absent,
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.
*Result Value.*
Case (i): The result of FINDLOC( ARRAY) or
FINDLOC( ARRAY, BACK=.false.) is a rank-one
array whose element values are the values
of the subscripts of the first element of
ARRAY, taken in array element order, having
the value true. The ith subscript lies in
the range 1 to ei, where ei is the extent
of the ith dimension of ARRAY. If ARRAY
has no true elements, all elements of the
result are zero.
Case (ii): The result of FINDLOC( ARRAY, BACK=.true.)
is a rank-one array whose element values
are the values of the subscripts of the
first element of ARRAY, taken in reverse
array element order, having the value true.
The ith subscript lies in the range 1 to ei,
where ei is the extent of the ith dimension
of ARRAY. If ARRAY has no true elements,
all elements of the result are zero.
Case (iii): If ARRAY has rank one, FINDLOC( ARRAY,
DIM=DIM) or FINDLOC( ARRAY, DIM=DIM, BACK=
.false.) is a scalar whose value is equal
to that of the first element of FINDLOC(
ARRAY [,BACK=.false.]). 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), DIM=1 [, BACK=.false.])
Case (iv): If ARRAY has rank one, FINDLOC( ARRAY,
DIM=DIM, BACK= .true.) is a scalar whose
value is equal to that of the first element
of FINDLOC( ARRAY, BACK=.true.). 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), DIM=1, BACK=.true.)
An example might be helpful, but this paper
does not contain one.
Since ARRAY cannot be of type character, there is no
need to discuss a character case (as is discussed
in the MINLOC/MAXLOC definitions).
For symmetry, it may be desirable to add
a BACK= to MAXLOC and MINLOC, however, this paper
does not propose to do so.
History: 04-113 at 167