Namespaces
Variants

wcrtomb, wcrtomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Défini dans l'en-tête <wchar.h>
(1)
size_t wcrtomb ( char * s, wchar_t wc, mbstate_t * ps ) ;
(depuis C95)
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 du caractère multi-octets de wc (en incluant toute séquence de changement, et en prenant en compte l'état actuel de conversion multi-octets * ps ), et stocke la représentation du caractère multi-octets 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 à 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é 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 la macro d'environnement __STDC_ISO_10646__ est définie, les valeurs du type wchar_t sont identiques aux identifiants courts des caractères dans le jeu requis par Unicode (généralement l'encodage UTF-32) ; sinon, cela est défini par l'implémentation. Dans tous les cas, l'encodage des caractères multi-octets utilisé par cette fonction est spécifié par les paramètres régionaux C actuellement actifs.
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 les 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 contraintes 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 pour toutes les fonctions à vérification de 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__ à la constante entière 1 avant d'inclure <wchar.h> .

Table des matières

Paramètres

s - pointeur vers un tableau de caractères étroits où le caractère multi-octets 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 multi-octets
ssz - nombre maximum d'octets à écrire (la taille du tampon s )
retval - pointeur vers un paramètre de sortie où le résultat (nombre d'octets dans la chaîne multi-octets incluant les séquences de changement) sera stocké

Valeur de retour

1) En cas de succès, retourne le nombre d'octets (y compris toute séquence 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 une valeur non nulle en cas d'échec, auquel cas, s [ 0 ] est défini à ' \0 ' (sauf si s est nul ou ssz est zéro ou supérieur à RSIZE_MAX ) et * retval est défini à ( size_t ) - 1 (sauf si retval est nul)

Exemple

Exécuter ce code 
#include <stdio.h>
#include <locale.h>
#include <string.h>
#include <wchar.h>
#include <stdlib.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 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 prochain caractère multioctet en caractère large, avec état
(fonction)
Documentation C++ pour wcrtomb