wcstombs (Windows CE 5.0)

Article
09/14/2012

Developing an Application > Microsoft C Run-time Library for Windows CE > Run-time Library Reference

Converts a sequence of wide characters to a corresponding sequence of multibyte characters.

size_t wcstombs( char *mbstr, constwchar_t *wcstr, size_tcount);

Parameters

mbstr
The address of a sequence of multibyte characters.
wcstr
The address of a sequence of wide characters.
count
The maximum number of bytes that can be stored in the multibyte output string.

Return Values

If wcstombs successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating NULL (if any).

If the mbstr argument is NULL, wcstombs returns the required size of the destination string.

In versions of Windows CE prior to 3.0, setting mbstr to NULL returns -1.

If wcstombs encounters a wide character it cannot be convert to a multibyte character, it returns –1 cast to type size_t.

Remarks

These functions are supported by all versions of the C run-time libraries.

The wcstombs function converts the wide-character string pointed to by wcstr to the corresponding multibyte characters and stores the results in the mbstr array. The count parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of mbstr).

In general, it is not known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two.

If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character NULL), the result is guaranteed to fit.

If wcstombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to an 8-bit 0 and stops. Thus, the multibyte character string at mbstr is null-terminated only if wcstombs encounters a wide-character null character during conversion.

If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcstombs is undefined.

If the mbstr argument is NULL, wcstombs returns the required size of the destination string.

Example

Description

The following code illustrates the behavior of the wcstombs function.

Code

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

void main( void )
{
   int      i;
   char    *pmbbuf   = (char *)malloc( MB_CUR_MAX );
   wchar_t *pwchello = L"Hello, world.";

   printf( "Convert wide-character string:\n" );
   i = wcstombs( pmbbuf, pwchello, MB_CUR_MAX );
   printf( "\tCharacters converted: %u\n", i );
   printf( "\tMultibyte character: %s\n\n", pmbbuf );
}
// Output
Convert wide-character string:
  Characters converted: 1
  Multibyte character: H

Requirements

OS Versions: Windows CE 2.0 and later.

Header: stdio.h, stdlib.h.

Link Library: coredll.dll.