NSPR Reference: Chapter 17 Floating Point Number to String Conversion
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 17 Floating Point Number to String Conversion

NSPR provides functions that convert double-precision floating point numbers to and from their character string representations.

These conversion functions were originally written by David M. Gay of AT&T. They use IEEE double-precision (not IEEE double-extended) arithmetic.

The header file `prdtoa.h` declares these functions. The functions are:

`PR_strtod``
` `PR_dtoa``
` `PR_cnvtf```

#### PR_strtod

Converts the prefix of a decimal string to the nearest double-precision floating point number.

##### Syntax

    #include <prdtoa.h>

    PRFloat64 PR_strtod(const char *s00, char **se);

##### Parameters

The function has the following parameters:

s00 | The input string to be scanned.
`se` | A pointer that, if not `NULL`, will be assigned the address of the last character scanned in the input string.

##### Returns

The result of the conversion is a `PRFloat64` value equivalent to the input string. If the parameter `se` is not `NULL` the location it references is also set.

##### Description

`PR_strtod` converts the prefix of the input decimal string pointed to by `s00` to a nearest double-precision floating point number. Ties are broken by the IEEE round-even rule. The string is scanned up to the first unrecognized character. If the value of `se` is not `(char **) NULL`, `PR_strtod` stores a pointer to the character terminating the scan in `*se`. If the answer would overflow, a properly signed `HUGE_VAL` (infinity) is returned. If the answer would underflow, a properly signed 0 is returned. In both cases, `PR_GetError()` returns the error code `PR_RANGE_ERROR`. If no number can be formed, `se` is set to `s00`, and 0 is returned.

#### PR_dtoa

Converts a floating point number to a string.

##### Syntax

    #include <prdtoa.h>

    PRStatus PR_dtoa(
        PRFloat64 d,
        PRIntn mode,
        PRIntn ndigits,
        PRIntn *decpt,
        PRIntn *sign,
        char **rve,
        char *buf,
        PRSize bufsz);

##### Parameters

This function takes the following parameters:

`d` | The floating point number to be converted to a string.
`mode` | The type of conversion to employ.
`ndigits` | The number of digits desired in the output string.
`decpt` | A pointer to a memory location where the runtime will store the offset, relative to the beginning of the output string, of the conversion's decimal point.
`sign` | A location where the runtime can store an indication that the conversion was of a negative value.
`*rve` | If not `NULL` this location is set to the address of the end of the result.
`buf` | The address of the buffer in which to store the result.
`bufsz` | The size of the buffer provided to hold the result.

##### Results

The principle output is the null-terminated string stored in `buf`. If `rve` is not `NULL`, `*rve` is set to point to the end of the returned value.

##### Description

This function converts the specified floating point number to a string, using the method specified by `mode`. Possible modes are:

`0` | Shortest string that yields `d` when read in and rounded to nearest.
`1` | Like 0, but with Steele & White stopping rule. For example, with IEEE 754 arithmetic, mode 0 gives 1e23 whereas mode 1 gives 9.999999999999999e22.
`2` | `max(1, ndigits)` significant digits. This gives a return value similar to that of `ecvt`, except that trailing zeros are suppressed.
`3` | Through `ndigits` past the decimal point. This gives a return value similar to that from `fcvt`, except that trailing zeros are suppressed, and `ndigits` can be negative.
`4,5,8,9` | Same as modes 2 and 3, but using left to right digit generation.
`6-9` | Same as modes 2 and 3, but do not try fast floating-point estimate (if applicable).
`all others` | Treated as mode 2.

Upon return, the buffer specified by `buf` and `bufsz` contains the converted string. Trailing zeros are suppressed. Sufficient space is allocated to the return value to hold the suppressed trailing zeros.

If the input parameter `d` is +Infinity, -Infinity or NAN, `*decpt` is set to 9999.

#### PR_cnvtf

Converts a floating point number to a string.

##### Syntax

    #include <prdtoa.h>

    void PR_cnvtf (
       char *buf,
       PRIntn bufsz,
       PRIntn prcsn,
       PRFloat64 fval);

##### Parameters

This function takes the following parameters:

`buf` | The address of the buffer in which to store the result.
`bufsz` | The size of the buffer provided to hold the result.
`prcsn` | The number of digits of precision to which to generate the floating point value.
`fval` | The double-precision floating point number to be converted.

##### Description

`PR_cnvtf` is a simpler interface to convert a floating point number to a string. It conforms to the ECMA standard of Javascript (ECMAScript).

On return, the result is written to the buffer pointed to by `buf` of size `bufsz`.

## References

Gay's implementation is inspired by these two papers.

[1] William D. Clinger, "How to Read Floating Point Numbers Accurately," Proc. ACM SIGPLAN '90, pp. 92-101.

[2] Guy L. Steele, Jr. and Jon L. White, "How to Print Floating-Point Numbers Accurately," Proc. ACM SIGPLAN '90, pp. 112-126.

Previous Contents Next

Last Updated May 18, 2001