mbtowc
Convert a multibyte character to a corresponding wide character.
intmbtowc(wchar_t*wchar,constchar*mbchar,size_tcount**);**
| Routine | Required Header | Compatibility |
| mbtowc | <stdlib.h> | ANSI, Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
Return Value
If mbchar is not NULL and if the object that mbchar points to forms a valid multibyte character, mbtowc returns 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'), the function returns 0. If the object that mbchar points to does not form a valid multibyte character within the first count characters, it returns –1.
Parameters
wchar
Address of a wide character (type wchar_t)
mbchar
Address of a sequence of bytes (a multibyte character)
count
Number of bytes to check
Remarks
The mbtowc function converts count or fewer bytes pointed to by mbchar, if mbchar is not NULL, to a corresponding wide character. mbtowc stores the resulting wide character at wchar, if wchar is not NULL. mbtowc does not examine more than MB_CUR_MAX bytes.
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: 2d02d4
Convert multibyte character back to a wide character:
Bytes converted: 1
Wide character: 2d02dc
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
Data Conversion Routines | Locale Routines | Interpretation of Multibyte-Character Sequences