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
isspace
function (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
2
and36
. If base is16
, the digits may optionally be preceded by `0x' or `0X'. If base has no legal value the value returned is0l
and the global variableerrno
is set toEINVAL
.- 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 eitherLONG_MAX
orLONG_MIN
(see Range of Type), as appropriate for the sign of the value. It also setserrno
toERANGE
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 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
wcstol
function is equivalent to thestrtol
function in nearly all aspects but handles wide character strings.The
wcstol
function was introduced in Amendment 1 of ISO C90.
The
strtoul
(“string-to-unsigned-long”) function is likestrtol
except it converts to anunsigned long int
value. 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,
strtoul
acts the same as strtol but casts the result to an unsigned integer. That means for example thatstrtoul
on"-1"
returnsULONG_MAX
and an input more negative thanLONG_MIN
returns (ULONG_MAX
+ 1) / 2.
strtoul
sets errno toEINVAL
if base is out of range, orERANGE
on overflow.
The
wcstoul
function is equivalent to thestrtoul
function in nearly all aspects but handles wide character strings.The
wcstoul
function was introduced in Amendment 1 of ISO C90.
The
strtoll
function is likestrtol
except that it returns along 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 eitherLONG_LONG_MAX
orLONG_LONG_MIN
(see Range of Type), as appropriate for the sign of the value. It also setserrno
toERANGE
to indicate there was overflow.The
strtoll
function was introduced in ISO C99.
The
wcstoll
function is equivalent to thestrtoll
function in nearly all aspects but handles wide character strings.The
wcstoll
function was introduced in Amendment 1 of ISO C90.
strtoq
(“string-to-quad-word”) is the BSD name forstrtoll
.
The
wcstoq
function is equivalent to thestrtoq
function in nearly all aspects but handles wide character strings.The
wcstoq
function is a GNU extension.
The
strtoull
function is related tostrtoll
the same waystrtoul
is related tostrtol
.The
strtoull
function was introduced in ISO C99.
The
wcstoull
function is equivalent to thestrtoull
function in nearly all aspects but handles wide character strings.The
wcstoull
function was introduced in Amendment 1 of ISO C90.
strtouq
is the BSD name forstrtoull
.
The
wcstouq
function is equivalent to thestrtouq
function in nearly all aspects but handles wide character strings.The
wcstoq
function is a GNU extension.
The
strtoimax
function is likestrtol
except that it returns aintmax_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 eitherINTMAX_MAX
orINTMAX_MIN
(see Integers), as appropriate for the sign of the value. It also setserrno
toERANGE
to indicate there was overflow.See Integers for a description of the
intmax_t
type. Thestrtoimax
function was introduced in ISO C99.
The
wcstoimax
function is equivalent to thestrtoimax
function in nearly all aspects but handles wide character strings.The
wcstoimax
function was introduced in ISO C99.
The
strtoumax
function is related tostrtoimax
the same way thatstrtoul
is related tostrtol
.See Integers for a description of the
intmax_t
type. Thestrtoumax
function was introduced in ISO C99.
The
wcstoumax
function is equivalent to thestrtoumax
function in nearly all aspects but handles wide character strings.The
wcstoumax
function was introduced in ISO C99.
This function is similar to the
strtol
function with a base argument of10
, except that it need not detect overflow errors. Theatol
function is provided mostly for compatibility with existing code; usingstrtol
is more robust.
This function is like
atol
, except that it returns anint
. Theatoi
function is also considered obsolete; usestrtol
instead.
This function is similar to
atol
, except it returns along long int
.The
atoll
function was introduced in ISO C99. It too is obsolete (despite having just been added); usestrtoll
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; }