ISO/ IEC JTC1/SC22/WG14 N755

*                          Document Number:  WG14 N755/J11 97-118


                               C9X Revision Proposal
                               =====================

*      Title: LIA-1 Binding: <fenv.h> to <stdmath.h>
       Author: Fred J. Tydeman
       Author Affiliation: Tydeman Consulting
       Postal Address: 3711 Del Robles Dr., Austin, Texas, USA, 78727
       E-mail Address: tydeman@tybor.com
       Telephone Number: +1 (512) 255-8696
       Fax Number: +1 (512) 255-8696
       Sponsor: WG14
       Date: 1997-09-16
       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
          __ Language
          __ Preprocessor
          __ Library
             __ Macro/typedef/tag name
             __ Function
             __ Header
          Y_ Other (please specify)  Rational______________________
       Prior Art: None known.
       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/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
       Proposal Attached: _Y Yes __ No, but what's your interest?

       Abstract: The current <fenv.h> supports the floating-point
       environment. This proposal adds the integer environment to
       the floating-point environment to get the combined
       arithmetic environment.  In the process, the header is
       renamed to <stdmath.h> and the combined arithmetic types,
       macros, and functions are renamed.  This then allows the
       addition of three macros to denote the LIA-1 required
       integer exceptions to provide LIA-1 conformance.  If those
       three integer macros are not defined, <stdmath.h> is
       equivalent to the current <fenv.h>.

       Proposal:

       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.

*      Here are the changes to turn <fenv.h> into <stdmath.h>.
       These are given in terms of Draft 10, 1997-06-27 (as found
       on the ftp site).  These first set of changes (up until the
       ================ separator) convert the floating-point
       specific environment header <fenv.h> into a combined
       floating-point and integer environment header <stdmath.h>.
       They are independent of LIA, but make adding LIA easier.

       Note: I do not care what the names get changed to.  The
       prefix could be math, arith, me (math env.), ae (arith
       env.), or something else.

**     -- Specific changes (not in 7.6 <fenv.h>)

***    Page 14, footnote 9: Change from:
	 The IEC 559 standard for binary floating-point arithmetic
	 requires certain status flags and control modes, with user
	 access.  Floating-point operations implicitly set the status
	 flags; modes affect result values of floating-point
	 operations.  Implementations that support such
	 floating-point state will need to regard changes to it as
	 side effects - see Annex F for details.  The floating-point
	 environment library <fenv.h> provides a programming facility
	 for indicating when these side effects matter, freeing the
	 implementations in other cases.
       to:
	 The LIA-1 standard for language independent arithmetic and
	 the IEC 559 standard for binary floating-point arithmetic
	 require certain status flags and control modes, with user
	 access.  Arithmetic operations implicitly set the status
	 flags; modes affect result values of arithmetic operations.
	 Implementations that support such arithmetic state will need
	 to regard changes to it as side effects - see Annex F for
	 details of IEC 559 and Annex H for details of LIA-1.  The
	 arithmetic environment library <stdmath.h> provides a
	 programming facility for indicating when these side effects
	 matter, freeing the implementations in other cases.

**     -- Specific changes for 7.6 Floating-point environment <fenv.h>:

***    Page 207, paragraph #2, 2nd bullet:  Change from:
	 unless its documentation promises otherwise or unless the
	 function is known not to use floating-point;
       to: 
	 unless its documentation promises otherwise;

***    Page 207, paragraph #2, 3rd bullet:  Change from:
	 unless its documentation promises otherwise, or unless the
	 function is known not to use floating-point.
       to:
	 unless its documentation promises otherwise.

***    Page 207, footnote 127:  Change from:
	 This header is designed to support the exception status
	 flags and directed-rounding control modes required by IEC
	 559, and other similar floating-point state information.
	 Also it is designed to facilitate code portability among all
	 systems.
       to:
	 This header is designed to support the directed-rounding
	 control modes required by IEC 559, and exception status
	 flags and other similar arithmetic state information
	 required by both LIA-1 and IEC 559.  Also it is designed to
	 facilitate code portability among all systems.

***    Page 209, paragraph 9:  Change from:
	 beginning with FE_
       to:
	 beginning with MATH_

