NCEG Generic Functions: Second Draft

[David Hough]

At the NCEG (X3J11.1) January 1991 meeting in Plano, Texas, I will move to
adopt the following proposal, perhaps modified slightly, into the NCEG
Technical Report.  Consequently I request that persons planning to attend that
meeting who would vote against such a motion please advise dghavalidgh.com as
to what changes would be required to convert their "no" vote to a "yes" one so
that relatively minor points can be resolved in advance of the meeting.  Note
that the proposal must be frozen from the mailing deadline of 16 November
until the meeting, at which 90 minutes have been tentatively allocated to
discuss generic functions.

     There is no need to advise me if you would vote in favor of the following
or a similar proposal, or if you would vote against this proposal or any simi-
lar one, or if your only objections relate to specific functions that are on
or off the list proposed for section 3.3.18; that list has to be worked out
later in any event, in conjunction with the IEEE, complex, and array exten-
sions proposals.

     tbl | troff -ms source is available from dghavalidgh.com.

Introduction

     The Numerical C Extensions Group is preparing a technical report of
recommended extensions for ANSI-C to render it more suitable for scientific
computation.   My goal is to render the extended language at least as adequate
as Fortran-77 in all areas.

     The NCEG report is expected to contain a number of independent sections.
Pioneering implementations might choose to implement some or all of the sec-
tions.  Zortech has already incorporated some preliminary ideas from one of
the subgroups in a C compiler product for PC's.  My goal is to get the
language extensions defined, published, and implemented at least on a GCC base
before work begins on the next major revision of the ANSI-C Standard.

     A well-constructed technical report and working implementations enhance
the propsect that particular language extensions will be accepted for the next
major revision of ANSI-C, although nothing is guaranteed.

     The following proposes an extension to provide a facility like the gen-
eric intrinsic function operators of Fortran-77.  Text and Rationale sections
are intermixed.

New Section 3.3.2.2.1: Generic Function Calls

     Constraints: The expression that denotes the called function shall be an
identifier that is a generic function designator.  The number of arguments
shall agree with the number of operands for that generic function.   Each
argument shall be of appropriate arithmetic type - integral, floating-point,
imaginary, or complex - according to the built-in prototype for that generic
function.

     Semantics: A generic function identifier followed by parentheses contain-
ing a non-empty comma-separated list of expressions is a generic function
call.  The list of expressions specifies the arguments to the function.  In
preparing for the call to a function, the arguments are evaluated, and each
parameter is assigned the value of the corresponding argument.

     When the floating-point evaluation style "evaluate-to-narrowest-need" is
in effect, generic functions of one argument are evaluated in the type of that
argument; generic functions of more than one argument are evaluated in the
type of least precision and dimension to which all arguments can be promoted.
When the floating-point evaluation style "evaluate-to-widest-need" is in
effect, generic functions are evaluated in the type of the complete expres-
sion, widened if appropriate in the cases of assignment and function arguments
as described elsewhere.  Arguments to generic functions are not complete
expressions.  Like conventional arithmetic operators, generic functions do not
bound complete expressions in evaluate-to-widest-need expression evaluation.

     In both expression evaluation modes, the precision of floating-point
expressions will be at least as high as the minimum precision currently speci-
fied.

     Like conventional arithmetic operators, generic function semantics are
not specified rigorously but rely on common mathematical understanding.

     Like conventional arithmetic operators, generic function exception han-
dling is not specified.  The FPCE section defines exception handling for
implementations defining __FPCE_IEEE__.

     Like conventional arithmetic operators, generic functions can't be passed
as parameters nor be operands of the & address-of operator.

     The order of evaluation of the arguments, and subexpressions within the
arguments, is unspecified.

     Rationale: See the proposal for IEEE extensions for discussions of
"evaluate-to-narrowest-need" vs. "evaluate-to-widest-need", "minimum evalua-
tion precision", and "complete expression".  See the proposal for complex
extensions for "dimension" and "imaginary" types; floating-point and imaginary
expressions must be promoted to complex types before they can be combined with
each other or with complex types.

     Rationale: It would be possible to build each generic function into the
