mbtowc

Run-Time   Library   Reference    
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.

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.   mbtowc   uses   the   current   locale   for   locale-dependent   behavior;   _mbtowc_l   is   identical   except   that   it   uses   the   locale   passed   in   instead.

Requirements

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.

Example

  Copy   Code
//   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   );
}
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