Condividi tramite

mbstowcs_s, _mbstowcs_s_l

  • Articolo

Converte una sequenza di caratteri multibyte in una sequenza di caratteri wide corrispondente. Versioni di , _mbstowcs_lcon miglioramenti dellambstowcs sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Sintassi

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Parametri

pReturnValue
Numero di caratteri convertiti.

wcstr
Indirizzo del buffer per la stringa di caratteri wide convertita risultante.

sizeInWords
Dimensioni del buffer wcstr in parole.

mbstr
Indirizzo di una sequenza di caratteri multibyte con terminazione Null.

count
Numero massimo di caratteri wide da archiviare nel wcstr buffer, non inclusi i valori Null di terminazione o _TRUNCATE.

locale
Impostazioni locali da usare.

Valore restituito

Zero in caso di esito positivo, un codice di errore in caso di esito negativo.

Condizione di errore Valore restituito e errno
wcstr è NULL e sizeInWords> 0 EINVAL
mbstr è NULL EINVAL
Il buffer di destinazione è troppo piccolo per contenere la stringa convertita (a meno che count non sia _TRUNCATE; vedere la sezione Note di seguito) ERANGE
wcstr non NULL è e sizeInWords == 0 EINVAL

Se si verifica una di queste condizioni, viene richiamata l'eccezione di parametro non valida come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce un codice errore e imposta errno come indicato nella tabella.

Osservazioni:

La funzione mbstowcs_s converte una stringa di caratteri multibyte a cui punta mbstr in caratteri wide archiviati nel buffer a cui punta wcstr. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:

  • Viene rilevato un carattere Null multibyte

  • Viene rilevato un carattere multibyte non valido

  • Il numero di caratteri wide archiviati nel buffer wcstr è uguale a count.

La stringa di destinazione è sempre con terminazione Null (anche se si verifica un errore).

Se count è il valore _TRUNCATEspeciale , mbstowcs_s converte la maggior parte della stringa che verrà inserita nel buffer di destinazione, lasciando allo stesso tempo spazio per un terminatore Null.

Se mbstowcs_s la stringa di origine viene convertita correttamente, inserisce le dimensioni in caratteri wide della stringa convertita, incluso il carattere di terminazione Null, in *pReturnValue (specificato pReturnValue non NULLè ). La dimensione viene calcolata anche se l'argomento wcstr è NULLe fornisce un modo per determinare le dimensioni del buffer necessarie. Se wcstr è NULL, count viene ignorato e sizeInWords deve essere 0.

Se mbstowcs_s rileva un carattere multibyte non valido, inserisce 0 in *pReturnValue, imposta il buffer di destinazione su una stringa vuota, imposta errno su EILSEQ e restituisce EILSEQ.

Se le sequenze a cui punta mbstr e wcstr si sovrappongono, il comportamento di mbstowcs_s non è definito.

Importante

Verificare che wcstr e mbstr non si sovrappongano e che count rispecchi correttamente il numero di caratteri multibyte da convertire.

mbstowcs_s usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _mbstowcs_s_l è identica, ma usa le impostazioni locali passate. Per altre informazioni, vedere Locale.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) 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.

Requisiti

Ciclo Intestazione obbligatoria
mbstowcs_s <stdlib.h>
_mbstowcs_s_l <stdlib.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Vedi anche

Conversione dati
impostazioni locali
MultiByteToWideChar
Interpretazione di sequenze di caratteri multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l