strtoul() – strtoull() — Convert Character String to Unsigned Long and Unsigned Long Long Integer
Format (strtoul()
)
#include <stdlib.h>
unsigned long int strtoul(const char *nptr, char **endptr, int base);
Format (strtoull()
)
#include <stdlib.h>
unsigned long long int strtoull(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 strtoul()
function
converts a character string to an unsigned long integer value. The
parameter nptr points to a sequence of characters that can
be interpreted as a numeric value of type unsigned long int.
The strtoull()
function converts a character
string to an unsigned long long integer value. The parameter nptr points
to a sequence of characters that can be interpreted as a numeric value
of type unsigned 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. The strtoul()
function will return
ULONG_MAX and the strtoull()
function will return
ULONGLONG_MAX.
If no characters are converted, the strtoull()
function
will set errno
to EINVAL and 0 is returned. The strtoul()
function
will return 0 but will not set errno
to EINVAL. In
both cases 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 <stdio.h>
#include <stdlib.h>
#define BASE 2
int main(void)
{
char *string, *stopstring;
unsigned long ul;
string = "1000e13 e";
printf("string = %s\n", string);
ul = strtoul(string, &stopstring, BASE);
printf(" strtoul = %ld (base %d)\n", ul, BASE);
printf(" Stopped scan at %s\n\n", stopstring);
}
/***************** Output should be similar to: *****************
string = 1000e13 e
strtoul = 8 (base 2)
Stopped scan at e13 e
*/
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
- strtol() – strtoll() — Convert Character String to Long and Long Long Integer
- wcstoul() – wcstoull() — Convert Wide Character String to Unsigned Long and Unsigned Long Long Integer
- <stdlib.h>