To: J3                                                     J3/23-167
From: T. Clune
Subject: Specs for rank-agnostic intrinsics.
Date: 2023-June-09

Reference: 23-007

1. Introduction:
================

Several intrinsic procedures are unnecessarily limited to arrays (i.e,
non-scalars and/or non assumed-rank).  Such limitations will be
prevent use of these intrinsics in rank-agnostic algorithms enabled by
recent and expected extensions to the language.

Closely related: Some intrinsics have already been amended to allow
for assumed-rank arrays, but several others would benefit by similar
amendments.

Further, some intrinsics that currently support assumed-rank are
lacking notes about not permitting use of DIM arguments when the rank
is 0.

This paper provides specifications for the desired changes in a
somewhat informal manner.  It does not include edits.


2. Specifications
=================

Note 1. It is unclear to me whether assumed-rank entities can be
        passed to elemental procedures.  If they are not, then a
        separate change should be made to allow that.  With that, no
        further changes are needed for intrinsic procedures that are
        elemental.


Note 2. Several intrinsics have a first argument called "ARRAY".  This
        is a bit awkward when extending such an intrinsic to allow
        scalars.  But the requirements for generic programming and
        backward compatibility will necessitate preserving the name
        of such first arguments.

A. ALL, ANY

   - MASK shall be an assumed-rank, an array, or a scalar of type
     logical.
   - DIM shall not be present if MASK is a scalar

B. COUNT

   - MASK shall be an assumed-rank, an array, or a scalar of type
     logical.
   - DIM shall not be present if MASK is a scalar

C. IALL, IANY, IPARITY, MAXLOC, MINLOC
   - ARRAY shall be an assumed-rank, an array, or a scalar of
     type logical.
   - DIM shall not be present if MASK is a scalar


D. FINDLOC - problematic case

   The scalar case here is highly problemat, and yet this is a very
   important use case.  The result characteristics would of necessity
   be a size zero 1D array, which therefore carries no
   information about whether the scalar argument matches VALUE.

   A fix would be to add an INTENT(OUT) logical argument to indicate
   whether any match occurs.  But we do not allow INTENT(OUT)
   arguments for intrinsic functions.  The text below assumes we can
   allow INTENT(OUT), just to get expose specific issues.  A proper
   fix may require an entirely new intrinsic subroutine with analogous
   functionality.

   1. Existing interfaces add a new optional argument FOUND:

      - FOUND shall be a scalar of type logical.  If any element
        matches, then FOUND shall .TRUE., otherwise it is .FALSE.

   2. A new interface is introduced for scalar case.

     - FINDLOC (SCALAR, VALUE, FOUND, [, MASK, KIND, BACK])
       - SCALAR shall be a scalor of intrinsic type
       - VALUE shall be a scalar in type conformance with ARRAY <<or
         SCALAR>> as specified in Table 10.2 for the operator == or the
         operator .EQV..n
       - MASK shall be a scalar logical

   Result Characteristics for new interface:

   Note 1.  The scalar use case is a bit of a weird beast.  The result
            is a 0-sized array of rank-1, and thus contains no
            information.

E. CSHIFT, EOSHIFT

   - ARRAY may be of any type.  It shall be an assumed-rank or an
     array or a scalar.

   -  Result value:
      - CSHIFT:  result is the scalar value of ARRAY
      - EOSHIFT: result is the scalar value of ARRAY if SHIFT is 0,
        otherwise the result is 0.

F. IS_CONTIGUOUS
   - It shall be assumed-rank or an array or a scalar.

G. LBOUND, UBOUND
   - ARRAY shall be assumed-rank or an array or a scalar.
   - DIM shall not be present if ARRAY is a rank-0 assumed-rank or a scalar
   - Amend note about rank zero and DIM argument to include scalar case.

H. NORM2
    - X shall be an assumed-type, an array, or a scalar of type real.
    - If X is a scalar or rank-0 assumed-type, DIM shall not be present.

I. PACK
   - ARRAY shall be an assumed-rank, an array, or a scalar of any type.

J. PARITY
   - MASK shall be an assumed-rank, an array, or a scalar of type logical.
   - Add note about use of DIM rank-0 and scalar.

K. PRECISION
   - X shall be an assumed-rank, an array or a scalar of type real or
     complex.

L. PRODUCT, SUM
   - ARRAY shall be an assumed-rank, an array, or a scalar.
   - Add note that DIM cannot be used with rank-0 assumed-rank nor
     with scalar.

M. RESHAPE
   - SOURCE shall be an assumed-rank, array, or scalar of any type.
   - Q: Maybe allow SHAPE to be rank-1 assumed-rank array?

N. SIZE
   - Array shall be assumed-rank, an array or a scalar.
   - Amend NOTE about rank zero assumedd rank and DIM argument to
     include scalar.

O. SHAPE
   - SOURCE shall be assumed-rank, an array, or a scalar of any type.

===END===