wcrtomb_s

Articolo
06/09/2015

Converte un carattere wide nella relativa rappresentazione di caratteri multibyte. Una versione di wcrtomb con miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

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

Parametri

[out] pReturnValue
Restituisce il numero di byte scritti o -1 se si verifica un errore.
[out] mbchar
Il carattere convertito multibyte risultante.
[in] sizeOfmbchar
La dimensione della variabile mbchar in byte.
[in] wchar
Un carattere wide da convertire
[in] mbstate
Un puntatore ad un oggetto mbstate_t.

Valore restituito

Restituisce zero o un valore di errno se si verifica un errore.

Note

La funzione wcrtomb_s 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 di pReturnValue sarà il numero di byte convertito, ma non più dei byte di MB_CUR_MAX, oppure -1 se si è verificato un errore.

Se mbstate è null, viene utilizzato lo stato interno di conversione di mbstate_t. Se il carattere contenuto in wchar non dispone di un carattere multibyte corrispondente, il valore di pReturnValue sarà -1 e la funzione restituirà il valore di errno di EILSEQ.

La funzione wcrtomb_s differisce da wctomb_s, _wctomb_s_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é wcslen, se è stata utilizzata una chiamata successiva a wcsrtombs_s al posto di wcstombs_s.

In C++ l'utilizzo di questa funzione è semplificato dagli overload dei modelli; gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure. Per ulteriori informazioni, vedere Overload di modelli sicuri.

Eccezioni

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

Esempio

// crt_wcrtomb_s.c
// This program converts a wide character
// to its corresponding multibyte character.
//

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

int main( void )
{
    errno_t     returnValue;
    size_t      pReturnValue;
    mbstate_t   mbstate;
    size_t      sizeOfmbStr = 1;
    char        mbchar = 0;
    wchar_t*    wchar = L"Q\0";

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

    returnValue = wcrtomb_s(&pReturnValue, &mbchar, sizeof(char),
                            *wchar, &mbstate);
    if (returnValue == 0) {
        printf("The corresponding wide character \"");
        wprintf(L"%s\"", wchar);
        printf(" was converted to a the \"%c\" ", mbchar);
        printf("multibyte character.\n");
    }
    else
    {
        printf("No corresponding multibyte character "
               "was found.\n");
    }
}