wcsrtombs

size_t wcsrtombs (char* dest, const wchar_t** src, size_t max, mbstate_t* ps);

Convert wide-character string to multibyte string

Translates up to max characters of the C wide string indirectly pointed by src to their multibyte sequence equivalents and stores them in the buffer pointed by dest, stopping if a terminating null wide character is encountered (which is also translated and stored, but not counted in the length returned by the function).

The function uses (and updates) the shift state described by ps. If ps is a null pointer, the function uses its own internal shift state, which is altered as necessary only by calls to this function.

If the function translates an entire C wide string (until it finds a null wide character), and dest is not a null pointer, the function sets src to a null pointer value and the resulting state is guaranteed to be the initial conversion state.

The behavior of this function depends on the LC_CTYPE category of the selected C locale.

This is the restartable version of wcstombs (<cstdlib>).

Parameters

dest: Pointer to an array of char elements long enough to store a C string of max bytes.
If this is a null pointer, the function does not store the resulting sequence, but still counts how many bytes are needed to store the translation of src (parameter max is ignored in this case).
src: Pointer to a C wide string to be translated (an indirect pointer).
This value is modified by the function to point to past the last wide character converted if conversion stops prematurely, or to a null pointer if the function reached the terminating null character.
max: Maximum number of bytes characters to write to dest.
size_t is an unsigned integral type.
ps: Pointer to a mbstate_t object that defines a conversion state.

Return Value

The number of bytes written to dest (not including the eventual terminating null character).

If, during the translation, the function encountered a wide character that has no valid multibyte sequence equivalent, the function sets errno to EILSEQ and returns (size_t)-1 (src will point to the first character that could not be translated.

Notice that size_t is an unsigned integral type, and thus none of the values possibly returned is less than zero.

Example

/* wcsrtombs example */
#include <stdio.h>
#include <wchar.h>

int main() {
  const wchar_t str[] = L"wcstombs example";
  const wchar_t * p;
  mbstate_t mbs;
  char buffer[32];
  int ret;

  mbrlen (NULL,0,&mbs);    /* initialize mbs */

  printf ("wchar_t string: %ls \n",str);

  p = str;
  ret = wcsrtombs ( buffer, &p, sizeof(buffer), &mbs );
  if (ret==32) buffer[31]='\0';
  if (ret) printf ("multibyte string: %s \n",buffer);

  return 0;
}

Output:


wchar_t string: wcstombs example 
multibyte string:  wcstombs example

functions

types

macro constants

wcsrtombs

Parameters

Return Value

Example

See also