wcstombs, _wcstombs_l

Articolo
03/05/2013

Converte una sequenza di caratteri di tipo " wide " a una sequenza corrispondente di caratteri multibyte.Più versioni sicure di queste funzioni sono disponibili, vedere wcstombs_s, _wcstombs_s_l.

size_t wcstombs(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count 
);
size_t _wcstombs_l(
   char *mbstr,
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
size_t wcstombs(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count 
); // C++ only
template <size_t size>
size_t _wcstombs_l(
   char (&mbstr)[size],
   const wchar_t *wcstr,
   size_t count,
   _locale_t locale
); // C++ only

Parametri

mbstr
l'indirizzo di una sequenza di caratteri multibyte.
wcstr
L'indirizzo di una sequenza di caratteri di tipo " wide ".
count
Numero massimo di byte che possono essere archiviati nella stringa di output di multibyte.
locale
le impostazioni locali da utilizzare.

Valore restituito

se wcstombs correttamente converte la stringa multibyte, restituisce il numero di byte scritti nella stringa di output di multibyte, senza terminare NULL (se presente).se mbstr l'argomento è NULL, wcstombs restituisce la dimensione richiesta in byte della stringa di destinazione.se wcstombs rileva un carattere di tipo " wide " che non può convertire a un carattere multibyte, restituisce - 1 eseguito il cast nel tipo size_t e set errno in EILSEQ.

Note

wcstombs la funzione converte la stringa con caratteri estesi indicata da wcstr i caratteri multibyte e dei file corrispondenti i risultati in mbstr matrice.count il parametro indica il numero massimo di byte che possono essere archiviati nella stringa di output di multibyte (ovvero la dimensione di mbstr).È in genere non si conosce il numero di byte saranno necessari quando si converte una stringa di caratteri estesi.Alcuni caratteri di tipo " wide " richiede solo un byte nella stringa di output, altre richiedono due.Se c " è due byte in multibyte di output stringa per ogni carattere di tipo " wide " nella stringa di input (carattere di tipo " wide " compresi NULL), il risultato è garantito l'allungamento.

se wcstombs 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 wcstombs rileva un carattere null a caratteri estesi durante la conversione.Se le sequenze puntassero da wcstr e mbstr sovrapposizione, il comportamento di wcstombs è definito.

se mbstr l'argomento è NULL, wcstombs restituisce la dimensione richiesta in byte della stringa di destinazione.

wcstombs convalida dei parametri.se wcstr viene NULL, o se count è maggiore diINT_MAX, questa funzione viene richiamato il gestore non valido di parametro, come descritto in Convalida dei parametri .Se l'esecuzione è consentita per continuare, set di funzione errno in EINVAL e restituisce -1.

wcstombs utilizza le impostazioni locali correnti per il comportamento impostazioni locali-dipendente; _wcstombs_l è identico con la differenza che utilizza le impostazioni locali passate in alternativa.Per ulteriori informazioni, vedere Impostazioni locali.

In C++, queste funzioni presentano overload del modello da richiamare le più recenti, controparti sicure di queste funzioni.Per ulteriori informazioni, vedere Assicurarsi che gli overload del modello.

Requisiti

routine	Intestazione di associazione
wcstombs	<definito>
_wcstombs_l	<definito>

per informazioni di compatibilità aggiuntive, vedere compatibilità nell'introduzione.

Esempio

Questo programma viene illustrato il comportamento di wcstombs funzione.

// crt_wcstombs.c
// compile with: /W3
// This example demonstrates the use
// of wcstombs, which converts a string
// of wide characters to a string of 
// multibyte characters.

#include <stdlib.h>
#include <stdio.h>

#define BUFFER_SIZE 100

int main( void )
{
    size_t  count;
    char    *pMBBuffer = (char *)malloc( BUFFER_SIZE );
    wchar_t *pWCBuffer = L"Hello, world.";

    printf("Convert wide-character string:\n" );

    count = wcstombs(pMBBuffer, pWCBuffer, BUFFER_SIZE ); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s instead
    printf("   Characters converted: %u\n",
            count );
    printf("    Multibyte character: %s\n\n",
           pMBBuffer );

    free(pMBBuffer);
}