6.23.17 mbrtowc Function

Convert a multibyte character sequence to a wide character.

Attention: This function is implemented only by MPLAB XC32 C compilers.

Include

<wchar.h>

Prototype

size_t mbrtowc(wchar_t * restrict pwc, const char * restrict s, size_t n, mbstate_t * restrict ps);

Arguments

pwc: a pointer to the object to hold the converted wide character
s: the mulitbyte character sequence to convert
n: the maximum number of bytes to convert
ps: a pointer to a mbstate_t object that holds the current conversion state

Return Value

The function returns the first of the following that applies (given the current conversion state):

0: if the complete and valid corresponding wide character is the null wide character
a positive value: for all other complete and valid corresponding wide characters, where the returned value is the number of bytes that complete the multibyte character
(size_t)(-2): if an incomplete (but potentially valid) multibyte character has been determined after processing all n bytes

(size_t)(-1): if an encoding error occurs while processing the multibyte characters

Remarks

If s is a null pointer, the function behaves as if it had been called, mbrtowc(NULL, "", 1, ps).

For non-null values of s, the function inspects at most n bytes of s to determine the number of bytes needed to complete the next multibyte character (including any shift sequences). If this multibyte character is complete and valid, the value of the corresponding wide character is stored in the object pointed to by pwc, provided that is not a null pointer. If the corresponding wide character is the null wide character, the resulting state described is the initial conversion state.

If the processed multibyte character is complete and valid, it is stored to the object pointed to by pwc; otherwise, no value is stored.

The function uses and updates the shift state described by ps. If ps is a null pointer, the function uses its own internal object to hold the shift state.

If an encoding error occurs, the value of the macro EILSEQ is stored in errno, and the conversion state is unspecified.

An object of type mbstate_t is used to describe the current conversion state from a particular multibyte character sequence to a wide character sequence (or the reverse conversion) based on the current locale. For both conversions, the initial conversion state corresponds to the beginning of a new multibyte character in the initial shift state. A zero-valued mbstate_t always represents an 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 <wchar.h>

void printMulti(const char * pt, size_t max)
{
  size_t length;
  wchar_t ws;
  mbstate_t mbs;
  char needNL = 0;

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

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

int main(void)
{
  const char str[] = "a string";

  printMulti(str, sizeof(str));

  return 0;
}

Example Output

[a][ ][s][t][r][i][n][g]