mbtowc, _mbtowc_l
Convert a multibyte character to a corresponding wide character.
int mbtowc( wchar_t *wchar, const char *mbchar, size_t count ); int _mbtowc_l( wchar_t *wchar, const char *mbchar, size_t count, _locale_t locale );
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.
- locale
-
The locale to use.
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.
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. mbtowc uses the current locale for locale-dependent behavior; _mbtowc_l is identical except that it uses the locale passed in instead.
| Routine | Required header | Compatibility |
|---|---|---|
| mbtowc | <stdlib.h> | ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 |
| _mbtowc_l | <stdlib.h> | ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
All versions of the C run-time libraries.
// crt_mbtowc.c
/* Illustrates the behavior of the mbtowc function
*/
#include <stdlib.h>
#include <stdio.h>
int 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" );
wctomb_s( &i, pmbc, sizeof(char), wc );
printf( " Characters converted: %u\n", i );
printf( " Multibyte character: %x\n\n", *pmbc );
printf( "Convert multibyte character back to a wide "
"character:\n" );
i = mbtowc( pwc, pmbc, MB_CUR_MAX );
printf( " Bytes converted: %u\n", i );
printf( " Wide 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( " Length 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( " Bytes converted: %u\n", i );
}
Convert a wide character to multibyte character: Characters converted: 1 Multibyte character: 61 Convert multibyte character back to a wide character: Bytes converted: 1 Wide character: 61 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
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
