C strtoull() Function – stdlib.h

strtoull() Function

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

The strtoull() function converts a string representing a number into an unsigned long long integer. It interprets the content of the string as an integral number in the specified base, and can also provide information on where the conversion stopped.

---

Syntax of strtoull()

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

Parameters

Parameter	Description
str	A C-string beginning with the representation of an integral number.
endptr	Pointer to a pointer that will be set to the first character after the number. Can be NULL if not used.
base	The numerical base (radix) used to interpret the string. If 0 is provided, the base is determined by the string format.

Note: If no valid conversion is performed, the function returns 0ULL. When the conversion value exceeds the range representable by an unsigned long long int, the function returns ULLONG_MAX (defined in <climits>) and sets errno to ERANGE.

---

Return Value

The function returns the converted value as an unsigned long long int. On failure, if no conversion could be performed, 0ULL is returned. If the converted value is out of range, ULLONG_MAX is returned and errno is set to ERANGE.

---

Examples for strtoull()

Example 1: Simple Decimal Conversion

This example demonstrates converting a simple decimal number represented as a string into an unsigned long long integer.

Program

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

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

    num = strtoull(str, &endptr, 10);
    printf("Converted number: %llu\n", num);
    return 0;
}

Explanation:

1. The string "123456789" is provided for conversion.
2. The strtoull() function is called with a base of 10 for decimal conversion.
3. The result is stored in num and printed.

Program Output:

Converted number: 123456789

Example 2: Conversion with Hexadecimal Input

This example shows how to convert a string representing a hexadecimal number into an unsigned long long integer.

Program

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

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

    num = strtoull(str, &endptr, 16);
    printf("Converted hexadecimal: %llu\n", num);
    return 0;
}

Explanation:

1. The string "0x1A3F" represents a hexadecimal number.
2. The strtoull() function is invoked with a base of 16.
3. The function converts the hexadecimal string into its unsigned long long integer equivalent.
4. The result is then printed.

Program Output:

Converted hexadecimal: 6719

Example 3: Using Endptr to Detect Non-Numeric Characters

This example illustrates how the endptr parameter can be used to detect where the numeric conversion stops in the string.

Program

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

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

    num = strtoull(str, &endptr, 10);
    printf("Converted number: %llu\n", num);
    printf("Remaining string: %s\n", endptr);
    return 0;
}

Explanation:

1. The string "789xyz" begins with numeric characters followed by non-numeric characters.
2. The strtoull() function converts the numeric part "789" into an unsigned long long integer.
3. The endptr parameter is set to point to the first non-numeric character ('x'), which is printed as the remaining string.

Program Output:

Converted number: 789
Remaining string: xyz

Example 4: Handling Out-of-Range Values

This example demonstrates how strtoull() handles values that exceed the representable range of an unsigned long long int.

Program

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

int main() {
    const char *str = "18446744073709551616"; // ULLONG_MAX is 18446744073709551615
    unsigned long long int num;
    char *endptr;

    errno = 0;
    num = strtoull(str, &endptr, 10);

    if (errno == ERANGE) {
        printf("Error: Number out of range.\n");
    } else {
        printf("Converted number: %llu\n", num);
    }
    return 0;
}

Explanation:

1. The string represents a number that is one greater than ULLONG_MAX.
2. The strtoull() function attempts the conversion, and since the value is out of range, it returns ULLONG_MAX and sets errno to ERANGE.
3. The program checks errno and prints an error message indicating the out-of-range condition.

Program Output:

Error: Number out of range.