mbstowcs, _mbstowcs_l

Articolo
03/05/2013

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

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

Parametri

[out] wcstr
L'indirizzo di una sequenza di caratteri di tipo " wide ".
[in] mbstr
l'indirizzo di una sequenza di caratteri multibyte con terminazione null.
[in] count
Il numero massimo di caratteri multibyte da convertire.
[in] locale
le impostazioni locali da utilizzare.

Valore restituito

se mbstowcs correttamente converte la stringa di origine, restituisce il numero di caratteri multibyte convertiti.se wcstr l'argomento è NULL, la funzione restituisce la dimensione richiesta (i caratteri di tipo " wide ") della stringa di destinazione.se mbstowcs rileva un carattere multibyte non valido, restituisce a 1.se il valore restituito è count, la stringa di caratteri estesi non è con terminazione null.

Nota sulla sicurezza
Assicurarsi che wcstr e mbstr non si sovrappone e quello count correttamente riflette il numero di caratteri multibyte per la conversione.

Note

mbstowcs la funzione di conversione fino al numero massimo di count caratteri multibyte operazioni da mbstr in una stringa di caratteri di tipo " wide " corrispondenti sono determinati dalle impostazioni locali correnti.Archivia la stringa con caratteri estesi risultante all'indirizzo rappresentato da wcstr*.* Il risultato è simile a una serie di chiamate a mbtowc.se mbstowcs rileva (" a byte singolo \ 0 " del carattere null) o prima o dopo count si verifica, converte il carattere null a un carattere null a caratteri estesi (" \ 0 ") e interruzioni.Pertanto la stringa con caratteri estesi a wcstr è con terminazione null solo se un carattere null viene rilevato durante la conversione.Se le sequenze puntassero da wcstr e mbstr la sovrapposizione, il comportamento è definita.

se wcstr l'argomento è NULL, mbstowcs restituisce il numero di caratteri di tipo " wide " che deriverebbero da conversione, a esclusione di un carattere di terminazione null.La stringa di origine sia con terminazione null per il valore corretto venga restituita.Se si richiede una stringa di caratteri estesi risultante di essere con terminazione null, aggiungerne uno al valore restituito.

se mbstr l'argomento è NULL, o se count è > INT_MAX, il gestore non valido di parametro viene richiamato, come descritto in Convalida dei parametri .Se l'esecuzione è consentita per continuare, il errno è impostato su EINVAL e la funzione restituisce -1.

mbstowcs utilizza le impostazioni locali correnti per il comportamento impostazioni locali-dipendente; _mbstowcs_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
mbstowcs	<definito>
_mbstowcs_l	<definito>

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

Esempio

// crt_mbstowcs.c
// compile with: /W3
// illustrates the behavior of the mbstowcs function

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

int main( void )
{
    size_t size;
    int nChar = 2; // number of characters to convert
    int requiredSize;

    unsigned char    *pmbnull  = NULL;
    unsigned char    *pmbhello = NULL;
    char* localeInfo;
    
    wchar_t *pwchello = L"\x3042\x3043"; // 2 Hiragana characters
    wchar_t *pwc;

    /* Enable the Japanese locale and codepage */
    localeInfo = setlocale(LC_ALL, "Japanese_Japan.932");
    printf("Locale information set to %s\n", localeInfo);
    
    printf( "Convert to multibyte string:\n" );

    requiredSize = wcstombs( NULL, pwchello, 0); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    printf("  Required Size: %d\n", requiredSize);

    /* Add one to leave room for the null terminator. */
    pmbhello = (unsigned char *)malloc( requiredSize + 1);
    if (! pmbhello)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = wcstombs( pmbhello, pwchello, requiredSize + 1); // C4996
    // Note: wcstombs is deprecated; consider using wcstombs_s
    if (size == (size_t) (-1))
    {
        printf("Couldn't convert string. Code page 932 may"
                " not be available.\n");
        return 1;
    }
    printf( "  Number of bytes written to multibyte string: %u\n",
            (unsigned int) size );
    printf( "  Hex values of the " );
    printf( " multibyte characters: %#.2x %#.2x %#.2x %#.2x\n",
            pmbhello[0], pmbhello[1], pmbhello[2], pmbhello[3] );
    printf( "  Codepage 932 uses 0x81 to 0x9f as lead bytes.\n\n");

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

    /* Assume we don't know the length of the multibyte string.
     Get the required size in characters, and allocate enough space. */

    requiredSize = mbstowcs(NULL, pmbhello, 0); // C4996
    /* Add one to leave room for the NULL terminator */
    pwc = (wchar_t *)malloc( (requiredSize + 1) * sizeof( wchar_t ));
    if (! pwc)
    {
        printf("Memory allocation failure.\n");
        return 1;
    }
    size = mbstowcs( pwc, pmbhello, requiredSize + 1); // C4996
    if (size == (size_t) (-1))
    {
       printf("Couldn't convert string--invalid multibyte character.\n");
    }
    printf( "  Characters converted: %u\n", (unsigned int)size );
    printf( "  Hex value of first 2" );
    printf( " wide characters: %#.4x %#.4x\n\n", pwc[0], pwc[1] );
    free(pwc);
    free(pmbhello);
}