1.32 fpclassify, isfinite, isinf, isnan, and isnormal—floating-point classification macros; finite, finitef, isinf, isinff, isnan, isnanf—test for exceptional numbers

Synopsis

     [C99 standard macros:]
     #include <math.h>
     int fpclassify(real-floating x);
     int isfinite(real-floating x);
     int isinf(real-floating x);
     int isnan(real-floating x);
     int isnormal(real-floating x);
     
     [Archaic SUSv2 functions:]
     #include <math.h>
     int isnan(double arg);
     int isinf(double arg);
     int finite(double arg);
     int isnanf(float arg);
     int isinff(float arg);
     int finitef(float arg);
     

Description
fpclassify, isfinite, isinf, isnan, and isnormal are macros defined for use in classifying floating-point numbers. This is a help because of special "values" like NaN and infinities. In the synopses shown, "real-floating" indicates that the argument is an expression of real floating type. These function-like macros are C99 and POSIX-compliant, and should be used instead of the now-archaic SUSv2 functions.

The fpclassify macro classifies its argument value as NaN, infinite, normal, subnormal, zero, or into another implementation-defined category. First, an argument represented in a format wider than its semantic type is converted to its semantic type. Then classification is based on the type of the argument. The fpclassify macro returns the value of the number classification macro appropriate to the value of its argument:

FP_INFINITE

x is either plus or minus infinity;

FP_NAN

x is "Not A Number" (plus or minus);

FP_NORMAL

x is a "normal" number (i.e. is none of the other special forms);

FP_SUBNORMAL

x is too small be stored as a regular normalized number (i.e. loss of precision is likely); or

FP_ZERO

x is 0 (either plus or minus).

The "is" set of macros provide a useful set of shorthand ways for classifying floating-point numbers, providing the following equivalent relations:

isfinite(x)

returns non-zero if x is finite. (It is equivalent to (fpclassify(x) != FP_INFINITE && fpclassify(x) != FP_NAN).)

isinf(x)

returns non-zero if x is infinite. (It is equivalent to (fpclassify(x) == FP_INFINITE).)

isnan(x)

returns non-zero if x is NaN. (It is equivalent to (fpclassify(x) == FP_NAN).)

isnormal(x)

returns non-zero if x is normal. (It is equivalent to (fpclassify(x) == FP_NORMAL).)

The archaic SUSv2 functions provide information on the floating-point argument supplied.

There are five major number formats ("exponent" referring to the biased exponent in the binary-encoded number):

zero

A number which contains all zero bits, excluding the sign bit.

subnormal

A number with a zero exponent but a nonzero fraction.

normal

A number with an exponent and a fraction.

infinity

A number with an all 1's exponent and a zero fraction.

NAN

A number with an all 1's exponent and a nonzero fraction.

isnan returns 1 if the argument is a nan. isinf returns 1 if the argument is infinity. finite returns 1 if the argument is zero, subnormal or normal. The isnanf, isinff and finitef functions perform the same operations as their isnan, isinf and finite counterparts, but on single-precision floating-point numbers.

It should be noted that the C99 standard dictates that isnan and isinf are macros that operate on multiple types of floating-point. The SUSv2 standard declares isnan as a function taking double. Newlib has decided to declare them both as functions and as macros in math.h to maintain backward compatibility.

The functions originate from BSD; isnan was listed in the X/Open Portability Guide and Single Unix Specification, but was dropped when the macro was standardized in POSIX.1-2001.