atoi, atol, strtol, strtoul - Convert a character string
to the specified integer data type
#include <stdlib.h>
int atoi(
const char *nptr ); long int atol(
const char *nptr ); long int strtol(
const char *nptr,
char **endptr,
int base ); unsigned long int strtoul(
const char *nptr,
char **endptr,
int base );
Standard C Library (libc)
Points to the character string to convert. Points to a
pointer in which the function stores the position in the
string specified by the nptr parameter where a character
is found that is not a valid character for the purpose of
this conversion. Specifies the radix to use for the conversion.
The atoi(), atol(), strtol(), and strtoul() functions are
used to convert a character string pointed to by the nptr
parameter to an integer having a specified data type. The
atoi() and atol() functions convert a character string
containing decimal integer constants, but the strtol() and
strtoul() functions can convert a character string containing
a integer constant in octal, decimal, hexadecimal,
or a base specified by the base parameter.
The atoi() function converts the character string pointed
to by the nptr parameter, up to the first character inconsistent
with the format of a decimal integer, to an integer
data type. Leading white-space characters are
ignored. A call to this function is equivalent to a call
to strtol(nptr, (char**) NULL, 10). The int value of the
input string is returned.
The atol() function converts the character string pointed
to by the nptr parameter, up to the first character inconsistent
with the format of a decimal integer, to a long
integer data type. Leading white-space characters are
ignored. A call to this function is equivalent to a call
to strtol(nptr, (char**) NULL, 10). The long int value of
the input string is returned.
The strtol() function converts the initial portion of the
character string pointed to by the nptr parameter to a
long integer representation. The input character string is
first broken down into three parts: White space -- an initial
(possibly empty) sequence of spaces (as specified by
the isspace() function) Subject sequence -- a sequence of
characters that are valid in an integer constant of the
radix determined by the base parameter Unrecognized
characters -- final sequence of unrecognized character
codes, including the terminating null character
If possible, the subject is then converted to a long integer
and the result is returned.
The base parameter can take values between 0 and 36. If
the base value is 0 (zero), the subject string can be a
decimal, octal, or hexadecimal integer constant. A decimal
constant begins with a nonzero digit, and consists of a
sequence of decimal digits. An octal constant consists of
the prefix 0 (zero) optionally followed by a sequence of
digits in the range 0 through 7. A hexadecimal constant
consists of the prefix 0x or 0X followed by a sequence
consisting of decimal digits and the letters in the range
a (or A) to f (or F). If the base value is between 2 and
36, the subject string can be a sequence of digits and
letters a (or A) to z ( or Z ) that are used to represent
an integer in the specified base. Alphabetic characters
represent digits with an equivalent decimal value from 10
(for the letter A) to 35 (for the letter Z). The subject
string can only have digits with a value less than base
and alphabetic characters with equivalent values less than
base. For example, when the value of the base parameter is
20, only the following value assignments are converted:
Character 0 1 2 3 4 5 6 7 8 9 A B C D E F
G H I J
a b c d e f
g h i j
Value 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
16 17 18 19
The subject string can optionally be preceded by a + (plus
sign) or - (minus sign), but cannot include an integer
suffix (such as L). If the subject string is preceded by
a - (minus sign), the converted integer value has a negative
value. If the value of base is 16, the characters 0x
or 0X may optionally precede the sequence of letters or
digits, following the sign, if present.
The character string is parsed to skip the initial space
characters (as determined by the isspace() function). Any
nonspace character is the starting of a potential subject
string that may form an integer in the base specified by
the base parameter. The subject sequence is defined to be
the longest initial substring that is of the expected form
of long integer. Any character that does not satisfy this
expected form begins the final sequence of unrecognized
characters. The strtol() function sets the location
pointed to by the endptr parameter to point to this final
sequence of unrecognized characters except when endptr is
a null pointer.
The LC_CTYPE category of the locale controls what characters
are treated as spaces but does not effect the interpretation
of characters as part of the subject string. The
characters in the subject string are always treated as if
the locale was the C locale.
The strtoul() function is the same as the strtol() function,
except that strtoul() returns an unsigned long integer.
The atoi() function returns the converted value of an
integer if the expected form is found. If no conversion
could be performed, a value of 0 (zero) is returned. If
the converted value is outside the range of representable
values, INT_MAX or INT_MIN is returned (according to the
sign of the value).
The atol() and strtol() functions return the converted
value of long integer if the expected form is found. If
no conversion could be performed, a value of 0 (zero) is
returned. If the converted value is outside the range of
representable values, LONG_MAX or LONG_MIN is returned
(according to the sign of the value).
The strtoul() function returns the converted value of long
integer if the expected form is found. If no conversion
could be performed, a value of 0 (zero) is returned. If
the converted value is outside the range of representable
values, ULONG_MAX is returned.
In the strtol() and strtoul() functions, if the endptr
parameter is not a null pointer, the function stores a
pointer to the final sequence of unrecognized characters
in the object pointed to by endptr except when the subject
sequence is empty or invalid. In this case, the function
stores the nptr pointer in the object pointed to by the
endptr parameter.
Since these functions may return INT_MIN, INT_MAX,
LONG_MIN, LONG_MAX, and ULONG_MAX in the event of an error
and these values may also be valid returns if the function
is successful, applications should set errno to 0 (zero)
before calling these functions, and check errno after
return from the function. If errno is nonzero, an error
occurred.
Additionally, for the strtol() and strtoul() functions, if
0 (zero) is returned, applications should check if the
endptr parameter equals the nptr parameter. In this case,
there was no valid subject string.
If nptr is NULL, the functions return 0 and do not set
errno.
If any of the following conditions occurs, the atoi(),
atol(), strtol(), or strtoul() function sets errno to the
corresponding value. The base parameter has a value less
than 0 or greater than 36. The converted value is outside
the range of representable values.
The following example converts a character string to a
signed long integer.
#include <stdio.h> #include <stdlib.h> #include <locale.h>
#include <errno.h> #define LENGTH 40
main() {
char String[LENGTH], *endptr;
long int retval;
(void)setlocale(LC_ALL, );
if (fgets(String, LENGTH, stdin) != NULL) {
errno = 0;
retval = strtol ( String, &endptr, 0 );
if (retval == 0 && (errno != 0
|| String == endptr)) {
/* No conversion could be performed */
printf("No conversion performed\n");
} else if (errno !=0 && (retval == LONG_MAX
|| retval == LONG_MIN)) {
/* Error handling */
} else {
/* retval contains long integer */
printf("Integer in decimal is %d\n", retval);
}
}
}
Functions: atof(3), scanf(3), wcstol(3), wcstoul(3).
atoi(3)
[ Back ] |
