Namespaces
Variants

wctomb, wctomb_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Défini dans l'en-tête <stdlib.h>
int wctomb ( char * s, wchar_t wc ) ;
(1)
errno_t wctomb_s ( int * restrict status, char * restrict s, rsize_t ssz, wchar_t wc ) ;
(2) (depuis C11)
1) Convertit un caractère large wc en encodage multioctet et le stocke (y compris toute séquence de changement) dans le tableau de caractères dont le premier élément est pointé par s . Pas plus de MB_CUR_MAX caractères sont stockés. La conversion est affectée par la catégorie LC_CTYPE des paramètres régionaux actuels.
Si wc est le caractère nul, l'octet nul est écrit dans s , précédé de toute séquence de changement nécessaire pour restaurer l'état de changement initial.
Si s est un pointeur nul, cette fonction réinitialise l'état de conversion global et détermine si les séquences de décalage sont utilisées.
2) Identique à (1) , sauf que le résultat est retourné dans le paramètre de sortie status et les erreurs suivantes sont détectées à l'exécution et appellent la fonction constraint handler actuellement installée :
  • ssz est inférieur au nombre d'octets qui seraient écrits (sauf si s est null)
  • ssz est supérieur à RSIZE_MAX (sauf si s est null)
  • s est un pointeur null mais ssz n'est pas zéro
Comme pour toutes les fonctions à vérification de limites, wctomb_s est uniquement garantie d'être disponible 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 <stdlib.h> .

Table des matières

Notes

Chaque appel à wctomb met à jour l'état de conversion global interne (un objet statique de type mbstate_t , connu uniquement de cette fonction). Si l'encodage multioctet utilise des états de changement, cette fonction n'est pas réentrante. Dans tous les cas, plusieurs threads ne devraient pas appeler wctomb sans synchronisation : wcrtomb ou wctomb_s peuvent être utilisés à la place.

Contrairement à la plupart des fonctions avec vérification des limites, wctomb_s ne termine pas sa sortie par un caractère nul, car elle est conçue pour être utilisée dans des boucles qui traitent les chaînes caractère par caractère.

Paramètres

s - pointeur vers le tableau de caractères pour la sortie
wc - caractère large à convertir
ssz - nombre maximum d'octets à écrire dans s (taille du tableau s )
status - pointeur vers un paramètre de sortie où le résultat (longueur de la séquence multioctet ou statut de la séquence de décalage) sera stocké

Valeur de retour

1) Si s n'est pas un pointeur nul, retourne le nombre d'octets contenus dans la représentation multioctet de wc ou - 1 si wc n'est pas un caractère valide.
Si s est un pointeur nul, réinitialise son état de conversion interne pour représenter l'état de décalage initial et retourne ​ 0 ​ si l'encodage multioctet actuel n'est pas dépendant de l'état (n'utilise pas de séquences de décalage) ou une valeur non nulle si l'encodage multioctet actuel est dépendant de l'état (utilise des séquences de décalage).
2) zéro en cas de succès, auquel cas la représentation multi-octets de wc est stockée dans s et sa longueur est stockée dans * status , ou, si s est nul, l'état de la séquence de décalage est stocké dans status ). Non-zéro en cas d'erreur d'encodage ou de violation de contrainte d'exécution, auquel cas ( size_t ) - 1 est stocké dans * status . La valeur stockée dans * status ne dépasse jamais MB_CUR_MAX

Exemple

Exécuter ce code 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
void demo(wchar_t wc)
{
    const char* dep = wctomb(NULL, wc) ? "Yes" : "No";
    printf("State-dependent encoding? %s.\n", dep);
    char mb[MB_CUR_MAX];
    int len = wctomb(mb, wc);
    printf("wide char '%lc' -> multibyte char [", wc);
    for (int idx = 0; idx < len; ++idx)
        printf("%s%#2x", idx ? " " : "", (unsigned char)mb[idx]);
    printf("]\n");
}
int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    printf("MB_CUR_MAX = %zu\n", MB_CUR_MAX);
    demo(L'A');
    demo(L'\u00df');
    demo(L'\U0001d10b');
}

Sortie possible : 

MB_CUR_MAX = 6
State-dependent encoding? No.
wide char 'A' -> multibyte char [0x41]
State-dependent encoding? No.
wide char 'ß' -> multibyte char [0xc3 0x9f]
State-dependent encoding? No.
wide char '𝄋' -> multibyte char [0xf0 0x9d 0x84 0x8b]

Références

  • Norme C17 (ISO/CEI 9899:2018) :
  • 7.22.7.3 La fonction wctomb (p: 261)
  • K.3.6.4.1 La fonction wctomb_s (p: 443)
  • Norme C11 (ISO/IEC 9899:2011):
  • 7.22.7.3 La fonction wctomb (p: 358-359)
  • K.3.6.4.1 La fonction wctomb_s (p: 610-611)
  • Norme C99 (ISO/CEI 9899:1999) :
  • 7.20.7.3 La fonction wctomb (p: 322-323)
  • Norme C89/C90 (ISO/IEC 9899:1990) :
  • 4.10.7.3 La fonction wctomb

Voir aussi

convertit le caractère multioctet suivant en caractère large
(fonction)
(C95) (C11)
convertit un caractère large en sa représentation multioctet, avec état donné
(fonction)
Documentation C++ pour wctomb