String to Numeric Value Functions
Remarks
Each function in the strtod family converts a null-terminated string to a numeric value. The available functions are listed in the following table.
Function |
Description |
|---|---|
strtod |
Convert string to double-precision floating point value |
strtol |
Convert string to long integer |
strtoul |
Convert string to unsigned long integer |
_strtoi64 |
Convert string to 64-bit __int64 integer |
_strtoui64 |
Convert string to unsigned 64-bit __int64 integer |
wcstod, wcstol, wcstoul, and _wcstoi64 are wide-character versions of strtod, strtol, strtoul, and _strtoi64, respectively. The string argument to each of these wide-character functions is a wide-character string; each function behaves identically to its single-byte–character counterpart otherwise.
The strtod function takes two arguments: the first is the input string, and the second a pointer to the character which ends the conversion process. strtol, strtoul, _strtoi64 and _strtoui64 take a third argument as the number base to use in the conversion process.
The input string is a sequence of characters that can be interpreted as a numerical value of the specified type. Each function stops reading the string at the first character it cannot recognize as part of a number. This may be the terminating null character. For strtol, strtoul, _strtoi64, and _strtoui64, this terminating character can also be the first numeric character greater than or equal to the user-supplied number base.
If the user-supplied pointer to an end-of-conversion character is not set to NULL at call time, a pointer to the character that stopped the scan will be stored there instead. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of the string pointer is stored at that address.
strtod expects a string of the following form:
[whitespace] [sign] [digits] [**.**digits] [ {d | D | e | E}[sign]digits]
A whitespace may consist of space or tab characters, which are ignored; sign is either plus (+) or minus (–); and digits are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (d, D, e, or E) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan.
The strtol, strtoul, _strtoi64, and _strtoui64 functions expect a string of the following form:
[whitespace] [{+ | –}] [0 [{ x | X }]] [digits]
If the base argument is between 2 and 36, then it is used as the base of the number. If it is 0, the initial characters referenced to by the end-of-conversion pointer are used to determine the base. If the first character is 0 and the second character is not 'x' or 'X', the string is interpreted as an octal integer; otherwise, it is interpreted as a decimal number. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than base are permitted. strtoul and _strtoui64 allow a plus (+) or minus (–) sign prefix; a leading minus sign indicates that the return value is negated.
The output value is affected by the setting of the LC_NUMERIC category setting of the locale; see setlocale for more information. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead.
When the value returned by these functions would cause an overflow or underflow, or when conversion is not possible, special case values are returned as shown:
Function |
Condition |
Value returned |
|---|---|---|
strtod |
Overflow |
+/- HUGE_VAL |
strtod |
Underflow or no conversion |
0 |
strtol |
+ Overflow |
LONG_MAX |
strtol |
- Overflow |
LONG_MIN |
strtol |
Underflow or no conversion |
0 |
_strtoi64 |
+ Overflow |
_I64_MAX |
_strtoi64 |
- Overflow |
_I64_MIN |
_strtoi64 |
No conversion |
0 |
_strtoui64 |
Overflow |
_UI64_MAX |
_strtoui64 |
No conversion |
0 |
_I64_MAX, _I64_MIN, and _UI64_MAX are defined in LIMITS.H.
wcstod, wcstol, wcstoul, _wcstoi64, and _wcstoui64 are wide-character versions of strtod, strtol, strtoul, _strtoi64, and _strtoui64, respectively; the pointer to an end-of-conversion argument to each of these wide-character functions is a wide-character string. Otherwise, each of these wide-character functions behaves identically to its single-byte–character counterpart.