strtol() – strtoll() — Convert Character String to Long and Long Long Integer
Format (strtol()
)
#include <stdlib.h>
long int strtol(const char *nptr, char **endptr, int base);
Format (strtoll()
)
#include <stdlib.h>
long long int strtoll(char *string, char **endptr, int base);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of these functions might be affected by the LC_CTYPE category of the current locale. For more information, see Understanding CCSIDs and Locales.
Description
The strtol()
function
converts a character string to a long integer value. The parameter nptr points
to a sequence of characters that can be interpreted as a numeric value
of type long int.
The strtoll()
function converts a character
string to a long long integer value. The parameter nptr points
to a sequence of characters that can be interpreted as a numeric value
of type long long int.
When you use these functions, the nptr parameter should point to a string with the following form:
If the base parameter is a value between 2 and
36, the subject sequence's expected form is a sequence of letters
and digits representing an integer whose radix is specified by the base parameter.
This sequence is optionally preceded by a positive (+) or negative
(-) sign. Letters from a to z inclusive (either upper or lower case)
are ascribed the values 10 to 35; only letters whose ascribed values
are less than that of the base parameter are permitted. If the base
parameter has a value of 16, the characters 0x
or 0X
optionally
precede the sequence of letters and digits, following the positive
(+) or negative (-) sign, if present.
If the value of the base parameter is 0, the string determines
the base. After an optional leading sign a leading 0 indicates octal
conversion, a leading 0x
or 0X
indicates
hexadecimal conversion, and all other leading characters result in
decimal conversion.
These functions scan the string up to the first character
that is inconsistent with the base parameter. This character
may be the null character ('\0')
at the end of the
string. Leading white-space characters are ignored, and an optional
sign may precede the digits.
If the value of the endptr parameter is not null a pointer, a pointer to the character that ended the scan is stored in the value pointed to by endptr. If a value cannot be formed, the value pointed to by endptr is set to the nptr parameter
Return Value
If base has an invalid value
(less than 0, 1, or greater than 36), errno
is set
to EINVAL and 0 is returned. The value pointed to by the endptr parameter
is set to the value of the nptr parameter.
If the value is outside the range of representable values, errno
is
set to ERANGE. If the value is positive, the strtol()
function
will return LONG_MAX, and the strtoll()
function
will return LONGLONG_MAX. If the value is negative, the strtol()
function
will return LONG_MIN, and the strtoll()
function
will return LONGLONG_MIN.
If no characters are converted, the strtoll()
and strtol()
functions
will set errno to EINVAL and 0 is returned. For both functions, the
value pointed to by endptr is set to the value of the nptr parameter.
Upon successful completion, both functions return the converted value.
Example
#include <stdlib.h>
#include <stdio.h>
int main(void)
{
char *string, *stopstring;
long l;
int bs;
string = "10110134932";
printf("string = %s\n", string);
for (bs = 2; bs <= 8; bs *= 2)
{
l = strtol(string, &stopstring, bs);
printf(" strtol = %ld (base %d)\n", l, bs);
printf(" Stopped scan at %s\n\n", stopstring);
}
}
/***************** Output should be similar to: *****************
string = 10110134932
strtol = 45 (base 2)
Stopped scan at 34932
strtol = 4423 (base 4)
Stopped scan at 4932
Related Information
- atof() — Convert Character String to Float
- atoi() — Convert Character String to Integer
- atol() – atoll() — Convert Character String to Long or Long Long Integer
- strtod() - strtof() - strtold() — Convert Character String to Double, Float, and Long Double
- strtod32() - strtod64() - strtod128() — Convert Character String to Decimal Floating-Point
- strtoul() – strtoull() — Convert Character String to Unsigned Long and Unsigned Long Long Integer
- wcstol() – wcstoll() — Convert Wide Character String to Long and Long Long Integer
- <stdlib.h>