GNU Info

(libc.info)Parsing of Floats

---

Prev: Parsing of Integers Up: Parsing of Numbers

---

Enter node , (file) or (file)node

Parsing of Floats
-----------------

   The `str' functions are declared in `stdlib.h' and those beginning
with `wcs' are declared in `wchar.h'.  One might wonder about the use
of `restrict' in the prototypes of the functions in this section.  It
is seemingly useless but the ISO C standard uses it (for the functions
defined there) so we have to do it as well.

 - Function: double strtod (const char *restrict STRING, char
          **restrict TAILPTR)
     The `strtod' ("string-to-double") function converts the initial
     part of STRING to a floating-point number, which is returned as a
     value of type `double'.

     This function attempts to decompose STRING as follows:

        * A (possibly empty) sequence of whitespace characters.  Which
          characters are whitespace is determined by the `isspace'
          function (Note: Classification of Characters).  These are
          discarded.

        * An optional plus or minus sign (`+' or `-').

        * A floating point number in decimal or hexadecimal format.  The
          decimal format is:
             - A nonempty sequence of digits optionally containing a
               decimal-point character--normally `.', but it depends on
               the locale (Note: General Numeric).

             - An optional exponent part, consisting of a character `e'
               or `E', an optional sign, and a sequence of digits.


          The hexadecimal format is as follows:
             - A 0x or 0X followed by a nonempty sequence of
               hexadecimal digits optionally containing a decimal-point
               character--normally `.', but it depends on the locale
               (Note: General Numeric).

             - An optional binary-exponent part, consisting of a
               character `p' or `P', an optional sign, and a sequence
               of digits.


        * Any remaining characters in the string.  If TAILPTR is not a
          null pointer, a pointer to this tail of the string is stored
          in `*TAILPTR'.

     If the string is empty, contains only whitespace, or does not
     contain an initial substring that has the expected syntax for a
     floating-point number, no conversion is performed.  In this case,
     `strtod' returns a value of zero and the value returned in
     `*TAILPTR' is the value of STRING.

     In a locale other than the standard `"C"' or `"POSIX"' locales,
     this function may recognize additional locale-dependent syntax.

     If the string has valid syntax for a floating-point number but the
     value is outside the range of a `double', `strtod' will signal
     overflow or underflow as described in Note: Math Error Reporting.

     `strtod' recognizes four special input strings.  The strings
     `"inf"' and `"infinity"' are converted to oo, or to the largest
     representable value if the floating-point format doesn't support
     infinities.  You can prepend a `"+"' or `"-"' to specify the sign.
     Case is ignored when scanning these strings.

     The strings `"nan"' and `"nan(CHARS...)"' are converted to NaN.
     Again, case is ignored.  If CHARS... are provided, they are used
     in some unspecified fashion to select a particular representation
     of NaN (there can be several).

     Since zero is a valid result as well as the value returned on
     error, you should check for errors in the same way as for
     `strtol', by examining ERRNO and TAILPTR.

 - Function: float strtof (const char *STRING, char **TAILPTR)
 - Function: long double strtold (const char *STRING, char **TAILPTR)
     These functions are analogous to `strtod', but return `float' and
     `long double' values respectively.  They report errors in the same
     way as `strtod'.  `strtof' can be substantially faster than
     `strtod', but has less precision; conversely, `strtold' can be
     much slower but has more precision (on systems where `long double'
     is a separate type).

     These functions have been GNU extensions and are new to ISO C99.

 - Function: double wcstod (const wchar_t *restrict STRING, wchar_t
          **restrict TAILPTR)
 - Function: float wcstof (const wchar_t *STRING, wchar_t **TAILPTR)
 - Function: long double wcstold (const wchar_t *STRING, wchar_t
          **TAILPTR)
     The `wcstod', `wcstof', and `wcstol' functions are equivalent in
     nearly all aspect to the `strtod', `strtof', and `strtold'
     functions but it handles wide character string.

     The `wcstod' function was introduced in Amendment 1 of ISO C90.
     The `wcstof' and `wcstold' functions were introduced in ISO C99.

 - Function: double atof (const char *STRING)
     This function is similar to the `strtod' function, except that it
     need not detect overflow and underflow errors.  The `atof' function
     is provided mostly for compatibility with existing code; using
     `strtod' is more robust.

   The GNU C library also provides `_l' versions of these functions,
which take an additional argument, the locale to use in conversion.
Note: Parsing of Integers.