wcrtomb_s

Articolo
03/05/2013

Convertire un carattere di tipo " wide " nella relativa rappresentazione di caratteri multibyte.una versione di wcrtomb con i 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 è verificato un errore.
[out] mbchar
il carattere convertito multibyte risultante.
[in] sizeOfmbchar
La dimensione di mbchar variabile in byte.
[in] wchar
Un carattere di tipo da convertire.
[in] mbstate
Un puntatore a un oggetto mbstate_t oggetto.

Valore restituito

Restituisce zero o errno valore se si verifica un errore.

Note

wcrtomb_s la funzione consente di convertire un carattere di tipo " wide ", a partire dallo stato specificato di conversione contenuto in mbstate, il valore contenuto in wchar, l'indirizzo rappresentato da mbchar.pReturnValue il valore sarà il numero di byte convertiti, ma non più di MB_CUR_MAX byte, oppure -1 se si è verificato un errore.

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

wcrtomb_s la funzione è diverso da wctomb_s, _wctomb_s_l dal restartability.Lo stato di conversione viene archiviato in mbstate per le chiamate successive agli stessi o ad altre funzioni restartable.I risultati vengono definiti quando si combinano l'utilizzo delle funzioni restartable e nonrestartable.Ad esempio, un'applicazione utilizzerebbe wcsrlen anziché wcslen, se una chiamata successiva a wcsrtombs_s sono stati utilizzati anziché wcstombs_s.

In C++, l'utilizzo di questa funzione viene semplificata dagli overload del modello; gli overload possono dedurre la lunghezza del buffer automaticamente (che elimina la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le più recenti, controparti sicure.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Eccezioni

wcrtomb_s la funzione è multithread-safe se nessuna funzione nelle chiamate del thread corrente setlocale 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");
    }
}