Parsing of Floats (The GNU C Library)

#### 20.11.2 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)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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 (see 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 (see Generic Numeric Formatting Parameters).
    - 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 (see Generic Numeric Formatting Parameters).
    - 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 Error Reporting by Mathematical Functions.

  `strtod` recognizes four special input strings. The strings `"inf"` and `"infinity"` are converted to ∞, 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)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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: `_FloatN` strtofN `(const char *string, char **tailptr)` ¶
Function: `_FloatNx` strtofNx `(const char *string, char **tailptr)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  These functions are like `strtod`, except for the return type.

  They were introduced in ISO/IEC TS 18661-3 and are available on machines that support the related types; see Mathematics.

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)` ¶
Function: `_FloatN` wcstofN `(const wchar_t *string, wchar_t **tailptr)` ¶
Function: `_FloatNx` wcstofNx `(const wchar_t *string, wchar_t **tailptr)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `wcstod`, `wcstof`, `wcstol`, `wcstofN`, and `wcstofNx` functions are equivalent in nearly all aspects to the `strtod`, `strtof`, `strtold`, `strtofN`, and `strtofNx` functions, but they handle wide character strings.

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

  The `wcstofN` and `wcstofNx` functions are not in any standard, but are added to provide completeness for the non-deprecated interface of wide character string to floating-point conversion functions. They are only available on machines that support the related types; see Mathematics.

Function: `double` atof `(const char *string)` ¶

  Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

See also Parsing of Integers.