mbstowcs, _fmbstowcs

Description

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

#include <stdlib.h>

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

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

Remarks

The mbstowcs function converts count or fewer multibyte characters pointed to by mbstr to a string of corresponding wide characters that are determined by the current locale. It stores the resulting wide-character string at the address represented by wcstr. The result is similiar to a series of calls to the mbtowc function.

If mbstowcs encounters the null character ('\0') either before or when count occurs, it converts the null character to a wide-character null character (L'\0') and stops. Thus, the wide-character string at wcstr is null-terminated only if a null character is encountered during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior is undefined.

The _fmbstowcs function is a model-independent (large-model) form of the mbstowcs function. It can be called from any point in any program.

Return Value

If mbstowcs or (_fmbstowcs) successfully converts the source string, it returns the number of converted multibyte characters. If either function encounters an invalid multibyte character, it returns –1. If the return value is count, the wide-character string is not null-terminated.

Compatibility

mbstowcs

Standards:ANSI

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

32-Bit:DOS32X

_fmbstowcs

Standards:None

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

32-Bit:None

See Also

mblen, mbtowc, wcstombs, wctomb, MB_CUR_MAX, MB_LEN_MAX

Example

/* MBSTOWCS.CPP illustrates the behavior of the mbstowcs function. */

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

int i;

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

wchar_t *pwchello = L"Hi";

wchar_t *pwc = (wchar_t *)malloc( sizeof( wchar_t ));

printf( "Convert to multibyte string:\n" );

i = wcstombs( pmbhello, pwchello, MB_CUR_MAX );

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

printf( "\tHex value of first" );

printf( " multibyte character: %#.4x\n\n", pmbhello );

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

i = mbstowcs( pwc, pmbhello, MB_CUR_MAX );

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

printf( "\tHex value of first" );

printf( " wide character: %#.4x\n\n", pwc );

}

Output

Convert to multibyte string:

Characters converted: 1

Hex value of first multibyte character: 0x0e26

Convert back to wide-character string:

Characters converted: 1

Hex value of first wide character: 0x0e2a