Standards / Extensions | C or C++ | Dependencies |
---|---|---|
Language Environment |
both |
#include <stdlib.h>
unsigned long int strtoul(const char * __restrict__ string1,
char ** __restrict__ string2, int base);
Converts string1, a character string, to an unsigned long int value.
If the base is greater than zero, the subject sequence contains decimal digits and letters, possibly preceded by either a plus or a minus sign. The letters a (or A) through z (or Z) represent values from 10 through 36, but only those letters whose value is less than the value of the base are allowed. The function stops reading the string at the first character that it cannot recognize as part of a number. This character can be the first numeric character greater than or equal to the base. The strtoul() function sets string2 to point to the end of the resulting output string if a conversion is performed and provided that string2 is not a NULL pointer.
>>-+-------------+--+-----+--+----+--+--------+---------------->< '-white space-' +- + -+ +-0--+ '-digits-' '- - -' +-0x-+ '-0X-'
If base is in the range of 2-36, it becomes the base of the number. If base is 0, the prefix determines the base (8, 16, or 10): the prefix 0 means base 8; the prefix 0x or 0X means base 16; using any other digit without a prefix means decimal.
The pointer to the converted characters, even if conversion was unsuccessful, is stored in the object pointed to by string2, as long as string2 is not a NULL pointer.
If successful, strtoul() returns the converted unsigned long int value, represented in the string.
If unsuccessful, strtoul() returns 0 if no conversion could be performed. If the correct value is outside the range of representable values, strtoul() returns ULONG_MAX. If the value of base is not supported, strtoul() returns 0.
If unsuccessful strtoul() sets errno to one of the following values:
⁄* CELEBS56
This example converts the string to an unsigned long value.
It prints out the converted value and the substring that
stopped the conversion.
*⁄
#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);
}
string = 1000e13 e
strtoul = 8 (base 2)
Stopped scan at e13 e