mbtowc

Convert a multibyte character to a corresponding wide character.

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

For additional compatibility information, see Compatibility in the Introduction.

Libraries

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

See Also   mblen, wcstombs, wctomb, MultiByteToWideChar