Namespaces
Variants

    wcrtomb, wcrtomb_s

    Depuis fr.cppreference.net
     
    C
     
    Bibliothèque de chaînes
     
    Chaînes multioctets terminées par zéro
     
    Défini dans l'en-tête <wchar.h> 
    size_t wcrtomb( char* s, wchar_t wc, mbstate_t* ps);
    		(1) (depuis C95)
    (jusqu'à C99)    		 
    size_t wcrtomb( char* restrict s, wchar_t wc, mbstate_t* restrict ps);
    		(depuis C99) 
    errno_t wcrtomb_s(size_t* restrict retval, char* restrict s, rsize_t ssz,
                  wchar_t wc, mbstate_t* restrict ps);
    		(2) (depuis C11)

    Convertit un caractère large en sa représentation multioctet étroite.

    1) Si s n'est pas un pointeur nul, la fonction détermine le nombre d'octets nécessaires pour stocker la représentation multioctet de wc (y compris les éventuelles séquences de décalage, et en tenant compte de l'état de conversion multioctet actuel *ps), et stocke la représentation multioctet dans le tableau de caractères dont le premier élément est pointé par s, en 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 à wcrtomb(buf, L'\0', ps) pour un tampon interne buf.
    Si wc est le caractère large nul L'\0', un octet nul est stocké, précédé de toute séquence de décalage nécessaire pour restaurer l'état de décalage initial et le paramètre d'état de conversion *ps est mis à jour pour représenter l'état de décalage initial.
    Si la macro d'environnement __STDC_ISO_10646__ est définie, les valeurs de type wchar_t sont les mêmes que les identifiants courts des caractères dans l'ensemble requis Unicode (généralement encodage UTF-32) ; sinon, c'est défini par l'implémentation. Dans tous les cas, l'encodage de caractères multioctets utilisé par cette fonction est spécifié par la locale C actuellement active.
    2) Identique à (1), sauf que
    si s est un pointeur nul, l'appel est équivalent à wcrtomb_s(&retval, buf, sizeof buf, L'\0', ps) avec des variables internes retval et buf (dont la taille est supérieure à MB_CUR_MAX)
    le résultat est retourné dans le paramètre de sortie retval
    les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contrainte actuellement installée :
    • retval ou ps est un pointeur nul.
    • ssz est zéro ou supérieur à RSIZE_MAX (sauf si s est nul)
    • ssz est inférieur au nombre d'octets qui seraient écrits (sauf si s est nul)
    • s est un pointeur nul mais ssz n'est pas zéro
    Comme toutes les fonctions avec vérification des limites, wcrtomb_s n'est garantie d'être disponible que si __STDC_LIB_EXT1__ est défini par l'implémentation et si l'utilisateur définit __STDC_WANT_LIB_EXT1__ comme la constante entière 1 avant d'inclure <wchar.h>.

    Paramètres

    s - pointeur vers le tableau de caractères étroits où le caractère multioctet sera stocké
    wc - le caractère large à convertir
    ps - pointeur vers l'objet d'état de conversion utilisé lors de l'interprétation de la chaîne multioctet
    ssz - nombre maximal d'octets à écrire (taille du tampon s)
    retval - pointeur vers un paramètre de sortie où le résultat (nombre d'octets dans la chaîne multioctet y compris les séquences de décalage) sera stocké

    Valeur de retour

    1) En cas de succès, retourne le nombre d'octets (y compris les séquences de décalage) écrits dans le tableau de caractères dont le premier élément est pointé par s.
    En cas d'échec (si wc n'est pas un caractère large valide), retourne (size_t)-1, stocke EILSEQ dans errno, et laisse *ps dans un état non spécifié.
    2) Retourne zéro en cas de succès et non nul en cas d'échec, auquel cas s[0] est mis à '\0' (sauf si s est nul ou ssz est zéro ou supérieur à RSIZE_MAX) et *retval est mis à (size_t)-1 (sauf si retval est nul)

    Exemple

    Exécuter ce code
    #include <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    mbstate_t state;
    memset(&state, 0, sizeof state);
    wchar_t in[] = L"zß水🍌"; // or "z\u00df\u6c34\U0001F34C"
    size_t in_sz = sizeof in / sizeof *in;
 
    printf("Processing %zu wchar_t units: [ ", in_sz);
    for (size_t n = 0; n < in_sz; ++n)
        printf("%#x ", (unsigned int)in[n]);
    puts("]");
 
    char out[MB_CUR_MAX * in_sz];
    char* p = out;
    for (size_t n = 0; n < in_sz; ++n)
    {
        int rc = wcrtomb(p, in[n], &state);
        if (rc == -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("%#x ", +(unsigned char)out[x]);
    puts("]");
}

    Sortie : 

    Processing 5 wchar_t units: [ 0x7a 0xdf 0x6c34 0x1f34c 0 ]
into 11 UTF-8 code units: [ 0x7a 0xc3 0x9f 0xe6 0xb0 0xb4 0xf0 0x9f 0x8d 0x8c 0 ]

    Références

    • Norme C23 (ISO/IEC 9899:2024) :
    • 7.29.6.3.3 La fonction wcrtomb (p: TBD)
    • K.3.9.3.1.1 La fonction wcrtomb_s (p: TBD)
    • Norme C17 (ISO/IEC 9899:2018) :
    • 7.29.6.3.3 La fonction wcrtomb (p: TBD)
    • K.3.9.3.1.1 La fonction wcrtomb_s (p: TBD)
    • Norme C11 (ISO/IEC 9899:2011) :
    • 7.29.6.3.3 La fonction wcrtomb (p: 444)
    • K.3.9.3.1.1 La fonction wcrtomb_s (p: 647-648)
    • Norme C99 (ISO/IEC 9899:1999) :
    • 7.24.6.3.3 La fonction wcrtomb (p: 390)

    Voir aussi

    (C11)
    		 convertit un caractère large en sa représentation multioctet
    (fonction)
    (C95)
    		 convertit le caractère multioctet suivant en caractère large, en tenant compte de l'état
    (fonction)
    Documentation C++ pour wcrtomb