mbstowcs, _mbstowcs_l

  • Articolo

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

Sintassi

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

wcstr
Indirizzo di una sequenza di caratteri wide.

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

count
Numero massimo di caratteri multibyte da convertire.

locale
Impostazioni locali da usare.

Valore restituito

Se mbstowcs converte correttamente la stringa di origine, restituisce il numero di caratteri multibyte convertiti. Se l'argomento wcstr è NULL, la funzione restituisce le dimensioni richieste (in caratteri wide) della stringa di destinazione. Se mbstowcs rileva un carattere multibyte non valido, restituisce -1. Se il valore restituito è count, la stringa di caratteri wide non viene terminata con null.

Importante

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

Osservazioni:

La funzione mbstowcs converte fino a un numero massimo di caratteri multibyte pari a count a cui punta mbstr in una stringa di caratteri wide corrispondenti che dipendono dalle impostazioni locali correnti. Archivia la stringa di caratteri wide risultante in corrispondenza dell'indirizzo rappresentato da wcstr. Il risultato è simile a una serie di chiamate a mbtowc. Se mbstowcs rileva il carattere Null a byte singolo ('\0') prima o quando count si verifica, converte il carattere Null in un carattere null wide (L'\0') e si arresta. Pertanto, la stringa di caratteri wide in wcstr termina con Null solo se viene rilevato un carattere Null durante la conversione. Se le sequenze a cui puntano wcstr e mbstr si sovrappongono, il comportamento non è definito.

Se l'argomento wcstr è NULL, mbstowcs restituisce il numero di caratteri wide risultanti dalla conversione, senza includere un carattere di terminazione Null. La stringa di origine deve avere terminazione Null perché venga restituito il valore corretto. Se è necessario che la stringa di caratteri wide risultante abbia terminazione Null, aggiungere un carattere di terminazione Null al valore restituito.

Se l'argomento mbstr è o se count è >NULLINT_MAX, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, errno viene impostato su EINVAL e la funzione restituisce -1.

mbstowcs usa le impostazioni locali correnti per qualsiasi comportamento dipendente dalle impostazioni locali. La funzione _mbstowcs_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

Ciclo Intestazione obbligatoria
mbstowcs <stdlib.h>
_mbstowcs_l <stdlib.h>

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

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

Locale information set to Japanese_Japan.932
Convert to multibyte string:
   Required Size: 4
   Number of bytes written to multibyte string: 4
   Hex values of the  multibyte characters: 0x82 0xa0 0x82 0xa1
   Codepage 932 uses 0x81 to 0x9f as lead bytes.

Convert back to wide-character string:
   Characters converted: 2
   Hex value of first 2 wide characters: 0x3042 0x3043

Vedi anche

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