wcsrtombs

Article
03/04/2013

Convertit une chaîne à caractères larges à sa représentation de chaîne à caractères multioctets.un plus version sécurisée de cette fonction est disponible ; consultez wcsrtombs_s.

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Paramètres

[out] mbstr
L'emplacement de l'adresse de la chaîne à caractères multioctets convertie résultante.
[in] wcstr
Indirectement pointe vers l'emplacement de la chaîne à caractères larges à convertir.
[in] count
Le nombre de caractères à convertir.
[in] mbstate
Un pointeur vers un objet du rapport de conversion d' mbstate_t .

Valeur de retour

Retourne le nombre d'octets avec succès convertis, sans null et l'octet null (le cas échéant), sinon l'si une erreur s'est produite.

Notes

La fonction d' wcsrtombs convertit une chaîne de caractères larges, en commençant dans le rapport de conversion spécifié contenu dans mbstate, de l'aigu indirect de valeurs à dans wcstr, dans l'adresse d' mbstr.La conversion continuera pour chaque caractère until : après que la valeur null de fin le caractère élargi est produit, lorsqu'un caractère non-concordant est produit ou lorsque le caractère suivant dépasse la limite contenue dans count.Si wcsrtombs rencontre le caractère NULL à caractères larges (L \ 0 ') ou avant ou lorsque count se produit, il convertit en 0 de 8 bits et s'arrête.

Ainsi, la chaîne à caractères multioctets à l'adresse mbstr se terminant par null uniquement si wcsrtombs rencontre un caractère Null de caractère élargi pendant la conversion.Si les séquences pointées par wcstr et mbstr se chevauchent, le comportement d' wcsrtombs n'est pas défini.wcsrtombs est affectée par la catégorie de LC_TYPE des paramètres régionaux.

la fonction d' wcsrtombs diffère de wcstombs, _wcstombs_l par sa capacité à redémarrer.Le rapport de conversion est stocké dans mbstate pour les appels suivants à la même transparence ou à d'autres fonctions restartable.Les résultats sont indéfinis en combinant l'utilisation des fonctions restartable et nonrestartable.Par exemple, une application utilise wcsrlen plutôt qu' wcsnlen, si un appel suivant à wcsrtombs étaient utilisés au lieu d' wcstombs.

Si l'argument d' mbstr est NULL, wcsrtombs retourne la taille requise en octets de la chaîne de destination.Si mbstate est null, le rapport de conversion interne d' mbstate_t est utilisé.Si la séquence de caractères wchar n'a pas de représentation correspondante de caractères multioctets, une valeur est retournée par et errno est défini à EILSEQ.

En C++, cette fonction a une surcharge de modèle qui appelle les homologues plus récentes et sécurisées de cette fonction.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

Exceptions

La fonction d' wcsrtombs est multithread-safe tant qu'aucune fonction dans le thread actuel n'appelle setlocale bien que cette fonction s'exécute et mbstate n'est pas null.

Exemple

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] = 
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else 
    {
        printf( "The string was successfuly converted.\n" );
    }
}