ISO/ IEC JTC1/SC22/WG14 N792

*                     Document Number:  WG14 N792/J11 97-156

                               C9X Revision Proposal

*      Title: C9X and LIA-1 informative annex.
       Author: Fred J. Tydeman
       Author Affiliation: Tydeman Consulting
       Postal Address: 3711 Del Robles Dr., Austin, Texas, 78727, USA
       E-mail Address:
       Telephone Number: +1 (512) 255-8696
       Fax Number: +1 (512) 255-8696
       Sponsor: WG14
       Date: 1997-10-23
       Document History: WG14 N758/J11 97-121.
       Proposal Category:
          Y_ Editorial change/non-normative contribution
          __ Correction
          __ New feature
          __ Addition to obsolescent feature list
          __ Addition to Future Directions
          __ Other (please specify)  ______________________________
       Area of Standard Affected:
          __ Environment
          Y_ Language
          __ Preprocessor
          __ Library
             __ Macro/typedef/tag name
             __ Function
             __ Header
          Y_ Other (please specify)  Annex_________________________
       Prior Art: None.____________________________________________
       Target Audience: Programmers writing programs that perform a
       significant amount of numeric processing.___________________
       Related Documents (if any):
        WG14/N758 C9X and LIA-1 informative annex,
        WG14/N756 LIA-1 Binding: Arithmetic exception => SIGFPE,
        WG14/N755 LIA-1 Binding: <fenv.h> to <stdmath.h>,
        WG14/N753 LIA-1 Binding: Rationale,
        WG14/N752 LIA-1 Binding: Optional parts annex,
        WG14/N751 LIA-1 Binding: Combined LIA-1 + IEC-559 annex,
        WG14/N750 LIA-1 Binding: LIA-1 annex.
        WG14/N749 LIA-1 Binding: <stdlia.h>,
        WG14/N748 LIA-1 Binding: Adding 'pole' from LIA-2,
        WG14/N747 IEC 559 Binding: Signaling NaNs,
        WG14/N528 C Binding for LIA-1,
        WG14/N488 LIA-2 (math library),
        WG14/N487 LIA-1 (arithmetic),
        WG14/N486 LIA Overview,
        WG14/N463 Impact of adding LIA-1,
        WG14/N461 C Binding of LIA-1,
        Defect Report 152 longjmp from a signal handler,
        Defect Report 099 Narrowing of FP expression,
        Defect Report 056/063 Accuracy of floating-point,
        Defect Report 036 Representation of FP constants,
        Defect Report 025 Floating-point representation.
       Proposal Attached: _Y Yes __ No, but what's your interest?

       Abstract: This is an informative annex to C9X to document
       the extent to which the C language currently supports the
       LIA-1 requirements.  It is NOT a binding bewteen C and LIA-1.

       The other proposals should be considered a starting point
       of the LIA-1 to C binding (if that binding is wanted).


       Note: The '*' characters in the lefthand column are not part
       of the proposal (they are useful for emacs M-x outline mode)

       In the following, bold text, italic text,
       <TT>code sample</TT> are the conventions used to indicate
       text different from normal.

*      -- Add to Annex A Bibliography:

       ISO/IEC 10967-1:1994(E) Information technology --
       Language independent arithmetic -- Part 1: Integer and
       floating point arithmetic.

*      -- Add a new annex, here called H, after annex G IEC
       559-compatible complex arithmetic:

                               Annex H

                    Language independent arithmetic

**     H.1 Introduction
       This annex documents the extent to which the C language
       supports the standard: ISO/IEC 10967-1 Language independent
       arithmetic, part 1, integer and floating-point arithmetic
       (LIA-1).  LIA-1 is more general than IEC 559 (annex F) in
       that it covers integer and diverse floating-point arithmetics.

**     H.2 Types

       The relevant C arithmetic types meet the requirements of LIA-1 
       types if an implementation adds notification of exceptional 
       arithmetic operations and meets the 1-ULP accuracy requirement.

***    H.2.1 Boolean Type

       The LIA-1 data type Boolean is implemented by the C data
       type bool with values of true and
       false, all from <stdbool.h>.

