Legacy Document

num2dec

You can use the num2dec function to convert a binary floating-point number to a decimal number.

void num2dec (const decform *f, double_t x, decimal *d);
void num2decl (const decform *f, long double x, decimal *d);

f

A decform structure that describes how the number should look in decimal. See page 9-14 for a description of the decform structure.

x

The floating-point number to be converted.

d

Upon return, a pointer to the decimal structure containing the number. See page 9-13 for a description of the decimal structure.

DESCRIPTION

The num2dec function converts a floating-point number to a decimal number. The decimal number is contained in a decimal structure. Each conversion to a decimal structure d is controlled by a decform structure f. All implementations allow 36 digits to be returned in the sig field of the decimal structure. The implied decimal point is at the right end of sig, with exp set accordingly.

After using the num2dec function, you can use the dec2str function to convert the decimal structure to a character string.

IMPORTANT

Use the same decimal format structure settings for dec2str as you used for num2dec; otherwise, the results are unspecified.

EXCEPTIONS

When the number of digits specified in a decform structure exceeds an implementation maximum (which is 36), the result is undefined.

A number might be too large to represent in a chosen fixed style. For instance, if the implementation's maximum length for sig is 36, then $1035$ (which requires 33 digits to the left of the point in fixed-style representations) is too large for a fixed-style representation specifying more than two digits to the right of the point. If a number is too large for a chosen fixed style, then (depending on the numeric implementation) one of two results is returned: an implementation might return the most significant digits of the number in sig and set exp so that the decimal structure contains a valid floating-style approximation of the number; alternatively, an implementation might simply set sig to the string "?". Note that in any implementation, the following test determines whether a nonzero finite number is too large for the chosen fixed style.

   decimal d;
   decform f;
   int too_big; /* Boolean */

   too_big = (-d.exp != f.digits) || (d.sig.text[0] == "?");

For fixed-point formatting, PowerPC Numerics treats a negative value for digits as a specification for rounding to the left of the decimal point; for example, digits = -2 means to round to hundreds. For floating-point formatting, a negative value for digits gives unspecified results.

SPECIAL CASES

• For zeros, the character "0" is placed in sig.text[0].
• For NaNs, The character "N" is placed in sig.text[0]. The character "N" might be followed by a hexadecimal representation of the input significand. The third and fourth hexadecimal digits following the "N" give the NaN code. For example, "N4021000000000000" has NaN code 0x21.
• For Infinities, the character "I" is placed in sig.text[0].

In all three of these cases, exp is undefined.

EXAMPLES

decimal d;
decform f;
double_t fp_num = 1.000007;

f.style = FLOATDECIMAL;    /* floating-point format */
f.digits = 7;              /* seven significant digits */
num2dec(&f, fp_num, &d);   /* d now contains 1.000007 expressed
                              in decimal structure */