This topic has not yet been rated - Rate this topic

mbtowc

Visual Studio .NET 2003

Convert a multibyte character to a corresponding wide character.

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

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.

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.

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.

Requirements

Routine	Required header	Compatibility
mbtowc	<stdlib.h>	ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// 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" );
    i = wctomb( pmbc, 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 );
}

Output

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