GNU Info

(libc.info)System V Number Conversion

---

Prev: Parsing of Numbers Up: Arithmetic

---

Enter node , (file) or (file)node

Old-fashioned System V number-to-string functions
=================================================

   The old System V C library provided three functions to convert
numbers to strings, with unusual and hard-to-use semantics.  The GNU C
library also provides these functions and some natural extensions.

   These functions are only available in glibc and on systems descended
from AT&T Unix.  Therefore, unless these functions do precisely what you
need, it is better to use `sprintf', which is standard.

   All these functions are defined in `stdlib.h'.

 - Function: char * ecvt (double VALUE, int NDIGIT, int *DECPT, int
          *NEG)
     The function `ecvt' converts the floating-point number VALUE to a
     string with at most NDIGIT decimal digits.  The returned string
     contains no decimal point or sign. The first digit of the string
     is non-zero (unless VALUE is actually zero) and the last digit is
     rounded to nearest.  `*DECPT' is set to the index in the string of
     the first digit after the decimal point.  `*NEG' is set to a
     nonzero value if VALUE is negative, zero otherwise.

     If NDIGIT decimal digits would exceed the precision of a `double'
     it is reduced to a system-specific value.

     The returned string is statically allocated and overwritten by
     each call to `ecvt'.

     If VALUE is zero, it is implementation defined whether `*DECPT' is
     `0' or `1'.

     For example: `ecvt (12.3, 5, &d, &n)' returns `"12300"' and sets D
     to `2' and N to `0'.

 - Function: char * fcvt (double VALUE, int NDIGIT, int *DECPT, int
          *NEG)
     The function `fcvt' is like `ecvt', but NDIGIT specifies the
     number of digits after the decimal point.  If NDIGIT is less than
     zero, VALUE is rounded to the NDIGIT+1'th place to the left of the
     decimal point.  For example, if NDIGIT is `-1', VALUE will be
     rounded to the nearest 10.  If NDIGIT is negative and larger than
     the number of digits to the left of the decimal point in VALUE,
     VALUE will be rounded to one significant digit.

     If NDIGIT decimal digits would exceed the precision of a `double'
     it is reduced to a system-specific value.

     The returned string is statically allocated and overwritten by
     each call to `fcvt'.

 - Function: char * gcvt (double VALUE, int NDIGIT, char *BUF)
     `gcvt' is functionally equivalent to `sprintf(buf, "%*g", ndigit,
     value'.  It is provided only for compatibility's sake.  It returns
     BUF.

     If NDIGIT decimal digits would exceed the precision of a `double'
     it is reduced to a system-specific value.

   As extensions, the GNU C library provides versions of these three
functions that take `long double' arguments.

 - Function: char * qecvt (long double VALUE, int NDIGIT, int *DECPT,
          int *NEG)
     This function is equivalent to `ecvt' except that it takes a `long
     double' for the first parameter and that NDIGIT is restricted by
     the precision of a `long double'.

 - Function: char * qfcvt (long double VALUE, int NDIGIT, int *DECPT,
          int *NEG)
     This function is equivalent to `fcvt' except that it takes a `long
     double' for the first parameter and that NDIGIT is restricted by
     the precision of a `long double'.

 - Function: char * qgcvt (long double VALUE, int NDIGIT, char *BUF)
     This function is equivalent to `gcvt' except that it takes a `long
     double' for the first parameter and that NDIGIT is restricted by
     the precision of a `long double'.

   The `ecvt' and `fcvt' functions, and their `long double'
equivalents, all return a string located in a static buffer which is
overwritten by the next call to the function.  The GNU C library
provides another set of extended functions which write the converted
string into a user-supplied buffer.  These have the conventional `_r'
suffix.

   `gcvt_r' is not necessary, because `gcvt' already uses a
user-supplied buffer.

 - Function: char * ecvt_r (double VALUE, int NDIGIT, int *DECPT, int
          *NEG, char *BUF, size_t LEN)
     The `ecvt_r' function is the same as `ecvt', except that it places
     its result into the user-specified buffer pointed to by BUF, with
     length LEN.

     This function is a GNU extension.

 - Function: char * fcvt_r (double VALUE, int NDIGIT, int *DECPT, int
          *NEG, char *BUF, size_t LEN)
     The `fcvt_r' function is the same as `fcvt', except that it places
     its result into the user-specified buffer pointed to by BUF, with
     length LEN.

     This function is a GNU extension.

 - Function: char * qecvt_r (long double VALUE, int NDIGIT, int *DECPT,
          int *NEG, char *BUF, size_t LEN)
     The `qecvt_r' function is the same as `qecvt', except that it
     places its result into the user-specified buffer pointed to by
     BUF, with length LEN.

     This function is a GNU extension.

 - Function: char * qfcvt_r (long double VALUE, int NDIGIT, int *DECPT,
          int *NEG, char *BUF, size_t LEN)
     The `qfcvt_r' function is the same as `qfcvt', except that it
     places its result into the user-specified buffer pointed to by
     BUF, with length LEN.

     This function is a GNU extension.