function
<cstdlib>

mbtowc

int mbtowc (wchar_t* pwc, const char* pmb, size_t max);
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.

mbtowc has its own internal shift state, which is altered as necessary only by calls to this function. A call to the function with a null pointer as pmb resets the state (and returns whether multibyte characters are state-dependent).

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

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, this argument can be a null pointer, in which case the function resets its internal shift state to the initial value and returns whether multibyte characters have a state-dependent encoding.
max
Maximum number of bytes of pmb to consider for the multibyte character.
No more than MB_CUR_MAX characters are examined in any case.
size_t is an unsigned integral type.

Return Value

If the argument passed as pmb is not a null pointer, the size in bytes of the multibyte character pointed by pmb is returned when it forms a valid multibyte character and is not the terminating null character. If it is the terminating null character, the function returns zero, and in the case they do not form a valid multibyte character, -1 is returned.

If the argument passed as pmb is a null pointer, the function returns a nonzero value if multibyte character encodings are state-dependent, and zero otherwise.

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
 
/* mbtowc example */
#include <stdio.h>      /* printf */
#include <stdlib.h>     /* mbtowc, wchar_t(C) */

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

  mbtowc (NULL, NULL, 0);  /* reset mbtowc */

  while (max>0) {
    length = mbtowc(&dest,pt,max);
    if (length<1) break;
    printf ("[%lc]",dest);
    pt+=length; max-=length;
  }
}

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

  printbuffer (str,sizeof(str));

  return 0;
}


printbuffer prints a multibyte string character by character.

The example uses a trivial string using the "C" locale, but locales that interpret multibyte strings are supported by the function.

Output:

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

Data races

The function accesses the array pointed by pmb, and modifies the object pointed by pwc (if not null).
The function also accesses and modifies an internal state object, which may cause data races on concurrent calls to this function (see mbrtowc for an alternative that may use an external state object).
Concurrently changing locale settings may also introduce data races.

Exceptions (C++)

No-throw guarantee: this function throws no exceptions.

If pwc is neither a null pointer nor points to a valid object, or if pmb is neither a null pointer nor a pointer to an array long enough (as described above), it causes undefined behavior.

See also

mblen
Get length of multibyte character (function )
wctomb
Convert wide character to multibyte sequence (function )
mbstowcs
Convert multibyte string to wide-character string (function )
wcstombs
Convert wide-character string to multibyte string (function )

C++