c16rtomb

Convertit un point de code unique de sa représentation en caractères larges 16 bits à longueur variable (généralement, UTF-16) vers sa représentation en caractères multioctets étroits.

Si s n'est pas un pointeur nul et c16 est la dernière unité de code 16 bits dans un codage de longueur variable valide d'un point de code, la fonction détermine le nombre d'octets nécessaires pour stocker la représentation du caractère multioctet de ce point de code (en incluant toute séquence de changement, et en tenant compte de l'état actuel de conversion multioctet * ps ), et stocke la représentation du caractère multioctet dans le tableau de caractères dont le premier élément est pointé par s , mettant à jour * ps si nécessaire. Au maximum MB_CUR_MAX octets peuvent être écrits par cette fonction.

Si s est un pointeur nul, l'appel est équivalent à c16rtomb ( buf, u ' \0 ' , ps ) pour un tampon interne buf .

Si c16 est le caractère large nul u ' \0 ' , un octet nul est stocké, précédé par toute séquence de changement nécessaire pour restaurer l'état de changement initial et le paramètre d'état de conversion * ps est mis à jour pour représenter l'état de changement initial.

Si c16 n'est pas l'unité de code finale dans une représentation 16 bits d'un caractère étendu, il n'écrit pas dans le tableau pointé par s , seulement * ps est mis à jour.

Si la macro __STDC_UTF_16__ est définie, l'encodage 16 bits utilisé par cette fonction est UTF-16 ; sinon, il est défini par l'implémentation. La macro est toujours définie et l'encodage est toujours UTF-16. (depuis C23) Dans tous les cas, l'encodage des caractères multioctets utilisé par cette fonction est spécifié par les paramètres régionaux C actuellement actifs.

Paramètres

Valeur de retour

En cas de succès, retourne le nombre d'octets (incluant toute séquence de décalage) écrits dans le tableau de caractères dont le premier élément est pointé par s . Cette valeur peut être ​ 0 ​ , par exemple lors du traitement des unités char16_t initiales dans une séquence multi-unités char16_t (se produit lors du traitement de la première unité d'une paire de substitution en UTF-16).

En cas d'échec (si c16 n'est pas une unité de code 16-bit valide), retourne - 1 , stocke EILSEQ dans errno , et laisse * ps dans un état non spécifié.

Notes

En C11 tel que publié, contrairement à mbrtoc16 qui convertit des caractères multioctets à largeur variable (comme UTF-8) vers un encodage 16 bits à largeur variable (comme UTF-16), cette fonction ne peut convertir que des encodages 16 bits à unité unique, ce qui signifie qu'elle ne peut pas convertir UTF-16 vers UTF-8 malgré l'intention initiale de cette fonction. Ce problème a été corrigé par le rapport de défaut post-C11 DR488 .

Exemple

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

Références

Voir aussi