wcstombs, _wcstombs_l

Convertit une séquence de caractères larges en une séquence correspondante de caractères multioctets. Des versions plus sécurisées de ces fonctions sont disponibles ; voir wcstombs_s, _wcstombs_s_l.

Syntaxe

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Paramètres

mbstr
Adresse d’une séquence de caractères multioctets.

wcstr
Adresse d’une séquence de caractères larges.

count
Nombre maximal d’octets pouvant être stockés dans la chaîne de sortie multioctet.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Si la fonction wcstombs convertit correctement la chaîne multioctet, elle retourne le nombre d’octets écrits dans la chaîne de sortie multioctet, à l’exclusion du caractère NULL de fin (le cas échéant). Si l’argument mbstr a la valeur NULL, wcstombs retourne la taille requise de la chaîne de destination en octets. Si wcstombs vous rencontrez un caractère large, il ne peut pas convertir en caractère multioctet, il retourne -1 cast en type size_t et définit errno sur EILSEQ.

Notes

La fonction wcstombs convertit la chaîne de caractères larges vers laquelle pointe wcstr en caractères multioctets correspondants et stocke les résultats dans le tableau mbstr. Le paramètre count indique le nombre maximal d’octets qui peuvent être stockés dans la chaîne de sortie multioctet (c’est-à-dire, la taille de mbstr). En général, il n’est pas connu le nombre d’octets requis lors de la conversion d’une chaîne à caractères larges. Certains caractères larges ne nécessitent qu’un seul octet dans la chaîne de sortie ; d’autres nécessitent 2 octets. S’il existe 2 octets dans la chaîne de sortie multioctet pour chaque caractère large de la chaîne d’entrée (y compris le caractère NULLlarge), le résultat est garanti.

À compter de Windows 10 version 1803 (10.0.17134.0), le runtime C universel prend en charge l’utilisation d’une page de codes UTF-8. Permet wcstombs(NULL, wcstr, 0) d’obtenir la taille correcte dont vous aurez besoin pour la conversion, car en supposant que vous aurez besoin de deux octets pour chaque caractère large peut ne pas suffire. Pour plus d’informations sur la prise en charge de UTF-8, consultez la prise en charge de UTF-8

Si wcstombs le caractère NULL large (L'\0') se produit avant ou lorsqu’il count se produit, il le convertit en 8 bits 0 et s’arrête. Ainsi, la chaîne de caractères multioctets est mbstr terminée par null uniquement si wcstombs elle rencontre un caractère NULL large lors de la conversion. Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement de wcstombs n'est pas défini.

Si l’argument mbstr a la valeur NULL, wcstombs retourne la taille requise de la chaîne de destination en octets.

wcstombs valide ses paramètres. Si wcstr elle est NULLsupérieure ou countINT_MAXsupérieure, cette fonction appelle le gestionnaire de paramètres non valide, comme décrit dans la validation des paramètres. Si l’exécution est autorisée à se poursuivre, la fonction affecte à errno la valeur EINVAL et retourne -1.

La fonction wcstombs utilise les paramètres régionaux actuels pour tout comportement dépendant des paramètres régionaux ; la fonction _wcstombs_l est identique, à ceci près qu’elle utilise à la place les paramètres régionaux qui ont été passés. Pour plus d’informations, consultez Locale.

En C++, ces fonctions ont des surcharges de modèle qui appellent les équivalents plus récents et sécurisés de ces fonctions. Pour plus d’informations, consultez Surcharges de modèles sécurisés.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Spécifications

Routine	En-tête requis
wcstombs	<stdlib.h>
_wcstombs_l	<stdlib.h>

Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

Ce programme illustre le comportement de la fonction wcstombs.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Voir aussi

Conversion de données
Paramètres régionaux
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte