c16rtomb

Convierte un único punto de código desde su representación de caracteres anchos de 16 bits de longitud variable (típicamente, UTF-16) a su representación de caracteres multibyte estrechos.

Si s no es un puntero nulo y c16 es la última unidad de código de 16 bits en una codificación de longitud variable válida de un punto de código, la función determina el número de bytes necesarios para almacenar la representación del carácter multibyte de ese punto de código (incluyendo cualquier secuencia de desplazamiento, y teniendo en cuenta el estado actual de conversión multibyte * ps ), y almacena la representación del carácter multibyte en el arreglo de caracteres cuyo primer elemento está apuntado por s , actualizando * ps según sea necesario. Como máximo MB_CUR_MAX bytes pueden ser escritos por esta función.

Si s es un puntero nulo, la llamada es equivalente a c16rtomb ( buf, u ' \0 ' , ps ) para algún búfer interno buf .

Si c16 es el carácter ancho nulo u ' \0 ' , se almacena un byte nulo, precedido por cualquier secuencia de cambio necesaria para restaurar el estado de cambio inicial y el parámetro de estado de conversión * ps se actualiza para representar el estado de cambio inicial.

Si c16 no es la unidad de código final en una representación de 16 bits de un carácter ancho, no escribe en el array apuntado por s , solo se actualiza * ps .

Si la macro __STDC_UTF_16__ está definida, la codificación de 16 bits utilizada por esta función es UTF-16; de lo contrario, está definida por la implementación. La macro siempre está definida y la codificación es siempre UTF-16. (desde C23) En cualquier caso, la codificación de caracteres multibyte utilizada por esta función está especificada por la configuración regional de C actualmente activa.

Parámetros

Valor de retorno

En caso de éxito, retorna el número de bytes (incluyendo cualquier secuencia de desplazamiento) escritos en el arreglo de caracteres cuyo primer elemento está apuntado por s . Este valor puede ser ​ 0 ​ , por ejemplo, al procesar las unidades char16_t iniciales en una secuencia multi- char16_t -unidad (ocurre cuando se procesa el sustituto inicial en un par sustituto de UTF-16).

En caso de fallo (si c16 no es una unidad de código de 16 bits válida), retorna - 1 , almacena EILSEQ en errno , y deja * ps en un estado no especificado.

Notas

En C11 tal como se publicó, a diferencia de mbrtoc16 , que convierte codificación multibyte de ancho variable (como UTF-8) a codificación de 16 bits de ancho variable (como UTF-16), esta función solo puede convertir codificación de 16 bits de una sola unidad, lo que significa que no puede convertir UTF-16 a UTF-8 a pesar de que esa era la intención original de esta función. Esto fue corregido por el informe de defectos posterior a C11 DR488 .

Ejemplo

#include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <uchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char16_t in[] = u"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    const size_t in_sz = sizeof in / sizeof *in;
    printf("Processing %zu UTF-16 code units: [", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%s%04X", n ? " " : "", in[n]);
    puts("]");
    char* out = malloc(MB_CUR_MAX * in_sz);
    char* p = out;
    mbstate_t state = {0};
    for (size_t n = 0; n < in_sz; ++n)
    {
        size_t rc = c16rtomb(p, in[n], &state);
        if (rc == (size_t)-1)
            break;
        p += rc;
    }
    size_t out_sz = p - out;
    printf("into %zu UTF-8 code units: [", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%s%02X", x ? " " : "", +(unsigned char)out[x]);
    puts("]");
    free(out);
}

Processing 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]
into 13 UTF-8 code units: [7A C3 9F E6 B0 B4 ED A0 BC ED BD 8C 00]

Referencias

Véase también