mbrlen

Determine o número de bytes necessários para completar um caractere multibyte na localidade atual, com a capacidade de reiniciar no meio de um caractere multibyte.

Sintaxe

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

Parâmetros

str
O ponteiro para o próximo byte a ser inspecionado em uma cadeia de caracteres multibyte.

count
O número máximo de bytes a serem inspecionados.

mbstate
O ponteiro para o estado de deslocamento atual do byte inicial de str.

Valor retornado

Um dos seguintes valores:

Valor	Descrição
0	Os próximos count ou menos bytes completam o caractere multibyte que representa o caractere nulo largo.
1 para count, inclusive	Os próximos count ou menos bytes completam um caractere multibyte válido. O valor retornado é o número de bytes que completa os caracteres multibyte.
(size_t)(-2)	Os próximos count bytes contribuem para um caractere multibyte incompleto, mas potencialmente válido e todos os count bytes foram processados.
(size_t)(-1)	Erro de codificação. Os próximos count bytes ou menos bytes não contribuem para um caractere multibyte completo e válido. Nesse caso, errno é definido como EILSEQ e o estado da conversão em mbstate não é especificado.

Comentários

A função mbrlen inspeciona no máximo count bytes, começando com o byte apontado por str para determinar o número de bytes que são necessários para completar o próximo caractere multibyte, incluindo as sequências de deslocamento. É equivalente à chamada mbrtowc(NULL, str, count, &mbstate) em que mbstate é um objeto fornecido pelo mbstate_t usuário ou um objeto interno estático fornecido pela biblioteca.

A função mbrlen salva e usa o estado de deslocamento de um caractere multibyte incompleto no parâmetro mbstate. É por isso que **mbrlen** pode reiniciar no meio de um caractere multibyte, se necessário, e examinar no máximo count bytes. Se mbstate for um ponteiro nulo, mbrlen usará um objeto mbstate_t estático interno para armazenar o estado de deslocamento. Como o objeto interno mbstate_t não é thread-safe, recomendamos que você sempre aloque e passe seu próprio mbstate parâmetro.

A mbrlen função difere de _mbclen, mblen, _mblen_l por sua capacidade de reinicialização. O estado de deslocamento é armazenado em mbstate para chamadas posteriores às mesmas funções ou a outras funções reiniciáveis. Os resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciáveis. Por exemplo, um aplicativo deverá usar wcsrlen em vez de wcslen se uma chamada subsequente para wcsrtombs for usada em vez de wcstombs.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Rotina TCHAR.H	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
não aplicável	não aplicável	mbrlen	não aplicável

Requisitos

Rotina	Cabeçalho necessário
mbrlen	<wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Este exemplo mostra como a interpretação de caracteres multibyte depende da página de código atual e demonstra a capacidade de retomada do 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

Confira também

Manipulação de cadeia de caracteres
Localidade