strtoul() — Convert string to unsigned integer
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
Language Environment®
ISO C XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 |
both |
Format
#include <stdlib.h>
unsigned long int strtoul(const char * __restrict__ string1,
char ** __restrict__ string2, int base);
General description
Converts string1, a character string, to an unsigned long int value.
- A sequence of characters, which in the current locale are defined as white space characters. This part may be empty.
- A sequence of characters interpreted as an unsigned integer in some base notation. This is the subject sequence.
- A sequence of unrecognized characters.
- 10
- Sequence starts with nonzero decimal digit.
- 8
- Sequence starts with 0, followed by a sequence of digits with values from 0 to 7.
- 16
- Sequence starts with either
0x
or0X
, followed by digits, and lettersA
throughF
ora
throughf
.
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.
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.
Returned value
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:
- Error Code
- Description
- EINVAL
- The value of base is not supported.
- ERANGE
- The conversion caused an overflow.
Example
/* 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
Related information
- stdlib.h — Standard library functions
- atof() — Convert character string to double
- atoi() — Convert character string to integer
- atol() — Convert character string to long
- fscanf(), scanf(), sscanf() — Read and format data
- strtod() — Convert character string to double
- strtol() — Convert character string to long