CVTNAN 3CW "26 February 2007" "mathcw-1.00"

Table of contents


NAME

cvtnanf, cvtnan, cvtnanl, cvtnanw, cvtnanq, cvtnanll, cvtnandf, cvtnand, cvtnandl, cvtnandll - convert NaN string to number

SYNOPSIS

cc [ flags ] -I/usr/local/include file(s) -L/usr/local/lib -lmcw [ ... ]

#include <mathcw.h>
#include <cvticw.h>

extern float cvtnanf (const char *s, char **endptr);

extern double cvtnan (const char *s, char **endptr);

extern long double cvtnanl (const char *s, char **endptr);

extern __float80 cvtnanw (const char *s, char **endptr);

extern __float128 cvtnanq (const char *s, char **endptr);

extern long_long_double cvtnanll (const char *s, char **endptr);

extern decimal_float cvtnandf (const char *s, char **endptr);

extern decimal_double cvtnand (const char *s, char **endptr);

extern decimal_long_double cvtnandl (const char *s, char **endptr);

extern decimal_long_long_double cvtnandll (const char *s, char **endptr);

NB: Functions with prototypes containing underscores in type names may be available only with certain extended compilers.


DESCRIPTION

Convert a floating-point NaN (Not a Number) string to a NaN. Lettercase is not significant. Acceptable strings have one of the forms nan(payload), qnan(payload), snan(payload), nan(), qnan(), snan(), nan, qnan, or snan. A leading q means a quiet NaN, and a leading s means a signaling NaN. Otherwise, a quiet NaN is assumed. Some architectures (notably, Intel IA-32 and Motorola 68000) provide only one kind of NaN, a quiet one, so a signaling NaN is treated as a quiet NaN. Any leading sign must be handled separately.

ABOUT NaNs

NaNs are features of the IEEE 754 floating-point architecture, allowing limited representation of undefined results from operations such as 0 / 0, 1 + NaN, Infinity - Infinity, acos(2.0), and sqrt(-1.0)".

NaNs have the unique property that they are unequal to anything, including themselves. Thus, the test expression x != x is true (1) if, and only if, x is a NaN. Regrettably, some compilers botch this simple code, so NaN tests should be handled by the isnan(3CW) functions.

Quiet NaNs in arithmetic operations never raise exceptions, and are therefore not detectable, or trappable, until explicit NaN tests on results are made.

Signaling NaNs in arithmetic operations raise exceptions, but those exceptions may be masked or ignored. The results of such operations are normally quiet NaNs, so the signaling property is lost.

The payloads can be used to identify NaNs produced in particular program locations, but it is necessary to use a bitwise comparison function, such as that provided by memcmp(3), to distinguish between such NaNs.

A common practical use of NaNs in floating-point programs is to distinguish missing data from valid data. For example, a spreadsheet program might ignore NaN cells in computing functions on columns of numbers.

Some compilers provide an option to store NaNs in otherwise-uninitialized floating-point variables, to help catch use-before-definition errors.


RETURN VALUES

Return the converted number using the nan(), qnan(), or snan(), functions, or zero if the string is not recognized. Any parenthesized payload following the alphabetic NaN string is processed by those functions. If present, it should be a hexadecimal string representing the desired bit pattern to be stored in the significand field of the NaN, such as nan(0x0123456789abcdef), nan(beadcafe), qnan(0xdead_beef), or snan(0xaccede_decade_deface_efface_facade). Digit-separating underscores, and the 0x prefix, are optional, and any excess high-order bits of the payload are discarded.

If the payload is not followed by a close parenthesis, the payload is silently discarded without any error indication, but the specified NaN is still recognized.

If endptr is not NULL, set the pointer to which it points to the address of the character following the last character successfully converted. With suitable conventions for value delimiters, it is then possible to determine whether the value is erroneous or not.

Conversion of NaN strings does not set errno.


ERRORS

None.

SEE ALSO

cvtia(3CW), cvtid(3CW), cvtig(3CW), cvtih(3CW), cvtinf(3CW), cvtio(3CW), cvtob(3CW), cvtod(3CW), cvtog(3CW), cvtoh(3CW), cvton(3CW), cvtoo(3CW), infty(3CW), isnan(3CW), memcmp(3), printf(3CW), scanf(3CW), strtod(3), strtof(3), strtold(3).