wcstombs, _fwcstombs

Description

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

#include <stdlib.h>

size_t wcstombs( char *mbstr, const wchar_t *wcstr, size_t count );

size_t __far _fwcstombs( char __far *mbstr, const wchar_t __far *wcstr,
size_t count );

Remarks

The wcstombs function converts count or fewer wide characters pointed to by wcstr to the corresponding multibyte characters and stores the results in the mbstr array.

If wcstombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to the multibyte null character (a 16-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.

The _fwcstombs function is a model-independent (large-model) form of the wcstombs function.

Return Value

If either wcstombs or _fwcstombs successfully converts the multibyte string, it returns the number of converted multibyte characters, excluding the wide-character null character. If either function encounters a wide character that cannot be converted to a multibyte character, it returns –1 cast to type size_t.

Compatibility

wcstombs

Standards:ANSI

16-Bit:DOS, QWIN, WIN, WIN DLL

32-Bit:DOS32X

_fwcstombs

Standards:None

16-Bit:DOS, QWIN, WIN, WIN DLL

32-Bit:None

See Also

mblen, mbstowcs, mbtowc, wctomb, MB_CUR_MAX, MB_LEN_MAX

Example

/* WCSTOMBS.CPP illustrates the behavior of the wcstombs function */

#include <stdio.h>

#include <stdlib.h>

void main( void )

{

int i;

char *pmbbuf = (char *)malloc( MB_CUR_MAX );

wchar_t *pwcEOL = L'\0';

wchar_t *pwchello = L"Hello, world.";

printf( "Convert entire wide-character string:\n" );

i = wcstombs( pmbbuf, pwchello, MB_CUR_MAX );

printf( "\tCharacters converted: %u\n", i );

printf( "\tMultibyte character: %s\n\n", pmbbuf );

printf( "Attempt to convert null character:\n" );

i = wcstombs( pmbbuf, pwcEOL, MB_CUR_MAX );

printf( "\tCharacters converted: %u\n", i );

printf( "\tMultibyte character: %s\n\n", pmbbuf );

}

Output

Convert entire wide-character string:

Characters converted: 1

Multibyte character: H

Attempt to convert null character:

Characters converted: 0

Multibyte character: