| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both |
#include <stdlib.h>
size_t mbstowcs(wchar_t * __restrict__pwc, const char* __restrict__string, size_t n);Determines the length of the sequence of the multibyte characters that start in the initial shift state and that are pointed to by string. It then converts each of the multibyte characters to a wchar_t, and stores no more than n codes in the array pointed to by pwc. The conversion stops if either an invalid multibyte sequence is encountered or if n codes have been converted.
Processing continues up to and including the terminating NULL character, and characters that follow it are not processed. The terminating NULL character is converted into a code with the value 0.
The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.
If pwc is a NULL pointer, mbstowcs() will return the length required to convert the entire array regardless of the value of n, but no values are stored.
If successful, mbstowcs() returns the number of pwc array elements modified (or required if pwc is NULL) , not counting the terminating 0 code (the wchar_t 0 code). Note that, if the return value is n, the resulting wchar_t array will not be NULL-terminated.
If an invalid multibyte character is encountered, mbstowcs() returns (size_t)-1.
⁄* CELEBM07
This example uses &mbstowcs. to convert a multibyte character
string to a wide character string.
*⁄
#include <stdio.h>
#include <stdlib.h>
int main()
{
char mbsin[8] = "\x50\x0e\x42\xf1\x0f\x50\x00";
wchar_t wcsout[5];
size_t wcssize;
printf("mbsin is 0x%.2x 0x%.2x 0x%.2x 0x%.2x 0x%.2x 0x%.2x 0x%.2x\n",
mbsin[0], mbsin[1], mbsin[2],
mbsin[3], mbsin[4], mbsin[5],
mbsin[6]);
wcssize = mbstowcs(wcsout, mbsin, 5);
printf("mbstowcs(wcsout, mbsin, 5); returned %d\n", wcssize);
printf("wcsout is 0x%.4x 0x%.4x 0x%.4x 0x%.4x\n",
wcsout[0], wcsout[1],
wcsout[2], wcsout[3]);
} mbsin is 0x50 0x0e 0x42 0xf1 0x0f 0x50 0x00
mbstowcs(wcsout, mbsin, 5); returned 3
wcsout is 0x0050 0x42f1 0x0050 0x0000