mbtowc()

convert a multibyte character to a wide character

Synopsis:

#include <stdlib.h>
int mbtowc( wchar_t *pwc,
            const char *s,
            size_t n );

Description:

The mbtowc() function converts a single multibyte character pointed to by s into the wide character code that corresponds to it. The code for the null character is zero. If the multibyte character is valid and pwc isn't a NULL pointer, the code is stored in the object pointed to by pwc. At most n bytes of the array pointed to by s will be examined.

The mbtowc() function doesn't examine more than MB_CUR_MAX bytes.

Returns:

If s is a NULL pointer, the mbtowc() function returns zero if multibyte character encodings aren't state-dependent, and nonzero otherwise. If s isn't a NULL pointer, the mbtowc() function returns:

• 0 if s points to the null character
• the number of bytes that comprise the multibyte character if the next n or fewer bytes form a valid multibyte character
• -1 if the next n bytes don't form a valid multibyte character

Examples:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
    char    *wc = "string";
    wchar_t wbuffer[10];
    int     i, len;

    printf( "Character encodings do %shave "
        "state-dependent \nencoding.\n",
        ( mbtowc( wbuffer, NULL, 0 ) )
        ? "" : "not " );

    len = mbtowc( wbuffer, wc, 2 );
    wbuffer[len] = '\0';
    printf( "%s(%d)\n", wc, len );
    for( i = 0; i < len; i++ )
      printf( "/%4.4x", wbuffer[i] );
    printf( "\n" );
  }

produces the output:

Character encodings do not have state-dependent 
encoding.
string(1)
/0073

Classification:

ANSI

See also:

mblen(), mbstowcs(), wcstombs(), wctomb()