fpclassify, isfinite, isinf, isnan, and isnormal—floating-point classification macros; finite, finitef, isinf, isinff, isnan, isnanf—test for exceptional numbersSynopsis
[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_INFINITEx is either plus or minus infinity;
FP_NANx is "Not A Number" (plus or minus);
FP_NORMALx is a "normal" number (i.e. is none of the other special forms);
FP_SUBNORMALx is too small be stored as a regular normalized number (i.e. loss of precision is likely); or
FP_ZEROx 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):
zeroA number which contains all zero bits, excluding the sign bit.
subnormalA number with a zero exponent but a nonzero fraction.
normalA number with an exponent and a fraction.
infinityA number with an all 1’s exponent and a zero fraction.
NANA 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.
Returns
The fpclassify macro returns the value corresponding to the appropriate FP_ macro.
The isfinite macro returns nonzero if x is finite, else 0.
The isinf macro returns nonzero if x is infinite, else 0.
The isnan macro returns nonzero if x is an NaN, else 0.
The isnormal macro returns nonzero if x has a normal value, else 0.
Portability
math.h macros are C99, POSIX.1-2001.
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.