wcsrtombs

Converte una stringa di caratteri wide nella relativa rappresentazione di stringa di caratteri multibyte. È disponibile una versione più sicura di questa funzione; vedere wcsrtombs_s.

Sintassi

size_t wcsrtombs(
   char *mbstr,
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
   char (&mbstr)[size],
   const wchar_t **wcstr,
   sizeof count,
   mbstate_t *mbstate
); // C++ only

Parametri

mbstr
Posizione dell'indirizzo della stringa di caratteri multibyte convertita risultante.

wcstr
Punta indirettamente alla posizione della stringa di caratteri wide da convertire.

count
Numero di caratteri da convertire.

mbstate
Puntatore a un oggetto stato di conversione mbstate_t.

Valore restituito

Restituisce il numero di byte convertito correttamente, escluso il byte di terminazione Null, se presente. In caso contrario restituisce -1 se si verifica un errore.

Osservazioni:

La funzione wcsrtombs converte una stringa di caratteri wide, a partire dallo stato di conversione specificato contenuto in mbstate, dai valori a cui punta indirettamente wcstr, nell'indirizzo di mbstr. La conversione continuerà per ogni carattere fino a quando: viene rilevato un carattere wide di terminazione Null, viene rilevato un carattere non corrispondente o il carattere successivo causerebbe il superamento del limite contenuto in count. Se wcsrtombs rileva il carattere Null wide (L'\0') in corrispondenza di count o prima, lo converte in 0 a 8 bit e si arresta.

Pertanto, la stringa di caratteri multibyte in mbstr termina con Null solo se wcsrtombs rileva un carattere wide Null durante la conversione. Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcsrtombs non è definito. wcsrtombs viene influenzato dalla categoria LC_TYPE delle impostazioni locali correnti.

La wcsrtombs funzione differisce da wcstombs, _wcstombs_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é wcsnlen se viene usata una chiamata successiva a wcsrtombs invece di wcstombs.

Se l'argomento mbstr è NULL, wcsrtombs restituisce le dimensioni necessarie in byte della stringa di destinazione. Se mbstate è Null, viene usato lo stato di conversione interno mbstate_t. Se la sequenza wchar di caratteri non ha una rappresentazione di caratteri multibyte corrispondente, viene restituito un -1 e viene errno impostato su EILSEQ.

In C++, questa funzione presenta un overload di modello che richiama la relativa controparte sicura più recente. 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 wcsrtombs funzione è multithread safe purché nessuna funzione nel thread corrente chiami setlocale mentre questa funzione è in esecuzione e non mbstate è null.

Esempio

// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    countConverted = wcsrtombs(mbString, &wcsIndirectString,
                               MB_BUFFER_SIZE, &mbstate); // C4996
    // Note: wcsrtombs is deprecated; consider using wcsrtombs_s
    if (errno == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfuly converted.\n" );
    }
}

The string was successfuly converted.

Requisiti

Vedi anche

Conversione dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit