_mbclen, mblen
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

_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

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tclen Maps to macro or inline function _mbclen Maps to macro or inline function

Requirements

Routine Required header Compatibility
_mbclen <mbstring.h> Win 98, Win Me, Win NT, Win 2000, Win XP
mblen <stdlib.h> ANSI, Win 98, Win Me, Win NT, Win 2000, Win XP

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

Show:
© 2016 Microsoft