c16rtomb

Konvertiert einen einzelnen Codepunkt von seiner variablen 16-Bit Breitzeichen-Darstellung (typischerweise UTF-16) in seine schmale Multibyte-Zeichendarstellung.

Wenn s kein Nullzeiger ist und c16 die letzte 16-Bit-Codeeinheit in einer gültigen variablen Längenkodierung eines Codepoints ist, bestimmt die Funktion die Anzahl der Bytes, die notwendig sind, um die Multibyte-Zeichendarstellung dieses Codepoints zu speichern (einschließlich aller Shift-Sequenzen und unter Berücksichtigung des aktuellen Multibyte-Konvertierungszustands * ps ), und speichert die Multibyte-Zeichendarstellung im Zeichenarray, dessen erstes Element durch s gezeigt wird, wobei * ps bei Bedarf aktualisiert wird. Diese Funktion kann maximal MB_CUR_MAX Bytes schreiben.

Wenn s ein Nullzeiger ist, entspricht der Aufruf c16rtomb ( buf, u ' \0 ' , ps ) für einen internen Puffer buf .

Wenn c16 das breite Nullzeichen u ' \0 ' ist, wird ein Nullbyte gespeichert, vorangestellt von jeder Shift-Sequenz, die notwendig ist, um den initialen Shift-Zustand wiederherzustellen, und der Konvertierungszustandsparameter * ps wird aktualisiert, um den initialen Shift-Zustand darzustellen.

Wenn c16 nicht das letzte Codeelement in einer 16-Bit-Darstellung eines Breitzeichens ist, schreibt es nicht in das durch s adressierte Array, nur * ps wird aktualisiert.

Falls das Makro __STDC_UTF_16__ definiert ist, ist die von dieser Funktion verwendete 16-Bit-Kodierung UTF-16; andernfalls ist sie implementierungsdefiniert. Das Makro ist immer definiert und die Kodierung ist immer UTF-16. (seit C23) In jedem Fall wird die von dieser Funktion verwendete Multibyte-Zeichenkodierung durch das aktuell aktive C-Locale festgelegt.

Parameter

Rückgabewert

Bei Erfolg gibt die Anzahl der Bytes (einschließlich aller Shift-Sequenzen) zurück, die in das Zeichenarray geschrieben wurden, dessen erstes Element durch s gezeigt wird. Dieser Wert kann ​ 0 ​ sein, z.B. bei der Verarbeitung der führenden char16_t -Einheiten in einer Multi- char16_t -Unit-Sequenz (tritt bei der Verarbeitung des führenden Surrogats in einem Surrogatpaar von UTF-16 auf).

Bei Fehler (wenn c16 keine gültige 16-Bit-Codeeinheit ist), wird - 1 zurückgegeben, EILSEQ in errno gespeichert und * ps in einem nicht spezifizierten Zustand belassen.

Hinweise

In C11, wie veröffentlicht, im Gegensatz zu mbrtoc16 , das variable Breite Multibyte (wie UTF-8) in variable Breite 16-Bit (wie UTF-16) Kodierung konvertiert, kann diese Funktion nur Einheiten-16-Bit-Kodierung konvertieren, was bedeutet, dass sie UTF-16 nicht in UTF-8 konvertieren kann, obwohl dies die ursprüngliche Absicht dieser Funktion war. Dies wurde durch den nach-C11-Fehlerbericht DR488 korrigiert.

Beispiel

#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]

Referenzen

Siehe auch