***    Page 216, footnote 135:  Change from:
	 IEC 559 systems have a default non-stop mode, and typically
	 at least one other mode for trap handling or aborting;
       to:
	 IEC 559 systems have a default non-stop mode, and typically
	 at least one other mode for trap handling or aborting; LIA-1
	 systems have non-stop, trapping, and aborting modes;

       Except for change bars, these sed substitute global commands
       will do the changes in the main body text and the footnotes:

       s/Floating-point/Arithmetic/g
       s/floating-point/arithmetic/g

       Those above sed commands are to be applied only to 7.6
       <fenv.h>

**     -- General changes for the entire standard. Except for
       change bars, these sed substitute global commands will do
       the changes in the main body text and the footnotes:

       s/<fenv.h>/<stdmath.h>/g
       s/fenv_t/math_env_t/g
       s/fexcept_t/math_except_t/g
       s/FE_INEXACT/MATH_FP_INEXACT/g
       s/FE_DIVBYZERO/MATH_FP_DIVBYZERO/g
       s/FE_UNDERFLOW/MATH_FP_UNDERFLOW/g
       s/FE_OVERFLOW/MATH_FP_OVERFLOW/g
       s/FE_INVALID/MATH_FP_INVALID/g
       s/FE_ALL_EXCEPT/MATH_ALL_EXCEPT/g
       s/FE_DFL_ENV/MATH_DFL_ENV/g
       s/FENV_ACCESS/MATH_ENV_ACCESS/g

       s/feclearexcept/mathclearexcept/g
       s/fegetexceptflag/mathgetexceptflag/g
       s/feraiseexcept/mathraiseexcept/g
       s/fesetexceptflag/mathsetexceptflag/g
       s/fetestexcept/mathtestexcept/g
       s/fegetenv/mathgetenv/g
       s/feholdexcept/mathholdexcept/g
       s/fesetenv/mathsetenv/g
       s/feupdateenv/mathupdateenv/g

       [Note:  The following are left as is in C9X:
	      FE_TONEAREST
	      FE_UPWARD
	      FE_DOWNWARD
	      FE_TOWARDZERO
	      fegetround
	      fesetround
       although it might be better to change 'fe' to 'fp'
       and 'FE' to 'FP'.]

       ================

*      These next changes are to mesh the LIA-1 proposal with the
       above changes.

**     In N749 <stdlia.h>:

       -- Remove discussion of integer environment in 7.x opening
       paragraph and footnote.

       -- Change 
	 INT_OVERFLOW to MATH_INT_OVER 
	 INT_DIVBYZERO to MATH_INT_DIVBYZERO 
	 INT_INVALID to MATH_INT_INVALID 
       everywhere and move then to <stdmath.h> after
       MATH_FP_INVALID.  Remove the paragraph describing them from
       7.x.4

       -- Change FE_* to whatever as per changes in <stdmath.h>
       above.

       -- Remove INT_ALL_EXCEPT and the paragraph describing it in
       7.x.4

       -- Remove 7.x.4.2 Exception flags section
       -- Remove 7.x.4.2.1 The ieclearexcept function section
       -- Remove 7.x.4.2.2 The ieraiseexcept function section
       -- Remove 7.x.4.2.3 The ietestexcept function section

**     In N750 LIA-1 annex:

       -- Change macro names to match above changes.
       -- Merge (fe/ie)(clear/raise/test)except into 
       math(clear/raise/test)except.

**     In N751 Combined LIA-1 + IEC 559 annex:

       -- Change macro names to match above changes.
       -- Change function names to match above changes.

**     In N752 Optional parts:

       -- Change macro names to match above changes.
       -- Change function names to match above changes.
       -- Change FE_TRAP_* to MATH_TRAP_*.
       -- Change INT_TRAP_* to MATH_TRAP_*.
       -- Merge (fe/ie)(enable/disable/test)trap into 
       math(enable/disable/test)trap.
       -- Make precision control match rounding control, either
       FE/fe or FP/fp.

**     In N753 Rationale:

       -- Change macro names to match above changes.  
       -- Change function names to match above changes.
       -- Change FE_* to whatever as per changes in <stdmath.h>
       above.