 |
Index for
Section 3 |
|
 |
Alphabetical
listing for A |
|
 |
Bottom of
page |
|
atoi(3)
NAME
atoi, atol, strtol, strtoul - Convert a character string to the specified
integer data type
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
PARAMETERS
nptr
Points to the character string to convert.
endptr
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.
base
Specifies the radix to use for the conversion.
DESCRIPTION
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.
RETURN VALUES
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.
ERRORS
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.
[EINVAL]
The base parameter has a value less than 0 or greater than 36.
[ERANGE]
The converted value is outside the range of representable values.
EXAMPLES
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);
}
}
}
SEE ALSO
Functions: atof(3), scanf(3), wcstol(3), wcstoul(3).
|
Index for
Section 3 |
|
|
Alphabetical
listing for A |
|
 |
Top of
page |
|