***    H.2.2 Integer Types

       The signed C integer types int, long, 
       long long and the corresponding unsigned types are 
       compatible with LIA-1.  If an implementation adds support 
       for the LIA-1 exceptional values integer_overflow 
       and undefined, then those types are LIA-1 conformant 
       types.  C's unsigned integer types are "modulo" in the LIA-1
       sense in that overflows or out-of-bounds results silently wrap.  
       An implementation that defines signed integer types as also 
       being modulo need not detect integer overflow, in which case, 
       only integer divide-by-zero need be detected.

       The parameters for the integer data types can be
       accessed by the following:

       maxint         INT_MAX, LONG_MAX, LLONG_MAX,
                      UINT_MAX, ULONG_MAX, ULLONG_MAX

       minint         INT_MIN, LONG_MIN, LLONG_MIN

       The parameter "bounded" is always true, and is not provided.
       The parameter "minint" is always 0 for the unsigned types, and
       is not provided for those types.

****   H.2.2.2 Integer Operations

       The integer operations on integer types are the following:

       addI           x + y

       subI           x - y

       mulI           x * y

       divI, divtI    x / y

       remI, remtI    x % y

       negI           - x

       absI           abs(x), labs(x), llabs(x)

       eqI            x == y

       neqI           x != y

       lssI           x < y

       leqI           x <= y

       gtrI           x > y

       geqI           x >= y

       where x and y are expressions of the same integer type.

***    H.2.3 Floating-Point Types

       The C floating-point types float, double, and long double 
       are compatible with LIA-1.  If an implementation adds
       support for the LIA-1 exceptional values underflow,
       floating_overflow, and undefined, then those 
       types are conformant with LIA-1.  An implementation that
       uses IEC 559 floating-point formats and operations (see 
       Annex F) along with IEC 559 status flags and traps has 
       LIA-1 conformant types.

****   H.2.3.1 Floating-Point Parameters

       The parameters for a floating point data type can
       be accessed by the following:

       r              FLT_RADIX

       p              FLT_MANT_DIG, DBL_MANT_DIG, LDBL_MANT_DIG

       emax           FLT_MAX_EXP, DBL_MAX_EXP, LDBL_MAX_EXP

       emin           FLT_MIN_EXP, DBL_MIN_EXP, LDBL_MIN_EXP

       The derived constants for the floating point
       types are accessed by the following:

       fmax           FLT_MAX, DBL_MAX, LDBL_MAX

       fminN          FLT_MIN, DBL_MIN, LDBL_MIN


       rnd_style      FLT_ROUNDS

****   H.2.3.2 Floating-Point Operations

       The floating-point operations on floating-point
       types are the following:

       addF           x + y

       subF           x - y

       mulF           x * y

       divF           x / y

       negF           - x

       absF           fabsf(x), fabs(x), fabsl(x)

       exponentF      1.f+logbf(x), 1.0+logb(x), 1.L+logbl(x)

       scaleF         scalbnf(x, n), scalbn(x, n), scalbnl(x, n)
                      scalblnf(x, li), scalbln(x, li), scalblnl(x, li)

       intpartF       modff(x, &y), modf(x, &y), modfl(x, &y)

       fractpartF     modff(x, &y), modf(x, &y), modfl(x, &y)

       eqF            x == y

       neqF           x != y

       lssF           x < y

       leqF           x <= y

       gtrF           x > y

       geqF           x >= y

       where x and y are expressions of the same floating point
       type, n is of type int, and li is of type long int.

****   H.2.3.3 Rounding Styles

       The C Standard requires all floating types use the same
       radix and rounding style, so that only one identifier for
       each is provided to map to LIA-1.

       The FLT_ROUNDS parameter can be used to indicate the LIA-1
       rounding styles:

           truncate       FLT_ROUNDS == 0

           nearest        FLT_ROUNDS == 1

           other          FLT_ROUNDS != 0 && FLT_ROUNDS != 1

       provided that an implementation extends FLT_ROUNDS to cover
       the rounding style used in all relevant LIA-1 operations, not
       just addition as in C.

