Date: 2002-01-02

Title: Optional support for Signaling NaNs

- Optional support for Signaling NaNs
- 5.2.4.2.2 Characteristics of floating types
`<float.h>` - 6.10.8 Predefined macro names
- 7.12 Mathematics
`<math.h>` - 7.12.11.x The
functions`nans` - 7.19.6.1 The
function`fprintf` - 7.19.6.2 The
function`fscanf` - 7.20.1.3 The
,`strtod`, and`strtof`functions`strtold` - 7.24.2.1 The
function`fwprintf` - 7.24.2.2 The
function`fwscanf` - 7.24.4.1.1 The
,`wcstod`, and`wcstof`functions`wcstold`

- 5.2.4.2.2 Characteristics of floating types

The following was adopted from NCEG 91-028 (Floating-Point C Extensions), the last NCEG (Numerical C Extensions Group) document to discuss support for Signaling NaNs.

IEC-60559 (International version of IEEE-754) requires two kinds of NaNs: Quiet NaNs and Signaling NaNs. Standard C only adopted Quiet NaNs. It did not adopt Signaling NaNs because it was believed that they are of too limited utility for the amount of work required. But, for implementations that do wish to support Signaling NaNs, it is highly recommended that they be supported in the following manner (to promote consistency in implementations and portability among applications).

For this to work, there are several requirements on both applications and implementations. The application needs to be able to determine if the implementation supports signaling NaNs. The application needs to indicate to the implementation that it wishes to use signaling NaNs. The implementation needs a way to determine, both at translation time and runtime, if support for signaling NaNs is being asked for.

An application indicates that it wants to use signaling NaNs by
defining the macro symbol ** _WANT_SNAN**. If defined,

An implementation indicates that it supports signaling NaNs by
predefining the macro symbol ** __SUPPORT_SNAN__**.

It is assumed that if both ** _WANT_SNAN** and

Floating types may support not only numeric values, finite and
possibly infinite, but also NaN (Not-a-Number) values, which do not
represent numbers. A NaN that generally raises an exception when
encountered as an operand of arithmetic operations is called a
*signaling NaN*; the operation is said to *trigger* the signaling NaN. A
NaN that behaves predictably and does not raise exceptions in
arithmetic operations is called a *quiet NaN*. The IEEE floating-point
standards specify quiet and signaling NaNs, but this document applies
the general terms for non-IEEE implementations as well -- for example,
the VAX reserved operand and the CDC and CRAY indefinite qualify as
signaling NaNs. In IEEE standard arithmetic, operations that trigger
a signaling NaN argument generally return a quiet NaN result, provided
no trap is taken.

The primary utility of quiet NaNs -- "to handle otherwise intractable situations, such as providing a default value for 0.0/0.0" -- can be well supported through straightforward extensions to Standard C.

Other applications of NaNs may prove useful. Available parts of NaNs have been used to encode auxiliary information, for example about the NaN's origin. Signaling NaNs are good candidates for filling uninitialized storage; and their available parts could distinguish uninitialized floating objects. IEEE signaling NaNs and trap handlers potentially provide hooks for maintaining diagnostic information or for implementing special arithmetics.

However, C support for signaling NaNs, or for auxiliary information that could be encoded in NaNs, is problematic. Implementation mechanisms may trigger signaling NaNs, or fail to, in mysterious ways. The IEEE floating-point standards require that NaNs propagate, but not all implementations faithfully propagate the entire contents. And even the IEEE standards fail to specify the contents of NaNs through format conversion, which is pervasive in some C implementation mechanisms.

Whether an operation that merely returns the value of a numeric
operand, changing at most its sign, triggers signaling NaNs is
unspecified. Such operations include conversions that do not change
precision, the unary + and - operators, and the ** fabs**
and

Leaving the semantics unspecified allows more efficient implementation. The IEEE floating-point standards explicitly give the option to implement same-precision conversions by either arithmetic operations or data moves, which is important because of the frequency of such conversions in parameter passing and assignments.

The predefined macro names are augmented with

__SUPPORT_SNAN__

which has the value integer constant 1, intended to indicate conformance to these specifications (optional support for Signaling NaNs).

The number classification macros are augmented with

FP_NANSFP_NANQ

which expand to integer constant expressions with values distinct
from all the other number classification macros.
** FP_NANS** is a subset of

Results for the inquiry macros specified in the remainder of this section are undefined if the argument is not of floating type. These macros should not trigger signaling NaNs.

Synopsis

#include <math.h>double nans(const char *tagp);float nansf(const char *tagp);long double nansl(const char *tagp);

Description

An implementation declares a ** nans** function if and
only if it supports signaling NaNs in the type of the function. The
call

Returns

The ** nans** functions return a signaling NaN with
content indicated through tagp, provided they don't trigger it
first.

For a signaling NaN value, the implementation has the options to
trigger the signaling NaN or to convert it in one of the styles
*[*`-`*]*** nans** or

Use of an upper case format specifier, ** E**,

All valid syntax -- including infinity, NaN, and signed zero -- is
treated in the same manner as ** strtod**.

The ** fscanf** function should not trigger a signaling
NaN that it produces in response to a signaling NaN input string.

By not triggering signaling NaNs, ** fscanf** provides
a way of setting signaling NaN values. This might appear to be in
conflict with the IEEE floating-point standards which require that
binary-decimal conversion trigger signaling NaN input; however, the
conversion of

The expected form of the subject sequence (after an optional sign) is augmented to include:

** -- NANS** or

Strings of the form ** NANS** or

The option to trigger a signaling NaN is needed by implementations
whose function-return mechanism involves conversion between different
formats, which may trigger the signaling NaN. For example, an
implementation that returns functions' results in a wider-than-float
register might not be able to return a signaling NaN result for
** strtof**.

Although ** SNAN** would have been a more suggestive representation for
signaling NaNs,

This function is extended in the same manner as
** fprintf**.

This function is extended in the same manner as
** fscanf**.

These functions are extended in the same manner as
** strtod**,