docs/nspr/reference/pr_dtoa.rst

   1 PR_dtoa
   2 =======
   3
   4 Converts a floating point number to a string.
   5
   6
   7 Syntax
   8 ------
   9
  10 .. code::
  11
  12    #include <prdtoa.h>
  13
  14    PRStatus PR_dtoa(
  15       PRFloat64 d,
  16       PRIntn mode,
  17       PRIntn ndigits,
  18       PRIntn *decpt,
  19       PRIntn *sign,
  20       char **rve,
  21       char *buf,
  22       PRSize bufsz);
  23
  24
  25 Parameters
  26 ~~~~~~~~~~
  27
  28 The function has these parameters:
  29
  30 ``d``
  31    The floating point number to be converted to a string.
  32 ``mode``
  33    The type of conversion to employ.
  34 ``ndigits``
  35    The number of digits desired in the output string.
  36 ``decpt``
  37    A pointer to a memory location where the runtime will store the
  38    offset, relative to the beginning of the output string, of the
  39    conversion's decimal point.
  40 ``sign``
  41    A location where the runtime can store an indication that the
  42    conversion was of a negative value.
  43 ``*rve``
  44    If not ``NULL`` this location is set to the address of the end of the
  45    result.
  46 ``buf``
  47    The address of the buffer in which to store the result.
  48 ``bufsz``
  49    The size of the buffer provided to hold the result.
  50
  51 Results
  52 ~~~~~~~
  53
  54 The principle output is the null-terminated string stored in ``buf``. If
  55 ``rve`` is not ``NULL``, ``*rve`` is set to point to the end of the
  56 returned value.
  57
  58
  59 Description
  60 -----------
  61
  62 This function converts the specified floating point number to a string,
  63 using the method specified by ``mode``. Possible modes are:
  64
  65 ``0``
  66    Shortest string that yields ``d`` when read in and rounded to
  67    nearest.
  68 ``1``
  69    Like 0, but with Steele & White stopping rule. For example, with IEEE
  70    754 arithmetic, mode 0 gives 1e23 whereas mode 1 gives
  71    9.999999999999999e22.
  72 ``2``
  73    ``max(1, ndigits)`` significant digits. This gives a return value
  74    similar to that of ``ecvt``, except that trailing zeros are
  75    suppressed.
  76 ``3``
  77    Through ``ndigits`` past the decimal point. This gives a return value
  78    similar to that from ``fcvt``, except that trailing zeros are
  79    suppressed, and ``ndigits`` can be negative.
  80 ``4,5,8,9``
  81    Same as modes 2 and 3, but using\ *left to right* digit generation.
  82 ``6-9``
  83    Same as modes 2 and 3, but do not try fast floating-point estimate
  84    (if applicable).
  85 ``all others``
  86    Treated as mode 2.
  87
  88 Upon return, the buffer specified by ``buf`` and ``bufsz`` contains the
  89 converted string. Trailing zeros are suppressed. Sufficient space is
  90 allocated to the return value to hold the suppressed trailing zeros.
  91
  92 If the input parameter ``d`` is\ *+Infinity*,\ *-Infinity* or\ *NAN*,
  93 ``*decpt`` is set to 9999.