wcsrtombs

Articolo
03/05/2013

Convertire una stringa di caratteri estesi nella relativa rappresentazione di stringa di caratteri multibyte.Una versione più sicura di questa funzione è disponibile; vedere wcsrtombs_s.

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

[out] mbstr
La posizione relativa della stringa convertita risultante di caratteri multibyte.
[in] wcstr
Indirettamente punti al percorso della stringa con caratteri estesi da convertire.
[in] count
Il numero di caratteri da convertire.
[in] mbstate
Un puntatore a un oggetto mbstate_t oggetto stato di conversione.

Valore restituito

Restituisce il numero di byte correttamente convertiti, escluso il byte null di terminazione null (se presenti), in caso contrario di un -1 se si è verificato un errore.

Note

wcsrtombs la funzione converte una stringa di caratteri di tipo " wide ", a partire dallo stato specificato di conversione contenuto in mbstate, quindi aguzzo indiretto di valori in wcstr, l'indirizzo di mbstr.la conversione continuerà per ogni carattere fino a: dopo che un carattere di tipo " wide " di terminazione null viene rilevato, quando un carattere non concordante viene rilevato o quando il carattere successivo determinerebbe un overflow del limite contenuto in count.se wcsrtombs rileva il carattere null a caratteri estesi (" \ 0 ") o prima o dopo count si verifica, lo converte in un 8 bit 0 e si arresta.

Pertanto, la stringa di caratteri multibyte a mbstr è con terminazione null solo se wcsrtombs rileva un carattere null di caratteri di tipo " wide " durante la conversione.Se le sequenze puntassero da wcstr e mbstr sovrapposizione, il comportamento di wcsrtombs è definito.wcsrtombs è interessati alla categoria di LC_TYPE delle impostazioni locali correnti.

wcsrtombs la funzione è diverso da wcstombs, _wcstombs_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é wcsnlen, se una chiamata successiva a wcsrtombs sono stati utilizzati anziché wcstombs.

se mbstr l'argomento è NULL, wcsrtombs restituisce la dimensione richiesta in byte della stringa di destinazione.se mbstate è null, l'interno mbstate_t lo stato di conversione viene utilizzato.se la sequenza di caratteri wchar non dispone di una rappresentazione di caratteri multibyte corrispondente, -1 viene restituito e errno è impostato su EILSEQ.

In C++, la funzione presenta un overload del modello che richiama la più recente, controparte protetta della funzione.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Eccezioni

wcsrtombs la funzione è multithread-safe se nessuna funzione nelle chiamate del thread corrente setlocale questa funzione è in esecuzione e mbstate non è 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" );
    }
}