totn C Functions

C Language: strtoul function
(Convert String to Unsigned Long Integer)

In the C Programming Language, the strtoul function converts a string to an unsigned long integer.

The strtoul function skips all white-space characters at the beginning of the string, converts the subsequent characters as part of the number, and then stops when it encounters the first character that isn't a number.

Syntax

The syntax for the strtoul function in the C Language is:

unsigned long int strtoul(const char *nptr, char **endptr, int base);

Parameters or Arguments

nptr
A pointer to a string to convert to an unsigned long integer.
endptr
It is used by the strtoul function to indicate where the conversion stopped. The strtoul function will modify endptr (if endptr is not a null pointer) so that endptr points to the first character that was not converted.
base
The base of the number being converted. If base is between 2 and 36, it is used as the radix of the number. If base is zero, the number is assumed to be decimal unless the converted number starts with O (for Octal), Ox (for hex) or OX (for hex).

Returns

The strtoul function returns the unsigned long integer representation of a string. The strtoul function skips all white-space characters at the beginning of the string, converts the subsequent characters as part of the number, and then stops when it encounters the first character that isn't a number.

If the strtoul function converts a value that is too large or too small to convert, it will store ERANGE in errono.

Required Header

In the C Language, the required header for the strtoul function is:

#include <stdlib.h>

Applies To

In the C Language, the strtoul function can be used in the following versions:

  • ANSI/ISO 9899-1990

strtoul Example

Let's look at an example to see how you would use the strtoul function in a C program:

/* Example using strtoul by TechOnTheNet.com */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>

int main(int argc, const char * argv[])
{
    /* Define temporary variables */
    char value[10];
    char *eptr;
    unsigned long result;

    /* Copy a value into the variable */
    /* It's okay to have whitespace before the number */
    strcpy(value, " 234");

    /* Convert the provided value to a decimal unsigned long */
    result = strtoul(value, &eptr, 10);

    /* If the result is 0, test for an error */
    if (result == 0)
    {
        /* If a conversion error occurred, display a message and exit */
        if (errno == EINVAL)
        {
            printf("Conversion error occurred: %d\n", errno);
            exit(0);
        }

        /* If the value provided was out of range, display a warning message */
        if (errno == ERANGE)
            printf("The value provided was out of range\n");
    }

    /* Display the converted result */
    printf("%lu decimal\n", result);

    /* Copy a hexadecimal value into the variable */
    strcpy(value, "0x5d9");

    /* Convert the provided value to a hexadecimal unsigned long */
    result = strtoul(value, &eptr, 16);

    /* If the result is 0, test for an error */
    if (result == 0)
    {
        /* If a conversion error occurred, display a message and exit */
        if (errno == EINVAL)
        {
            printf("Conversion error occurred: %d\n", errno);
            exit(0);
        }

        /* If the value provided was out of range, display a warning message */
        if (errno == ERANGE)
            printf("The value provided was out of range\n");
    }

    /* Display the converted result */
    printf("%lx hexadecimal\n", result);

    return 0;
}

When compiled and run, this application will output:

234 decimal
5d9 hexadecimal

Similar Functions

Other C functions that are similar to the strtoul function:

See Also

Other C functions that are noteworthy when dealing with the strtoul function: