wcrtomb

Articolo
06/09/2015

Converte un carattere wide nella relativa rappresentazione di caratteri multibyte. È disponibile una versione più sicura di questa funzione; vedere 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

Parametri

[out] mbchar
Il carattere convertito multibyte risultante.
[in] wchar
Un carattere wide da convertire
[in] mbstate
Un puntatore ad un oggetto mbstate_t.

Valore restituito

Restituisce il numero di byte necessari per rappresentare il carattere multibyte convertito, altrimenti un -1 se si verifica un errore.

Note

La funzione wcrtomb converte un carattere wide, a partire dallo stato specificato di conversione contenuto in mbstate, dal valore contenuto in wchar, nell'indirizzo rappresentato da mbchar. Il valore restituito è il numero di byte necessari per rappresentare il carattere multibyte corrispondente, ma non restituirà più byte di MB_CUR_MAX.

Se mbstate è null, viene utilizzato l'oggetto interno mbstate_t contenente lo stato di conversione di mbchar. Se la sequenza di caratteri wchar non dispone di una rappresentazione di caratteri multibyte corrispondente, viene restituito un -1 e errno viene impostato a EILSEQ.

La funzione wcrtomb differisce da wctomb, _wctomb_l dalla sua possibilità di essere avviata nuovamente. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alla stessa o ad altre funzioni avviabili nuovamente. I risultati non sono definiti quando si combina l'utilizzo delle funzioni avviabili nuovamente e non avviabili nuovamente. Ad esempio, un'applicazione utilizzerebbe wcsrlen anziché wcsnlen, se è stata utilizzata una chiamata successiva a wcsrtombs al posto di wcstombs.

In C++, questa funzione presenta un overload del modello che invoca le relative controparti sicure e più recenti. Per ulteriori informazioni, vedere Overload di modelli sicuri.

Eccezioni

La funzione wcrtomb è multithread-safe mentre nessuna funzione nella thread corrente chiama setlocale mentre questa funzione è in esecuzione e mbstate è null.

Esempio

// 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");
    }
}