C library - mbtowc() function

The C stdlib library mbtowc() function is used to convert a multi-byte character string pointed to by 'str' to its wide character representation. This function is same like "mbstowcs".

The converted characters are stored in the successive elements of the array pointed to by 'pwc'.

The destination array will only take a maximum of n wide characters.

Syntax

Following is the C library syntax of the mbtowc() function −

int mbtowc(whcar_t *pwc, const char *str, size_t n)

Parameters

This function accepts following parameters −

• pwc − It represents a pointer to an array of wchar_t elements, long enough to store a wide string of up to n characters.

• str − It represents a pointer to the first element of a null-terminated multi-byte string that need to be convert.

• n − It represent maximum number of wchar_t characters present in the array pointed to by 'pwc'.

Return Value

This function returns the number of converted characters, excluding the null-character. If an invalid multi-byte character is found, it returns -1.

Example 1

In this example, we create a basic c program to demonstrate the use of mbtowc() function.

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
void mbtowc_func(const char *ptr, size_t max) {
   int length;
   wchar_t dest_arr;
   
   // Reset mbtowc internal state
   mbtowc(NULL, NULL, 0); 

   while (max > 0) {
      length = mbtowc(&dest_arr, ptr, max);
      if (length < 1) {
         break;
      }
      // Print each character in square braces
      printf("[%lc]", dest_arr); 
      ptr += length;
      max -= length;
   }
}
int main() {
   const char str[] = "tutorialspoint India";
   mbtowc_func(str, sizeof(str));
   return 0;
}

Output

Following is the output −

[t][u][t][o][r][i][a][l][s][p][o][i][n][t][ ][I][n][d][i][a]

Example 2

The following c example, convert a multi-byte string to a wide-character string using mbtowc() function.

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
#include <wchar.h>
int main() {
   // Set the locale to handle multibyte characters
   setlocale(LC_ALL, "");

   const char mbString[] = "This is tutorialspoint.com"; 
   wchar_t wideChar;
   
   size_t i;

   for (i = 0; i < sizeof(mbString);) {
      int length = mbtowc(&wideChar, &mbString[i], MB_CUR_MAX);
      if (length > 0) {
	     // Print each wide character in square braces
         wprintf(L"[%lc]", wideChar); 
         i += length;
      } else {
         break;
      }
   }
   return 0;
}

Output

Following is the output −

[T][h][i][s][ ][i][s][ ][t][u][t][o][r][i][a][l][s][p][o][i][n][t][.][c][o][m]

Example 3

Let's create another example to convert a invalid multi-byte sequence to a wide-character, using mbtowc() function.

#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
#include <locale.h>

int main() {
   // Set the locale to the user's default locale
   setlocale(LC_ALL, "");

   // An invalid multibyte sequence
   const char *invalid_mb_str = "\xC3\x28";
   wchar_t ptr;
   int len;

   len = mbtowc(&ptr, invalid_mb_str, MB_CUR_MAX);

   if (len == -1) {
      printf("Invalid multibyte sequence.\n");
   } else {
      printf("Converted wide character: %lc\n", ptr);
   }
   return 0;
}

Output

Following is the output −

Invalid multibyte sequence.