mbrtowc

Converte un carattere multibyte delle impostazioni locali correnti nel carattere wide equivalente, con la possibilità di ricominciare nel mezzo di un carattere multibyte.

Sintassi

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

Parametri

wchar
Indirizzo di un carattere wide per ricevere la stringa di caratteri wide convertita (tipo wchar_t). Questo valore può essere un puntatore Null se non è richiesta la restituzione di caratteri wide.

mbchar
Indirizzo di una sequenza di byte (carattere multibyte).

count
Numero di byte da controllare.

mbstate
Puntatore all'oggetto stato di conversione. Se questo valore è un puntatore Null, la funzione userà un oggetto stato di conversione interno statico. Poiché l'oggetto interno mbstate_t non è thread-safe, è consigliabile passare sempre il proprio mbstate argomento.

Valore restituito

Uno dei valori seguenti:

0 I byte successivi count o minori completano il carattere multibyte che rappresenta il carattere wide Null, archiviato in wchar, se wchar non è un puntatore Null.

Da 1 a count, inclusi I byte successivi count o minori completano un carattere multibyte valido. Il valore restituito è il numero di byte che completa il carattere multibyte. L'equivalente di caratteri wide viene archiviato in wchar, se wchar non è un puntatore Null.

(size_t) (-1) Si è verificato un errore di codifica. I byte successivi count o minori non contribuiscono a un carattere multibyte completo e valido. In tal caso, errno viene impostato su EILSEQ e non viene specificato lo stato di spostamento conversione in mbstate.

(size_t) (-2) I byte successivi count contribuiscono a un carattere multibyte incompleto ma potenzialmente valido e tutti i count byte sono stati elaborati. Nessun valore viene archiviato in wchar, ma mbstate viene aggiornato per riavviare la funzione.

Osservazioni:

Se mbchar è un puntatore Null, la funzione è equivalente alla chiamata seguente:

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

In questo caso, i valori degli wchar argomenti e count vengono ignorati.

Se mbchar non è un puntatore Null, la funzione esamina i count byte da mbchar per determinare il numero di byte necessario per completare il carattere multibyte successivo. Se il carattere successivo è valido, il carattere multibyte corrispondente viene archiviato in wchar se non è un puntatore Null. Se il carattere è il carattere wide Null corrispondente, lo stato risultante di mbstate è lo stato di conversione iniziale.

La mbrtowc funzione differisce da mbtowc, _mbtowc_l in base alla riavviibilità. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili. Ad esempio, un'applicazione deve usare wcsrlen anziché wcslen se viene usata una chiamata successiva a wcsrtombs anziché wcstombs.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Esempio

Converte un carattere multibyte nel relativo carattere wide equivalente.

// 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);
}

Output di esempio

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

Requisiti

Ciclo	Intestazione obbligatoria
mbrtowc	<wchar.h>

Vedi anche

Conversione dei dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte