Namespaces
Variants

wcstombs, wcstombs_s

From cppreference.net
C
Strings library
Null-terminated multibyte strings
Défini dans l'en-tête <stdlib.h>
(1)
size_t wcstombs ( char * dst, const wchar_t * src, size_t len ) ;
(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 multioctet é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 caractères 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écalage (si nécessaire) suivie de ' \0 ' ,
* Un wchar_t a été trouvé qui ne correspond pas à un caractère valide dans les paramètres régionaux C actuels.
* Le prochain caractère multioctet à stocker dépasserait len .
Si src et dst se chevauchent, le comportement n'est pas spécifié.
2) Identique à (1) , sauf que
* la conversion est effectuée comme par wcrtomb , et non par wctomb
* la fonction retourne son résultat en tant que 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 de dst , qui peut être dst[len] ou dst[dstsz] , selon celui qui vient en premier (ce qui signifie que jusqu'à len+1/dstsz+1 octets au total peuvent être écrits). Dans ce cas, il se peut qu'aucune séquence de décalage ne soit é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 à partir du caractère nul de fin et jusqu'à dstsz
* Si src et dst se chevauchent, le comportement n'est pas spécifié.
* les erreurs suivantes sont détectées à l'exécution et appellent la fonction gestionnaire de contraintes 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 avant d'atteindre dstsz (sauf si dst est nul)
Comme pour toutes les fonctions à vérification de limites, 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__ à la constante entière 1 avant d'inclure <stdlib.h> .

Table des matières

Notes

Dans la plupart des implémentations, wcstombs met à jour un objet statique global de type mbstate_t pendant le traitement de la chaîne, et ne peut pas être appelée simultanément par deux threads, wcsrtombs ou wcstombs_s devrait être utilisée 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 , s'ils étaient convertis. 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 un caractère nul à convertir
len - nombre d'octets disponibles dans le tableau pointé par dst
dstsz - nombre maximum 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 (incluant les séquences de décalage, mais excluant le caractère de fin ' \0 ' ) é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 (auquel cas le nombre d'octets, à l'exclusion du zéro terminal, qui ont été ou seraient écrits dans dst , est stocké dans * retval ), non-zéro 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 dstmax est zéro ou supérieur à RSIZE_MAX )

Exemple

Exécuter ce code 
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
int main(void)
{
    // 4 caractères larges
    const wchar_t src[] = L"z\u00df\u6c34\U0001f34c";
    // ils occupent 10 octets en 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 C11 (ISO/CEI 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/CEI 9899:1999) :
  • 7.20.8.2 La fonction wcstombs (p: 324)
  • Norme C89/C90 (ISO/CEI 9899:1990) :
  • 4.10.8.2 La fonction wcstombs

Voir aussi

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