std:: mbsrtowcs

Converts a null-terminated multibyte character sequence, which begins in the conversion state described by * ps , from the array whose first element is pointed to by * src to its wide character representation. If dst is not null, converted characters are stored in the successive elements of the wchar_t array pointed to by dst . No more than len wide characters are written to the destination array.

Each multibyte character is converted as if by a call to std::mbrtowc . The conversion stops if:

• The multibyte null character was converted and stored. src is set to a null pointer and *ps represents the initial shift state.
• An invalid multibyte character (according to the current C locale) was encountered. src is set to point at the beginning of the first unconverted multibyte character.
• The next wide character to be stored would exceed len . src is set to point at the beginning of the first unconverted multibyte character. This condition is not checked if dst is a null pointer.

Parameters

Return value

On success, returns the number of wide characters, excluding the terminating L ' \0 ' , written to the character array. If dst is a null pointer, returns the number of wide characters that would have been written given unlimited length.

On conversion error (if invalid multibyte character was encountered), returns static_cast < std:: size_t > ( - 1 ) , stores EILSEQ in errno , and leaves * ps in unspecified state.

Notes

This function moves the src pointer to the end of the converted multibyte string. This doesn't happen if dst is a null pointer.

Example

#include <clocale>
#include <cwchar>
#include <iostream>
#include <vector>
 
void print_as_wide(const char* mbstr)
{
    std::mbstate_t state = std::mbstate_t();
    std::size_t len = 1 + std::mbsrtowcs(nullptr, &mbstr, 0, &state);
    std::vector<wchar_t> wstr(len);
    std::mbsrtowcs(&wstr[0], &mbstr, wstr.size(), &state);
    std::wcout << "Wide string: " << &wstr[0] << '\n'
               << "The length, including '\\0': " << wstr.size() << '\n';
}
 
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = "z\u00df\u6c34\U0001f34c"; // or u8"zß水🍌"
    print_as_wide(mbstr);
}

Wide string: zß水🍌
The length, including '\0': 5

See also