Understanding the `wcstoll()` Function in C/C++

Table of Content#

1. Syntax of wcstoll()
2. Functionality and Return Values
3. Example Usage
4. Common Practices
5. Best Practices
6. Error Handling
7. References

1. Syntax of wcstoll()#

The syntax of the wcstoll() function in C and C++ is as follows:

#include <wchar.h>
 
long long wcstoll(const wchar_t *nptr, wchar_t **endptr, int base);

• nptr: A pointer to the wide character string that you want to convert. This string should represent a valid integer in the specified base.
• endptr: A pointer to a pointer (of type wchar_t**). If endptr is not NULL, after successful conversion, wcstoll() will set *endptr to point to the first wide character in nptr that was not part of the converted number. This can be useful for parsing strings that may have additional data after the number.
• base: The base (radix) in which the number in the string is represented. It can be an integer value between 2 and 36 (inclusive). If base is 0, the function will determine the base automatically based on the prefix of the string (e.g., 0x for hexadecimal, 0 for octal, or default to decimal if no prefix is present).

2. Functionality and Return Values#

The wcstoll() function attempts to convert the wide character string pointed to by nptr into a long long integer. It starts scanning the string from the beginning and stops when it encounters a character that is not a valid digit for the specified base.

• Return Value on Success: If the conversion is successful, it returns the converted long long value.
• Return Value on Failure: If there is an error (e.g., the string does not start with a valid number representation, or there is an overflow/underflow), it returns LLONG_MAX (for overflow) or LLONG_MIN (for underflow) if the errno is set to ERANGE. Otherwise, it returns 0 (but you should always check errno to be sure).

3. Example Usage#

Here's a simple example in C++ to demonstrate the usage of wcstoll():

#include <iostream>
#include <wchar.h>
#include <clocale>
 
int main() {
    // Set the locale based on environment variables
    std::setlocale(LC_ALL, "");
 
    const wchar_t* str = L"1234567890";
    wchar_t* end;
    long long num = wcstoll(str, &end, 10);
 
    if (*end!= L'\0') {
        std::wcout << L"String had additional characters after the number: " << end << std::endl;
    }
    std::wcout << L"Converted number: " << num << std::endl;
 
    return 0;
}

In this example:

• We first set the locale to handle wide characters properly.
• Then we define a wide character string str representing a decimal number.
• We call wcstoll() with base set to 10 (decimal). After conversion, we check if there were any remaining characters in the string (using the end pointer).
• Finally, we print the converted number.

Another example with a hexadecimal string:

#include <iostream>
#include <wchar.h>
#include <clocale>
 
int main() {
    std::setlocale(LC_ALL, "");
 
    const wchar_t* hexStr = L"0x1A";
    wchar_t* end;
    long long hexNum = wcstoll(hexStr, &end, 0); // base 0 will detect the 0x prefix and use hexadecimal
 
    std::wcout << L"Hexadecimal string: " << hexStr << L", converted to decimal: " << hexNum << std::endl;
 
    return 0;
}

4. Common Practices#

• Input Validation: Always assume that the input string may not be in the expected format. Check that the string is not NULL and that it starts with characters that are valid for the intended base.
• Using endptr: When parsing strings that may have additional data (e.g., a number followed by some text), use the endptr parameter to know where the conversion stopped. This helps in further processing of the string if needed.

5. Best Practices#

• Error Handling: Always check the errno variable after calling wcstoll() to determine if an error occurred (e.g., overflow, underflow, or invalid input). For example:

#include <iostream>
#include <wchar.h>
#include <clocale>
#include <cerrno>
 
int main() {
    std::setlocale(LC_ALL, "");
 
    const wchar_t* str = L"9223372036854775808"; // This is larger than LLONG_MAX (assuming 64-bit long long)
    wchar_t* end;
    long long num = wcstoll(str, &end, 10);
 
    if (errno == ERANGE) {
        std::wcout << L"Overflow occurred during conversion." << std::endl;
    } else if (*end!= L'\0') {
        std::wcout << L"String had additional characters after the number: " << end << std::endl;
    } else {
        std::wcout << L"Converted number: " << num << std::endl;
    }
 
    return 0;
}

• Portability: Be aware that the behavior of wcstoll() regarding locale and character encoding (since it deals with wide characters) may vary slightly between different platforms. Test your code thoroughly on the target platforms.

6. Error Handling#

As mentioned earlier, wcstoll() can set errno to ERANGE in case of overflow or underflow. Additionally, if the input string is not in a valid format (e.g., starts with non-digit characters for the given base), it may return 0 (but you need to check errno to confirm if it was a valid conversion or an error).

Here's a more comprehensive error handling example:

#include <iostream>
#include <wchar.h>
#include <clocale>
#include <cerrno>
 
int main() {
    std::setlocale(LC_ALL, "");
 
    int base = 10;
    if (base != 0 && (base < 2 || base > 36)) {
        std::wcout << L"Invalid base specified (must be 0 or 2-36)." << std::endl;
        return 1;
    }
 
    const wchar_t* invalidStr = L"abc123";
    wchar_t* end;
    long long num = wcstoll(invalidStr, &end, base);
 
    if (errno == ERANGE) {
        std::wcout << L"Overflow/Underflow occurred." << std::endl;
    } else if (*end == invalidStr) { // No characters were converted (e.g., invalid start)
        std::wcout << L"String does not start with a valid number." << std::endl;
    } else {
        std::wcout << L"Converted number: " << num << std::endl;
    }
 
    return 0;
}

7. References#

• C/C++ Standard Library Documentation - Provides detailed information about the wcstoll() function, including its behavior in different C and C++ standards.
• GCC Documentation on wcstoll() - Useful for understanding the implementation details and any platform-specific considerations when using the function with the GCC compiler.

By following the concepts and examples in this blog post, you should be able to effectively use the wcstoll() function in your C/C++ programs to handle the conversion of wide character strings to long long integers while also handling errors and edge cases appropriately.