_mbclen, mblen

Get the length and determine the validity of a multibyte character.

size_t _mbclen(
   const unsigned char *c 
);
int mblen(
   const char *mbstr,
   size_t count 
);

Parameters

c

Multibyte character.

mbstr

Address of multibyte-character byte sequence.

count

Number of bytes to check.

Return Value

_mbclen returns 1 or 2, according to whether the multibyte character c is one or two bytes long. There is no error return for _mbclen. If mbstr is not NULL, mblen returns the length, in bytes, of the multibyte character. If mbstr is NULL, or if it points to the wide-character null character, mblen returns 0. If the object that mbstr points to does not form a valid multibyte character within the first count characters, mblen returns –1.

Remarks

The _mbclen function returns the length, in bytes, of the multibyte character c. If c does not point to the lead byte of a multibyte character as determined by an implicit call to _ismbblead, the result of _mbclen is unpredictable.

mblen returns the length in bytes of mbstr if it is a valid multibyte character. It examines count or fewer bytes contained in mbstr, but not more than MB_CUR_MAX bytes. mblen determines multibyte-character validity according to the LC_CTYPE category setting of the current locale. For more information on the LC_CTYPE category, see setlocale.

Generic-Text Routine Mappings

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_mblen.c
/* illustrates the behavior of the mblen function
 */

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

int main( void )
{
    int      i;
    char    *pmbc = (char *)malloc( sizeof( char ) );
    wchar_t  wc   = L'a';

    printf( "Convert wide character to multibyte character:\n" );
    i = wctomb( pmbc, wc );
    printf( "  Characters converted: %u\n", i );
    printf( "  Multibyte character: %x\n\n", *pmbc );

    i = mblen( pmbc, MB_CUR_MAX );
    printf( "Length in bytes of multibyte character %x: %u\n", *pmbc, i );

    pmbc = NULL;
    i = mblen( pmbc, MB_CUR_MAX );
    printf( "Length in bytes of NULL multibyte character %x: %u\n", pmbc, i );
}

Output

Convert wide character to multibyte character:
  Characters converted: 1
  Multibyte character: 61

Length in bytes of multibyte character 61: 1
Length in bytes of NULL multibyte character 0: 0

See Also

Character Classification Routines | Locale Routines | Interpretation of Multibyte-Character Sequences | _mbccpy | _mbslen | Run-Time Routines and .NET Framework Equivalents