Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <wchar.h>
    int mbrtowc( wchar_t *pwc, const char *s,
                 size_t n, mbstate_t *ps );
    int _fmbrtowc( wchar_t __far *pwc, const char __far *s,
                   size_t n, mbstate_t __far *ps );

Description:
    If s is a null pointer, the mbrtowc function determines the number of
    bytes necessary to enter the initial shift state (zero if encodings are
    not state-dependent or if the initial conversion state is described).
     In this case, the value of the pwc argument will be ignored, and the
    resulting state described will be the initial conversion state.

    If s is not a null pointer, the mbrtowc function determines the number
    of bytes that are contained in the multibyte character (plus any leading
    shift sequences) pointed to by s, produces the value of the
    corresponding wide character and then, if pwc is not a null pointer,
    stores that value in the object pointed to by pwc.  If the corresponding
    wide character is the null wide character, the resulting state described
    will be the initial conversion state.

    The _fmbrtowc function is a data model independent form of the mbrtowc
    function that accepts far pointer arguments.  It is most useful in mixed
    memory model applications.

    The restartable multibyte/wide character conversion functions differ
    from the corresponding internal-state multibyte character functions (
     mblen,  mbtowc, and  wctomb) in that they have an extra argument, ps,
    of type pointer to  mbstate_t that points to an object that can
    completely describe the current conversion state of the associated
    multibyte character sequence.  If ps is a null pointer, each function
    uses its own internal  mbstate_t object instead.  You are guaranteed
    that no other function in the library calls these functions with a null
    pointer for ps, thereby ensuring the stability of the state.

    Also unlike their corresponding functions, the return value does not
    represent whether the encoding is state-dependent.

    If the encoding is state-dependent, on entry each function takes the
    described conversion state (either internal or pointed to by ps) as
    current.  The conversion state described by the pointed-to object is
    altered as needed to track the shift state of the associated multibyte
    character sequence.  For encodings without state dependency, the pointer
    to the  mbstate_t argument is ignored.

Returns:
    If s is a null pointer, the mbrtowc function returns the number of bytes
    necessary to enter the initial shift state.  The value returned will not
    be greater than that of the  MB_CUR_MAX macro.

    If s is not a null pointer, the mbrtowc function returns the first of
    the following that applies:

    Value     Meaning

0
    if the next n or fewer bytes form the multibyte character that
    corresponds to the null wide character.

>0
    if the next n or fewer bytes form a valid multibyte character; the value
    returned is the number of bytes that constitute that multibyte
    character.

-2
    if the next n bytes form an incomplete (but potentially valid) multibyte
    character, and all n bytes have been processed; it is unspecified
    whether this can occur when the value of n is less than that of the
     MB_CUR_MAX macro.

-1
    if an encoding error occurs (when the next n or fewer bytes do not form
    a complete and valid multibyte character); the value of the macro
     EILSEQ will be stored in  errno, but the conversion state will be
    unchanged.



Example:
    #include <stdio.h>
    #include <wchar.h>
    #include <mbctype.h>
    #include <errno.h>


    const char chars[] = {
        ' ',
        '.',
        '1',
        'A',
        0x81,0x40, /* double-byte space */
        0x82,0x60, /* double-byte A */
        0x82,0xA6, /* double-byte Hiragana */
        0x83,0x42, /* double-byte Katakana */
        0xA1,      /* single-byte Katakana punctuation */
        0xA6,      /* single-byte Katakana alphabetic */
        0xDF,      /* single-byte Katakana alphabetic */
        0xE0,0xA1, /* double-byte Kanji */
        0x00
    };

    void main()
      {
        int         i, j, k;
        wchar_t     pwc;

        _setmbcp( 932 );
        i = mbrtowc( NULL, NULL, MB_CUR_MAX, NULL );
        printf( "Number of bytes to enter "
                "initial shift state = %d\n", i );
        j = 1;
        for( i = 0; j > 0; i += j ) {
          j = mbrtowc( &pwc, &chars[i], MB_CUR_MAX, NULL );
          printf( "%d bytes in character ", j );
          if( errno == EILSEQ ) {
            printf( " - illegal multibyte character\n" );
          } else {
            if( j == 0 ) {
              k = 0;
            } else if ( j == 1 ) {
              k = chars[i];
            } else if( j == 2 ) {
              k = chars[i]<<8 | chars[i+1];
            }
            printf( "(%#6.4x->%#6.4x)\n", k, pwc );
          }
        }
      }

    produces the following:

    Number of bytes to enter initial shift state = 0
    1 bytes in character (0x0020->0x0020)
    1 bytes in character (0x002e->0x002e)
    1 bytes in character (0x0031->0x0031)
    1 bytes in character (0x0041->0x0041)
    2 bytes in character (0x8140->0x3000)
    2 bytes in character (0x8260->0xff21)
    2 bytes in character (0x82a6->0x3048)
    2 bytes in character (0x8342->0x30a3)
    1 bytes in character (0x00a1->0xff61)
    1 bytes in character (0x00a6->0xff66)
    1 bytes in character (0x00df->0xff9f)
    2 bytes in character (0xe0a1->0x720d)
    0 bytes in character (  0000->  0000)

Classification:
    mbrtowc is ANSI, _fmbrtowc is not ANSI

Systems:
     mbrtowc - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

    _fmbrtowc - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

See Also:
    _mbccmp, _mbccpy, _mbcicmp, _mbcjistojms, _mbcjmstojis, _mbclen,
    _mbctohira, _mbctokata, _mbctolower, _mbctombb, _mbctoupper, mblen,
    mbrlen, mbsrtowcs, mbstowcs, mbtowc, sisinit, wcrtomb, wcsrtombs,
    wcstombs, wctob, wctomb