wcstombs, _wcstombs_l

Converte una sequenza di caratteri wide in una sequenza di caratteri multibyte corrispondente. Sono disponibili versioni più sicure di queste funzioni; vedere wcstombs_s, _wcstombs_s_l.

Sintassi

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
Indirizzo di una sequenza di caratteri multibyte.

wcstr
Indirizzo di una sequenza di caratteri wide.

count
Numero massimo di byte che possono essere archiviati nella stringa di output multibyte.

locale
Impostazioni locali da usare.

Valore restituito

Se wcstombs converte correttamente la stringa multibyte, restituisce il numero di byte scritti nella stringa di output multibyte, escluso il carattere NULL di terminazione (se presente). Se l'argomento mbstr è NULL, wcstombs restituisce le dimensioni necessarie in byte della stringa di destinazione. Se wcstombs rileva un carattere wide che non può convertire in un carattere multibyte, restituisce il cast -1 al tipo size_t e imposta errno su EILSEQ.

Osservazioni:

La funzione wcstombs converte la stringa di caratteri wide a cui punta wcstr nei caratteri multibyte corrispondenti e archivia il risultato nella matrice mbstr. Il parametro count indica il numero massimo di byte che possono essere archiviati nella stringa di output multibyte, ovvero le dimensioni di mbstr. In generale, non è noto il numero di byte necessari per la conversione di una stringa di caratteri wide. Alcuni caratteri wide richiedono un solo byte nella stringa di output; altri richiedono 2 byte. Se nella stringa di output multibyte sono presenti 2 byte per ogni carattere wide nella stringa di input (incluso il carattere NULLwide ), il risultato è garantito per adattarsi.

A partire da Windows 10 versione 1803 (10.0.17134.0), Universal C Runtime supporta l'uso di una tabella codici UTF-8. Usare wcstombs(NULL, wcstr, 0) per ottenere le dimensioni corrette necessarie per la conversione perché supponendo che siano necessari due byte per ogni carattere wide potrebbe non essere sufficiente. Per altre informazioni sul supporto UTF-8, vedere Supporto UTF-8

Se wcstombs rileva il carattere NULL wide (L'\0') prima o quando count si verifica, lo converte in 8 bit 0 e si arresta. Pertanto, la stringa di caratteri multibyte in è mbstr con terminazione Null solo se wcstombs rileva un carattere NULL wide durante la conversione. Se le sequenze a cui punta wcstr e mbstr si sovrappongono, il comportamento di wcstombs non è definito.

Se l'argomento mbstr è NULL, wcstombs restituisce le dimensioni necessarie in byte della stringa di destinazione.

wcstombs convalida i propri parametri. Se wcstr è o se count è NULLmaggiore di INT_MAX, questa funzione richiama il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione imposta errno su EINVAL e restituisce -1.

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

In C++ queste funzioni presentano overload di modello che richiamano le relative 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

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

Esempio

Questo programma illustra il comportamento della funzione wcstombs.

// 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);
}

Convert wide-character string:
   Characters converted: 13
    Multibyte character: Hello, world.

Vedi anche

Conversione dati
impostazioni locali
_mbclen, mblen, _mblen_l
mbstowcs, _mbstowcs_l
mbtowc, _mbtowc_l
wctomb, _wctomb_l
WideCharToMultiByte