Namespaces
Variants

    wcstombs, wcstombs_s

    Depuis fr.cppreference.net
     
    C
     
    Bibliothèque de chaînes
     
    Chaînes multi-octets terminées par null
     
    Défini dans l'en-tête <stdlib.h> 
    size_t wcstombs( char* dst, const wchar_t* src, size_t len );
    		(1) (jusqu'à C99) 
    size_t wcstombs( char* restrict dst, const wchar_t* restrict src, size_t len );
    		(depuis C99) 
    errno_t wcstombs_s( size_t* restrict retval, char* restrict dst, rsize_t dstsz,
                    const wchar_t* restrict src, rsize_t len );
    		(2) (depuis C11)
    1) Convertit une séquence de caractères larges du tableau dont le premier élément est pointé par src en sa représentation multi-octets étroite qui commence dans l'état de décalage initial. Les caractères convertis sont stockés dans les éléments successifs du tableau de char pointé par dst. Pas plus de len octets sont écrits dans le tableau de destination.
    Chaque caractère est converti comme par un appel à wctomb, sauf que l'état de conversion de wctomb n'est pas affecté. La conversion s'arrête si :
    • Le caractère nul L'\0' a été converti et stocké. Les octets stockés dans ce cas sont la séquence de désynchronisation (si nécessaire) suivie de '\0',
    • A wchar_t a été trouvé qui ne correspond pas à un caractère valide dans la locale C actuelle.
    • Le prochain caractère multi-octets à stocker dépasserait len.
    Si src et dst se chevauchent, le comportement est indéfini.
    2) Identique à (1), sauf que
    • la conversion est comme par wcrtomb, pas wctomb
    • la fonction retourne son résultat comme un paramètre de sortie retval
    • si la conversion s'arrête sans écrire un caractère nul, la fonction stockera '\0' dans l'octet suivant dans dst, qui peut être dst[len] ou dst[dstsz], selon ce qui vient en premier (ce qui signifie jusqu'à len+1/dstsz+1 octets totaux peuvent être écrits). Dans ce cas, il peut n'y avoir aucune séquence de désynchronisation écrite avant le caractère nul de terminaison.
    • si dst est un pointeur nul, le nombre d'octets qui seraient produits est stocké dans *retval
    • la fonction écrase le tableau de destination depuis le caractère nul de terminaison et jusqu'à dstsz
    • Si src et dst se chevauchent, le comportement est indéfini.
    • les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contrainte actuellement installée :
    • retval ou src est un pointeur nul
    • dstsz ou len est supérieur à RSIZE_MAX (sauf si dst est nul)
    • dstsz n'est pas zéro (sauf si dst est nul)
    • len est supérieur à dstsz et la conversion ne rencontre pas de caractère nul ou d'erreur d'encodage dans le tableau src au moment où dstsz est atteint (sauf si dst est nul)
    Comme pour toutes les fonctions avec vérification des bornes, wcstombs_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 <stdlib.h>.

    Notes

    Dans la plupart des implémentations, wcstombs met à jour un objet statique global de type mbstate_t en parcourant la chaîne, et ne peut pas être appelé simultanément par deux threads, wcsrtombs ou wcstombs_s doivent être utilisés dans de tels cas.

    POSIX spécifie une extension courante : si dst est un pointeur nul, cette fonction retourne le nombre d'octets qui seraient écrits dans dst, si converti. Un comportement similaire est standard pour wcsrtombs et wcstombs_s.

    Paramètres

    dst - pointeur vers le tableau de caractères étroits où le caractère multi-octets sera stocké
    src - pointeur vers le premier élément d'une chaîne large terminée par null à convertir
    len - nombre d'octets disponibles dans le tableau pointé par dst
    dstsz - nombre maximal d'octets qui seront écrits (taille du tableau dst)
    retval - pointeur vers un objet size_t où le résultat sera stocké

    Valeur de retour

    1) En cas de succès, retourne le nombre d'octets (y compris les éventuelles séquences de décalage, mais excluant le '\0' de terminaison) écrits dans le tableau de caractères dont le premier élément est pointé par dst. En cas d'erreur de conversion (si un caractère large invalide a été rencontré), retourne (size_t)-1.
    2) Retourne zéro en cas de succès (dans ce cas le nombre d'octets excluant le zéro de terminaison qui ont été ou auraient été écrits dans dst, est stocké dans *retval), non nul en cas d'erreur. En cas de violation de contrainte d'exécution, stocke (size_t)-1 dans *retval (sauf si retval est nul) et définit dst[0] à '\0' (sauf si dst est nul ou si dstmax est zéro ou supérieur à RSIZE_MAX)

    Exemple

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

int main(void)
{
    // 4 wide characters
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // they occupy 10 bytes in UTF-8
    char dst[11];

    setlocale(LC_ALL, "en_US.utf8");
    printf("wide-character string: '%ls'\n",src);
    for (size_t ndx = 0; ndx < sizeof src / sizeof src[0]; ++ndx)
        printf("   src[%2zu] = %#8x\n", ndx, src[ndx]);
    
    int rtn_val = wcstombs(dst, src, sizeof dst);
    printf("rtn_val = %d\n", rtn_val);
    if (rtn_val > 0)
        printf("multibyte string:  '%s'\n",dst);
    for (size_t ndx = 0; ndx < sizeof dst; ++ndx)
        printf("   dst[%2zu] = %#2x\n", ndx, (unsigned char)dst[ndx]);
}

    Sortie : 

    wide-character string: 'zß水🍌'
   src[ 0] =     0x7a
   src[ 1] =     0xdf
   src[ 2] =   0x6c34
   src[ 3] =  0x1f34c
   src[ 4] =        0
rtn_val = 10
multibyte string:  'zß水🍌'
   dst[ 0] = 0x7a
   dst[ 1] = 0xc3
   dst[ 2] = 0x9f
   dst[ 3] = 0xe6
   dst[ 4] = 0xb0
   dst[ 5] = 0xb4
   dst[ 6] = 0xf0
   dst[ 7] = 0x9f
   dst[ 8] = 0x8d
   dst[ 9] = 0x8c
   dst[10] =  0

    Références

    • Norme C23 (ISO/IEC 9899:2024) :
    • 7.22.8.2 La fonction wcstombs (p: TBD)
    • K.3.6.5.2 La fonction wcstombs_s (p: TBD)
    • Norme C17 (ISO/IEC 9899:2018) :
    • 7.22.8.2 La fonction wcstombs (p: TBD)
    • K.3.6.5.2 La fonction wcstombs_s (p: TBD)
    • Norme C11 (ISO/IEC 9899:2011) :
    • 7.22.8.2 La fonction wcstombs (p: 360)
    • K.3.6.5.2 La fonction wcstombs_s (p: 612-614)
    • Norme C99 (ISO/IEC 9899:1999) :
    • 7.20.8.2 La fonction wcstombs (p: 324)
    • Norme C89/C90 (ISO/IEC 9899:1990) :
    • 4.10.8.2 La fonction wcstombs

    Voir aussi

    (C95)(C11)
    		 convertit une chaîne large en chaîne de caractères multi-octets étroite, avec état donné
    (fonction)
    (C11)
    		 convertit une chaîne de caractères multi-octets étroite en chaîne large
    (fonction)
    Documentation C++ pour wcstombs