C++ In a Nutshell

Name

mbsrtowcs function — Converts a multibyte string to a wide string

Synopsis

size_t mbsrtowcs(wchar_t* dst, const char** src, size_t len, mbstate_t* ps)

The mbsrtowcs converts a multibyte string to a wide character string. The src parameter indirectly points to the null-terminated multibyte string, that is, *src points to the start of the multibyte string.

If dst is not null, up to len wide characters are stored in dst. If fewer than len characters are stored, a trailing null character is appended to the wide character array. If conversion stops upon reaching a null character in the src string, a null pointer is assigned to *src; otherwise, *src is assigned a pointer to the byte immediately past the end of the last multibyte character converted.

The dst parameter can be a null pointer, in which case no wide characters are stored and *src is not altered, but ps is updated and the return value is the same as it would be if dst were large enough to hold the entire converted string.

The ps parameter points to the shift state, which keeps track of the conversion state between calls to mbsrtowcs. If ps is a null pointer, an internal shift state is used (which is similar to calling mbstowcs in <cstdlib>). If the conversion ends without a terminating null character in *src, the shift state is reset to an mbstate_t initial state.

The return value is the number of wide characters successfully converted. If any multibyte character is not valid, the return value is static_cast<size_t>(-1).

See Also ...