mbrtowc

Artigo
06/09/2015

Converta um caractere multibyte na localidade atual do caractere largo equivalente, com a capacidade de reinicialização no meio de um caractere multibyte.

size_t mbrtowc(    wchar_t *wchar,    const char *mbchar,    size_t count,    mbstate_t *mbstate );

Parâmetros

wchar
Endereço de um caractere largo para receber a cadeia de caracteres largos convertido (tipo wchar_t). Esse valor pode ser um ponteiro nulo se nenhum caractere de retorno de longa é necessário.
mbchar
Endereço de uma seqüência de bytes (um caractere multibyte).
count
Número de bytes para verificar.
mbstate
Ponteiro para o objeto de estado de conversão. Se esse valor for um ponteiro nulo, a função usa um objeto de estado estático conversão interna. Porque o interno mbstate_t objeto não é thread-safe, recomendamos que você sempre passa seu próprio mbstate argumento.

Valor de retorno

Um dos seguintes valores:

0
O próximo count ou menos bytes concluir os caracteres multibyte que representa o caractere largo null, que é armazenado em wchar, se wchar não é um ponteiro nulo.
1 para count, inclusive
O próximo count ou menos bytes concluir um caractere multibyte válido. O valor retornado é o número de bytes que concluir os caracteres multibyte. O equivalente de caractere largo é armazenado em wchar, se wchar não é um ponteiro nulo.
(size_t)(-1)
Ocorreu um erro de codificação. O próximo count ou menos bytes não contribuem para um caractere multibyte completo e válido. Nesse caso, errno é definido como EILSEQ e o estado de shift conversão no mbstate não é especificado.
(size_t)-(2)
O próximo count bytes contribuem para um caractere multibyte incompleto, mas potencialmente válido e todos os count bytes foram processadas. Nenhum valor é armazenado em wchar, mas mbstate atualizado para reiniciar a função.

Comentários

Se mbchar é um ponteiro nulo, a função é equivalente à chamada:

mbrtowc(NULL, "", 1, &mbstate)

Nesse caso, o valor dos argumentos wchar e count são ignorados.

Se mbchar não é um ponteiro nulo, examina a função count bytes do mbchar para determinar o número necessário de bytes que são necessárias para concluir o próximo caractere multibyte. Se o próximo caractere for válido, o caractere multibyte correspondente é armazenado em wchar se não for um ponteiro nulo. Se o caractere for correspondente nulo ampla de caracteres, o estado resultante do mbstate é o estado inicial de conversão.

O mbrtowc função difere da mbtowc, _mbtowc_l por sua capacidade de reinicialização. O estado de conversão é armazenado em mbstate para chamadas subseqüentes para o mesmo ou outras funções reinicializáveis. Resultados são indefinidos ao combinar o uso de funções reiniciáveis e não reiniciável. Por exemplo, um aplicativo deve usar wcsrlen em vez de wcslen se uma chamada subsequente wcsrtombs é usado em vez de wcstombs.

Exemplo

Converte um caractere multibyte em seu equivalente de caractere largo.

// crt_mbrtowc.cpp

#include <stdio.h>
#include <mbctype.h>
#include <string.h>
#include <locale.h>
#include <wchar.h>

#define BUF_SIZE 100

int Sample(char* szIn, wchar_t* wcOut, int nMax)
{
    mbstate_t   state = {0}; // Initial state
    size_t      nConvResult, 
                nmbLen = 0,
                nwcLen = 0;
    wchar_t*    wcCur = wcOut;
    wchar_t*    wcEnd = wcCur + nMax;
    const char* mbCur = szIn;
    const char* mbEnd = mbCur + strlen(mbCur) + 1;
    char*       szLocal;
    
    // Sets all locale to French_Canada.1252
    szLocal = setlocale(LC_ALL, "French_Canada.1252");
    if (!szLocal)
    {
        printf("The fuction setlocale(LC_ALL, \"French_Canada.1252\") failed!\n");
        return 1;
    }

    printf("Locale set to: \"%s\"\n", szLocal);

    // Sets the code page associated current locale's code page
    // from a previous call to setlocale.
    if (_setmbcp(_MB_CP_SBCS) == -1)
    {
        printf("The fuction _setmbcp(_MB_CP_SBCS) failed!");
        return 1;
    }

    while ((mbCur < mbEnd) && (wcCur < wcEnd))
    {
        //
        nConvResult = mbrtowc(wcCur, mbCur, 1, &state);
        switch (nConvResult)
        {
            case 0:
            {  // done
                printf("Conversion succeeded!\nMultibyte String: ");
                printf(szIn);
                printf("\nWC String: ");
                wprintf(wcOut);
                printf("\n");
                mbCur = mbEnd;
                break;
            }

            case -1:
            {  // encoding error
                printf("The call to mbrtowc has detected an encoding error.\n");
                mbCur = mbEnd;
                break;
            }

            case -2:
            {  // incomplete character
                if   (!mbsinit(&state))
                {
                    printf("Currently in middle of mb conversion, state = %x\n", state);
                    // state will contain data regarding lead byte of mb character
                }

                ++nmbLen;
                ++mbCur;
                break;
            }

            default:
            {
                if   (nConvResult > 2) // The multibyte should never be larger than 2
                {
                    printf("Error: The size of the converted multibyte is %d.\n", nConvResult);
                }

                ++nmbLen;
                ++nwcLen;
                ++wcCur;
                ++mbCur;
            break;
            }
        }
    }

   return 0;
}

int main(int argc, char* argv[])
{
    char    mbBuf[BUF_SIZE] = "AaBbCc\x9A\x8B\xE0\xEF\xF0xXyYzZ";
    wchar_t wcBuf[BUF_SIZE] = {L''};

    return Sample(mbBuf, wcBuf, BUF_SIZE);
}

Exemplo de saída

Locale set to: "French_Canada.1252"
Conversion succeeded!
Multibyte String: AaBbCcÜïα∩≡xXyYzZ
WC String: AaBbCcÜïα∩≡xXyYzZ

Requisitos

Rotina	Cabeçalho necessário
mbrtowc	< WCHAR. h >

Equivalência do .NET Framework

Não aplicável. Para chamar a função C padrão, use PInvoke. Para obter mais informações, consulte Exemplos de invocação de plataforma.

Consulte também

Referência

Conversão de dados

Localidade

Interpretação de sequências de caracteres multibyte

Compartilhar via