C++ wcsxfrm()

The wcsxfrm() function transforms a wide string such that comparing two transformed wide string using wcscmp() function produces identical result as comparing the original wide strings using wcscoll() function in the current C locale.

For example, x and y are two wide strings. a and b are two wide strings formed by transforming x and y respectively using the wcsxfrm function.

Then,

wcscmp(a,b) = wcscoll(x,y)

It is defined in <cwchar> header file.

wcsxfrm() prototype

size_t wcsxfrm( wchar_t* dest, const wchar_t* src, size_t count );

The wcsxfrm() function converts the first count wide characters of the wide string pointed to by src to an implementation defined form and the result is stored in the memory location pointed to by dest.

The behavior of this function is undefined if:

• size of dest is less than the required size.
• dest and src overlap.

wcsxfrm() Parameters

• dest: pointer to the array where the transformed wide string is stored.
• src: pointer to the null terminated wide string to be transformed.
• count: maximum number of wide characters to convert.

wcsxfrm() Return value

The wcsxfrm() function returns the number of wide characters transformed, excluding the terminating null wide character L'\0'.

Example: How wcsxfrm() function works?

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

int main()
{
	setlocale(LC_COLLATE, "cs_CZ.UTF-8");
	
	const wchar_t* s1 = L"\u0068\u0072\u006e\u0065\u0063";
	const wchar_t* s2 = L"\u0063\u0068\u0072\u0074";
	wchar_t t1[20], t2[20];
	
	cout << "wcscoll returned " << wcscoll(s1,s2) << endl;
	cout << "Before transformation, " << "wcscmp returned " << wcscmp(s1,s2) << endl;
	
	wcsxfrm(t1,s1,10);
	wcsxfrm(t2,s2,10);
	
	cout << "After transformation, " << "wcscmp returned " << wcscmp(t1,t2) << endl;
	return 0;
}

When you run the program, the output will be:

wcscoll returned -1
Before transformation, wcscmp returned 1
After transformation, wcscmp returned -1