You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

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