This section describes functions for "reading" integer and floating-point numbers from a string. It may be more convenient in some cases to use sscanf or one of the related functions; see the section called “Formatted Input ”. But often you can make a program more robust by finding the tokens in the string by hand, then converting the numbers one by one.
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.
long int function>strtol/function> (const char *restrict string, char **restrict tailptr, int base) The strtol ("string-to-long") function converts the initial part of string to a signed integer, which is returned as a value of type long int.
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 (the section called “Classification of Characters”). These are discarded.
An optional plus or minus sign (+ or -).
A nonempty sequence of digits in the radix specified by base.
If base is zero, decimal radix is assumed unless the series of digits begins with 0 (specifying octal radix), or 0x or 0X (specifying hexadecimal radix); in other words, the same syntax used for integer constants in C.
Otherwise base must have a value between 2 and 36. If base is 16, the digits may optionally be preceded by 0x or 0X. If base has no legal value the value returned is 0l and the global variable errno is set to EINVAL.
Any remaining characters in the string. If tailptr is not a null pointer, strtol stores a pointer to this tail in *tailptr.
If the string is empty, contains only whitespace, or does not contain an initial substring that has the expected syntax for an integer in the specified base, no conversion is performed. In this case, strtol returns a value of zero and the value stored in *tailptr is the value of string.
In a locale other than the standard "C" locale, this function may recognize additional implementation-dependent syntax.
If the string has valid syntax for an integer but the value is not representable because of overflow, strtol returns either LONG_MAX or LONG_MIN (the section called “Range of an Integer Type ”), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.
You should not check for errors by examining the return value of strtol, because the string might be a valid representation of 0l, LONG_MAX, or LONG_MIN. Instead, check whether tailptr points to what you expect after the number (e.g. '\0' if the string should end after the number). You also need to clear errno before the call and check it afterward, in case there was overflow.
There is an example at the end of this section.
long int function>wcstol/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstol function is equivalent to the strtol function in nearly all aspects but handles wide character strings.
The wcstol function was introduced in Amendment 1 of ISO C90.
unsigned long int function>strtoul/function> (const char *retrict string, char **restrict tailptr, int base) The strtoul ("string-to-unsigned-long") function is like strtol except it converts to an unsigned long int value. The syntax is the same as described above for strtol. The value returned on overflow is ULONG_MAX (the section called “Range of an Integer Type ”).
If string depicts a negative number, strtoul acts the same as strtol but casts the result to an unsigned integer. That means for example that strtoul on "-1" returns ULONG_MAX and an input more negative than LONG_MIN returns (ULONG_MAX + 1) / 2.
strtoul sets errno to EINVAL if base is out of range, or ERANGE on overflow.
unsigned long int function>wcstoul/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoul function is equivalent to the strtoul function in nearly all aspects but handles wide character strings.
The wcstoul function was introduced in Amendment 1 of ISO C90.
long long int function>strtoll/function> (const char *restrict string, char **restrict tailptr, int base) The strtoll function is like strtol except that it returns a long long int value, and accepts numbers with a correspondingly larger range.
If the string has valid syntax for an integer but the value is not representable because of overflow, strtoll returns either LONG_LONG_MAX or LONG_LONG_MIN (the section called “Range of an Integer Type ”), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.
The strtoll function was introduced in ISO C99.
long long int function>wcstoll/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoll function is equivalent to the strtoll function in nearly all aspects but handles wide character strings.
The wcstoll function was introduced in Amendment 1 of ISO C90.
long long int function>strtoq/function> (const char *restrict string, char **restrict tailptr, int base) strtoq ("string-to-quad-word") is the BSD name for strtoll.
long long int function>wcstoq/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoq function is equivalent to the strtoq function in nearly all aspects but handles wide character strings.
The wcstoq function is a GNU extension.
unsigned long long int function>strtoull/function> (const char *restrict string, char **restrict tailptr, int base) The strtoull function is related to strtoll the same way strtoul is related to strtol.
The strtoull function was introduced in ISO C99.
unsigned long long int function>wcstoull/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoull function is equivalent to the strtoull function in nearly all aspects but handles wide character strings.
The wcstoull function was introduced in Amendment 1 of ISO C90.
unsigned long long int function>strtouq/function> (const char *restrict string, char **restrict tailptr, int base) strtouq is the BSD name for strtoull.
unsigned long long int function>wcstouq/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstouq function is equivalent to the strtouq function in nearly all aspects but handles wide character strings.
The wcstoq function is a GNU extension.
intmax_t function>strtoimax/function> (const char *restrict string, char **restrict tailptr, int base) The strtoimax function is like strtol except that it returns a intmax_t value, and accepts numbers of a corresponding range.
If the string has valid syntax for an integer but the value is not representable because of overflow, strtoimax returns either INTMAX_MAX or INTMAX_MIN (the section called “Integers”), as appropriate for the sign of the value. It also sets errno to ERANGE to indicate there was overflow.
See the section called “Integers” for a description of the intmax_t type. The strtoimax function was introduced in ISO C99.
intmax_t function>wcstoimax/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoimax function is equivalent to the strtoimax function in nearly all aspects but handles wide character strings.
The wcstoimax function was introduced in ISO C99.
uintmax_t function>strtoumax/function> (const char *restrict string, char **restrict tailptr, int base) The strtoumax function is related to strtoimax the same way that strtoul is related to strtol.
See the section called “Integers” for a description of the intmax_t type. The strtoumax function was introduced in ISO C99.
uintmax_t function>wcstoumax/function> (const wchar_t *restrict string, wchar_t **restrict tailptr, int base) The wcstoumax function is equivalent to the strtoumax function in nearly all aspects but handles wide character strings.
The wcstoumax function was introduced in ISO C99.
long int function>atol/function> (const char *string) This function is similar to the strtol function with a base argument of 10, except that it need not detect overflow errors. The atol function is provided mostly for compatibility with existing code; using strtol is more robust.
int function>atoi/function> (const char *string) This function is like atol, except that it returns an int. The atoi function is also considered obsolete; use strtol instead.
long long int function>atoll/function> (const char *string) This function is similar to atol, except it returns a long long int.
The atoll function was introduced in ISO C99. It too is obsolete (despite having just been added); use strtoll instead.
All the functions mentioned in this section so far do not handle alternative representations of characters as described in the locale data. Some locales specify thousands separator and the way they have to be used which can help to make large numbers more readable. To read such numbers one has to use the scanf functions with the ' flag.
Here is a function which parses a string as a sequence of integers and returns the sum of them:
int sum_ints_from_string (char *string) { int sum = 0; while (1) { char *tail; int next; /* Skip whitespace by hand, to detect the end. */ while (isspace (*string)) string++; if (*string == 0) break; /* There is more nonwhitespace, */ /* so it ought to be another number. */ errno = 0; /* Parse it. */ next = strtol (string, tail, 0); /* Add it in, if not overflow. */ if (errno) printf ("Overflow\n"); else sum += next; /* Advance past it. */ string = tail; } return sum; }
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.
double function>strtod/function> (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 (the section called “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 (the section called “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 (the section called “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 the section called “Error Reporting by Mathematical Functions”.
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.
float function>strtof/function> (const char *string, char **tailptr) long double function>strtold/function> (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.
double function>wcstod/function> (const wchar_t *restrict string, wchar_t **restrict tailptr) float function>wcstof/function> (const wchar_t *string, wchar_t **tailptr) long double function>wcstold/function> (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.
double function>atof/function> (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. the section called “Parsing of Integers”.