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

Table of contents


NAME

cvtohf, cvtoh, cvtohl, cvtohw, cvtohq, cvtohll, cvtohdf, cvtohd, cvtohdl, cvtohdll - convert number to hexadecimal floating-point string

SYNOPSIS

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

#include <mathcw.h>
#include <cvtocw.h>

extern const char * cvtohf (float x, int min_width, int p_digits, int e_digits, int g_digits, int flags);

extern const char * cvtoh (double x, int min_width, int p_digits, int e_digits, int g_digits, int flags);

extern const char * cvtohl (long double x, int min_width, int p_digits, int e_digits, int g_digits, int flags);

extern const char * cvtohw (__float80 x, int min_width, int p_digits, int e_digits, int g_digits, int flags);

extern const char * cvtohq (__float128 x, int min_width, int p_digits, int e_digits, int g_digits, int flags);

extern const char * cvtohll (long_long_double x, int min_width, int p_digits, int e_digits, int g_digits,

int flags); extern const char * cvtohdf (decimal_float x, int min_width, int p_digits, int e_digits, int g_digits,
int flags); extern const char * cvtohd (decimal_double x, int min_width, int p_digits, int e_digits, int g_digits,
int flags); extern const char * cvtohdl (decimal_long_double x, int min_width, int p_digits, int e_digits, int g_digits,
int flags); extern const char * cvtohdll (decimal_long_long_double x, int min_width, int p_digits, int e_digits,
int g_digits, int flags);

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


DESCRIPTION

Convert a floating-point number to a string in hexadecimal floating-point format, with control over field width, justification, precision, exponent width, digit grouping, and lettercase, and return a pointer to the string. Examples of such strings for numbers approximating the value pi (pi) are:

0x1.921fb6p+1
+0x1.921fb54442d18469898cc51701b8p1
0x1.921f_b544_42d1_8469_898c_c517_01b8p+0000_0001
0X1.921F_B544_42D1_8469_898C_C517_01B8P+0000_0001

The exponent is always given as a power of two.

Infinity is output as inf or INF, and may be signed if that feature is selected by the flags argument.

NaN is output as described for cvton(3CW).

The min_width argument specifies the minimum field width. A shorter value is padded with spaces or zeros and justified, according to specification of the flags argument. A negative value for min_width is treated as a zero value.

The p_digits argument specifies the desired precision of the output number, and is the number of digits following the point. There is always one additional digit before the point. A zero value for p_digits means that there is only one significant digit in the output.

A negative value for p_digits requests automatic determination of the precision needed to represent the number exactly, if the input or output base is an nonnegative integer power of the other, or sufficiently precisely for correct round-trip conversion, according to Goldberg's formula (Comm. ACM 10(2), 105---106, February 1967).

The e_digits argument specifies the number of exponent digits required. Padding zero digits are supplied on the left, if needed. The exponent of a zero value is always reported as zero, even though in decimal floating-point arithmetic, other values are possible.

The g_digits argument specifies the number of digits in a group in the significand and exponent. Underscores separate groups, counting away from the binary point of the significand, and from the right of the exponent. A zero or negative value of g_digits suppresses digit grouping.

The flags argument contains the logical OR (or arithmetic sum, as long as there are no repetitions) of these symbolic flags defined in the header file <cvtocw.h> (some have alternate names shown in the center column):

CVTO_NONE                                  Placeholder for no flags.
CVTO_E_STYLE                               Use %e-style conversion.
CVTO_FILL_WITH_ZERO       CVTO_FLAG_ZERO   Pad with leading zeros.
CVTO_F_STYLE                               Use %f-style conversion.
CVTO_G_STYLE                               Use %g-style conversion.
CVTO_JUSTIFY_CENTER       CVTO_FLAG_EQUALS Center value in field width.
CVTO_JUSTIFY_LEFT         CVTO_FLAG_MINUS  Left-justify value in field width.
CVTO_JUSTIFY_RIGHT                         Right-justify value in field width.
CVTO_SHOW_EXACT_ZERO                       Show exact zero as 0.
CVTO_SHOW_PLUS            CVTO_FLAG_PLUS   Show plus sign.
CVTO_SHOW_PLUS_AS_SPACE   CVTO_FLAG_SPACE  Show plus sign as space.
CVTO_SHOW_POINT           CVTO_FLAG_SHARP  Show point when no fractional digits.
CVTO_SHOW_SUBNORMAL                        Show subnormals with leading zeros.
CVTO_SHOW_UPPERCASE                        Show value in uppercase.
CVTO_TRIM_TRAILING_ZEROS  CVTO_FLAG_SLASH  Trim trailing fractional zero digits.

RETURN VALUES

Return a pointer to the result string stored in an internal static buffer that is overwritten on subsequent calls to the function.

CAVEATS

Because the result is accumulated in an internal static buffer, and because its computation requires determination of the floating-point rounding mode, the function is not thread safe. Threaded applications should restrict use of this function to a single thread, or else carefully control access to it with exclusion locks, and should avoid altering the rounding mode dynamically.

All applications should take care to avoid calling this function more than once in the same expression or argument list, because the result buffer can be correct for only one of those calls, unless a copy is made immediately.


ERRORS

None.

SEE ALSO

cvtia(3CW), cvtib(3CW), cvtid(3CW), cvtig(3CW), cvtih(3CW), cvtio(3CW), cvtob(3CW), cvtod(3CW), cvtog(3CW), cvtoi(3CW), cvton(3CW), cvtoo(3CW), printf(3CW), scanf(3CW).