function
<cwchar>

mbrtowc

size_t mbrtowc (wchar_t* pwc, const char* pmb, size_t max, mbstate_t* ps);
Convert multibyte sequence to wide character
The multibyte character pointed by pmb is converted to a value of type wchar_t and stored at the location pointed by pwc. The function returns the length in bytes of the multibyte character.

The function uses (and updates) the shift state described by ps. If ps is a null pointer, the function uses its own internal shift state, which is altered as necessary only by calls to this function.

If pmb points to a null character, the function resets the shift state and returns zero after storing the wide null character at pwc.

A call to the function with a null pointer as pmb also resets the shift state, ignoring parameters pwc and max (no character is stored ad pwc).

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

This is the restartable version of mbtowc (<cstdlib>).

Parameters

pwc
Pointer to an object of type wchar_t.
Alternativelly, this argument can be a null pointer, in which case the function does not store the wchar_t translation, but still returns the length in bytes of the multibyte character.
pmb
Pointer to the first byte of a multibyte character.
Alternativelly, the function may be called with a null pointer, in which case the function resets the shift state (either ps or its own internal state) to the initial state and returns zero.
max
Maximum number of bytes to read from pmb.
The macro constant MB_CUR_MAX defines the maximum number of bytes that can form a multibyte character under the current locale settings.
size_t is an unsigned integral type.
ps
Pointer to a mbstate_t object that defines a conversion state.

Return Value

The number of bytes from pmb used to produce the wide character.

If this was the null wide character, or if pmb is a null pointer, the function returns zero (in the first case, the null wide character is stored at pwc).

If the max first characters of pmb form an incomplete (but potentially valid) multibyte character, the function returns (size_t)-2 (no value is stored at pwc).

Otherwise, if the characters pointed by pmb do not form a valid multibyte character (or the beginning of one), the function returns (size_t)-1 and sets errno to EILSEQ (no value is stored at pwc).

Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
/* mbrtowc example */
#include <wchar.h>

void printbuffer (const char* pt, size_t max)
{
  size_t length;
  wchar_t dest;
  mbstate_t mbs;

  mbrlen ( NULL, 0, &mbs );  /* initialize mbs */

  while (max>0) {
    length = mbrtowc(&dest,pt,max,&mbs);
    if ((length==0)||(length>max)) break;
    wprintf (L"[%lc]",dest);
    pt+=length; max-=length;
  }
}

int main()
{
  const char str [] = "mbrtowc example";

  printbuffer (str,sizeof(str));

  return 0;
}


The function printbuffer prints a multibyte string character by character.

The example uses a trivial string on the "C" locale, but locales supporting multibyte string are supported by the function.

Output:

[m][b][r][t][o][w][c][ ][e][x][a][m][p][l][e]

See also

mbrlen
Get length of multibyte character (function )
wcrtomb
Convert wide character to multibyte sequence (function )
mbsrtowcs
Convert multibyte string to wide-character string (function )
wcsrtombs
Convert wide-character string to multibyte string (function )

C++