Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
mbrlen
and
div
eof
not
or
xor
Collapse the table of content
Expand the table of content

mbrlen

Determine the number of bytes that are required to complete a multibyte character in the current locale, with the capability of restarting in the middle of a multibyte character.

size_t mbrlen(
   const char * str,
   size_t count,
   mbstate_t * mbstate
);

str

Pointer to the next byte to inspect in a multibyte character string.

count

The maximum number of bytes to inspect.

mbstate

Pointer to the current shift state of the initial byte of str.

One of the following values:

0

The next count or fewer bytes complete the multibyte character that represents the wide null character.

1 to count, inclusive

The next count or fewer bytes complete a valid multibyte character. The value returned is the number of bytes that complete the multibyte character.

(size_t)(-2)

The next count bytes contribute to an incomplete but potentially valid multibyte character and all count bytes have been processed.

(size_t)(-1)

An encoding error occurred. The next count or fewer bytes do not contribute to a complete and valid multibyte character. In this case, errno is set to EILSEQ and the conversion state in mbstate is unspecified.

The mbrlen function inspects at most count bytes starting with the byte pointed to by str to determine the number of bytes that are required to complete the next multibyte character, including any shift sequences. It is equivalent to the call mbrtowc(NULL, str, count, &mbstate) where mbstate is either a user-provided mbstate_t object, or a static internal object provided by the library.

The mbrlen function saves and uses the shift state of an incomplete multibyte character in the mbstate parameter. This gives mbrlen the capability of restarting in the middle of a multibyte character if need be, examining at most count bytes. If mbstate is a null pointer, mbrlen uses an internal, static mbstate_t object to store the shift state. Because the internal mbstate_t object is not thread-safe, we recommend that you always allocate and pass your own mbstate parameter.

The mbrlen function differs from _mbclen, mblen, _mblen_l by its restartability. The shift state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application should use wcsrlen instead of wcslen if a subsequent call to wcsrtombs is used instead of wcstombs.

Generic-Text Routine Mappings

TCHAR.H routine

_UNICODE & _MBCS not defined

_MBCS defined

_UNICODE defined

not applicable

not applicable

mbrlen

not applicable

Routine

Required header

mbrlen

<wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

This example shows how the interpretation of multibyte characters depends on the current code page, and demonstrates the resuming capability of mbrlen.

 // crt_mbrlen.c
// Compile by using: cl crt_mbrlen.c
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <locale.h>
#include <wchar.h>

size_t Example(const char * pStr)
{
    size_t      charLen = 0;
    size_t      charCount = 0;
    mbstate_t   mbState = {0};

    while ((charLen = mbrlen(pStr++, 1, &mbState)) != 0 &&
            charLen != (size_t)-1)
    {
        if (charLen != (size_t)-2) // if complete mbcs char,
        {
            charCount++;
        }
    } 
    return (charCount);
} 

int main( void )
{
    int         cp;
    size_t      charCount = 0;
    const char  *pSample = 
        "\x82\xD0\x82\xE7\x82\xAA\x82\xC8: Shift-jis hiragana.";

    cp = _getmbcp();
    charCount = Example(pSample);
    printf("\nCode page: %d\n%s\nCharacter count: %d\n", 
        cp, pSample, charCount);
    
    setlocale(LC_ALL, "ja-JP"); // Set Japanese locale
    _setmbcp(932); // and Japanese multibyte code page
    cp = _getmbcp();
    charCount = Example(pSample);
    printf("\nCode page: %d\n%s\nCharacter count: %d\n", 
        cp, pSample, charCount);
}
 
Code page: 0
é╨éτé¬é╚: Shift-jis hiragana.
Character count: 29

Code page: 932
????: Shift-jis hiragana.
Character count: 25
Show:
© 2015 Microsoft