mbsrtowcs

Converte una stringa di caratteri multibyte delle impostazioni locali correnti in una stringa di caratteri wide corrispondente, con la possibilità di ricominciare nel mezzo di un carattere multibyte. È disponibile una versione più sicura di questa funzione; vedere mbsrtowcs_s.

Sintassi

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

Parametri

wcstr
Indirizzo in cui archiviare la stringa di caratteri wide convertita risultante.

mbstr
Puntatore indiretto alla posizione della stringa di caratteri multibyte da convertire.

count
Numero massimo di caratteri (non byte) da convertire e archiviare in wcstr.

mbstate
Puntatore a un oggetto stato di conversione mbstate_t. Se questo valore è un puntatore Null, viene usato un oggetto stato di conversione interno statico. Poiché l'oggetto interno mbstate_t non è thread-safe, è consigliabile passare sempre il proprio mbstate parametro.

Valore restituito

Restituisce il numero di caratteri convertito correttamente, escluso il carattere di terminazione Null, se presente. Restituisce (size_t)(-1) se si è verificato un errore e imposta su errno EILSEQ.

Osservazioni:

La funzione mbsrtowcs converte una stringa di caratteri multibyte a cui punta indirettamente mbstr in caratteri wide archiviati nel buffer a cui punta wcstr, usando lo stato di conversione contenuto in mbstate. La conversione continua per ogni carattere fino a quando non viene rilevato un carattere multibyte null di terminazione, una sequenza multibyte che non corrisponde a un carattere valido nelle impostazioni locali correnti o fino a quando count non vengono convertiti caratteri. Se mbsrtowcs rileva il carattere multibyte Null ('\0') nel momento in cui si verifica count o subito prima, lo converte in un carattere di terminazione Null a 16 bit e si arresta.

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

La mbsrtowcs funzione differisce da mbstowcs, _mbstowcs_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 mbsrlen invece di mbslen, se viene usata una chiamata successiva a mbsrtowcs anziché mbstowcs.

Se wcstr non è un puntatore Null, all'oggetto puntatore a cui mbstr punta viene assegnato un puntatore Null se la conversione è stata arrestata perché è stato raggiunto un carattere Null di terminazione. In caso contrario, all'indirizzo viene assegnato solo oltre l'ultimo carattere multibyte convertito, se presente. Consente a una chiamata di funzione successiva di riavviare la conversione in cui la chiamata è stata arrestata.

Se l'argomento wcstr è un puntatore Null, l'argomento count viene ignorato e mbsrtowcs restituisce le dimensioni necessarie in caratteri wide per la stringa di destinazione. Se mbstate è un puntatore Null, la funzione userà un oggetto stato di conversione mbstate_t interno statico non thread-safe. Se la sequenza mbstr di caratteri non ha una rappresentazione di caratteri multibyte corrispondente, viene restituito un -1 e errno viene impostato su EILSEQ.

Se mbstr è un puntatore Null, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione imposta errno suEINVAL e restituisce -1.

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 mbsrtowcs funzione è multithread safe purché nessuna funzione nel thread corrente chiami setlocale finché questa funzione è in esecuzione e l'argomento mbstate non è un puntatore Null.

Requisiti

Ciclo	Intestazione obbligatoria
mbsrtowcs	<wchar.h>

Vedi anche

Conversione dati
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
mbrtowc
mbtowc, _mbtowc_l
mbstowcs, _mbstowcs_l
mbsinit