***    H.2.4 Type Conversions

       The LIA-1 type conversions are the following type casts:

       cvtI'->I       (int)i, (long)i, (long long)i,
                      (unsigned int)i, (unsigned long)i,
                      (unsigned long long)i

       cvtF->I        (int) x,
                      (long) x,
                      (long long) x,
                      (unsigned int) x,
                      (unsigned long) x,
                      (unsigned long long) x

       cvtI->F        (float) i, (double) i, (long double) i

       cvtF'->F       (float) x, (double) x, (long double) x

       In the above conversions from floating to integer, the use
       of (cast)x can be replaced with (cast)round(x), (cast)rint(x)
       (cast)nearbyint(x), (cast)trunc(x), (cast)ceil(x), or
       (cast)floor(x) as they all meet LIA's requirements on
       floating to integer rounding.  The remainder() function is
       useful for doing silent wrapping to unsigned integer types.

       C's floating-point to integer conversion functions,
       lrint(), llrint(), lround(), and llround(), can meet LIA-1's
       requirements if an implementation handles out of range as
       per LIA-1.

       C's conversions (type casts) from floating-point to
       floating-point can meet LIA-1 if an implementation uses
       round to nearest.

       C's conversions (type casts) from integer to floating-point
       can meet LIA-1 if an implementation uses round to nearest.

**     H.3 Notification

       Notification is the process by which a user or program is
       informed that an exceptional arithmetic operation has occured.
       C's operations are compatible with LIA-1 in that C allows an
       implementation to cause a notification to occur when any 
       arithmetic operation returns an exceptional value as 
       defined in LIA-1 clause 5.

***    H.3.1 Notification alternatives

       LIA-1 requires at least the following two alternatives 
       for handling of notifications: setting indicators or 
       trap-and-terminate.  LIA-1 allows a third alternative:

       An implementation need only support a given notification 
       alternative for the entire program.  An implementation may 
       support the ability to switch between notification 
       alternatives during execution, but is not required to do so.  
       An implementation can provide separate selection for each 
       kind of notification, but this is not required.

       C allows an implementation to provide notification.
       C's SIGFPE (for traps) and FE_INVALID, FE_DIVBYZERO, 
       FE_OVERFLOW, FE_UNDERFLOW (for indicators) can provide
       LIA notification.

       C's signal handlers are compatible with LIA-1.  Default 
       handling of SIGFPE can provide trap-and-terminate 
       behavior.  User provided signal handlers for SIGFPE 
       allow for trap-and-resume behavior.

****   H.3.1.1 Indicators

       C's <fenv.h> status flags are compatible with LIA's indicators.

       The following mapping is for floating-point types:

       undefined           FE_INVALID, FE_DIVBYZERO

       floating_overflow   FE_OVERFLOW

       underflow           FE_UNDERFLOW

       The floating-point indicator interrogation and manipulation
       operations are:

       set_indicators      feraiseexcept(i)

       clear_indicators    feclearexcept(i)

       test_indicators     fetestexcept(i)

       current_indicators  fetestexcept(FE_ALL_EXCEPT)

       where i is an expression of type int representing a
       LIA-1 indicator subset.

       C allows an implementation to provide the following LIA-1
       required behavior: at program termination if any indicator 
       is set the implementation shall send an unambiguous and 
       "hard to ignore" message (see LIA-1 subclause 6.1.2)

       LIA-1 does not make the distinction between floating-point
       and integer for undefined.  This documentation is 
       making that distinction because <fenv.h> covers only the
       floating-point indicators.

****   H.3.1.2 Traps

       C is compatible with LIA's trap requirements.  An
       implementation can provide an alternative of notification 
       through termination with a ``hard-to-ignore'' message 
       (see LIA-1 subclause 6.1.3).

       LIA-1 does not require that traps be precise.

       C does require that SIGFPE be the signal
       corresponding to arithmetic exceptions, if there is any
       signal raised for them.

       C has signal handlers for SIGFPE and allows trapping
       arithmetic exceptions.  When arithmetic exceptions do trap, 
       C's signal-handler mechanism allows trap-and-terminate (either 
       default implementation behavior or user replacement for it) 
       and trap-and-resume, at the programmer's option.