C strtoul() Function – stdlib.h

strtoul() Function

The strtoul() function is declared in the header file <stdlib.h>.

The strtoul() function converts a string into an unsigned long integer, interpreting the string according to the specified numerical base. It parses the string until it reaches a character that is not valid for the given base and returns the converted value.

---

Syntax of strtoul()

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

Parameters

Parameter	Description
str	C-string containing the representation of an integral number.
endptr	Pointer to a pointer to char. After conversion, this points to the first character after the numerical value. Can be NULL if not needed.
base	The numerical base (radix) to be used for conversion. If set to 0, the base is automatically detected from the string format.

Important details include: if no valid conversion is performed, strtoul() returns 0; if the converted value exceeds the range representable by an unsigned long int, the function returns ULONG_MAX and sets errno to ERANGE.

---

Return Value

The function returns the converted unsigned long integer value. If no valid conversion could be performed, it returns 0. If the value is out of range, it returns ULONG_MAX and sets errno to ERANGE.

---

Examples for strtoul()

Example 1: Basic Conversion from Decimal String

This example demonstrates converting a simple decimal string to an unsigned long integer.

Program

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

int main() {
    const char *str = "12345";
    char *endptr;
    unsigned long int num;

    num = strtoul(str, &endptr, 10);

    printf("Converted number: %lu\n", num);
    printf("Remaining string: %s\n", endptr);
    return 0;
}

Explanation:

1. The string "12345" is parsed as a base 10 number.
2. strtoul() converts the digits to an unsigned long integer.
3. The endptr points to the end of the parsed number, which is an empty string in this case.
4. The converted number is printed using printf().

Program Output:

Converted number: 12345
Remaining string: 

Example 2: Conversion with Hexadecimal String

This example shows how to convert a hexadecimal string to an unsigned long integer by specifying base 16.

Program

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

int main() {
    const char *str = "0x1A3F";
    char *endptr;
    unsigned long int num;

    num = strtoul(str, &endptr, 16);

    printf("Converted number: %lu\n", num);
    printf("Remaining string: %s\n", endptr);
    return 0;
}

Explanation:

1. The hexadecimal string "0x1A3F" is provided.
2. Using base 16, strtoul() converts the string to its unsigned long integer equivalent.
3. The endptr points to the end of the valid number part.
4. The resulting number is then printed.

Program Output:

Converted number: 6719
Remaining string: 

Example 3: Handling Invalid Conversion

This example demonstrates how strtoul() behaves when the string does not contain a valid numerical representation.

Program

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

int main() {
    const char *str = "HelloWorld";
    char *endptr;
    unsigned long int num;

    num = strtoul(str, &endptr, 10);

    printf("Converted number: %lu\n", num);
    printf("Remaining string: %s\n", endptr);
    return 0;
}

Explanation:

1. The string "HelloWorld" does not start with a valid numerical sequence.
2. strtoul() is unable to perform a conversion and returns 0.
3. The endptr points to the original string, as no conversion occurred.
4. The program prints 0 and the entire string as the remaining part.

Program Output:

Converted number: 0
Remaining string: HelloWorld

Example 4: Automatic Base Detection

This example illustrates using a base of 0 to let strtoul() automatically detect the numerical base from the string format.

Program

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

int main() {
    const char *str1 = "0755";   // Octal representation
    const char *str2 = "0xFF";    // Hexadecimal representation
    char *endptr;
    unsigned long int num1, num2;

    num1 = strtoul(str1, &endptr, 0);
    num2 = strtoul(str2, &endptr, 0);

    printf("Converted number from \"%s\": %lu\n", str1, num1);
    printf("Converted number from \"%s\": %lu\n", str2, num2);
    return 0;
}

Explanation:

1. For str1, the string "0755" is interpreted as an octal number due to the leading zero.
2. For str2, the string "0xFF" is recognized as a hexadecimal number because of the 0x prefix.
3. A base value of 0 allows strtoul() to automatically detect the correct numerical base.
4. The program prints the converted numbers accordingly.

Program Output:

Converted number from "0755": 493
Converted number from "0xFF": 255