6.19.26 mbtowc Function

Converts a multibyte character to a wide character.

Include

<stdlib.h>

Prototype

int mbtowc(wchar_t * restrict pwc, const char * restrict s, size_t n);

Arguments

pwc

a pointer to where the converted multibyte character should be stored

s

the multibyte character to convert

n

The maximum number of bytes to consider for conversion

Return Value

If s is a null pointer, the function returns a nonzero or zero value, which indicates if multibyte character encodings, respectively, do or do not have state-dependent encodings.

If s is not a null pointer, the function returns 0 if s points to the null character, returns −1 if the processed bytes do not form a valid multibyte character, or returns the number of bytes of the converted multibyte character.

The returned value will never exceed n or the value of the MB_CUR_MAX macro.

Remarks

If a valid multibyte character (including any shift sequences) can be formed from no more than the next n bytes of the sequence pointed to by s, that multibyte character is converted to a wide character that is then stored to the object pointed to by pwc, provided that pointer is not null. If the corresponding wide character is the null wide character, the function is left in the initial conversion state.

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 <stdlib.h>

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

  mbtowc(NULL, 0, 0); // reset the conversion state
  while(*mbstr) {
    len = mbtowc(&wstr, mbstr, 40);
    wprintf(L"%lc(%d)", wstr, len);
    mbstr += len;
  }
  wprintf(L"\n");
}

int main(void)
{
    setlocale(LC_CTYPE, "");
    printWide("PIC®");
}

Example Output

P(1)I(1)C(1)®(2)