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.
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:
isspace
function
(see section Classification of Characters). These are discarded.
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
.
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
(see section 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.
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.
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
(see section 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.
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.
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
(see section 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.
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.
strtoq
("string-to-quad-word") is the BSD name for strtoll
.
wcstoq
function is equivalent to the strtoq
function
in nearly all aspects but handles wide character strings.
The wcstoq
function is a GNU extension.
strtoull
function is related to strtoll
the same way
strtoul
is related to strtol
.
The strtoull
function was introduced in ISO C99.
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.
strtouq
is the BSD name for strtoull
.
wcstouq
function is equivalent to the strtouq
function
in nearly all aspects but handles wide character strings.
The wcstoq
function is a GNU extension.
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
(see section Integers), as
appropriate for the sign of the value. It also sets errno
to
ERANGE
to indicate there was overflow.
See section Integers for a description of the intmax_t
type. The
strtoimax
function was introduced in ISO C99.
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.
strtoumax
function is related to strtoimax
the same way that strtoul
is related to strtol
.
See section Integers for a description of the intmax_t
type. The
strtoumax
function was introduced in ISO C99.
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.
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.
atol
, except that it returns an int
.
The atoi
function is also considered obsolete; use strtol
instead.
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; }
Go to the first, previous, next, last section, table of contents.