mbrtowc

Convert a multi-byte character into the equivalent wide character.

size_t mbrtowc(
   wchar_t *wchar,
   const char *mbchar,
   size_t count,
   mbstate_t mbstate
);

Parameters

• wchar
  Address of a wide character to receive the converted wide character string (type wchar_t). This value can be NULL if no return wide character is required.

• mbchar
  Address of a sequence of bytes (a multibyte character).

• count
  Number of bytes to check.

• mbstate
  Conversion state. If this value is NULL, an internal conversion state category is used.

Return Value

• 0
  If the next count or fewer bytes complete the multibyte character that represents the NULL wide character.

• > 0
  If the next count or fewer bytes complete a valid multibyte character, the value returned is the number of bytes that complete the multibyte character.

• -1
  If an encoding error occurs, in which case the next count or fewer bytes do not contribute to the complete and valid multibyte character, the errno value will be EILSEQ and the conversion state ambiguous.

• -2
  If the next count bytes contribute to an incomplete multibyte and all count bytes have been processed.

Remarks

If wcharis a NULL value, the function is equivalent to the call:

mbrtowc(NULL, NULL, 1, mbstate)

In this case, the value of the arguments wchar and count are ignored.

If wchar is not NULL, the function examines count bytes from mbcharto determine the required number of bytes needed to complete the next multibyte character. If the next character is valid, the corresponding multibyte character is stored in wchar if it is not NULL. If the character is the corresponding wide NULL character, the resulting state is the initial conversion state.

The mbrtowc function differs from mbtowc, _mbtowc_l by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs where used instead of wcstombs.

Example

Converts a multibyte character to its wide character equivalent.

// crt_mbrtowc.cpp

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

#define BUF_SIZE 100

int Sample(char* szIn, wchar_t* wcOut, int nMax)
{
    mbstate_t   state = {0}; // Initial state
    size_t      nConvResult, 
                nmbLen = 0,
                nwcLen = 0;
    wchar_t*    wcCur = wcOut;
    wchar_t*    wcEnd = wcCur + nMax;
    const char* mbCur = szIn;
    const char* mbEnd = mbCur + strlen(mbCur) + 1;
    char*       szLocal;
    
    // Sets all locale to French_Canada.1252
    szLocal = setlocale(LC_ALL, "French_Canada.1252");
    if (!szLocal)
    {
        printf("The fuction setlocale(LC_ALL, \"French_Canada.1252\") failed!\n");
        return 1;
    }

    printf("Locale set to: \"%s\"\n", szLocal);

    // Sets the code page associated current locale's code page
    // from a previous call to setlocale.
    if (_setmbcp(_MB_CP_SBCS) == -1)
    {
        printf("The fuction _setmbcp(_MB_CP_SBCS) failed!");
        return 1;
    }

    while ((mbCur < mbEnd) && (wcCur < wcEnd))
    {
        //
        nConvResult = mbrtowc(wcCur, mbCur, 1, &state);
        switch (nConvResult)
        {
            case 0:
            {  // done
                printf("Conversion succeeded!\nMultibyte String: ");
                printf(szIn);
                printf("\nWC String: ");
                wprintf(wcOut);
                printf("\n");
                mbCur = mbEnd;
                break;
            }

            case -1:
            {  // encoding error
                printf("The call to mbrtowc has detected an encoding error.\n");
                mbCur = mbEnd;
                break;
            }

            case -2:
            {  // incomplete character
                if   (!mbsinit(&state))
                {
                    printf("Currently in middle of mb conversion, state = %x\n", state);
                    // state will contain data regarding lead byte of mb character
                }

                ++nmbLen;
                ++mbCur;
                break;
            }

            default:
            {
                if   (nConvResult > 2) // The multibyte should never be larger than 2
                {
                    printf("Error: The size of the converted multibyte is %d.\n", nConvResult);
                }

                ++nmbLen;
                ++nwcLen;
                ++wcCur;
                ++mbCur;
            break;
            }
        }
    }

   return 0;
}

int main(int argc, char* argv[])
{
    char    mbBuf[BUF_SIZE] = "AaBbCc\x9A\x8B\xE0\xEF\xF0xXyYzZ";
    wchar_t wcBuf[BUF_SIZE] = {L''};

    return Sample(mbBuf, wcBuf, BUF_SIZE);
}

Sample Output

Locale set to: "French_Canada.1252"
Conversion succeeded!
Multibyte String: AaBbCcÜïα∩≡xXyYzZ
WC String: AaBbCcÜïα∩≡xXyYzZ

Requirements

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

See Also

Reference

Data Conversion

Locale

Interpretation of Multibyte-Character Sequences