Chapter Contents
Previous
Next
|
Chapter Contents |
Previous |
Next |
| nan, nanf, nanl |
| Portability: | C99 |
| SYNOPSIS | |
| DESCRIPTION | |
| RETURN VALUE | |
| IMPLEMENTATION | |
| EXAMPLE | |
| RELATED FUNCTIONS | |
| SEE ALSO |
| SYNOPSIS |
#include <math.h> double nan(const char *tagp); float nanf(const char *tagp); long double nanl(const char *tagp);
| DESCRIPTION |
The functions nan, nanf, and nanl convert a
character
sequence pointed to by tagp to double, float,
and long double NaN representation, respectively. The character sequence is
an array of chars that indicates the bit pattern for the NaN. Valid values
differ depending on whether one is using Binary (IEEE) floating point numbers
(that is, compiled with the bfp option) or
the traditional, IBM hexadecimal floating point (HFP) numbers. See "Implementation"
for more information.
| RETURN VALUE |
For Binary floating point (BFP) the functions, nan, nanf, and
nanl return a double, float, and long double NaN representation,
respectively, with a fractional bit pattern based on the character sequence
pointed to by the tagp argument. If tagp points to a NULL string, then the default quiet NaN is
returned. If the first character in the character sequence string is invalid,
a diagnostic is issued, errno is set to EARG, and the default quiet NaN is
returned. If the character sequence begins with a quiet
or signaling NaN prefix letter, then any following hex
digits in the character sequence must be valid for that type of NaN. That
is, the most significant fraction bit must be represented correctly. Otherwise,
a diagnostic is issued, errno is set to EARG, and the default quiet or signaling
NaN as indicated by the prefix letter is returned. If any other characters
in the character sequence string is not valid, the conversion stops at that
point and a diagnostic is issued, errno is
set to EARG, and a NaN whose fraction bits
have been described by the string argument up to the point of the invalid
character is returned. See "Implementation" for a description
of the character sequence string.
For Hexadecimal floating point (HFP) the functions, nan, nanf, and
nanl return a double, float, and long double zero representation,
respectively, with the bits set in the sign and exponent fields based on the
character sequence pointed to by the tagp argument.
If tagp points to a NULL string, then the default
negative zero value, only sign bit set, is returned. If the first character
in the character sequence string is invalid, a diagnostic is issued, errno
is set to EARG, and the default negative zero is returned. If any other characters
in the character sequence string is not valid, the conversion stops at that
point and a diagnostic is issued, errno is
set to EARG, and a zero value whose sign and
exponent bits that have been described by the string argument up to the point
of the invalid character is returned. See "Implementation" for
a description of the character sequence string.
| IMPLEMENTATION |
A binary NaN is represented by all Exponent bits being set to one and at least one Fraction bit set to one. The most significant fraction bit determines whether the NaN is a signaling NaN or a quiet NaN. If the most significant fraction bit is set, then it is a quiet NaN. The value of the character sequence for a binary floating point NaN can be:
"" equals a NULL string, the default
quiet NaN.
"Q" or "q"
equals the default quiet NaN.
"S" or "s"
equals the default signaling NaN.
"xxxxxxxx" equals hex digits representing
the fraction bits starting with the most significant bit. Trailing zeros maybe
omitted. The hex digits may be prefixed optionally by "0x".
"l_xxxxxx" equals where l is either
a "Q" or "q",
for a quiet NaN or a "S" or "s", for a signaling NaN, followed by an underscore and hex
digits representing the fraction bits starting with the most significant bit.
Trailing zeros maybe omitted.
Technically, the traditional Hex Floating Point does not
support NaNs. However, there are certain bit patterns that are not valid numbers,
or rather are treated as if they had the value of zero, that have traditionally
been used to represent missing or invalid values. These missing values have
one or more bits set in the sign and/or exponent fields and all zeros in the
fraction field. The nan, nanf, and nanl functions have been
implemented for HFP to return these values. Therefore, the value of the character
sequence for Hexadecimal floating point numbers is a string consisting of
two hexadecimal characters, optionally prefixed by 0x,
that represent the bit values for the sign and exponent of the return value.
By default, that is, when the nan, nanf, or nanl functions are
called with a NULL string, a missing value of negative zero is returned, that
is, only the sign bit is set. Otherwise, these functions will return a value
based on the hex string pointed to by tagp.
For example, calling nan("0xaa") will return
a floating point zero value with the bit pattern 0xaa00000000000000.
Note: Because these values are equivalent to zero
for HFP, that is, 0.0 == nan("0xaa") is
TRUE, this does not violate the ANSI C99 standard, which states that any implementations
of these functions that do not support NaNs must return zero. ![[cautionend]](../common/images/cautend.gif)
| EXAMPLE |
Some results from calling BFP nan:
call bit pattern returned (hex)
_________ ____________________
nan("") = 0x7ff8000000000000
-nan("") = 0xfff8000000000000
nan("Q") = 0x7ff8000000000000
-nan("Q") = 0xfff8000000000000
nan("q") = 0x7ff8000000000000
-nan("q") = 0xfff8000000000000
nan("S") = 0x7ff4000000000000
-nan("S") = 0xfff4000000000000
nan("s") = 0x7ff4000000000000
-nan("s") = 0xfff4000000000000
nan("q_8fff") = 0x7ff8fff000000000
-nan("q_8fff") = 0xfff8fff000000000
nan("8fff") = 0x7ff8fff000000000
-nan("8fff") = 0xfff8fff000000000
nan("0x8fff") = 0x7ff8fff000000000
-nan("0x8fff") = 0xfff8fff000000000
nan("s_7fff") = 0x7ff7fff000000000
-nan("s_7fff") = 0xfff7fff000000000
nan("7fff") = 0x7ff7fff000000000
-nan("7fff") = 0xfff7fff000000000
nan("0x7fff") = 0x7ff7fff000000000
-nan("0x7fff") = 0xfff7fff000000000
Some results from calling HFP nan:
call bit pattern returned (hex)
_________ ____________________
nan("") = 0x8000000000000000
nan("0x03") = 0x0300000000000000
nan("03") = 0x0300000000000000
nan("0xff") = 0xff00000000000000
nan("ff") = 0xff00000000000000
| RELATED FUNCTIONS |
strtod, strtof, strtold
| SEE ALSO |
"Mathematical Functions" in Chapter 2, "Function Categories."
|
Chapter Contents |
Previous |
Next |
 Top of Page |
Copyright © 2004 by SAS Institute Inc., Cary, NC, USA. All rights reserved.