mbrlen

Determine the number of bytes in a string, with the capability of restarting in the middle of a multibyte character if need be, while using the current locale.

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

Parameters

• str
  Null-terminated string.

• maxSize
  The maximum size of the string, excluding the terminating null character.

• mbstate
  The shift state of conversion.

Return Value

If the string is less than maxSize characters in length, each of these functions returns the number of characters in str, excluding the terminal NULL. If the string is greater than maxSize characters in length, then maxSize is returned.

• 0
  If the next count or fewer bytes complete the multibyte character that represents the NULL wide character.

• > 0
  If the next count or fewer bytes complete a valid multibyte character, the value returned is the number of bytes that complete the multibyte character.

• -1
  If the next count bytes contribute to an incomplete multibyte and all count bytes have been processed.

• -2
  If an encoding error occurs, in which case the next count or fewer bytes do not contribute to the complete and valid multibyte character, the value errno value will be EILSEQ and the conversion state ambiguous.

Remarks

The mbrlen function determines the number of bytes constituting the multibyte character sequence of str, with the capability of restarting in the middle of a multi-byte character if need be, examining at most maxSize bytes. The mbstate_t argument mbstate is used to keep track of the shift state. If it is NULL, mbrlen uses an internal, static mbstate_t object. It is equivalent to:

mbrtowc(NULL, str, maxSize, mbstate)

Except when the case of mbstate is NULL, mbrlen relies upon its own static, internal mbstate_t object to keep track of the shift state.

The mbrlen function differs from _mbclen, mblen, _mblen_l by its restartability. The conversion 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 would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs where used instead of wcstombs.

Generic-Text Routine Mappings

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Example

// crt_mbrlen.c

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

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

    memset(&mbState, 0, sizeof(mbState));
    
    while ((charLen = mbrlen(pStr, MB_CUR_MAX, &mbState)) != 0 &&
            charLen != (size_t)-1 && charLen != (size_t)-2)
    {
        pStr += charLen;
        charCount++;
    } 

    return (charCount);
} 

int main( void )
{
    size_t      charCount = 0;
    const char  *pSample = "Every good boy does fine.";

    charCount = Example(pSample);
    printf("%s\nLength: %d\n", pSample, charCount);
}

Every good boy does fine.
Length: 25

.NET Framework Equivalent

System::String::Length

See Also

Reference

String Manipulation (CRT)

Locale