Next: Parsing of Floats, Up: Parsing of Numbers
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.
The
strtol(“string-to-long”) function converts the initial part of string to a signed integer, which is returned as a value of typelong int.This function attempts to decompose string as follows:
- A (possibly empty) sequence of whitespace characters. Which characters are whitespace is determined by the
isspacefunction (see 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
2and36. If base is16, the digits may optionally be preceded by `0x' or `0X'. If base has no legal value the value returned is0land the global variableerrnois set toEINVAL.- Any remaining characters in the string. If tailptr is not a null pointer,
strtolstores 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,
strtolreturns 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,
strtolreturns eitherLONG_MAXorLONG_MIN(see Range of Type), as appropriate for the sign of the value. It also setserrnotoERANGEto 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 of0l,LONG_MAX, orLONG_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.
The
wcstolfunction is equivalent to thestrtolfunction in nearly all aspects but handles wide character strings.The
wcstolfunction was introduced in Amendment 1 of ISO C90.
The
strtoul(“string-to-unsigned-long”) function is likestrtolexcept it converts to anunsigned long intvalue. The syntax is the same as described above forstrtol. The value returned on overflow isULONG_MAX(see Range of Type).If string depicts a negative number,
strtoulacts the same as strtol but casts the result to an unsigned integer. That means for example thatstrtoulon"-1"returnsULONG_MAXand an input more negative thanLONG_MINreturns (ULONG_MAX+ 1) / 2.
strtoulsets errno toEINVALif base is out of range, orERANGEon overflow.
The
wcstoulfunction is equivalent to thestrtoulfunction in nearly all aspects but handles wide character strings.The
wcstoulfunction was introduced in Amendment 1 of ISO C90.
The
strtollfunction is likestrtolexcept that it returns along long intvalue, 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,
strtollreturns eitherLONG_LONG_MAXorLONG_LONG_MIN(see Range of Type), as appropriate for the sign of the value. It also setserrnotoERANGEto indicate there was overflow.The
strtollfunction was introduced in ISO C99.
The
wcstollfunction is equivalent to thestrtollfunction in nearly all aspects but handles wide character strings.The
wcstollfunction was introduced in Amendment 1 of ISO C90.
strtoq(“string-to-quad-word”) is the BSD name forstrtoll.
The
wcstoqfunction is equivalent to thestrtoqfunction in nearly all aspects but handles wide character strings.The
wcstoqfunction is a GNU extension.
The
strtoullfunction is related tostrtollthe same waystrtoulis related tostrtol.The
strtoullfunction was introduced in ISO C99.
The
wcstoullfunction is equivalent to thestrtoullfunction in nearly all aspects but handles wide character strings.The
wcstoullfunction was introduced in Amendment 1 of ISO C90.
strtouqis the BSD name forstrtoull.
The
wcstouqfunction is equivalent to thestrtouqfunction in nearly all aspects but handles wide character strings.The
wcstouqfunction is a GNU extension.
The
strtoimaxfunction is likestrtolexcept that it returns aintmax_tvalue, 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,
strtoimaxreturns eitherINTMAX_MAXorINTMAX_MIN(see Integers), as appropriate for the sign of the value. It also setserrnotoERANGEto indicate there was overflow.See Integers for a description of the
intmax_ttype. Thestrtoimaxfunction was introduced in ISO C99.
The
wcstoimaxfunction is equivalent to thestrtoimaxfunction in nearly all aspects but handles wide character strings.The
wcstoimaxfunction was introduced in ISO C99.
The
strtoumaxfunction is related tostrtoimaxthe same way thatstrtoulis related tostrtol.See Integers for a description of the
intmax_ttype. Thestrtoumaxfunction was introduced in ISO C99.
The
wcstoumaxfunction is equivalent to thestrtoumaxfunction in nearly all aspects but handles wide character strings.The
wcstoumaxfunction was introduced in ISO C99.
This function is similar to the
strtolfunction with a base argument of10, except that it need not detect overflow errors. Theatolfunction is provided mostly for compatibility with existing code; usingstrtolis more robust.
This function is like
atol, except that it returns anint. Theatoifunction is also considered obsolete; usestrtolinstead.
This function is similar to
atol, except it returns along long int.The
atollfunction was introduced in ISO C99. It too is obsolete (despite having just been added); usestrtollinstead.
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;
}