wcstombs - Convert Wide-Character String to Multibyte String

Syntax

#include <stdlib.h>
size_t wcstombs(char *dest, const wchar_t *string, size_t n);

wcstombs converts the wide-character string pointed to by string into the multibyte array pointed to by dest. The conversion stops after n bytes in dest are filled or after a wide null character is encountered.

Only complete multibyte characters are stored in dest. If the lack of space in dest would cause a partial multibyte character to be stored, wcstombs stores fewer than n bytes and discards the incomplete character.

The behavior of wcstombs is affected by the LC_CTYPE category of the current locale.

If successful, wcstombs returns the number of bytes converted and stored in dest, not counting the terminating null character. The string pointed to by dest ends with a null character unless wcstombs returns the value n.

If it encounters an invalid wide character, wcstombs returns (size_t)-1.

If the area pointed to by dest is too small to contain all the wide characters represented as multibyte characters, wcstombs returns the number of bytes containing complete multibyte characters.

If dest is a null pointer, the value of len is ignored and wcstombs returns the number of elements required for the converted wide characters.

In this example, wcstombs converts a wide-character string to a multibyte character string twice. The first call converts the entire string, while the second call only converts three characters. The results are printed each time.

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

#define  SIZE          20

int main(void)
{
   char dest[SIZE];
   wchar_t *dptr = L"string";
   size_t count = SIZE;
   size_t length;

   length = wcstombs(dest, dptr, count);
   printf("%d characters were converted.\n", length);
   printf("The converted string is \"%s\"\n\n", dest);

   /* Reset the destination buffer                                            */

   memset(dest, '\0', sizeof(dest));

   /* Now convert only 3 characters                                           */

   length = wcstombs(dest, dptr, 3);
   printf("%d characters were converted.\n", length);
   printf("The converted string is \"%s\"\n", dest);
   return 0;

   /****************************************************************************
      The output should be:

      6 characters were converted.
      The converted string is "string"

      3 characters were converted.
      The converted string is "str"
   ****************************************************************************/
}

[Back]

[Next]