Legacy Document

dec2str

You can use the dec2str function to convert a number in a decimal structure to a decimal string.

void dec2str (const decform *f, const decimal *d, char *s);

f

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

d

The decimal structure to be converted. See page 9-13 for the definition of the decimal structure.

s

On return, a string representing the number in decimal.

DESCRIPTION

The dec2str function is the PowerPC Numerics formatter. It takes a number from a decimal structure and converts it to a string. You can use the num2dec function to convert a binary floating-point number to a decimal structure appropriate for input to the dec2str function.

IMPORTANT

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

The numeric formatter is controlled by a decform structure f. With floating style, numbers formatted using the same value for f.digits have aligning decimal points and e's. To ensure that numbers have the same width also, pad the exponent-digits field with spaces to a width of 4. For example, if f.digits = 12, then pad 12 + 8 - length(s) spaces on the right of the result string s. The value 8 accounts for the sign, point, letter e, exponent sign, and four exponent digits. Note that this scheme gives the correct field width for NaNs and Infinities too.

With fixed style, numbers formatted using the same value for f.digits have aligning decimal points if enough leading spaces are added to the result string s to attain a fixed width, which must be no narrower than the widest s.

IMPORTANT

When you create a decimal structure, you must set sig.length to the size of the string you place in sig.text. You cannot leave the length field undefined.

EXCEPTIONS

The formatter is always exact and signals no exceptions.

SPECIAL CASES

For fixed-point formatting, dec2str 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, values for digits less than 1 are treated as 1.

NaNs are formatted as NAN; Infinities are formatted as INF. A leading sign or space is included according to the style convention.

The formatter never returns fewer significant digits than are contained in sig. However, if the decform structure calls for more significant digits than are contained in sig, then the formatter pads with zeros as needed.

If more than 80 characters are required to honor digits, then the formatter returns the string "?".

EXAMPLES

Suppose you have an accounting program that computes exact values using binary numbers of pennies and prints outputs in dollars and cents. If you simply divide
the number of pennies by 100 to get dollars, you incur errors because hundredths are not exact in binary. One way to print out exact values in dollars and cents is to convert the number of pennies to a decimal structure, perform the division by adjusting the exponent, and print the result, as shown in Listing 9-1.

Listing 9-1 Accounting program

#include <fp.h>

   decform     df;
   double      pennies;    /* This is the input value */
   decimal     dpennies;   /* decimal value for pennies */
   char *      dollars;    /* string to print as $$$. */

{
   df.style = FIXEDDECIMAL;
   df.digits = 0;    /* start with 0 digits after decimal point */

   num2dec(&df, pennies, &dpennies);         /* decimal pennies */
   dpennies.exp = dpennies.exp - 2;          /* divide by 100 */

   df.digits = 2;       /* request 2 digits after decimal point */
   dec2str(&df, &dpennies, dollars);
   /* dollar string to print */
}