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

Synopsis:
    #include <wchar.h>
    int mbrlen( const char *s, size_t n, mbstate_t *ps );
    int _fmbrlen( const char far *s, size_t n, mbstate_t far *ps );

Description:
    The mbrlen function determines the number of bytes comprising the
    multibyte character pointed to by s.  The mbrlen function is equivalent
    to the following call:


         mbrtowc((wchar_t *)0, s, n, ps != 0 ? ps : &internal)

    where &internal is the address of the internal  mbstate_t object for the
    mbrlen function.

    The _fmbrlen function is a data model independent form of the mbrlen
    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:
    The mbrlen function returns a value between -2 and n, inclusive.  The
    mbrlen 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;

        _setmbcp( 932 );
        j = 1;
        for( i = 0; j > 0; i += j ) {
          j = mbrlen( &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)\n", k );
          }
        }
      }

    produces the following:

    1 bytes in character (0x0020)
    1 bytes in character (0x002e)
    1 bytes in character (0x0031)
    1 bytes in character (0x0041)
    2 bytes in character (0x8140)
    2 bytes in character (0x8260)
    2 bytes in character (0x82a6)
    2 bytes in character (0x8342)
    1 bytes in character (0x00a1)
    1 bytes in character (0x00a6)
    1 bytes in character (0x00df)
    2 bytes in character (0xe0a1)
    0 bytes in character (  0000)

Classification:
    mbrlen is ANSI, _fmbrlen is not ANSI

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

    _fmbrlen - 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,
    mbrtowc, mbsrtowcs, mbstowcs, mbtowc, sisinit, wcrtomb, wcsrtombs,
    wcstombs, wctob, wctomb