mbrtoc16

Convertit un point de code unique de sa représentation en caractère multioctet étroit vers sa représentation en caractère large 16 bits à longueur variable (généralement, UTF-16).

Si s n'est pas un pointeur nul, examine au plus n octets de la chaîne de caractères multioctets, en commençant par l'octet pointé par s pour déterminer le nombre d'octets nécessaires pour compléter le prochain caractère multioctet (en incluant toute séquence de changement, et en tenant compte de l'état actuel de conversion multioctet * ps ). Si la fonction détermine que le prochain caractère multioctet dans s est complet et valide, le convertit en caractère large 16 bits correspondant et le stocke dans * pc16 (si pc16 n'est pas nul).

Si le caractère multi-octet dans * s correspond à une séquence multi- char16_t (par exemple, une paire de substitution en UTF-16), alors après le premier appel à cette fonction, * ps est mis à jour de telle sorte que le prochain appel à mbrtoc16 écrira le char16_t supplémentaire, sans prendre en compte * s .

Si s est un pointeur nul, les valeurs de n et pc16 sont ignorées et l'appel est équivalent à mbrtoc16 ( NULL , "" , 1 , ps ) .

Si le caractère large produit est le caractère nul, l'état de conversion * ps représente l'état de décalage initial.

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

Le premier des éléments suivants qui s'applique :

• ​ 0 ​ si le caractère converti à partir de s (et stocké dans * pc16 s'il n'est pas nul) était le caractère nul.
• Le nombre d'octets [ 1 , n ] du caractère multi-octets converti avec succès à partir de s .
• ( size_t ) - 3 si le prochain char16_t d'un caractère multi- char16_t (par exemple une paire de substitution) a maintenant été écrit dans * pc16 . Aucun octet n'est traité en entrée dans ce cas.
• ( size_t ) - 2 si les prochains n octets constituent un caractère multi-octets incomplet, mais jusqu'ici valide. Rien n'est écrit dans * pc16 .
• ( size_t ) - 1 si une erreur d'encodage se produit. Rien n'est écrit dans * pc16 , la valeur EILSEQ est stockée dans errno et la valeur de * ps n'est pas spécifiée.

Exemple

#include <locale.h>
#include <stdio.h>
#include <uchar.h>
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char in[] = u8"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    enum { in_sz = sizeof in / sizeof *in };
    printf("Processing %d UTF-8 code units: [", in_sz);
    for (int n = 0; n < in_sz; ++n)
        printf("%s%02X", n ? " " : "", (unsigned char)in[n]);
    puts("]");
    char16_t out[in_sz];
    const char* p_in = in;
    const char* end = in + in_sz;
    char16_t* p_out = out;
    mbstate_t state = {0};
    for (size_t rc; (rc = mbrtoc16(p_out, p_in, end - p_in, &state));)
    {
        if (rc == (size_t)-1)     // invalid input
            break;
        else if(rc == (size_t)-2) // truncated input
            break;
        else if(rc == (size_t)-3) // UTF-16 high surrogate
            p_out += 1;
        else
        {
            p_in += rc;
            p_out += 1;
        };
    }
    const size_t out_sz = p_out - out + 1;
    printf("into %zu UTF-16 code units: [", out_sz);
    for (size_t x = 0; x < out_sz; ++x)
        printf("%s%04X", x ? " " : "", out[x]);
    puts("]");
}

Processing 11 UTF-8 code units: [7A C3 9F E6 B0 B4 F0 9F 8D 8C 00]
into 6 UTF-16 code units: [007A 00DF 6C34 D83C DF4C 0000]

Références

Voir aussi