mbstowcs, _mbstowcs_l

  • Artikel

Mengonversi urutan karakter multibyte ke urutan karakter lebar yang sesuai. Versi yang lebih aman dari fungsi-fungsi ini tersedia; lihat mbstowcs_s, _mbstowcs_s_l.

Sintaks

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

Parameter

wcstr
Alamat urutan karakter luas.

mbstr
Alamat urutan karakter multibyte null yang dihentikan.

count
Jumlah maksimum karakter multibyte yang akan dikonversi.

locale
Lokal yang akan digunakan.

Nilai hasil

Jika mbstowcs berhasil mengonversi string sumber, string sumber mengembalikan jumlah karakter multibyte yang dikonversi. wcstr Jika argumen adalah NULL, fungsi mengembalikan ukuran yang diperlukan (dalam karakter lebar) dari string tujuan. Jika mbstowcs menemukan karakter multibyte yang tidak valid, karakter tersebut mengembalikan -1. Jika nilai yang dikembalikan adalah count, string karakter lebar tidak dihentikan null.

Penting

Pastikan dan wcstrmbstr jangan tumpang tindih, dan itu mencerminkan jumlah karakter multibyte yang count akan dikonversi dengan benar.

Keterangan

Fungsi ini mbstowcs mengonversi hingga jumlah count maksimum karakter multibyte yang diarahkan ke mbstr string karakter lebar terkait yang ditentukan oleh lokal saat ini. Ini menyimpan string karakter lebar yang dihasilkan di alamat yang diwakili oleh wcstr. Hasilnya mirip dengan serangkaian panggilan ke mbtowc. Jika mbstowcs menemukan karakter null byte tunggal ('\0') baik sebelum atau ketika count terjadi, karakter null akan dikonversi ke karakter null karakter lebar (L'\0') dan berhenti. Dengan demikian string karakter lebar di dihentikan wcstr null hanya jika karakter null ditemui selama konversi. Jika urutan menunjuk ke dan wcstrmbstr tumpang tindih, perilaku tidak terdefinisi.

wcstr Jika argumen adalah NULL, mbstowcs mengembalikan jumlah karakter lebar yang akan dihasilkan dari konversi, tidak termasuk terminator null. String sumber harus dihentikan null agar nilai yang benar dikembalikan. Jika Anda memerlukan string karakter lebar yang dihasilkan untuk dihentikan null, tambahkan satu ke nilai yang dikembalikan.

mbstr Jika argumen adalah NULL, atau jika count adalahINT_MAX> , handler parameter yang tidak valid dipanggil, seperti yang dijelaskan dalam Validasi parameter. Jika eksekusi diizinkan untuk melanjutkan, errno diatur ke EINVAL dan fungsi mengembalikan -1.

mbstowcs menggunakan lokal saat ini untuk perilaku yang bergantung pada lokal; _mbstowcs_l identik kecuali menggunakan lokal yang diteruskan sebagai gantinya. Untuk informasi selengkapnya, lihat Lokal.

Di C++, fungsi-fungsi ini memiliki kelebihan beban templat yang memanggil rekan-rekan yang lebih baru dan aman dari fungsi-fungsi ini. Untuk informasi selengkapnya, lihat Mengamankan kelebihan beban templat.

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Persyaratan

Rutin Header yang diperlukan
mbstowcs <stdlib.h>
_mbstowcs_l <stdlib.h>

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

// 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

Baca juga

Konversi data
Lokal
Interpretasi urutan karakter multibyte
_mbclen, mblen, _mblen_l
mbtowc, _mbtowc_l
wcstombs, _wcstombs_l
wctomb, _wctomb_l
MultiByteToWideChar