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 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 (see 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 Math Error Reporting.

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.