C++ wcstoull()

The wcstoull() function also sets a pointer to point to the first character after the last valid character of the wide string if there is any, otherwise the pointer is set to null.

For base 10 and the wide string L"29hi$"
Valid numeric part -> 29
First character after valid numeric part -> h

It is defined in <cwchar> header file.

wcstoull() prototype

unsigned long wcstoull( const wchar_t* str, wchar_t** str_end, int base );

The wcstoull() function takes a wide string str, a pointer to wide character str_end and an integer value - base as its parameter.

It then interprets the content of wide string as an unsigned integral number of the given base and returns a unsigned long long int value.

wcstoull() Parameters

• str: A wide string having the representation of an unsigned integral number.
• str_end: A pointer to a pointer to a wide character. The value of str_end is set by the function to the next character in str after the last valid character. This parameter can also be a null pointer, in which case it is not used.
• base: The base of the integral value. The set of valid values for base is {0, 2, 3, …, 35, 36}.

wcstoull() Return value

The wcstoull() function returns:

• a unsigned long long int value (which is converted from the string).
• 0 if no valid conversion could be performed.

Example 1: How wcstoull() function works?

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	
	wchar_t str1[] = L"101aa\u16b6";
	wchar_t str2[] = L"59";
	wchar_t *end;
	unsigned long long value;
	int base = 10;
	
	value = wcstoull(str1, &end, base);
	wcout << L"String value = " << str1 << endl;
	wcout << L"Unsigned Long Long Int value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	value = wcstoull(str2, &end, base);
	wcout << L"String value = " << str2 << endl;
	wcout << L"Unsigned Long Long Int value = " << value << endl;
	wcout << L"End String = " << end << endl;
	
	return 0;
}

When you run the program, the output will be:

String value = 101aaᚶ
Unsigned Long Long Int value = 101
End String = aaᚶ
String value = 59
Unsigned Long Long Int value = 59
End String =

A valid integer value for wcstoull() function consists of:

• An optional + or - sign.
• A prefix 0 for octal base (applies only when base = 8 or 0).
• A prefix 0x or 0X for hexadecimal base (applies only when base = 16 or 0).
• A sequence of digits and/or alphabets (if base is greater than 10).

If the argument contains a minus (-) sign at the beginning, the negative number is implicitly converted to a unsigned long long int type which is a positive number.

The valid values for parameter base is {0, 2, 3, ..., 35, 36}. A set of valid digits for base 2 is {0, 1}, for base 3 is {0, 1, 2} and so on. For bases starting from 11 to 36, valid digits include alphabets.

The set of valid digits for base 11 is {0, 1, …, 9, A, a}, for base 12 is {0, 1, …, 9, A, a, B, b} and so on.

Example 2: wcstoull() function with different bases

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t *end;
	wchar_t str[] = L"311bz\u03fe\u03ff";
	
	wcout << str << L" to Unsigned Long Long Int with base-5 = " << wcstoull(str, &end, 5) << endl;
	wcout << L"End String = " << end << endl << endl;
	wcout << str << L" to Unsigned Long Long Int with base-12 = " << wcstoull(str, &end, 12) << endl;
	wcout << L"End String = " << end << endl << endl;
	wcout << str << L" to Unsigned Long Long Int with base-36 = " << wcstoull(str, &end, 36) << endl;
	wcout << L"End String = " << end << endl << endl;
	
	return 0;
}

When you run the program, the output will be:

311bzϾϿ to Unsigned Long Long Int with base-5 = 81
End String = bzϾϿ
311bzϾϿ to Unsigned Long Long Int with base-12 = 5351
End String = zϾϿ
311bzϾϿ to Unsigned Long Long Int with base-36 = 5087231
End String = ϾϿ

The wcstoull() function ignores all the leading whitespace characters until the primary non-whitespace character is found.

In general, a valid integer argument for wcstoull() function has the following form:

[whitespace] [- | +] [0 | 0x] [alphanumeric characters]

Then, beginning from this character, it takes as many characters as possible that forms a valid integer representation and converts them to a unsigned long int value. Whatever is left of the string after the last valid character is ignored and has no effect on the result.

Example 3: wcstoull() function for leading whitespace and invalid conversion

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t *end;
	
	wcout << L" 205\u03e2x to Unsigned Long Long Int with base-5 = " << wcstoull(L" 205\u03e2x", &end, 5) << endl;
	wcout << L"End String = " << end << endl << endl;
	wcout << L"x\u019cz201 to Unsigned Long Long Int with base-12 = " << wcstoull(L"x\u019cz201", &end, 12) << endl;
	wcout << L"End String = " << end << endl << endl;
	
	return 0;
}

When you run the program, the output will be:

205Ϣx to Unsigned Long Long Int with base-5 = 10
End String = 5Ϣx
xƜz201 to Unsigned Long Long Int with base-12 = 0
End String = xƜz201

If the base is 0, the numeric base is determined automatically by looking at the format of the string. If the prefix is 0, the base is octal (8). If the prefix is 0x or 0X, the base is hexadecimal (16), otherwise the base is decimal (10).

Example 4: wcstoull() function with base 0

#include <cwchar>
#include <clocale>
#include <iostream>
using namespace std;

int main()
{
	setlocale(LC_ALL, "en_US.UTF-8");
	wchar_t *end;
	
	wcout << L"0539\u1e84 to Unsigned Long Long Int with base-0 = " << wcstoull(L"0539\u1e84", &end, 0) << endl;
	wcout << L"End String = " << end << endl << endl;
	wcout << L"0xa31\u05e2 to Unsigned Long Long Int with base-0 = " << wcstoull(L"0xa31\u05e2", &end, 0) << endl;
	wcout << L"End String = " << end << endl << endl;
	wcout << L"119x\u060f to Unsigned Long Long Int with base-0 = " << wcstoull(L"119x\u060f", &end, 0) << endl;
	wcout << L"End String = " << end << endl << endl;
	
	return 0;
}

When you run the program, the output will be:

0539Ẅ to Unsigned Long Long Int with base-0 = 43
End String = 9Ẅ
0xa31ע to Unsigned Long Long Int with base-0 = 2609
End String = ע
119x؏ to Unsigned Long Long Int with base-0 = 119
End String = x؏