mbtowc, _fmbtowc

Description

Convert a multibyte character to a corresponding wide character.

#include <stdlib.h>

int mbtowc( wchar_t *wchar, const char *mbchar, size_t count );

int __far _fmbtowc(wchar_t __far *wchar, const char __far *mbchar,
size_t count );

Remarks

The mbtowc function converts count or fewer bytes pointed to by mbchar, if mbchar is not NULL, to a corresponding wide character that is determined by the current locale. It stores the resulting wide character at wchar, if wchar is not NULL. It will not examine more than MB_CUR_MAX bytes.

The _fmbtowc function is a model-independent (large-model) form of the mbtowc function.

Return Value

If mbchar is not NULL and if the object that mbchar points to forms a valid multibyte character, both mbtowc and _fmbtowc return the length in bytes of the multibyte character.

If mbchar is NULL or the object that it points to is a wide-character null character (L'\0'), both functions return 0. If the object that mbchar points to does not form a valid multibyte character within the first count characters, they return –1.

Compatibility

mbtowc

Standards:ANSI

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

32-Bit:DOS32X

_fmbtowc

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

/* MBTOWC.CPP illustrates the behavior of the mbtowc function. */

#include <stdlib.h>

#include <stdio.h>

void main( void )

{

int i;

char *pmbc = (char *)malloc( sizeof( char ) );

wchar_t wc = L'a';

wchar_t *pwcnull = NULL;

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

printf( "Convert a wide character to multibyte character:\n" );

i = wctomb( pmbc, wc );

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

printf( "\tMultibyte character: %x\n\n", pmbc );

printf( "Convert multibyte character back to a wide character:\n" );

i = mbtowc( pwc, pmbc, MB_CUR_MAX );

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

printf( "\tWide character: %x\n\n", pwc );

printf( "Attempt to convert when target is NULL\n" );

printf( " returns the length of the multibyte character:\n" );

i = mbtowc( pwcnull, pmbc, MB_CUR_MAX );

printf( "\tLength of multibyte character: %u\n\n", i );

printf( "Attempt to convert a NULL pointer to a" );

printf( " wide character:\n" );

pmbc = NULL;

i = mbtowc( pwc, pmbc, MB_CUR_MAX );

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

}

Output

Convert a wide character to multibyte character:

Characters converted: 1

Multibyte character: e36

Convert multibyte character back to a wide character:

Bytes converted: 1

Wide character: e3a

Attempt to convert when target is NULL

returns the length of the multibyte character:

Length of multibyte character: 1

Attempt to convert a NULL pointer to a wide character:

Bytes converted: 0