Converts a wide character to a multibyte character, or determines whether the multibyte encoding is stateful

#include <stdlib.h>
int wctomb ( char *s , wchar_t wc  );

The wctomb( ) function determines the multibyte representation that corresponds to the wide character wc, and stores it, including any necessary shift sequences, in the char array addressed by the pointer argument s. The size of this array is assumed to be at least MB_CUR_MAX to accommodate the multibyte character representation. If wc is a null wide character (L'\0'), wctomb( ) stores a null character, preceded by any necessary shift sequences to restore the initial shift state, in the char array addressed by s. The function returns the number of bytes in the multibyte sequence written, or -1 if the value of wc does not correspond to any valid multibyte character.

If you pass wctomb( ) a null pointer as the first argument, then the return value indicates whether the current multibyte encoding is stateful. This behavior is the same as that of mblen( ). If wctomb( ) returns 0, then the encoding is stateless. If it returns any other value, the encoding is stateful; that is, the interpretation of a given byte sequence may depend on the shift state.

Example

  char mbbuffer[MB_LEN_MAX] = { '\0' };
  wchar_t wcs[ ] =  L"Wir stehen auf den Füßen von Riesen";
  int n = 0, i = 0;

  printf( "The current locale is %s.\n", setlocale( LC_CTYPE, "" ));
  printf( "The locale's multibyte encoding is %s.\n",
          ( wctomb( NULL, L'\0' ) ? "stateful" : "stateless" ));
  do {
    n += wctomb( mbbuffer, wcs[i] );
  } while ( wcs[i++] != L'\0' );

  printf( "The wide string \"%ls\" is %u wide characters long.\n"
          "Its multibyte representation requires a buffer of %u bytes.\n",
           wcs, wcslen( wcs ), n );

This code produces output like this:

The current locale is en_US.UTF-8.
The locale's multibyte encoding is stateless.
The wide string "Wir stehen auf den Füßen von Riesen" is 35 wide characters long.
Its multibyte representation requires a buffer of 38 bytes.

See Also

wctob( ), wcrtomb( ), wcstombs( ), and wcsrtombs( ); btowc( ), mbtowc( ), mbrtowc( ), mbstowcs( ), and mbrstowcs( )