C library - mbstowcs() function



The C stdlib library mbstowcs() function is used to convert a multi-byte character string pointed to by 'str' to the array pointed to by pwcs.

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

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

Syntax

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

size_t mbstowcs(schar_t *pwcs, const char *str, size_t n)

Parameters

This function accepts following parameters −

  • pwcs − 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 'pwcs'.

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 mbstowcs() function.

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

int main() {
   // UTF-8 encoded multibyte string
   const char *mbstr = "zß?\xF0\x9F\x8D\x8C";
   
   // Set locale for UTF-8
   setlocale(LC_ALL, "en_US.utf8");
   
   // Wide character array
   wchar_t wcs[5];

   size_t len = mbstowcs(wcs, mbstr, 5);
   if (len != (size_t)-1) {
      wprintf(L"Wide string: %ls\n", wcs);
   } else {
      perror("Conversion error");
   }
   
   return 0;
}

Output

Following is the output −

Conversion error: Invalid or incomplete multibyte or wide character

Example 2

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

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

int main() {
   // Multibyte string
   const char *mbstr = "Hello, world!"; 
   
   // Set locale for UTF-8
   setlocale(LC_ALL, "en_US.utf8"); 
   
   // Wide character array (adjust size as needed)
   wchar_t wcs[20];
   
   size_t len = mbstowcs(wcs, mbstr, sizeof(wcs) / sizeof(wcs[0]));
   if (len != (size_t)-1) {
      wprintf(L"Wide string: %ls\n", wcs);
   } else {
      perror("Conversion error");
   }
   return 0;
}

Output

Following is the output −

Wide string: Hello, world!

Example 3

Let's create another c program to convert a multi-byte string to a wide-character string, display the wide character.

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

int main() {
   // Multibyte string
   const char *mbstr = "Hello World \n This is tutorialspoint"; 
   
   // Set locale for UTF-8
   setlocale(LC_ALL, "en_US.utf8"); 
   
   // Wide character array (adjust size as needed)
   wchar_t wcs[25];
   
   size_t len = mbstowcs(wcs, mbstr, sizeof(wcs) / sizeof(wcs[0]));
   if (len != (size_t)-1) {
      wprintf(L"Wide string: %ls\n", wcs);
   } else {
      perror("Conversion error");
   }
   return 0;
}

Output

Following is the output −

Wide string: Hello World
This is tut
Advertisements