function

mbsrtowcs

<cwchar>
size_t mbsrtowcs ( wchar_t * dest, const char ** src, size_t max, mbstate_t * ps );
Convert multibyte string to wide-character string
Translates up to max characters of the C multibyte string indirectly pointed by src to their wide-character equivalents and stores them in the buffer pointed by dest, stopping if a terminating null character is encountered (which is also translated and stored, but not counted in the length returned by the function).

The function uses (and updates) the shift state described by ps. If ps is a null pointer, the function uses its own internal shift state, which is altered as necessary only by calls to this function.

If the function translates an entire multibyte string (until it finds a null-character), and dest is not a null pointer, the function sets src to a null pointer value and the resulting state is guaranteed to be the initial conversion state.

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

This is the restartable version of mbstowcs (<cstdlib>).

Parameters

dest
Pointer to an array of wchar_t elements long enough to store a string of max wide characters.
If this is a null pointer, the function does not store the resulting string, but still counts how many bytes from src form a valid string (parameter max is ignored in this case).
src
Pointer to a C multibyte character string to be interpreted (an indirect pointer).
This value is modified by the function to point to past the last multibyte character converted if conversion stops prematurely, or to a null pointer if the function reached the terminating null character.
max
Maximum number of wide characters to write to dest.
size_t is an unsigned integral type.
ps
Pointer to a mbstate_t object that defines a conversion state.

Return Value

The number of wide characters written to dest (not including the eventual terminating null character).

If, during the translation, the function encountered a sequence of bytes that does not form a valid multibyte character, the function sets errno to EILSEQ and returns (size_t)-1 (src will point to the first byte that could not be translated.

Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.

See also