C library - wcstombs() function

The C stdlib library wcstombs() function is used to convert a wide-character string (pwcs) to its multi-byte string (str).

This function is commonly useful in programs that handle multiple character encodings, especially when dealing with internationalization and localization.

Syntax

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

size_t wcstombs(char *str, const wchar_t *pwcs, size_t n)

Parameters

This function accepts following parameters −

• str − It represent a pointer to the destination array where the resulting multi-byte string will be stored.

• pwcs − It represents a wide character string to be converted.

• n − It represent maximum number byte to be written to 'str'.

Return Value

This function returns the number of bytes (not characters) converted and written to str, excluding the ending null character. If an invalid multi-byte character is encountered, a -1 value is returned.

Example 1

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

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

int main() {
   setlocale(LC_ALL, "");
   
   // Wide-character string
   const wchar_t pwcs[] = L"Hello tutorialspoint";
   
   // Buffer to hold the multibyte string
   char mbstr[256];
   
   // Convert wide-character string to multibyte string
   size_t len = wcstombs(mbstr, pwcs, sizeof(mbstr));
   
   if (len == (size_t)-1) {
      printf("Conversion failed.\n");
   } else {
      printf("Converted multibyte string: %s\n", mbstr);
   }
   return 0;
}

Output

Following is the output −

Converted multibyte string: Hello tutorialspoint

Example 2

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

#include <stdio.h>
#include <stdlib.h>
int main () {
   size_t ret_val;
   char *mbstr = (char *)malloc(50);
   wchar_t *pwcs = L"https://www.tutorialspoint.com";

   // converting wide-character string to multi-byte
   ret_val = wcstombs(mbstr, pwcs, 50);
   
   printf("Characters converted = %lu\n", ret_val);
   printf("Multibyte character = %s\n\n", mbstr);
   
   return(0);
}

Output

Following is the output −

Characters converted = 30
Multibyte character = https://www.tutorialspoint.com

Example 3

Let's create another example, we convert a wide-character string containing different special characters to a multi-byte string using wcstombs() 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, "");

   // Wide-character string with special characters and emojis
   const wchar_t pwcs[] = L"Welcome tutorialspoint @#-";

   char mbstr[256];

   // Convert wide-character string to multibyte string
   size_t ret = wcstombs(mbstr, pwcs, sizeof(mbstr));
   
   // If conversion failed
   if (ret == (size_t)-1) {
      printf("Conversion failed.\n");
   } else {        
      // Conversion succeeded
      printf("Converted multibyte string: %s\n", mbstr);
      printf("Number of bytes written (excluding null terminator): %zu\n", ret);
   }
   return 0;
}

Output

Following is the output −

Converted multibyte string: Welcome tutorialspoint @#-
Number of bytes written (excluding null terminator): 26