`wcrtomb_s`

Articolo
10/12/2023

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

Sintassi

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

pReturnValue
Restituisce il numero di byte scritti o -1 se si è verificato un errore.

mbchar
Carattere multibyte convertito risultante.

sizeOfmbchar
Dimensioni della variabile mbchar in byte.

wchar
Carattere wide da convertire.

mbstate
Puntatore a un oggetto mbstate_t.

Valore restituito

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

Osservazioni:

La funzione wcrtomb_s converte un carattere wide, a partire dallo stato di conversione specificato contenuto in mbstate, dal valore contenuto in wchar, nell'indirizzo rappresentato da mbchar. Il valore pReturnValue sarà il numero di byte convertiti, ma non più di MB_CUR_MAX byte o -1 se si è verificato un errore.

Se mbstate è Null, viene usato lo stato di conversione interno mbstate_t. Se il carattere contenuto in wchar non ha un carattere multibyte corrispondente, il valore di pReturnValue è -1 e la funzione restituisce il errno valore di EILSEQ.

La wcrtomb_s funzione differisce da wctomb_s, _wctomb_s_l in base alla riavviibilità. Lo stato di conversione viene archiviato in mbstate per le chiamate successive alle stesse o ad altre funzioni riavviabili. I risultati non sono definiti quando si usano insieme funzioni riavviabili e non riavviabili. Ad esempio, un'applicazione deve usare wcsrlen anziché wcslen se viene usata una chiamata successiva a wcsrtombs_s invece di wcstombs_s.

In C++ l'uso di questa funzione è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento per le dimensioni) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Eccezioni

La funzione wcrtomb_s è multithread-safe a condizione che nessuna funzione nel thread corrente chiami 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");
    }
}

The corresponding wide character "Q" was converted to a the "Q" multibyte character.

Requisiti

Ciclo	Intestazione obbligatoria
`wcrtomb_s`	<wchar.h>

Vedi anche

Conversione dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
mbsinit

Condividi tramite