6.23.19 mbsrtowcs Function

Convert a multibyte character sequence to a wide character string.

Include

<wchar.h>

Prototype

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

Arguments

dst

a pointer to the object to hold the converted wide character

src

the mulitbyte character sequence to convert

len

the maximum number of bytes to convert

ps

a pointer to a mbstate_t object that holds the current conversion state

Return Value

The function returns the number of multibyte characters successfully converted, not including the terminating null character (if any). If src is not a valid multibyte character sequence, (size_t)(-1) is returned.

Remarks

The function converts a sequence of multibyte characters indirectly pointed to by src and that begins in the conversion state described by the object pointed to by ps into a sequence of corresponding wide characters, storing the converted characters (including a terminating null character) into the array pointed to by dst, provided dst is not a null pointer, Conversion stops when a terminating null wide character is encountered, when an invalid multibyte character sequence is encountered, or when len wide characters have been stored. Each conversion takes place as if by a call to the mbrtowc() function; however, by having the argument to specify the current conversion state, this function is restartable.

An encoding error occurs if src is not a valid multibyte character sequence, and the function stores the value of the macro EILSEQ in errno and the conversion state is unspecified.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

#include <locale.h>
#include <wchar.h>
#include <string.h>

void printWide(const char* mbstr)
{
    mbstate_t state;
    size_t len;
    wchar_t wstr[40];

    memset(&state, 0, sizeof state);
    len = mbsrtowcs(&wstr[0], &mbstr, 40, &state);
    wprintf(L"Converted wide string \"%ls\" has length %u\n", wstr, len);
}

int main(void)
{
    setlocale(LC_CTYPE, "");
    printWide("It is 75°F");
}

Example Output

Converted wide string "It is 75°F" has length 10