wcsrtombs

wcsrtombs

Converts a wide character string into a multibyte string and saves the parse state

#include <wchar.h>
size_t wcsrtombs ( char * restrict dest , const wchar_t ** restrict src ,
                  size_t len , mbstate_t * restrict state  );

The wcsrtombs( ) function converts one or more wide characters from the array indirectly addressed by src into a string of multibyte characters, beginning in the parse state indicated by the state argument, and stores the results in the array of char addressed by dest. (dest may also be a null pointer, in which case wcsrtombs( ) does not actually store any output characters, and does not modify the pointer in the location addressed by src. The function therefore merely returns the number of bytes that a multibyte representation of the wide character string would occupy.) The third argument, n, specifies the maximum number of characters that can be written to the output buffer. The conversion performed on each wide character is the same as that which would be performed by the wcrtomb( ) function, updating the mbstate_t object addressed by state. Conversion ends on the first of three possible events:

When a terminating null character has been written to the output buffer.: In this case, wcsrtombs( ) stores a null pointer in the location addressed by src, and returns the number of bytes in the multibyte sequence resulting from the conversion. The object addressed by state represents the initial parse state, and the terminating null character stored in the output buffer is preceeded by any shift sequence required to reach the initial parse state.
When writing another multibyte character would exceed the maximum length of n bytes.: In the location addressed by src, wcsrtombs( ) stores a pointer to the location that follows the last wide character read, and the object addressed by state represents the current parse state of the incomplete output string. The function returns the number of bytes in the multibyte sequence resulting from the conversion.
When a wide character read cannot be converted into a valid multibyte character.: In this case, wcsrtombs( ) sets the errno variable to the value of EILSEQ ("illegal sequence") and returns -1. The state of the object addressed by state is unspecified.

Example

int i = 0, n = 0;
size_t result;
wchar_t wc;
char mbstring[256] = { '\0' };
wchar_t widestring[ ] = L"This is originally a string of wide characters.\n";
const wchar_t *wcsptr = widestring;
mbstate_t state;

printf( "The current locale is %s.\n", setlocale(LC_CTYPE, "") );

memset( &state, '\0', sizeof state );

result = wcsrtombs( mbstring, &wcsptr, 256, &state );

while ( ( n = mbtowc( &wc, &mbstring[i], MB_CUR_MAX )) != 0 )
{
  if ( n == -1 )
  {  /* Encoding error */
    fputs( "Encoding error in multibyte string", stderr );
    break;
  }
  printf( "%lc", (wint_t)wc );
  i += n;
};

Example

See Also