mbrtoc16, mbrtoc32

Convierte el primer carácter multibyte UTF-8 de una cadena en el carácter UTF-16 o UTF-32 equivalente.

Sintaxis

size_t mbrtoc16(
   char16_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

size_t mbrtoc32(
   char32_t* destination,
   const char* source,
   size_t max_bytes,
   mbstate_t* state
);

Parámetros

destination
Puntero al equivalente char16_t o char32_t del carácter multibyte UTF-8 que se va a convertir. Si es NULL, la función no almacena un valor.

source
Puntero a la cadena de caracteres multibyte UTF-8 que se va a convertir.

max_bytes
El número máximo de bytes de source que se examinarán para un carácter que se va a convertir. Este argumento debe ser un valor entre uno y el número de bytes, incluidos los terminadores NULL, que quedan en source.

state
Puntero a un mbstate_t objeto de estado de conversión usado para interpretar la cadena multibyte UTF-8 en uno o varios caracteres de salida.

Valor devuelto

Si se ejecuta correctamente, devuelve el valor de la primera de estas condiciones que se aplica, dado el valor state actual:

Valor	Condición
0	Los caracteres siguientes max_bytes o menos convertidos corresponden source al carácter ancho nulo, que es el valor almacenado si destination no es null. state contiene el estado de desplazamiento inicial.
Entre 1 y max_bytes, ambos inclusive	El valor devuelto es el número de bytes de source que completan un carácter multibyte válido. El carácter ancho convertido se almacena si destination no es NULL.
-3	El siguiente carácter ancho resultante de una llamada anterior a la función se ha almacenado en destination si destination no es null. No se consumen bytes de source por esta llamada a la función. Cuando source apunta a un carácter multibyte UTF-8 que requiere más de un carácter ancho para representar (por ejemplo, un par suplente), el state valor se actualiza para que la siguiente llamada de función escriba el carácter adicional.
-2	Los bytes siguientes max_bytes representan un carácter multibyte UTF-8 incompleto, pero potencialmente válido. No se almacena ningún valor en destination. Este resultado se puede producir si max_bytes es cero.
-1	Se ha producido un error de codificación. Los siguientes max_bytes o menos bytes no contribuyen a un carácter multibyte UTF-8 completo y válido. No se almacena ningún valor en destination. EILSEQ se almacena en errno y el valor state de estado de conversión no está especificado.

Comentarios

La mbrtoc16 función lee hasta max_bytes bytes de source para encontrar el primer carácter multibyte UTF-8 completo y, a continuación, almacena el carácter UTF-16 equivalente en destination. Si el carácter requiere más de un carácter de salida UTF-16, como un par suplente, el state valor se establece para almacenar el siguiente carácter UTF-16 en en destination la siguiente llamada a mbrtoc16. La función mbrtoc32 es idéntica, pero la salida se almacena como carácter UTF-32.

Si source es null, estas funciones devuelven el equivalente de una llamada realizada mediante argumentos de NULL para destination, "" (una cadena vacía y terminada en NULL) para sourcey 1 para max_bytes. Se ignoran los valores pasados de destination y max_bytes .

Si source no es null, la función comienza al principio de la cadena e inspecciona hasta max_bytes bytes para determinar el número de bytes necesarios para completar el siguiente carácter multibyte UTF-8, incluidas las secuencias de desplazamiento. Si los bytes examinados contienen un carácter multibyte UTF-8 válido y completo, la función lo convierte al carácter ancho equivalente de 16 o 32 bits. Si destination no es null, la función almacena el primer carácter de resultado (y posiblemente solo) en el destino. Si se requieren caracteres de salida adicionales, se establece un valor en state, de modo que las llamadas posteriores a la función generan los caracteres adicionales y devuelven el valor -3. Si no se requieren más caracteres de salida, state se establece en el estado de desplazamiento inicial.

Para convertir caracteres multibyte que no sean UTF-8 a caracteres UTF-16 LE, use las mbrtowcfunciones , mbtowc o _mbtowc_l .

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.

Requisitos

Función	Encabezado C	Encabezado C++
mbrtoc16, mbrtoc32	<uchar.h>	<cuchar>

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

Consulte también

Conversión de datos
Configuración regional
Interpretación de secuencias de caracteres de varios bytes
c16rtomb, c32rtomb
mbrtowc
mbsrtowcs
mbsrtowcs_s