mbrtowc

Convierte un carácter multibyte en la configuración regional actual en el carácter ancho equivalente, con capacidad de reinicio en medio de un carácter multibyte.

Sintaxis

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

Parámetros

wchar
Dirección de un carácter ancho para recibir la cadena de caracteres anchos convertido (tipo wchar_t). Este valor puede ser un puntero nulo si no se requiere devolver ningún carácter ancho.

mbchar
Dirección de una secuencia de bytes (un carácter multibyte).

count
Número de bytes que se va a comprobar.

mbstate
Puntero al objeto de estado de la conversión. Si este valor es un puntero nulo, la función utiliza un objeto de estado de la conversión interno estático. Dado que el objeto interno mbstate_t no es seguro para subprocesos, se recomienda pasar siempre su propio mbstate argumento.

Valor devuelto

Uno de los siguientes valores:

0 Los siguientes count o menos bytes completan el carácter multibyte que representa el carácter ancho nulo, que se almacena en wchar, si wchar no es un puntero nulo.

De 1 a count, ambos incluidos Los siguientes 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. El equivalente de caracteres anchos se almacena en wchar, si wchar no es un puntero nulo.

(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 desplazamiento de la conversión en mbstate queda sin especificar.

(size_t) (-2) Los siguientes count bytes contribuyen a un carácter multibyte incompleto pero potencialmente válido y se han procesado todos los count bytes. Ningún valor se almacena en wchar, pero mbstate se actualiza para reiniciar la función.

Comentarios

Si mbchar es un puntero nulo, la función es equivalente a la llamada:

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

En este caso, se omiten los valores de los wchar argumentos y count .

Si mbchar no es un puntero nulo, la función examina count bytes de mbchar para determinar el número necesario de bytes necesarios para completar el siguiente carácter multibyte. Si el carácter siguiente es válido, el carácter multibyte correspondiente se almacena en wchar si no es un puntero nulo. Si el carácter es el carácter nulo ancho correspondiente, el estado resultante de mbstate es el estado inicial de la conversión.

La mbrtowc función difiere de mbtowc, _mbtowc_l por su capacidad de reinicio. El estado de la conversión se almacena en mbstate para 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.

Ejemplo

Convierte un carácter multibyte en su equivalente de carácter ancho.

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

Salida de ejemplo

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

Requisitos

Routine	Encabezado necesario
mbrtowc	<wchar.h>

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres de varios bytes