mbrlen

Determine el número de bytes que se necesitan para completar un carácter multibyte en la configuración regional actual, con capacidad de reinicio en medio de un carácter multibyte.

Sintaxis

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

Parámetros

str
Puntero al siguiente byte que se va a inspeccionar en una cadena de caracteres multibyte.

count
El número máximo de bytes a inspeccionar.

mbstate
Puntero al estado de desplazamiento actual del byte inicial de str.

Valor devuelto

Uno de los siguientes valores:

Valor	Descripción
0	Los siguientes count o menos bytes completan el carácter multibyte que representa el carácter nulo ancho.
1 a count, ambos inclusive	Los próximos count o menos bytes completan un carácter multibyte válido. El valor devuelto es el número de bytes que completan el carácter multibyte.
(size_t)(-2)	Los próximos count bytes contribuyen a un carácter multibyte incompleto pero potencialmente válido y los count bytes se han procesado.
(size_t)(-1)	Se produjo un error de codificación. Los siguientes count o menos bytes no contribuyen a un carácter multibyte completo y válido. En este caso, errno se establece a EILSEQ y el estado de la conversión en mbstate no está especificado.

Comentarios

La función mbrlen inspecciona a lo sumo count bytes a partir del byte señalado por str para determinar el número de bytes que son necesarios para completar el siguiente carácter multibyte, incluidas las secuencias de desplazamiento. Es equivalente a la llamada mbrtowc(NULL, str, count, &mbstate) donde mbstate es un objeto proporcionado mbstate_t por el usuario o un objeto interno estático proporcionado por la biblioteca.

La función mbrlen guarda y usa el estado de desplazamiento de un carácter multibyte incompleto en el parámetro mbstate. Es por eso que **mbrlen**puede reiniciarse en medio de un carácter multibyte, si es necesario, y examinar como máximo count bytes. Si mbstate es un puntero nulo, mbrlen usa un objeto mbstate_t estático interno para almacenar el estado de desplazamiento. Dado que el objeto interno mbstate_t no es seguro para subprocesos, se recomienda asignar y pasar siempre su propio mbstate parámetro.

La mbrlen función difiere de _mbclen, mblen_mblen_l por su capacidad de reinicio. El estado de desplazamiento se almacena en mbstate para las llamadas posteriores a la misma o a otras funciones reiniciables. Los resultados no están definidos cuando se combina el uso de funciones reiniciables y no reiniciables. Por ejemplo, una aplicación debe utilizar wcsrlen en lugar de wcslen si se utiliza una llamada subsiguiente a wcsrtombs en lugar de a wcstombs.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
no aplicable	no aplicable	mbrlen	no aplicable

Requisitos

Routine	Encabezado necesario
mbrlen	<wchar.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

Este ejemplo muestra cómo la interpretación de caracteres multibyte depende de la página de códigos actual, y demuestra la capacidad de reanudación de 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

Consulte también

Manipulación de cadenas
Configuración regional