std:: c16rtomb

Convierte un único punto de código de representación de caracteres de 16 bits de longitud variable (típicamente, UTF-16) a una 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 válida de longitud variable 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 std :: c16rtomb ( buf, u ' \0 ' , ps ) para algún búfer interno buf .

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 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.

La codificación 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 el primer char16_t en un par sustituto.

En caso de fallo (si c16 no es un carácter de 16 bits válido), retorna - 1 , almacena EILSEQ en errno , y deja * ps en estado no especificado.

Notas

El estándar de C++ remite al estándar de C para la semántica de esta función. En C11 tal como se publicó, a diferencia de std::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 <climits>
#include <clocale>
#include <cuchar>
#include <iomanip>
#include <iostream>
#include <string_view>
int main()
{
    std::setlocale(LC_ALL, "en_US.utf8");
    std::u16string_view strv = u"zß水🍌"; // or z\u00df\u6c34\U0001F34C
    std::cout << "Processing " << strv.size() << " UTF-16 code units: [ ";
    for (char16_t c : strv)
        std::cout << std::showbase << std::hex << static_cast<int>(c) << ' ';
    std::cout << "]\n";
    std::mbstate_t state{};
    char out[MB_LEN_MAX]{};
    for (char16_t c : strv)
    {
        std::size_t rc = std::c16rtomb(out, c, &state);
        std::cout << static_cast<int>(c) << " converted to [ ";
        if (rc != (std::size_t) - 1)
            for (unsigned char c8 : std::string_view{out, rc})
                std::cout << +c8 << ' ';
        std::cout << "]\n";
    }
}

Processing 5 UTF-16 code units: [ 0x7a 0xdf 0x6c34 0xd83c 0xdf4c ]
0x7a converted to [ 0x7a ]
0xdf converted to [ 0xc3 0x9f ]
0x6c34 converted to [ 0xe6 0xb0 0xb4 ]
0xd83c converted to [ ]
0xdf4c converted to [ 0xf0 0x9f 0x8d 0x8c ]

Véase también