6.19.25 mbstowcs Function

Converts a multibyte character sequence to a wide string.

Include

<stdlib.h>

Prototype

size_t mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);

Arguments

pwcs

a pointer to the array to hold the converted multibyte sequence

s

the multibyte character sequence to convert

n

the maximum number of wide characters to store

Return Value

The function returns the number of wide characters, not including the terminating null character (if any), stored to pwcs. If s cannot be converted, (size_t)(-1) is returned.

Remarks

The function converts a sequence of multibyte characters in the array s and that begins in the initial shift state into a sequence of corresponding wide characters, storing no more than n converted wide characters (including a terminating null wide character) into the array pointed to by pwcs. Conversion stops when a terminating null character is encountered, when an invalid multibyte character sequence is encountered, or when n wide characters have been stored. Each conversion takes place as if by a call to the mbtowc() function, except that the conversion state of the mbtowc() function is not affected.

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 <stdlib.h>
#include <wchar.h>

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

    len = mbstowcs(wstr, mbstr, 40);
    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