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

Table of contents


NAME

cvtigf, cvtig, cvtigl, cvtigw, cvtigq, cvtigll, cvtigdf, cvtigd, cvtigdl, cvtigdll - convert based-number floating-point 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 cvtigf (const char *s, char **endptr);

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

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

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

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

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

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

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

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

extern decimal_long_long_double cvtigdll (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 numeric string in based-number format to a number. Bases 2 ... 36 are supported, with digits taken from the string 0123456789abcdefghijklmnopqrstuvwxyz. Acceptable strings include character representations for Infinity and NaN. Examples of such numbers approximating the value pi (pi) are:

2@1.100_100_100_001_111_110_111@e+1
8@3.110_375_524_210_264_302_151_423_063_050_560_067_00@e+0
10@3.14159_26535_89793_23846_26433_83279_50241@e+00000_00000
+10@3.141_592_653_589_793@e+000_000
16@3.243_f6a_888_5a3_08d_313_199@e+0
36@3.53i5g@e+0

As illustrated, digits in the significand and/or exponent may be separated by a single underscore for enhanced readability, and lettercase is not significant.

The base and the exponent are always decimal values. Exponents in based numbers always represent powers of the base, whereas exponents in binary, hexadecimal, and octal floating-point numbers mean powers of two, and exponents in decimal floating-point numbers correspond to powers of ten.

Numbers may contain valid C-style numeric-precision suffixes: f or F (float), l or L (long double), ll or LL (long_long_double), df or DF (decimal_float), dd or DD (decimal_double), dl or DL (decimal_long_double), and dll or DLL (decimal_long_long_double). However, the suffix does not determine the final numerical precision: that is set by the declared precision of the conversion function.

Lettercase is not significant in Infinity and NaN representations. Acceptable strings include ones like these:

Inf
-INFINITY
+INF
-NaN(0xfeedface)
NaN(0xfacade)
-NaN
+NaN
QNAN(0x1234)
+QNAN(0xacceded)
+QNAN
QNAN
SNaN(0xbead6789)
snan(0xbeef)
-snan(0XEFFACEABLE)
SNAN(cafe_feed)
-snan
snan
SNaN
SNAN

Although all IEEE 754 floating-point designs support a sign on NaNs, the sign has no significance.

In the current implementation, a parenthesized hexadecimal tag, optionally prefixed with 0x or 0X, and possibly containing underscore digit separators, is recognized in a NaN as long as the parentheses are balanced, and low-order bits of the tag are installed in the payload bits of the significand of the NaN.

QNaN (quiet NaN) and SNaN (signaling NaN) are distinguishable on most systems, except on the widely-used Intel IA-32 architecture, the Java Virtual Machine, and possibly also the Microsoft .NET Framework Common Language Infrastructure (CLI) virtual machine.


RETURN VALUES

Return the converted number, and 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.

ERRORS

None.

SEE ALSO

cvtib(3CW), cvtid(3CW), cvtih(3CW), cvtinf(3CW), cvtio(3CW), cvtnan(3CW), cvtob(3CW), cvtod(3CW), cvtog(3CW), cvtoh(3CW), cvton(3CW), cvtoo(3CW), printf(3CW), scanf(3CW), strtod(3), strtof(3), strtold(3).