6.19.39 wcstombs Function

Converts a wide character string to a multibyte character sequence.

Include

<stdlib.h>

Prototype

size_t wcstombs(char * restrict s, const wchar_t * restrict pwcs, size_t n);

Arguments

s

a pointer to the object to hold the converted multibyte character sequence

pwcs

the wide character sequence to convert

n

the maximum number of bytes to store in s

Return Value

The function returns the number of bytes in the multibyte character sequence, not including the terminating null character (if any). If s cannot be converted to a mutlibyte character sequence, (size_t)(-1) is returned.

Remarks

The function converts a wide character string indirectly pointed to by pwcs beginning in the initial shift state into a sequence of corresponding multibyte characters, storing no more than n converted characters (including a terminating null character) into the array pointed to by s, provided dst is not a null pointer. Each conversion takes place as if by a call to the wctomb() function, except that the conversion state of the that function is not affected.

Example

See the notes at the beginning of this chapter or section for information on using printf() or scanf() (and other functions reading and writing the stdin or stdout streams) in the example code.

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

int main(void) {
  const wchar_t * ws = L"Volume: 2L±0.5mL";
  char buffer[20];
  size_t length;

  setlocale(LC_CTYPE, "");

  length = wcstombs(buffer, ws, 20);
  wprintf(L"multibyte string \"%s\" has length %d\n", buffer, length);
}

Example Output

multibyte string "Volume: 2L±0.5mL" has length 17