wcrtomb

Article
03/04/2013

Convertissez un caractère élargi en sa représentation de caractères multioctets.un plus version sécurisée de cette fonction est disponible ; consultez wcrtomb_s.

size_t wcrtomb(
   char *mbchar,
   wchar_t wchar,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcrtomb(
   char (&mbchar)[size],
   wchar_t wchar,
   mbstate_t *mbstate
); // C++ only

Paramètres

[out] mbchar
Le caractère converti multioctets résultant.
[in] wchar
Un caractère élargi à convertir.
[in] mbstate
Un pointeur vers un objet d' mbstate_t .

Valeur de retour

Retourne le nombre d'octets requis pour représenter le caractère multioctets, sinon l'une valeur convertis si une erreur se produit.

Notes

La fonction d' wcrtomb convertit un caractère élargi, en commençant dans le rapport de conversion spécifié contenu dans mbstate, la valeur contenue dans wchar, dans l'adresse représentée par mbchar.La valeur de retour est le nombre d'octets requis pour représenter le caractère multioctets correspondant, mais elle ne retourne pas plus que les octets d' MB_CUR_MAX .

Si mbstate est null, l'objet interne d' mbstate_t contenant le rapport de conversion d' mbchar 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.

la fonction d' wcrtomb diffère de wctomb, _wctomb_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.

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' wcrtomb est multithread-safe tant qu'aucune fonction dans le thread actuel n'appelle setlocale bien que cette fonction s'exécute et pendant qu' mbstate est null.

Exemple

// crt_wcrtomb.c
// compile with: /W3
// This program converts a wide character
// to its corresponding multibyte character.

#include <string.h>
#include <stdio.h>
#include <wchar.h>

int main( void )
{
    size_t      sizeOfCovertion = 0;
    mbstate_t   mbstate;
    char        mbStr = 0;
    wchar_t*    wcStr = L"Q";

    // Reset to initial conversion state
    memset(&mbstate, 0, sizeof(mbstate));

    sizeOfCovertion = wcrtomb(&mbStr, *wcStr, &mbstate); // C4996
    // Note: wcrtomb is deprecated; consider using wcrtomb_s instead
    if (sizeOfCovertion > 0)
    {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wcStr);
        printf(" was converted to the \"%c\" ", mbStr);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}