(j3.2006) CO_FINDLOC paper

[Dick Hendrickson]

Dan,
Please give this paper a number and add to the server.

Thanks,
Dick

---------------------------------

                                                       J3/07-xxx

Date:       22 January 2007
To:         J3
From:       Dick Hendrickson
Subject:    Clause 13; Add CO_FINDLOC function
References: J3/07-007

This adds the CO_FINDLOC function to clause 13;

Page 349:4, after CO_COUNT, add CO_FINDLOC to table
Insert:
CO_FINDLOC (CO_ARRAY, VALUE, RESULT [, TEAM, BACK])
                                     location of value in a co-array
or
CO_FINDLOC (CO_ARRAY, VALUE, RESULT, BACK)


Page 346:14, insert CO_FINDLOC description:

CO_FINDLOC (CO_ARRAY, VALUE, RESULT [, TEAM, BACK])
CO_FINDLOC (CO_ARRAY, VALUE, RESULT, BACK)

Description. Image indices of the of the first or last element,
in image order, having a value equal to VALUE, on a team of
images.

Class. Collective subroutine.

Arguments.

CO_ARRAY 	shall be a co-array of intrinsic type. It may be a
scalar or an array. It is an INTENT(IN) argument.

VALUE 	shall be scalar and in type conformance with ARRAY,
as specified in Table 7.11. It is an INTENT(IN) argument.

RESULT 	shall be of type integer and have the same shape as
CO_ARRAY. It is an INTENT(OUT) argument. If it is scalar, it is
assigned a value equal to the image index of an element of
CO_ARRAY having a value of VALUE on the images of the team. If
RESULT is an array, each element of RESULT is assigned a value
equal to the image index of an element having a value of VALUE
of all the corresponding elements of CO_ARRAY on the images of
the team.

	If no elements match VALUE, RESULT, or the corresponding
element of RESULT, is assigned the value zero.

	If CO_ARRAY is of type character, the result is the value
that would be selected by application of intrinsic relational
operators; that is, the collating sequence  for characters with
the kind type parameter of the argument is applied.

TEAM (optional) 	shall be a scalar of type IMAGE TEAM (13.8.3.7).
It is an INTENT(IN)argument that specifies the team for which
CO_FINDLOC is performed. If TEAM is not present, the team consists
of all images.

BACK (optional)	shall be scalar and of type logical. It is an
INTENT(IN) argument.


If more than one image has a value of VALUE, and BACK is absent
or present with the value false, the smallest such image index
is assigned. If BACK is present with the value true, the image
whose index is returned is the largest such image index.

  Examples. If the number of images is four and CO_ARRAY is a
scalar with the values 2, 4, 6, and 8 on the four different
images, the value of RESULT after the statement
CALL CO_FINDLOC (CO_ARRAY, 6 ) is 3 on all images.

If the number of images is two and CO ARRAY is the array [1, 5, 6]
on one image and [4, 1, 6] on the other image, the value of RESULT
after the statement
CALL CO_FINDLOC (CO_ARRAY, 1, RESULT) is [1, 2, 0]
and the value after the statement
CALL CO_FINDLOC (CO_ARRAY, 1, RESULT, .TRUE.) is [1, 2, 2].