wcstombs_s
, _wcstombs_s_l
Converte una sequenza di caratteri wide in una sequenza di caratteri multibyte corrispondente. Versione di , _wcstombs_l
con miglioramenti della wcstombs
sicurezza, come descritto in Funzionalità di sicurezza in CRT.
Sintassi
errno_t wcstombs_s(
size_t *pReturnValue,
char *mbstr,
size_t sizeInBytes,
const wchar_t *wcstr,
size_t count
);
errno_t _wcstombs_s_l(
size_t *pReturnValue,
char *mbstr,
size_t sizeInBytes,
const wchar_t *wcstr,
size_t count,
_locale_t locale
);
template <size_t size>
errno_t wcstombs_s(
size_t *pReturnValue,
char (&mbstr)[size],
const wchar_t *wcstr,
size_t count
); // C++ only
template <size_t size>
errno_t _wcstombs_s_l(
size_t *pReturnValue,
char (&mbstr)[size],
const wchar_t *wcstr,
size_t count,
_locale_t locale
); // C++ only
Parametri
pReturnValue
Dimensione in byte della stringa convertita, incluso il carattere di terminazione Null.
mbstr
Indirizzo di un buffer per la stringa di caratteri multibyte convertita risultante.
sizeInBytes
Dimensione del buffer mbstr
, in byte.
wcstr
Punta alla stringa di caratteri wide da convertire.
count
Numero massimo di byte da archiviare nel mbstr
buffer, non incluso il carattere 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 |
---|---|
mbstr è NULL e sizeInBytes > 0 |
EINVAL |
wcstr è 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 |
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 wcstombs_s
converte una stringa di caratteri wide a cui punta wcstr
in caratteri multibyte archiviati nel buffer a cui punta mbstr
. La conversione continuerà per ogni carattere fino a quando non viene soddisfatta una delle seguenti condizioni:
Viene rilevato un carattere Null wide
Viene rilevato un carattere wide che non può essere convertito
Il numero di byte archiviati nel buffer
mbstr
è uguale acount
.
La stringa di destinazione è sempre con terminazione Null (anche se si verifica un errore).
Se count
è il valore _TRUNCATE
speciale , wcstombs_s
converte la maggior parte della stringa che verrà inserita nel buffer di destinazione, lasciando allo stesso tempo spazio per un terminatore Null. Se la stringa viene troncata, il valore restituito è STRUNCATE
e la conversione viene considerata riuscita.
Se wcstombs_s
la stringa di origine viene convertita correttamente, inserisce le dimensioni in byte della stringa convertita, incluso il terminatore Null, in *pReturnValue
(specificato pReturnValue
non NULL
è ). La dimensione viene calcolata anche se l'argomento mbstr
è NULL
; fornisce un modo per determinare le dimensioni del buffer necessarie. Se mbstr
è NULL
, count
viene ignorato.
Se wcstombs_s
rileva un carattere wide che non può convertire in un carattere multibyte, inserisce 0 in , imposta il buffer di destinazione su *ReturnValue
una stringa vuota, imposta errno
su EILSEQ
e restituisce EILSEQ
.
Se le sequenze a cui punta wcstr
e mbstr
si sovrappongono, il comportamento di wcstombs_s
non è definito.
Importante
Verificare che wcstr
e mbstr
non si sovrappongano e che count
rispecchi correttamente il numero di caratteri wide da convertire.
wcstombs_s
usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _wcstombs_s_l
è identica a wcstombs
, 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 |
---|---|
wcstombs_s |
<stdlib.h> |
Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).
Esempio
Questo programma illustra il comportamento della funzione wcstombs_s
.
// crt_wcstombs_s.c
// This example converts a wide character
// string to a multibyte character string.
#include <stdio.h>
#include <stdlib.h>
#include <assert.h>
#define BUFFER_SIZE 100
int main( void )
{
size_t i;
char *pMBBuffer = (char *)malloc( BUFFER_SIZE );
const wchar_t*pWCBuffer = L"Hello, world.";
printf( "Convert wide-character string:\n" );
// Conversion
wcstombs_s(&i, pMBBuffer, (size_t)BUFFER_SIZE,
pWCBuffer, (size_t)BUFFER_SIZE - 1); // -1 so the appended NULL doesn't fall outside the allocated buffer
// Output
printf(" Characters converted: %u\n", i);
printf(" Multibyte character: %s\n\n", pMBBuffer );
// Free multibyte character buffer
if (pMBBuffer)
{
free(pMBBuffer);
}
return 0;
}
Convert wide-character string:
Characters converted: 14
Multibyte character: Hello, world.
Vedi anche
Conversione dati
impostazioni locali
_mbclen
, mblen
, _mblen_l
mbstowcs
, _mbstowcs_l
mbtowc
, _mbtowc_l
wctomb_s
, _wctomb_s_l
WideCharToMultiByte