grammar of the C language in the way that the conventional arithmetic opera-
tors are.  I don't believe that is worthwhile or as useful as enumerating them
with their permissible operands.

     Rationale: This proposal explicitly does not encompass user-defined gen-
eric functions for existing types; that would require a notion of generic type
declarations, which are not needed for a predefined function list.  Moreover
this proposal provides no way to extend its predefined generic functions to
user-defined types; that facility is of little value without a corresponding
capability to overload the conventional arithmetic operators +-*/ as well.
Operator overloading is important in higher-level languages such as C++ but
too heavyweight for C.

     Rationale: Generic functions might set errno, or they might not.  High-
performance implementations probably wouldn't.

     Rationale: In conventional expression evaluation, generic function
evaluation type is determined by the types of operands rather than by default
argument promotions or explicit prototypes.  In "widest-need" expression
evaluation, generic function evaluation type is determined by the entire com-
plete expression.

New Section 3.3.18: List of Standard Generic Functions

     Each implementation shall recognize the following generic function  iden-
tifiers:

Name          Args   Types   Definition

                             # from ANSI-C
__acos          1        F   trig
__asin          1        F   trig
__atan          1        F   trig
__ceil          1        F   integral part rounded up - exact
__cos           1       FC   trig
__cosh          1        F   trig
__exp           1       FC   exponential
__floor         1        F   integral part rounded down - exact
__fmod          2       IF   remainder, same sign as first arg
__log           1       FC   natural logarithm
__pow           2      IFC   power
__sin           1       FC   trig
__sinh          1        F   trig
__tan           1        F   trig
__tanh          1        F   trig
__sqrt          1      IFC   square root
                             # from Fortran-77
__abs           1      IFC   absolute value or modulus
__aint          1        F   integral part rounded toward zero - exact
__anint         1        F   integral part bias rounded toward nearest - exact
__conjg         1        C   complex conjugate
__dim           2       IF   positive difference
__max         >=1       IF   maximum
__min         >=1       IF   minimum
                             # from IEEE 754
__copysign      2       IF   copy sign bit
__logb          1        F   exponent of radix
__remainder     2       IF   remainder, minimum magnitude
__scalb         2        F   scale by power of radix
                             # suggestions from various sources
__arg           1      IFC   (complex) argument
__arint         1        F   integral part bias rounded per current rounding direction - inexact
__expm1         1        F   exp(x)-1
__log1p         1        F   log(1+x)
__lgamma        1        F   log(|gamma(x)|)
__mmax        >=1      IFC   maximum magnitude
__mmin        >=1      IFC   minimum magnitude

Permitted argument types are indicated thus:

Letter   Permitted Types

  I      integral (signed and unsigned)
  F      floating-point (float, double, long double, long float if defined)
  C      integral, floating-point, imaginary, complex

Multivalued complex functions return principal values.

     __aint, __anint: In __FPCE__754__ implementations, these functions do not
raise inexact.

     __arg:  This function computes the argument of a complex number between
-pi and +pi, and eliminates the need for generic __atan2. __abs(complex) elim-
inates the need for generic __hypot.

     __arint: In __FPCE_754__ implementations, this function raises inexact
when the result differs from the argument.

     __fmod:  This function could be subsumed by extending the % operator to
permit floating-point operands.

     __mmax,__mmin:  __mmax selects the argument with the largest magnitude
(absolute value).  __mmin selects the argument with the smallest magnitude.

     __scalb:  A generic function as originally envisioned by IEEE 754 with
both arguments in floating-point format.

     Rationale: The list of standard functions might be contentious.  The
foregoing indicates the approximate scope but the exact composition of the
list is to be worked out in conjunction with at least the IEEE, complex, and
array extensions committees.  ANSI-C, SVID 3, X/Open, POSIX, Fortran-77,
Fortran-90, IEEE 754, and IEEE 854 could all be examined for candidate func-
tions.

     Rationale: __nextafter looks like a potential generic function, but it
must not be.  The type of the function must be the type of the first argument.

New Section 4.14: <nceg_generic.h>

     This header file provides a convenient way to declare all the standard
generic functions by their conventional names. #include <nceg_generic.h> con-
tains declarations of the following type for each generic function listed in
3.3.18:


#undef sqrt
#define sqrt(x) __sqrt(x)