The mbsrtowcs() function is defined in <cwchar> header file.
size_t mbsrtowcs( wchar_t* dest, const char** src, size_t len, mbstate_t* ps );
The mbsrtowcs() function converts the multibyte character string whose first byte is represented by *src to corresponding wide character representation and is stored in the wide character array pointed to by dest. A maximum of len wide characters are written to dest.
The conversion process is similar to calling mbrtowc() repeatedly. The conversion stops if:
- A multibyte null character was converted and stored. In this case, src is set to null and ps represents initial shift state.
- An invalid multibyte character was encountered. In this case, src is set to point the beginning of the first unconverted multibyte character.
- len wide character has been stored in dest. In this case, src is set to point the beginning of the first unconverted multibyte character.
- dest: Pointer to the array where the converted wide character is stored.
- src: Pointer to pointer to the first multibyte character to convert.
- len: Maximum number wide character to store.
- ps: Pointer to the conversion state used when interpreting the multibyte string
mbsrtowcs() Return value
- On success, the mbsrtowcs() function returns the number of wide characters written to dest excluding the terminating wide null character. If dest is a null pointer, it returns the number of wide characters that would have been written considering unlimited length.
- On conversion error, -1 is returned and errno is set to EILSEQ.
Example: How mbsrtowcs() function works?
using namespace std;
const char* str = "\u0763\u0757\u077f\u075f";
mbstate_t ps = mbstate_t();
int len = 10;
retVal = mbsrtowcs(wstr, &str, len, &ps);
wcout << L"Number of wide characters written (excluding L\"\\0\") = " << retVal << endl;
wcout << L"Wide character = " << wstr << endl;
When you run the program, the output will be:
Number of wide characters written (excluding L"\0") = 4
Wide character = ݣݗݿݟ